CapSci 科研工作台：设计原则与操作介绍（v2）

状态：界面设计稿，尚未实现。更新日期：2026-10-20。 设计约束见 DESIGN.md 与 FRONTEND_DESIGN.md。 截图中的结构图由 ASE 与 3Dmol.js（py3Dmol）实际生成，曲线由 matplotlib 实际绘制；能量、受力等数值是样例数据，见第 5 节。

1. CapSci 是什么

CapSci 是研究员做材料计算的桌面 Agent。它的使用方式和 Claude Code、Codex 这类 Agent 一样：从对话开始，过程在对话里推进。区别在于它只调用人工批准过的计算能力，参数来源、批准和演示标记都会明确展示。

一次完整的计算是这样的：你用一句话描述目标，CapSci 从已批准的能力里匹配固定流程，在对话里向你确认几个关键值，你批准后开始计算，运行进度和结果都回到同一段对话里；需要细看的内容在右侧窗格打开。

2. 设计原则

2.1 对话主导

• 每个任务都从对话开始，也在对话里结束。匹配能力、补参、批准、运行、结果、失败，都按时间顺序出现在同一段对话里。
• 固定流程（Skill）的执行也放在对话里，以"运行块"的形式出现，不再是一个单独的页面。
• 对话以外只保留两个入口：右侧窗格（看细节）和能力管理（管流程），见 2.6。

2.2 分区原则：对话讲过程，右侧放对象

所有篇幅大的内容都定义成有编号的对象：运行、结构、计算方法、计算单、流程、文件、运行依据。

判断规则：

• 必须在对话里： 需要你决定的事。不能只放在右侧，否则流程卡住而你看不到。
• 放到右侧： 内容超过半屏、需要多次交互，或者会持续更新。

2.3 决策原则：决策留在对话，细节放右侧

标准是：一个人只看对话、不打开右侧，也能安全地做出这个决定。右侧是用来深入核对的，不是必经之路。

配套规则：

1. 会改变决定的信息（缺失值、警告、演示标记、未确认的来源）必须出现在对话里。
2. 按钮只有一套状态：右侧计算单底部的"开始计算"和对话里的是同一个操作。
3. 做完决定，卡片收成一行记录，可以重新展开。
4. 等待中的决定要看得见：输入框上方显示"等你确认 N 项"，左侧会话也显示，按 Enter 确认当前项。
5. 对话里出现新的待决定事项时，右侧不自动跳转，避免打断你正在看的内容。

2.4 对象与组件

• 每个对象有一个组件、两种尺寸：对话里的紧凑版（静态快照），右侧的完整版（可交互）。
• 对话里的摘要卡点击后在右侧打开对应对象，以标签页呈现；同一对象只开一个标签。
• 右侧窗格平时收起；运行开始时自动打开一次运行对象，之后是否自动打开按你的习惯记住；窄屏上右侧变成全屏的上层页面。

2.5 图样实现原则

• 图表和结构图由运行数据渲染，不由模型生成。 Agent 只输出"对象引用"，前端用 Runtime 的事件和产物来画，数字一定来自真实运行结果。
• 结构： 用 3Dmol.js 渲染（Python 端的 py3Dmol 用的就是它），输入是工具产出的 POSCAR/CIF。右侧完整版可旋转、换样式、对比初始结构；对话里放同一视角的静态快照。
• 曲线： 对话里的趋势线和快照由后端 matplotlib 生成静态图；右侧完整版可以用同样的数据接入可交互的图表库（例如 Plotly）。
• 实时内容只保留一个实例： 对话里显示快照和一行实时状态，右侧只放一个实时刷新的视图，避免长对话里多个 3D 实例和频繁重绘。

2.6 流程编排的三层

Agent 在对话里最多可以起草流程草案并提交审核；草案在扫描目录之外暂存，批准前不会被导入或执行；"批准并启用"只在能力管理里出现。

2.7 可信原则

• 参数来源标记在所有地方一致：● 你提供或确认，○ 从对话提取、待确认，— 流程或工具默认。
• 演示标记是灰色斜线，结果、文件、导出都保留。
• 失败即停： 任一步失败就停止，只有已批准的有限重试，不会自动换方法。
• 运行依据随结果保存：能力版本、批准人、提示词版本、模型、执行环境。

3. 界面结构

4. 操作案例：Ni–Mo 的 SQS 生成与结构弛豫

4.1 首次启动与项目（沿用简图）

