代码工作区与工作树

I. 代码工作区、Diff、引用与文件操作

• US-I01 边用终端边看代码：作为遥控开发任务的使用者，我希望在会话旁打开代码工作区，以便核对 agent 的工作而不离开终端。 验收要点：
  • 宽屏并排且可调整分栏；
  • 窄屏切换终端与代码；
  • 导航开关、文件标签、刷新全部与独立窗口同在一行，根路径与导航状态提示在导航面板顶部；
  • 代码导航可折叠、调整宽度；
  • 窄于 640px 时文档栏操作收进“代码菜单”（显示完整路径），文档提示仍直接显示，Diff 内容区不少于 393×851 视口高度的 70%；
  • 切换保留同一 PTY，输出继续接收。
• US-I02 确定阅读范围：作为使用者，我希望知道代码根目录对应哪份工作树，以便避免把另一个分支的代码当作当前任务。 验收要点：
  • 根绑定会话启动目录所属 Git worktree，无 Git 时绑定启动目录；
  • 终端内 cd 不改变它；
  • 不越过符号链接、嵌套仓库等受保护边界读取。
• US-I03 浏览与搜索路径：作为使用者，我希望展开树状目录并按文件名或路径搜索，以便找到要核对的代码。 验收要点：
  • 目录在原位按需展开，可同时展开多个分支，保留父目录和同级项；
  • 缩进线、目录/文件图标、当前文件高亮和 Git 状态可识别；
  • 支持方向键/Home/End 导航、全部折叠和刷新，刷新、收起导航与切换修改页保留展开分支；
  • 搜索与按路径打开从紧凑工具栏进入，目录定位展开对应祖先路径；
  • 默认隐藏 Git 忽略的未跟踪项，可从菜单显式显示忽略项，切换后目录树与搜索使用相同范围；
  • 根目录和子目录均可分页，搜索或扫描受限时提示缩小范围；
  • 搜索中全部折叠回到真实根目录，不把搜索结果作为目录项；
  • 路径搜索不等同于全仓库正文搜索。
• US-I04 多标签只读阅读：作为使用者，我希望同时打开多个文件并查看高亮内容，以便在相关实现间切换。 验收要点：
  • 最多 20 个文件或 Diff 标签；
  • 支持激活与关闭，标明路径和来源；
  • 只读，不保存修改、不操作 Git 索引或配置；
  • 单文件与 Diff 使用同一套 Pierre 渲染器、主题与高亮 worker，按文件名与扩展名识别常见语言并按需加载语法高亮，未识别时按纯文本显示；
  • 不提供编辑或保存。
• US-I05 文件内定位：作为使用者，我希望在文件和 Diff 中查找文字、跳转行并调整阅读显示，以便迅速定位细节。 验收要点：
  • 文件与 Diff 使用同一套查找面板、上/下一个匹配、大小写/正则/全词选项和 Ctrl/⌘+F、F3、Ctrl/⌘+G 键位；
  • 查找定位并选中整行，可关闭面板；
  • 普通文件可切换行号，偏好跨设备同步；
  • 文件的跳转行接受 N、+N、-N、N% 与 N:列；
  • Diff 换行偏好同样同步；
  • Diff 固定显示行号，保留自动换行和 Ctrl/⌘+Alt+G 跳转行快捷键。
• US-I06 总览 Git 修改：作为使用者，我希望按未暂存、已暂存、未跟踪查看修改，并筛选路径，以便了解 agent 改了什么。 验收要点：
  • 修改分组、来源和状态可识别；
  • 支持路径筛选、分页与大列表浏览；
  • 无 Git 时说明差异不可用，不阻止普通文件阅读。
• US-I07 阅读 Diff：作为使用者，我希望 Diff 自动适配阅读宽度并能展开上下文，以便直接理解增删内容和周边代码。 验收要点：
  • 显示新增/删除行数；
  • 宽度足够时并排、窄屏统一显示，固定保留行号，无需手动选择布局；
  • 按需展开上下文，区分新增、删除、重命名等变化；
  • 受限或计算失败时提示并提供重试或完整文件入口。
• US-I08 切换完整文件和比较来源：作为使用者，我希望从文件查看 Diff，也能打开 Diff 两侧完整文件，以便在变更与完整上下文间切换。 验收要点：
  • 根据修改组比较工作树、索引与 HEAD；
  • 通过一个“完整文件”菜单打开同一快照修改前或修改后的文件，不提供不存在的版本；
  • 文件与 Diff 切换只展示下一步操作；
  • 窄于 640px 时这些操作在“代码菜单”中；
  • 无差异或来源已变更时保留阅读并提示，不悄悄换成不同版本。
