# 🧭 研究主线图 · dsh-trajectory

把研究目标、假设、实验、论文阅读和写作组织成可追溯的项目记录。在 DSH 对话中推进工作，在清单和 DAG 中查看主线、分支、关键证据与阻塞点。

可以独立使用。安装学者工作台后可打开关联论文和 Idea；安装服务器看板后可观察已绑定实验的训练进度。

## 项目、目标与假设

每个项目可以记录研究问题、目标、假设及其状态。目标发生变化时保留演变记录；假设可以标记为活跃、已验证、已证伪、已替代或搁置。节点可关联假设，帮助区分哪些工作正在为哪条判断提供证据。

主线图按 DSH 工作区定位：优先使用显式项目 ID，其次匹配工作区；会话处于子目录时可按最长已绑定路径前缀匹配。需要项目归属的写操作在缺少工作区和项目 ID 时拒绝执行，避免误写到其他项目。

项目数据集中保存在插件数据目录，工作区绑定并不意味着文件写入各个工作区。

## 清单、DAG 与实验台账

- **清单视图**：研究问题、主线里程碑、分支工作、状态统计和实验台账，适合日常推进与组会整理。
- **DAG 视图**：节点包括里程碑、Idea、实验、论文、写作和其他事项；边表示推进条件、产出输入或组成关系。
- **主线管理**：调整关键节点及顺序，保留主线之外的分支；新增关系会检查端点、重复、自环和成环。
- **实验台账**：按节点记录日期、做了什么、关键数据、结构化指标、基线差值和结论，支持查看和删除条目。
- **状态流转**：待办、进行中、阻塞、完成、搁置。完成状态与研究结论需要由用户或对话工具明确维护。

图中的进度表示项目记录的状态；服务器上的进程存在、日志变化或进度百分比，不自动构成实验有效或假设成立的证据。

## 跨插件引用与进度

编辑节点时可以按名称查找论文、Idea 和服务器，实际保存稳定 ID，并保留显示名称。点击论文或卡片引用可打开学者工作台并定位。

服务器选择预览读取已有缓存，展示主机、GPU、日志和采样信息。实验进度需要日志路径或命令特征，主机 ID 用于限制匹配范围；**只选择一台主机不足以识别具体实验**。

面板开启且存在实验绑定时轮询看板快照。进度优先从原始日志的 `cur/total` 提取，无法计算百分比时显示已有 epoch 或进度信息。路径匹配保留大小写；多项匹配有歧义时不随意选择第一项。看板缺席或连接不可用时，仍可维护项目与台账。

## 开始使用

1. 在 DSH 中打开对应工作区，安装插件并完整重启宿主。
2. 新建或绑定项目，写下当前研究问题。
3. 添加目标和假设，将计划拆成主线节点与分支。
4. 实验节点关联论文、Idea 或服务器日志。
5. 每次实验后追加数据和结论，定期用清单或研究复盘整理下一步。

对话示例：

> 为当前工作区建立研究主线，研究问题是“这个改动能否稳定改善小目标检测”。
>
> 把方案拆成基线复现、方法验证、消融和论文整理几个节点，标出依赖关系。
>
> 把这轮实验的数据和结论记到对应节点，保留负结果。
>
> 复盘当前目标和假设，列出缺少的证据与下一步。

插件会向宿主对话注入当前项目的未完成摘要，并提供工具维护记录。主线图本身不另行调用模型；被注入的摘要和工具结果会进入宿主对话模型上下文。

## 编辑与数据保护

- 标题、详情、标签、主线状态、父节点及所有关联字段均计入未保存草稿。
- 关闭按钮、遮罩和 Escape 共用草稿保护；保存中不能直接关闭。
- 当前页面会话内按项目和节点保留有界草稿缓存；刷新或退出页面后不承诺恢复。
- 节点与主线调整一次原子落盘，写入失败不污染内存中的项目状态。
- 存储写操作串行化，损坏文件隔离并报告，已删除项目的在途写入不会重新创建项目。
- 删除项目会删除其节点、边和台账；项目删除工具要求显式确认。重要记录应备份整个数据目录。