1. 启动后本地服务自动运行；选择工作目录；连接模型（只验证连通，不代表科学能力）；给第一个项目起名，也可以用"默认项目"。计算软件不在这里配置，第一次用到时在对话里配。

2. 项目只用来组织会话和文件，不影响能力选择和参数。新建项目只需要名称，文件夹自动生成。

4.2 描述目标，在对话里完成简单确认

3. 输入"生成 Ni₀.₈₇₅Mo₀.₁₂₅ 的 FCC SQS，并进行结构弛豫"。对话里出现两行工具调用：读取能力目录、匹配能力，选定 sqs_vasp_relax。
4. 两个简单决定直接在对话里完成：组分是原子分数还是质量分数（两个按钮），以及初始晶格常数 a₀（一个输入框）。也可以直接用一句话回复。此时右侧窗格是收起的。

4.3 复杂补参：右侧打开完整计算方法

5. 点"查看完整计算方法（7 项）"，右侧打开表单，按流程步骤分组，每项带来源标记。
6. 对话里只保留待确认的一项（主元素 Ni，从描述中提取）。在右侧或对话里确认都行，两边同步。

4.4 批准开始计算

7. 本机还没配过 VASP 时，CapSci 会在对话里列出自动检测到的 vasp_std，点一下即可使用，配置结果留在对话里成为一行记录。
8. 批准卡列出：流程与版本、你定的值、默认值、提醒、环境、演示性质、预计时长。按 Enter 或点"开始计算"；右侧同时打开完整计算单，底部按钮是同一个操作。

4.5 运行中

9. 对话里是运行摘要卡：当前步骤、离子步、最大受力、已用时间，加一条受力趋势线。
10. 右侧自动打开一次运行对象：收敛曲线每个离子步刷新，步骤列表、OSZICAR 末尾。"停止生成回复"和"取消运行"是两个操作，取消需要再确认。

4.6 结果

11. 对话里是一句结论和结果摘要卡（结构缩略图、每原子能量、晶格常数、最大受力），带演示标记，下面是后续操作。
12. 右侧打开 3D 结构：旋转、缩放、换样式、对比初始结构，下方是结果表和文件。

4.7 失败

13. 失败卡说明在哪一步、因为什么停下、有限重试用到哪里、错误码和诊断编号，以及"不会自动换方法"。
14. 右侧是诊断：电子步 |ΔE| 曲线（两次重试都在 1e-4 附近振荡）、重试记录、OSZICAR 末尾、保留的中间文件。点"修改参数，新建任务"回到补参。

4.8 查看流程编排

15. 在对话里问"这个流程是怎么编排的"，或点运行块的"查看编排"，右侧以只读方式打开：输入值、每一步调用的工具、参数如何从上一步传过来、本次运行在每步的状态、运行规则。

4.9 能力管理：审核 Agent 起草的流程

16. 研究员在对话里说"先只算静态能量看看"，Agent 起草了 sqs_vasp_static 并提交审核。批准人在能力管理里看到 manifest 差异和审核清单：两项自动检查已通过，四项人工审核勾完前"批准并启用"不可用。批准后从下一个任务起生效。

4.10 计算环境（设置）

17. 设置里的计算环境是统一的"软件与资源"列表，字段由能力声明。通常不用专门来配：缺什么会在对话里提示，就地补上。

5. 图样是怎么做出来的

截图里的科学图样都是用真实的库生成的，脚本和产物在 figures/：

说明：

• 4 个 Mo 位点是按"彼此最远"选的，用来代替 SQS 候选，不是真正的 SQS 优化结果，与当前 sqs_generate 是演示实现的状态一致。
• 能量、受力、自洽迭代数据是样例数据，用来展示界面在真实数据下的样子。
• 重新生成：在装有 ase matplotlib py3Dmol 的环境里运行 python gen.py，再运行 python render3d.py，用 Chrome 打开生成的 HTML 截图。

6. 与当前实现的差距

• sqs_generate、jmatpro_creep、ml_predicted 是演示实现，两个固定流程的结果只能是演示结果；
• 还没有桌面应用、HTTP 接口、项目、任务持久化和事件推送；
• 消息协议需要支持结构化部件（文字、工具调用、对象引用、批准请求），对象需要服务端的编号和事件流；
• 工具 JSON 尚未声明环境需求，VASP 直接读取环境变量；
• Resolve 尚未输出选型理由，运行结果尚未携带执行性质标记；
• 能力管理（草案、审核、审批记录）尚未实现。

7. 截图清单