• US-I09 插入文件和行引用：作为使用者，我希望把整个文件、某行或连续行范围发送给终端或草稿，以便准确告诉 agent 关注哪里。 验收要点：
  • 桌面行号选择、Shift 连选，触摸点行后点底部“发送位置”；
  • 文字 Diff 根据选中行自动确定引用版本，无需选择旧侧/新侧；
  • 默认引用修改后版本，已删除文件引用修改前版本；
  • 文件与 Diff 都在选行后才显示“引用整个文件”；
  • 操作栏单行，宽屏左侧显示引用版本和选择方式提示，窄屏省略提示；
  • 生成绝对路径及可选行范围，不回车，路径正确转义；
  • 索引/HEAD 引用注明版本，不能把跨两侧选择伪装成同一来源。
• US-I10 发现变化后手动刷新：作为使用者，我希望阅读时收到外部更新提示，再决定何时刷新，以便不被 agent 的写入打断。 验收要点：
  • 代码可见且页面在前台时约每 5 秒检查，也在恢复可见或连接时检查；
  • 文件、目录、修改列表提示更新、删除或未知状态；
  • 保留旧内容，显式刷新才替换；
  • 状态异常时阻止发送陈旧引用。
• US-I11 识别不可阅读内容：作为使用者，我希望二进制、超大文件或不支持的路径给出清楚说明，以便知道为何没有正常代码视图。 验收要点：
  • 单个文本文件最多 2 MiB / 20000 行，图片与 PDF 另按 US-I15、US-I17 的上限预览，单目录最多检查 10000 项；
  • 非图片、非 PDF 的二进制，空或无法识别的图片，空或缺少 %PDF- 签名的 .pdf，特殊文件、子模块等按支持范围展示元信息或边界；
  • 其他扩展名的 PDF 内容仍为二进制内容；
  • 受限结果不冒充完整结果。
• US-I12 隔离快照与会话：作为使用者，我希望代码快照始终属于当前会话，并在过期时明确提示，以便不发送错误版本的引用。 验收要点：
  • 上下文与快照按会话校验，不能跨会话复用；
  • 快照过期时保留旧画面并提示刷新；
  • 不把过期快照默认为当前文件。
• US-I13 独立代码窗口：作为桌面使用者，我希望把代码工作区弹到独立窗口，以便同时给终端和代码留出更大阅读空间。 验收要点：
  • 支持时使用置顶画中画，否则回退普通弹出窗口，窗口内只有运行独立代码工作区的同源 iframe；
  • 弹出、收回与直接关闭窗口都保留标签与已加载内容、阅读位置与选择（滚动、选区、查找、Diff 展开与选中、预览位置）、展开的文件夹、待粘贴条目与“有更新”提示；
  • 主页面显示占位，可收回；
  • 右键菜单、对话框与底部面板显示在独立窗口内并定位在触发处，窄窗口按自身宽度布局；
  • 引用经消息通道插入主页面的终端或草稿；
  • 关闭独立窗口恢复原位，离开或刷新主页面会关闭它；
  • 不支持画中画且无精细指针，或在带触摸屏设备的主屏幕 Web App 中时隐藏入口，窄于 640px 时也不显示；
  • 独立窗口内文件与修改视图的行号单击、Shift 范围选择和重新选择照常可用；
  • 弹窗被拦截时提示。
• US-I14 按路径打开：作为在终端里 cd 的使用者，我希望输入相对当前目录的路径直接打开文件，以便不必从代码根逐层查找。 验收要点：
  • 相对路径以本机 Shell 报告目录为基点，无报告时用启动目录，也接受绝对路径；
  • 服务端解析符号链接后必须位于代码根内，目录跳转到文件树；
  • 远端报告、根外路径、.git 内部、不存在路径和特殊文件给出明确错误；
  • 读取仍走既有边界检查。
• US-I15 预览与下载图片：作为远程核对 agent 产物的使用者，我希望在代码工作区直接查看图片并下载到当前设备，以便确认截图、图表等生成结果。 验收要点：
  • PNG、JPEG、GIF、WebP、AVIF、BMP、ICO 按扩展名加文件头识别并预览，可适应窗口、1:1、缩放、拖动和双指缩放，显示格式、像素尺寸与大小；
  • 图片工具栏单行，窄屏触摸设备只保留适应窗口与 1:1，缩放靠双指；
  • SVG 默认预览、可切源码，脚本与外部资源不生效；
  • 20 MiB 以上只显示元信息，100 MiB 内可下载且字节一致、保留原名；
  • 图片 Diff 显示变更与大小并可切换修改前/修改后版本；
  • 文件变化、快照过期、过大与未认证给出明确错误，token 不进 URL。
