Workspace SOP

用途

Workspace SOP 是 Research-Claw 工作区的操作标准流程（SOP），用于规范工作区内的文件管理、Git 版本控制、目录约定以及命令行执行的安全规则。它面向使用 Research-Claw 工作区的用户与智能体，确保文件读写、版本追踪和格式转换行为一致且可追溯。

架构

工作区是一个本地 Git 仓库，首次使用时自动初始化。每次 workspace_save 都会创建一次 Git 提交（对快速批量操作有 5 秒防抖）。超过 10 MB 的文件会自动加入 .gitignore。该仓库仅存于本地，从不推送到任何远程。

仪表盘展示文件树、最近提交和文件预览，但不提供回滚功能——回滚与差异查看由用户通过智能体界面完成。

目录约定

两个顶层用户目录（系统目录 .ResearchClaw/ 对仪表盘隐藏）：

sources/：用户上传、导入的 PDF、数据集、参考资料
sources/chat/：用户直接拖入聊天输入框的原始文件（图片存放在 sources/chat/images/）
outputs/：智能体生成的草稿、图表、导出文件、报告
.ResearchClaw/：系统提示文件（隐藏）

可选子目录（按需创建，非必需）：sources/papers/、sources/data/、sources/references/、outputs/drafts/、outputs/figures/、outputs/exports/、outputs/reports/。

sources/ 表示用户输入，outputs/ 表示智能体生成的文件。当用户要求整理文件时，应将 sources/chat/ 中的文件归档到 sources/papers/ 等目录。

提交信息前缀

Add: 新建文件
Update: 修改已有文件
Upload: 保存用户上传的文件
Restore: 从历史恢复文件
Delete: 删除文件
Export: 从文本源转换出的二进制格式

工具链（11 个工具）

workspace_save：写入文本文件并自动提交
workspace_read：读取文件内容
workspace_list：列出文件（支持 glob 过滤与 git 状态）
workspace_diff：显示变更（无范围参数时比较未提交内容与 HEAD）
workspace_history：列出某文件或路径的提交历史
workspace_restore：检出历史版本并以 Restore: 提交
workspace_move：重命名/移动文件并提交
workspace_export：将文本转换为二进制格式（md→docx/pdf，csv→xlsx）
workspace_delete：删除文件并自动提交（需 confirm=true），可通过 workspace_restore 恢复
workspace_append：向已有文件追加内容（或创建），自动投影文件
workspace_download：从 URL 下载并将二进制文件保存到工作区

版本控制操作

撤销/回滚：workspace_history → 展示提交 → 用户选择 → workspace_restore → 用普通文本报告恢复后的路径。
差异：workspace_diff（默认比较未提交内容与 HEAD）。
主动提示：覆盖文件后提及 git 历史；删除时说明可用 workspace_restore 恢复。
删除：workspace_delete（需 confirm=true），始终说明 workspace_restore 可作为恢复手段。

写入纪律

强制预检：任何 workspace_save（覆盖）之前，必须先调用 workspace_read 或 workspace_list 确认文件是否存在及其内容，防止意外数据丢失。
追加与覆盖：当意图是“向文件添加内容”时，先读取现有内容再拼接，绝不能用新片段覆盖多段文件。
优先追加：向已有文件添加内容时，使用 workspace_append 而非读取+拼接+保存，可防止意外覆盖并减少 token 消耗。
仅限根目录范围：所有 workspace_* 工具严格操作工作区根目录内的相对路径。
越界（OOB）规则：对于工作区之外的路径，workspace_save 会失败或丢失版本控制。不要对系统级文件使用 workspace 工具；如确有必要，使用标准 CLI（配合 approval_card），但需注意这些操作没有 Git/历史支持。

二进制格式导出

workspace_save 仅写入 UTF-8 文本。要输出 Word/Excel/PDF：

将内容保存为 Markdown/CSV：workspace_save("outputs/drafts/paper.md", content)
转换：workspace_export({ source: "outputs/drafts/paper.md", format: "docx" })

转换引擎：

.md/.txt → .docx：pandoc
.md/.txt → .pdf：pandoc + xelatex（支持中日韩文字）
.csv/.json → .xlsx：Python pandas + openpyxl

输出默认到 outputs/exports/{name}.{format}，可用 output 参数覆盖。

绝不要用二进制扩展名（.docx、.xlsx、.pdf、.pptx 等）调用 workspace_save——工具会拒绝写入并引导使用 workspace_export。

原生安装依赖

Docker 镜像已预装所有依赖。对于原生（非 Docker）安装，workspace_export 需要外部工具。若转换失败并报 ENOENT 或 command not found，引导用户安装：

macOS（Homebrew）：

# 如未安装 Homebrew，先安装：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 然后安装转换依赖：
brew install pandoc            # md → docx
brew install --cask basictex   # md → pdf（xelatex 引擎）
pip3 install openpyxl          # csv → xlsx（pandas 通常已存在）

Windows：从 https://pandoc.org/installing.html 下载 pandoc 安装程序，安装 MiKTeX 以支持 PDF。

注意：workspace_export 不支持 .pptx 生成。PPT 创建通过专用 PPT 扩展（ExtensionsPanel → PPT Master）完成。

下载与导入

使用 workspace_download 从 URL 保存 PDF、图片等二进制文件：

workspace_download({ url: "https://arxiv.org/pdf/2301.00001", path: "sources/papers/paper.pdf" })

将 PDF 下载到 sources/papers/ 后，可提供 library_add_paper 以建立索引。

CLI 执行安全

无需审批（不需要 approval_card）：

wc、du、grep、find、pandoc、pdftotext、python3、xelatex、jq

需要 approval_card：

pip install、brew install、curl、wget、任何工作区之外的操作。

跨模块触发

PDF 保存/下载到 sources/papers/ → 提供 library_add_paper
论文加入库 → 建议通过 workspace_append 将 BibTeX 保存到 sources/references/refs.bib
创建代码文件 → 建议 task_create 跟踪工作
生成分析输出 → 报告其相对路径，如有关联则 task_complete

限制

仓库仅本地，不推送远程。
仪表盘不提供回滚，回滚与差异需通过智能体界面完成。
workspace_save 仅支持 UTF-8 文本，不支持二进制扩展名。
workspace_export 不支持 .pptx 生成。
原生安装需自行安装 pandoc、basictex、openpyxl 等外部依赖。
工作区工具仅限根目录内相对路径，越界路径无版本控制支持。

技能介绍

用途

架构