research-project

# 研究项目的建立、接管与维护 一个 research project 跨越几个月、几十次实验循环、多次 agent 会话。 **Agent 没有跨会话记忆，人也会忘。**没有单一事实源时，每次接手都要重新考古： 当初为什么选这个题？这个实验为什么失败的？下一步本来打算做什么？ 这个 skill 建立并维护那个事实源。核心约定只有一条： > **`PROJECT.md` 是唯一入口。接手任何项目，先读它；做完任何一轮工作，回写它。** ## 三条不可越过的红线 接管别人的项目时，你面对的是一个**你不了解、但对用户很重要**的工作区。 1. **不删除任何东西。** 这个 skill 的工具里根本没有删除操作。 判断没用的东西移进 `archive/`，附上理由，随时可以移回来。 你对"这个文件没用"的判断有可能是错的，而代价不对称。 2. **没得到明确同意前不移动任何文件。** 先探查、先汇报、先问。 用户可能正在跑依赖当前路径的脚本。 3. **保证可回滚。** 动手前先让工作区进入 git 干净状态； 迁移工具默认 dry-run，执行后生成撤销脚本。 ## 工具 ```bash SK=<这个 skill 的目录> # 新建项目 python3 $SK/scripts/init_project.py <path> --name "<一句话主题>" \ [--deadline 2026-11-14] [--venue "CVPR 2027"] [--force] # 探查一个陌生项目（只读，不改动任何文件） python3 $SK/scripts/explore_project.py <path> [--json] [--stale-days 60] # 执行用户已确认的整理方案（默认 dry-run，--apply 才动手；只移动和归档，无删除） python3 $SK/scripts/migrate.py <path> --plan plan.json [--apply] # 审计（初始化与否都能跑） python3 $SK/scripts/project_status.py <path> [--json] ``` `init_project.py` 是幂等的——已存在的文件默认跳过并列出来。 `--force` 会重置模板，但**不会直接覆盖**：原件先移进 `archive/<日期>/` 并记进 `archive/MANIFEST.md`，再写新模板。 **投稿排期归这个 skill 管。** 用户给出截稿日期时，直接生成带真实日期的时间表， 不要在对话里复述节奏：`--deadline` 会按方法论的四周节奏写出 `docs/writing/schedule.md`（每行具体日期 + 勾选框），之后 `project_status.py` 持续对照倒计时与章节进度。写作本身怎么做是 `paper-writing` 的事。 ## project_status.py 检查什么 它不只是列文件，它执行方法论里的判据： | 它检查什么 | 为什么这条值得自动检查 | |---|---| | 选题落在四种情况的哪一种 | 情况 1/2 = 已有 well-established solution。这时候继续往下做是纯浪费，越早停损越好，所以报 **阻塞** 而不是警告 | | PROJECT.md 多久没更新 | >14 天意味着接手者会拿到过期状态，比没有状态更危险 | | 距截稿天数 vs 章节进度 | 方法论要求截稿前一个月启动写作。倒计时进入 30 天而章节全空 → 阻塞 | | 实验日志里有多少条没写"本质技术原因" | 这些循环没拿到梯度，下一次改动是随机的。这是**项目速度的头号杀手**，比实验做得慢更致命 | | 最近一条实验记录距今多久 | >7 天说明循环频率掉了，要找原因 | | §6 下一步是否为空 | 没有明确下一个动作的项目会静默停摆 | ## 走哪条流程 | 情况 | 流程 | |---|---| | 全新项目 | **流程 A**（下面，一条命令 + 填 §1 §2） | | 已有的乱项目，用户要整理 | **流程 B**：五阶段多轮对话，全文见 [references/takeover.md](references/takeover.md) | | 项目已是这套结构 | **Agent 交接协议**（下面） | | 用户想干别的活、项目恰好很乱 | 先把活干了，收尾时提一句可以整理，**不要中途自作主张搬文件** | 最后一行是刻意的：整理是一件需要用户投入注意力的事， 挑他没准备好的时候做只会添乱。 ### 流程 A：新建项目 ```bash python3 $SK/scripts/init_project.py ~/work/sparse4d \ --name "稀疏视角下的动态场景重建" --deadline 2026-11-14 --venue "CVPR 2027" ``` 然后**先只填 PROJECT.md 的 §1 和 §2**，配合 `research-ideation`。 §2 的"四种情况判定"是闸门：判定为情况 1 或 2 就停下来换 failure case， 不要开始写代码。这一步花半天，能省掉半年。判定完跑一次 `project_status.py` 确认没有阻塞项，再进 §3。 ### 流程 B：接管一个已有的乱项目 用户丢过来的是一个跑了几个月、**不是按这套结构建立的**文件夹。 **这是多轮对话，不是一条命令**——五个阶段，每个阶段结束都停下来等用户： ``` 1 探查（只读，一个文件都不动） → explore_project.py 2 汇报画像，问要不要整理 → 先证明你看懂了，再提整理；给 A/B/C 三档 3 拟迁移方案，逐条对齐（多轮） → migrate.py dry-run，用户几乎一定会改几条 4 执行，然后补骨架 → migrate.py --apply，再 init_project.py 补空缺 5 考古式回填 PROJECT.md → 找不到的留空，留空比编造好 ``` **开始阶段 1 之前先读 [references/takeover.md](references/takeover.md)**： 每个阶段的话术、迁移方案的 `to` 语义、`--apply` 的安全保证、`archive/` 的约定都在那里。 有两处顺序陷阱不看会踩：**先迁移再建骨架**（反了的话用户真实的 `notes.md` 就迁不进 `docs/topic.md`），以及动手前先让 git 进入干净状态。 ## 文件格式 目录结构、`PROJECT.md` 六节各自何时回写、实验日志一条记录的合格标准 （含一个不合格→合格的改写实例）：[references/files.md](references/files.md)。 需要建目录、回写 PROJECT.md、或判断一条实验记录合不合格时读它。 其中一条判据值得先知道：**实验日志的目的不是记录做了什么，是记录拿到了什么梯度**—— 只写到"表面原因"就停的记录不合格，`project_status.py` 会报警。 ## Agent 交接协议 **项目已经是这套结构时：** 1. `project_status.py <path>` —— 30 秒拿到全局状态和阻塞项 2. 读 `PROJECT.md` —— 完整上下文 3. 只在需要时按 §6 的下一步深入对应的 `docs/` 或 `experiments/` 4. 干完活**回写 §4/§5/§6 和"最后更新"日期**，再结束会话 不要在没读 PROJECT.md 的情况下就开始改代码或写论文—— 你会重复项目已经排除过的路径，这正是实验日志存在的意义。 **项目不是这套结构时：**走流程 B，从 `explore_project.py` 开始， 先看懂、再汇报、再问、再动。 ## 与其他 skill 的关系 这个 skill 管**状态与结构**，具体每一步怎么做在别处： | PROJECT.md 的节 | 卡住时读哪个 skill | |---|---| | §2 选题状态 | `research-ideation` | | §3 技术方案 | `research-ideation` | | §4 实验状态 | `research-experiment` | | §5 论文状态 | `paper-writing` → `paper-revision` → `paper-self-review` | | `docs/literature/` | `research-ideation/references/literature-tree.md`；检索用 `literature-review`，读论文用 `pdf-explore` | | `paper/figures/` | `figure-style` → `figure-composer` → `paper-narrative` | 整体流程图见 `research-methodology`。