• US-I16 预览 Markdown：作为阅读 README、设计文档或说明的使用者，我希望在代码工作区直接查看 Markdown 的排版结果，以便确认标题、列表、代码块、链接和图片的呈现，并在文档之间跳转。 验收要点：
  • 打开 .md、.markdown、.mdown 或 .mkd 文本文件时，文档栏（窄屏为“代码菜单”）提供“预览”按钮切换到渲染视图，并可“返回源码”；
  • 渲染标题、列表、代码块、表格和链接；
  • 原始 HTML 经清洗，不执行脚本、不嵌入框架，作者的 id/name 被移除，外部图片只显示为“图片：说明（地址）”文字，javascript: 等协议的链接只剩文字，HTTP(S)/mailto 链接在新标签页打开；
  • 相对链接相对当前文档目录、/ 开头相对工作区根解析，在代码面板中打开文件标签或在文件导航中定位目录，越界、不存在、符号链接或不可读时就地提示，修饰键点击行为相同且不打开应用路由；
  • 标题生成 md-h- 前缀的 GitHub 风格锚点，#标题 在预览内滚动且不改地址栏，文件#标题 打开该文件预览并定位；
  • 两个及以上标题时提供“目录”（窄屏在“代码菜单”）；
  • 工作区内相对图片（含 SVG 与 <img>）进入可视区附近时经快照原始字节端点以认证请求加载，最多同时 2 张、每篇 50 张，失败显示不存在、不在工作区内、不是可预览的图片、超过 20 MiB、传输繁忙（可重试）或内容已变化，点击已加载图片在面板中打开，切换标签或离开预览时取消读取并释放对象 URL；
  • 带语言标注的代码块按 CodeMirror 语言数据高亮并跟随明暗主题，未知语言保持纯文本；
  • 切换文件或 Diff 后回到源码模式，预览状态不写入设置。
• US-I17 预览 HTML、表格、JSON 与 PDF：作为核对 agent 产出报告、数据和文档的使用者，我希望在代码工作区直接查看 HTML、CSV/TSV、JSON 与 PDF 的呈现结果，以便不下载到本地也能确认内容，在手机上同样可用。 验收要点：
  • .html、.htm、.csv、.tsv、.json（大小写不敏感）的完整文本文件默认显示源码，文档栏（窄屏为“代码菜单”）提供“预览”并可“返回源码”，切换文件、Diff 或刷新后回到源码，状态不写入设置；
  • 超过文本上限、编码不支持或二进制的同名文件以及 Diff 不提供预览；
  • HTML 先在惰性解析中去除脚本、<base>、meta 刷新、<object>/<embed>/<iframe>、事件属性、链接地址与表单动作，注入 CSP 后放入无 allow-* 的 sandbox 框架，白底显示并提示“静态预览，脚本与外部资源已禁用”，保留内联样式与 data: 图片，不发起任何请求、不提交、不导航；
  • CSV/TSV 按 RFC 4180 解析引号、转义引号与字段内换行，首行为表头、表头吸顶、可横向滚动，列数不齐补空，最多显示 2000 行并提示“仅显示前 2000 行，共 N 行”，引号未闭合时显示行号并可返回源码；
  • JSON 显示为默认展开两层的可折叠树，显示成员数，超过 200 个成员分批“再显示 200 项”，数字按源码原文显示，非法 JSON 显示“第 L 行第 C 列：JSON 语法错误”；
  • .pdf 且前 1024 字节内有 %PDF- 时识别为 PDF，打开即预览，渲染器、worker、CMap 与字体随应用打包、首次打开 PDF 时才加载，字节经认证请求读取；
  • 默认适应宽度，单行工具栏提供页码跳转、适应宽度、放大、缩小与下载，触摸设备双指缩放；
  • 只渲染可视区附近页面并释放远处画布，中文可显示并可选择复制，文档内链接跳页，HTTP(S)/mailto 在新标签页打开，脚本与表单不生效；
  • 超过 20 MiB 显示上限、大小与下载，受密码保护显示“PDF 受密码保护，请下载后查看”，损坏显示“PDF 无法解析”，均保留下载；
  • 切换文件或关闭标签时取消读取与渲染。