## 安装与更新

[GitHub Release v0.3.0](https://github.com/smilewhenever777/dsh-scholar/releases/tag/v0.3.0) 提供预构建包和校验文件。GitHub 发布与 npm 发布相互独立；本次没有发布 npm 版本。使用源码安装时可先在仓库根目录执行 `git checkout v0.3.0` 固定版本。

npm 已发布版本：

```sh
dsh plugin --profile web add dsh-trajectory
```

当前源码，在仓库根目录执行：

```sh
npm ci --prefix dsh-trajectory
npm run build --prefix dsh-trajectory
dsh plugin --profile web add ./dsh-trajectory
```

完整重启 DSH 宿主并重新加载页面。源码更新不等于 npm 已发布版本更新，见 [更新记录](./CHANGELOG.md)。

部分宿主版本不能正确注册含空格的本地路径。优先使用无空格路径；必要时校正 profile `package.json` 中 `dsh-trajectory` 的 `link:` 路径及 `dsh.profile.bundles`，在 profile 目录运行 `pnpm install`。路径使用正斜杠，并确认链接指向插件子目录。

## 数据与隐私

默认目录为 `<DSH_HOME>/trajectory`；未设置 DSH_HOME 时使用 `~/.dsh/trajectory`，可在设置中修改 `dataDir`。

`projects/<id>.json` 保存项目及节点、边、目标、假设等记录，`meta.json` 保存项目管理信息。默认容量上限为 20 个项目，每项目 500 个节点、1500 条边。

`/traj/*` 路由限制本机访问并校验来源。插件没有独立遥测；跨插件进度从本机服务器看板获取。研究摘要进入对话后是否传到云端，由宿主的模型 provider 决定。

## 对话工具（14 个）

| 工具 | 作用 |
|---|---|
| `traj_review` | 复盘项目目标、假设、证据和进展 |
| `traj_goal_set` | 设置研究目标 |
| `traj_hypothesis_add` / `traj_hypothesis_update` | 新增和更新假设 |
| `traj_overview` | 读取项目全景、计数及可获得的实验进度 |
| `traj_project_set` / `traj_project_delete` | 创建或更新项目 / 确认后删除项目 |
| `traj_node_add` / `traj_node_update` / `traj_node_remove` | 新增、更新和删除节点 |
| `traj_entry_add` | 追加实验台账 |
| `traj_link_add` / `traj_link_remove` | 增删关系边 |
| `traj_mainline_set` | 调整主线及顺序 |

工具按会话工作区解析项目；部分创建操作可自动建立绑定。推荐先读取全景，再提交有明确归属的修改。

## 开发接口

| 路由 | 作用 |
|---|---|
| `/traj/overview`、`/traj/stats` | 项目全景与统计 |
| `/traj/config` | 数据目录配置 |
| `/traj/projects` 及 `/:id` | 项目列表、创建、读取、更新和删除 |
| `/traj/projects/:id/active` | 设置活跃项目 |
| `/traj/goals` | 目标读取和设置 |
| `/traj/hypotheses` 及 `/:id` | 假设读取、创建和更新 |
| `/traj/nodes` 及 `/:id` | 节点管理 |
| `/traj/nodes/:id/entries/:eid` | 删除一条实验台账 |
| `/traj/edges` 及 `/:id` | 关系管理 |

项目归属、字段校验和错误语义以 `src/routes.ts` 为准；存储见 `src/store.ts`，对话工具见 `src/tools.ts`，上下文注入见 `src/prompt.ts`。

## 开发与许可证

在插件目录运行 `npm run build`、`npm run smoke`。`npm pack` 会先构建，包含客户端类型检查。

[测试说明](../tests/README.md) · [技术设计](./DESIGN.md) · [更新记录](./CHANGELOG.md) · [MIT 许可证](./LICENSE)