文件、工作区与恢复

先约定输入与输出#

任务组件开始处理文件前，应明确材料来自哪里、哪份是原件、输出保存在哪里，以及失败后能保留什么。

数据	推荐归属	不应该放在哪里
原始题目与数据	用户明确选择并登记的材料	不复制进组件代码充当运行配置
工作副本	当前项目允许的工作区	不覆盖只读输入原件
计算、论文、图表	明确的项目输出目录	不写回应用安装目录
阶段记录与检查点	组件自己的项目状态	不混进公共全局变量或密钥配置
可重建预览缓存	受支持的缓存位置	不将其当成唯一成果副本

大输入先登记，后按需读取#

打开窗口先读取路径、类型和当前视图需要的元信息。大型表格预览只取当前页，代码或计算工具需要完整数据时再走相应处理路径。

不要在“准备任务”阶段把所有 CSV、图片和压缩包都读进渲染层；这会放大内存、复制和启动时间，也会让正常任务看起来像启动超时。

规划可回看的项目结构#

下面是组件可以采用的设计例子，不是宿主强制目录，也不会由示例自动创建：

text

用户允许的项目目录/
  材料引用与说明
  工作副本/
  结果/
    本次运行/
      数据分析.csv
      结果图.png
      论文草稿.tex
  组件状态/
    state.json

目录和文件操作仍必须经过目标宿主实际开放的能力。不能因为文档画了一个目录树，就假定插件有任意创建和写入权限。

保存顺序影响恢复是否可靠#

生成当前阶段的内容，保留内存中的未保存状态。
等待允许路径上的写入完成，核对返回结果。
登记已经存在的输出文件。
再更新阶段检查点和用户界面。

如果第 2 步失败，不应先把第 4 步标成完成。写入过程中用户又修改的内容，也不能被旧保存结果覆盖。

一个内部持久状态示例#

json

{
  "schemaVersion": 1,
  "runId": "example-run-id",
  "status": "failed",
  "stage": "保存成果",
  "inputs": [{ "path": "<已授权材料引用>", "role": "source" }],
  "outputs": [{ "path": "<已保存输出引用>", "stage": "执行计算" }],
  "checkpoint": { "completedStages": ["检查输入", "执行计算"] },
  "error": { "stage": "保存成果", "message": "<脱敏后的原因>" }
}

这是推荐的组件内部结构，不是一个新增的宿主接口。保存位置、写入方式和恢复入口由组件结合实际能力实现。

恢复时逐项核对#

schemaVersion 是否支持，必要迁移是否完成。
输入引用和已登记成果是否仍存在。
上一运行是否真的结束，是否还有后台任务。
检查点代表的产出是否完整，而不仅是某个状态字符串。
用户外部修改的文件是否让检查点失效。

没有实现这些检查时，不要提供一个名为“继续”的按钮却暗中从头重跑。

更新文件与预览#

为当前预览保存文件身份及 stamp。发现变化后提示刷新，再读取需要的页面或内容；有未保存编辑时不能悄悄覆盖。