• US-I18 查看会话临时文件夹：作为让 agent 交付文件的使用者，我希望在代码工作区直接浏览本会话的临时文件夹，以便查看上传素材和 agent 生成的截图、报告而不让它们进入项目仓库。 验收要点：
  • 导航顶部“工作区 / 临时文件夹”切换，默认工作区；
  • 切到临时文件夹时按需创建 $TMPDIR 下按实例与会话隔离、权限 0700 的文件夹并显示其路径；
  • 浏览、搜索、按路径打开、预览、下载与资源管理器文件操作（US-I19）同工作区，不跟随符号链接，不提供“修改”页签与 Diff；
  • 两个根的标签可并存并标明来源，变化检测同样生效；
  • 文件夹不可用时显示原因与重试，不以工作区内容替代；
  • 普通会话删除后文件夹删除，混合会话保留到记录删除，服务启动清扫无主文件夹。
• US-I19 资源管理器文件操作：作为在浏览器里整理工作区和 agent 产物的使用者，我希望在文件树上用右键菜单上传、下载、重命名、复制、剪切、粘贴和删除文件或文件夹，以便不回到终端敲命令也能管理文件。 验收要点：
  • 文件树条目、根目录行与路径搜索结果支持右键、Shift+F10/菜单键、触屏长按（约 0.5 秒，移动即取消，不同时展开或打开条目，抬起手指不会误选弹出面板中的操作）和每行“⋯”（悬停或聚焦时显示，触屏常显）打开菜单；
  • 宽度不足 640px 时改为带条目名称与完整路径的底部操作面板，操作项与取消按钮满足触控尺寸，触屏与窄屏下树行加高；
  • 复制或剪切后显示剪贴板提示条，可直接粘贴到根目录或清除；
  • 重命名预选不含扩展名的文件名；
  • 文件可打开、下载，目录可下载为流式 ZIP（按“显示忽略项”决定是否含 Git 忽略文件，跳过 .git、嵌套仓库、符号链接与特殊文件）、上传到此目录、新建文件夹与粘贴；
  • 非根文件和目录可重命名、复制、剪切与删除，符号链接只可删除且不影响目标，根目录、嵌套仓库与特殊文件不可修改；
  • 工作区与临时文件夹都可写，但粘贴只限同一根，不能粘贴到自身或子目录，移动跨文件系统时报错；
  • 重名自动取最小可用的 (n) 后缀并提示，从不覆盖已有条目；
  • 名称拒绝空名、.、..、.git、路径分隔符、控制字符与超过 255 字节；
  • 复制与 ZIP 合计不超过 100 MiB / 10000 项，上传单文件不超过 100 MiB，超限返回 413；
  • 上传与下载显示进度并可取消，上传失败或取消不留下半个文件；
  • 删除文件夹前显示条目数与总大小并确认，含 .git 或嵌套仓库时拒绝且不部分删除；
  • 操作后刷新目录，并关闭被删除、移走或改名文件的标签；
  • 根不可写时禁用写入项；
  • 沿用认证、Origin 检查与错误状态映射；
  • 可从系统把文件拖到代码工作区上传（主页面与独立窗口相同）：落在文件夹行上传到该文件夹，落在文件行上传到其所在文件夹，其他位置上传到当前根目录，拖动时高亮目标并提示，只读根、包含文件夹或已有上传进行时拒绝并提示。

依据：

• 代码面板、独立窗口、平台能力判断
• 文件导航、文件树、文件操作菜单
• 文件与 Diff 切换、文件阅读
• Markdown 代码块语言匹配、Pierre 阅读器配置、高亮 worker
• Markdown 链接与图片路径解析、标题锚点、代码块高亮
• Markdown 预览、Diff 阅读、图片预览
• 代码引用、代码服务、文件操作、目录 ZIP 与上传
• 代码接口、临时文件夹服务。

US-I13 补充：弹出代码窗口取消原页面尚未完成的目录识别时，不缓存普通目录降级结果；独立窗口可重新识别 Git 并使用 Diff。依据：取消回归。

J. 仓库登记与 worktree 管理

• US-J01 登记已有仓库：作为使用者，我希望通过主仓库、worktree 或子目录登记已有 Git 仓库，以便集中管理项目的工作树。 验收要点：
  • 同一仓库只登记一次；
  • 只登记可信的现有目录，不 init 或 clone；
  • 登记保存在服务端状态目录，重启后仍在。
