Research Workspace

research-workspace：科研工作区约定

目的

研究产物散落于桌面和下载文件夹，是科研工作流最常见的崩坏起点。本技能规定一套统一的目录结构与路径契约，使得：

1. 任何 skill 都知道"产物该写到哪里""该去哪里读原始数据"；
2. 同一 skill 的多次运行互不覆盖，历史可追溯；
3. 新会话能通过目录结构 itself 恢复大部分上下文；
4. 原始数据永远保持到手时的样子，为证据胶囊（evidence-capsule）提供冻结基础。

前置检查

1. 确认当前工作目录是用户认定的项目根目录。拿不准时问用户："把 <当前路径> 当作本项目的工作区根目录，对吗？"
2. init 前检查目录是否已有内容：非空目录不报错，但初始化时只补缺、不改动已有文件（见"初始化清单"）。
3. check 模式只读不写，任何"顺手修复"都必须先向用户报告再执行。

标准目录结构

工作区根目录下的标准布局：

<project-root>/
├── data/            # 原始数据，只读。到手后不再修改
├── figures/         # 论文/报告用图的最终版本（由 output 中的产物精选而来）
├── notebooks/       # Jupyter / Quarto 等交互式笔记本
├── papers/          # 论文与报告文稿（草稿与版本）
├── reports/         # 阶段性报告、组会材料、stage-report 的精选副本
├── reviews/         # 收到的审稿意见、发布前审查的记录
├── scripts/         # 可重复执行的脚本（分析、作图、数据处理）
├── output/          # 各 skill 的运行产物（结构见"产物路径契约"）
└── .openscience/    # 工作台元数据：provenance.jsonl、env/ 等

各目录的职责边界：

• data/：只进不出的原始数据。包括实验导出文件、下载的数据集、问卷原始答卷。子目录建议按来源或日期组织（如 data/2026-08-xrd/），但插件不强制。
• figures/ 与 papers/：放"准备给人看"的版本。过程稿在 output/ 里，只有被用户选中后才复制到这里。
• output/：机器产物的家。用户一般不需要手动整理这里——结构由契约保证。
• .openscience/：隐藏目录，记录工作台的运行状态。用户不需要直接编辑，但可以随时查看。provenance-record 写这里。

产物路径契约

所有 skill 的运行产物统一遵守：

output/<skill 名>/<slug>/<timestamp>/    # 每次运行的完整产物
output/<skill 名>/<slug>/latest/         # 最近一次运行的副本（或指针）

规则：

1. 每次运行一个时间戳目录：<timestamp> 格式为 YYYYMMDD-HHMMSS（本地时间）。一次运行产生的所有文件都放进同一个时间戳目录，不允许跨目录散落。
2. latest 是副本不是链接：运行结束时，把本次时间戳目录的内容完整复制到 latest/（先清空再放）。选副本而非符号链接，是因为 Windows 与部分远程文件系统对符号链接支持不一致；副本的代价是磁盘占用翻倍，产物通常很小，可以接受。
3. 读产物一律从 latest 读：下游 skill 需要上游产物时，只引用 output/<skill>/<slug>/latest/... 路径，保证"用到的永远是最新批准的版本"。需要引用历史版本时写明完整时间戳路径。
4. 历史目录不删不改：时间戳目录一旦写完就冻结。清理磁盘是用户的决定，skill 不得自动删除历史运行（guardrail 第 8 条）。
5. slug 来源：研究项目产物用 research-lifecycle 的 slug；与具体项目无关的产物（如画像修改记录）使用固定 slug workspace。
6. 已登记的例外：evidence-loop 使用轮次目录 output/evidence-loop/<slug>/<round>/，是本契约的显式例外，替代 latest/（见该 skill 的产物结构说明）。

示例：

output/
├── literature-search/
│   └── 3f9a1c7e/
│       ├── 20260818-101500/
│       │   ├── results-openalex.json
│       │   └── results-cnki.json
│       ├── 20260819-090000/
│       │   └── results-openalex.json
│       └── latest/            # 与 20260819-090000/ 内容相同
└── research-lifecycle/
    └── 3f9a1c7e/
        └── latest/
            ├── research-question.md
            └── hypothesis.md

原始数据只读原则

