## 先约定输入与输出

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

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

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

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

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

## 规划可回看的项目结构

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

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

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

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

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

如果第 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。发现变化后提示刷新，再读取需要的页面或内容；有未保存编辑时不能悄悄覆盖。

项目迁移先备份旧状态，迁移成功再替换。清理临时文件时只能处理自己明确拥有的临时资源，不能删除整个用户项目来释放空间。