• US-J02 查看工作树状态：作为使用者，我希望看到分支、路径和工作树可用性，以便选择正确的代码副本。 验收要点：
  • 分支直接显示，路径、主工作区和已跟踪文件干净状态收在详情中；
  • bare、锁定及原因、待清理、有修改、未跟踪、不可用和未知/错误状态始终可见，bare 不可启动会话；
  • Git 读取慢时保留上次快照并继续显示读取中，只有真实失败才提示错误，单仓库失败不影响其他仓库或会话。
• US-J03 选择主页工作树：作为有大量工作树的使用者，我希望只把关注的工作树放到主页，以便降低总览噪声。 验收要点：
  • 默认主工作区可见，新建 worktree 自动添加；
  • 可按分支/路径搜索、多选添加或从主页移除；
  • 有会话的工作树始终显示，未添加者有标记；
  • 选择保存到服务端并跨设备同步，409 按 ID 重放；
  • 只读展示过滤不自动保存；
  • 移出主页不删除工作树。 从仓库菜单的“选择主页工作树”进入展示设置，该操作不启动会话。
• US-J04 为新任务创建分支工作树：作为使用者，我希望从已有本地提交创建新分支与 worktree，以便隔离新任务的文件变更。 验收要点：
  • “起始提交”默认显示主工作区的提交标题，候选项显示标题与本地/远程分支名；
  • 默认提交以精确 OID 创建，也可选分支引用或手动输入提交 OID；
  • 提供避开已有分支和目录的建议名及“换一个”；
  • 默认放在仓库旁的 worktrees 目录，目录名取分支末段，可修改完整路径，不覆盖已有目录。
• US-J05 检出现有分支：作为使用者，我希望搜索并选择未被占用的本地分支创建 worktree，以便继续已有工作。 验收要点：
  • 支持按名称搜索和键盘选择；
  • 已被其他工作树占用的分支禁选；
  • 不自动 fetch 远端分支。
• US-J06 单独创建与保留工作树：作为使用者，我希望工作树独立于会话存在，以便先准备环境或在任务结束后继续使用。 验收要点：
  • 可只创建工作树；
  • 仅检出版本控制内容，不复制 .env 或安装依赖；
  • 启动失败、关闭会话或服务重启不会自动删目录和分支。 仓库菜单提供独立命名的“新建工作树”；
  • 默认只创建，启动会话须显式勾选，未勾选时不要求启动命令。
• US-J07 同一工作树多个会话：作为使用者，我希望在同一 worktree 启动多个终端，以便同时运行 agent、测试或开发服务器。 验收要点：
  • 多个 PTY 独立运行但共享同一份工作树文件；
  • 启动目录或其子目录可关联工作树；
  • 关联基于启动位置，不实时跟踪终端里的 cd。
• US-J08 安全删除预览：作为使用者，我希望删除 worktree 前看到受保护文件和关联会话，以便避免丢失工作。 验收要点：
  • 安全删除拒绝未提交、未跟踪、忽略文件或活动会话；
  • 主工作区、bare、locked、含子模块等目标受保护；
  • 预览显示阻止原因和关联会话；
  • 有效确认限时且目标或会话变化后需重新预览。
• US-J09 明确强制删除：作为确实要丢弃任务的使用者，我希望在核对完整路径和相关会话后强制删除，以便清理不再需要的 worktree。 验收要点：
  • 仅允许可强制删除的目标；
  • 须输入完整路径并勾选关闭列出会话及删除全部内容的确认；
  • 可能丢弃未提交及忽略文件；
  • 保留分支与已退出记录；
  • 不能保证处理外部进程或终端 cd 后的归属。
• US-J10 移除仓库登记：作为使用者，我希望把不再关注的仓库从列表移除，以便整理项目清单。 验收要点：
  • 确认后仅移除持久登记，不删目录或分支，不关闭会话；
  • 原会话仍可在直接会话中访问。
• US-J11 局部失败时继续使用：作为使用者，我希望一个仓库损坏、路径消失或 Git 不可用时仍能使用其他终端，以便局部环境问题不阻断全部工作。 验收要点：
  • 单仓库失败保留错误和原会话入口；
  • Git 缺失或仓库存储不可用时禁用相关管理能力，直接目录终端仍可用；
  • 损坏清单不被静默覆盖。

依据：

• 工作区总览、主页选择、分支与路径表单、分支与提交信息、删除确认
• 仓库清单、创建、删除、工作区 API。