1. 文件进入 data/ 即冻结：不改名、不编辑、不删除、不覆盖。
2. 一切清洗、转换、筛选都生成新文件：中间产物放 output/<skill>/<slug>/，清洗后需要复用的数据集放 data/ 以外（建议 output/ 或项目自建的 derived/）。
3. 数据纠错走"增补"而非"修改"：发现原始数据有误时，新存一份修正版并附说明文件（README-correction.md 写明哪份文件哪里错了），原文件保留。
4. 任何 skill 检测到自己在写 data/ 下已存在的文件，必须停止并报告——这几乎一定是路径错误。
5. 大文件例外：原始数据体积巨大时（如测序原始数据），允许只存校验和与获取方式说明，但说明文件本身仍按只读原则管理。

1 · init：项目初始化清单

按顺序执行，每步完成后向用户报告：

1. 创建九个标准目录（已存在则跳过，不报错）。
2. 在 .openscience/ 下初始化空文件：provenance.jsonl（不存在则创建空文件）；env/ 子目录。
3. 生成工作区说明文件 WORKSPACE.md（根目录），内容：标准目录速查、产物路径契约、原始数据只读原则、本工作区初始化日期。已存在 WORKSPACE.md 时跳过不覆盖。
4. 检查 CLAUDE.md 画像状态：有 [填空] 时提醒用户先完成 cold-start-interview。
5. 如果用户提供了研究主题，顺手计算 slug 并创建 output/research-lifecycle/<slug>/ 目录骨架，提示可以直接进入 research-lifecycle。
6. 用 provenance-record 登记本次初始化（paths 为创建的目录清单，note 为 "workspace init"）。

初始化是幂等的：重复运行 init 不产生任何破坏，只补齐缺失部分。

2 · check：结构体检清单

只读检查，输出体检报告：

1. 九个标准目录哪些缺失、哪些非空；
2. output/ 下所有 <skill>/<slug>/ 组合，各自的运行次数与 latest 是否同步（latest 内容与最新时间戳目录是否一致）；
3. data/ 的健康度：是否有文件在过去 7 天内被修改（违反只读原则的信号，用文件 mtime 判断）；
4. .openscience/provenance.jsonl 是否存在、最后一条记录的时间；
5. 发现的问题按"建议修复 / 需要用户决定"分类列出，不自动动手。

3 · 多项目共存

一个工作区可以同时进行多个研究项目（多个 slug）。规则：

1. 每个项目的产物严格隔离在各自的 <slug>/ 目录下，互不引用对方的时间戳目录；
2. stage.yaml 每个项目一份，放在 output/<slug>/stage.yaml（见 stage-gate），因此恢复进度时以项目为单位；
3. data/ 是项目间共享的：同一批原始数据可以服务多个研究问题，子目录按来源组织即可，不必按项目复制；
4. .openscience/provenance.jsonl 是全局唯一一份，各项目的记录通过 paths 中的 slug 路径区分。

输出模板

init 完成后：

## 工作区初始化完成

- 根目录：<path>
- 新建目录：…（列出，已存在的标 [已存在]）
- 元数据：.openscience/provenance.jsonl 已就绪
- 画像状态：完整 / 有 N 节 [填空]（建议先运行 cold-start-interview）

下一步：对 research-lifecycle 说出你的研究主题，或先运行 cold-start-interview。

check 完成后：

## 工作区体检报告（<date>）

- 目录结构：9/9 就绪（缺失：…）
- 产物目录：N 个项目，M 次运行；latest 同步正常 / 异常（列出）
- 原始数据：只读原则正常 / 发现 N 个近期修改的文件（列出，[待复核]）
- provenance：最后记录 <时间>
- 建议：…

本技能不做什么

• 不整理 output/ 以外的用户文件：桌面、下载文件夹里的历史文件是否迁入工作区由用户决定，本技能最多给出迁移建议清单。
• 不自动删除任何文件：包括"明显过期"的时间戳目录和"明显冗余"的副本（guardrail 第 8 条）。
• 不强制子目录结构：data/ 内部怎么组织是用户自由，本技能只管根目录九件套。
• 不做备份：工作区约定降低混乱风险，但不替代备份策略；提醒用户重要工作区应有独立备份（本技能不实现）。
• 不管理 Git：工作区是否纳入版本控制、哪些目录进 .gitignore（通常 data/ 与 output/ 的历史目录不进）由用户决定，本技能被问到时可以给建议但不代执行。

收尾与下一步

• init 后：引导用户运行 cold-start-interview（画像未完成时）或直接进入 research-lifecycle。
• check 发现问题时：逐项给出修复建议并等待用户选择；修复动作（建目录、同步 latest）经用户同意后执行，删除类动作一律只建议不执行。
• 向用户说明契约的日常收益："以后任何 skill 的产物都去 output/<skill>/<slug>/latest/ 找，历史版本在同名时间戳目录里，永远不用担心被覆盖。"