Research Timeline 机器使用指南

更新日期：2026-10-26。本文说明当前研究门户的接口用法、专家材料提交与学习作答边界。

1. 入口与权限

所有路径均相对门户所在站点：https://aisb.98.142.241.90.sslip.io。

• 研究接口：当前读取、创建、回答、确认、选择关键节点和刷新无需访问密钥。写入请求携带 Origin 时须与站点同源；这不是身份认证，也不提供私人记录隔离。不要修改他人研究记录或上传私人材料。
• 专家采集：默认无密钥可审阅、编辑题目；论文材料提交需要专家提供的本主题专属凭据，详见第9节。无需密钥不等于可自行接受论文提交或发布题目。
• 学习作答：无需访问密钥，但只可从已发布主题创建会话，详见第10节。
• 管理员操作：不属于本文接口契约，不公开管理入口、服务配置或认证材料。

下文研究写入示例使用 JSON 请求体和 Content-Type: application/json，无需添加认证头。浏览器应使用同源接口；不要依赖跨站写入。创建、确认、扩展、刷新或构建可能启动检索与模型调用，先确认使用者授权和费用范围。不要自动重发不确定是否成功的写入请求；目前没有这些研究写入接口的幂等保证。

2. 读取接口

表中 {id} 必须替换为列表返回的真实编号；卷宗编号与时间线编号不可混用。200 还应结合响应类型与内容判断，不能把网页回退响应当成接口成功。

3. 先读取，再决定是否创建

阅读材料时先检查来源的 metadata.savedArtifactAvailable、metadata.savedTextAvailable 和 metadata.sourceContent.kind。正文存在时读取上述原件或文本接口，不用 excerpt 代替全文。metadata_fallback 是题录，abstract_page 是摘要页；网页抓取也可能只是出版社摘要页，不能据此声称取得完整论文。rawArtifactPath 是内部附件位置，不是可直接打开的网址。最近抓取失败原因见 metadata.lastAccessAttempt，保留的旧文件仍可阅读。

上述可用标记只说明文件存在，不能证明内容合格。读取后检查是否为验证码、登录、错误页或只有摘要；这些内容不能用于支持论文结论。节点和观点的来源编号也需核对题名、正文与具体表述，历史记录存在引用错配的情况；无法支持时明确记录缺口，不自行补造关系。

较大的时间线详情可能超过数兆字节。先保存完整响应，再在本地选择研究范围、所需分支、节点和来源字段；不要将整个响应直接放入模型上下文，也不要把终端截断当成服务器返回了完整内容。当前未提供详情分页或字段裁剪接口。branches、relations 为空时可另读研究分析中的路线归属，但绘图连线不代表有证据的引用、因果或继承关系。

以下命令用于支持 shell 语法的终端；导出示例另使用 jq。这些命令只读取资料。

SITE='https://aisb.98.142.241.90.sslip.io'
curl --fail-with-body --silent --show-error "$SITE/api/research-timelines"
curl --fail-with-body --silent --show-error "$SITE/api/dossier-sessions"
curl --fail-with-body --silent --show-error "$SITE/api/research-timelines/providers"

时间线列表元素含 id、title、question、status、updatedAt、nodeCount、sourceCount、version。详情包含 timeline 和 runtime：

• timeline：研究范围 questionContract、节点 nodes、来源 sources、观点 claims、关系、覆盖缺口 coverage 和版本 version。
• runtime：status、phase、active、error、events、候选节点 candidateWorkIds 与推荐节点 recommendedCandidateWorkIds。
• 引用应保留已有来源编号和公开链接。列表摘要、检索命中、成功读取正文、取得评论是不同状态，不能互相代替；未取得证据时保留缺口。

4. 创建问题卷宗

智能体统一使用 POST /api/dossier-sessions/agent；普通网页仍使用 POST /api/dossier-sessions。返回201与会话对象。message 或 question 至少12个字符；language 可为 zh 或 en。创建后会异步澄清，不应立即重复创建。

{
  "message": "检索增强生成如何减少科学问答中的事实错误，哪些评价证据足以区分不同方法？",
  "language": "zh",
  "researchOptions": {
    "stageBudgetUsd": 1,
    "maxSearches": 5,
    "maxFetches": 5,
    "timeoutMinutes": 10,
    "enabledTools": ["openalex", "crossref", "arxiv"],
    "allowPaidSocialDetails": false
  }
}

researchOptions 控制本次检索设置。新会话默认不设费用上限；stageBudgetUsd: null 明确取消费用上限，正数则设置每阶段上限（上例为显式限额）。更新旧会话时省略该字段保留旧值，普通页面的继续、追加操作会提交 null，避免沿用历史默认限额；历史费用记录不变。卷宗转时间线时预算传入 discoveryMaxBudgetUsd 和 synthesisMaxBudgetUsd，两者同样支持 null；时间线接口省略字段保留已有配置。费用上限不是整个工作流统一的总额，空值也不代表调用免费；搜索次数、技术超时、失败保护和检索停机策略仍生效。

将请求体保存为 create-dossier.json 后提交：

curl --fail-with-body --silent --show-error \
  -H 'Content-Type: application/json' --data-binary @create-dossier.json \
  "$SITE/api/dossier-sessions/agent"

保存返回的 id，用 GET /api/dossier-sessions/{id} 轮询。建议间隔5秒，设置客户端最长等待时间；停止轮询不会取消服务端任务。关注 status、phase、jobRunning、pendingQuestions、questionContract、error、timelineId。

智能体每轮读取 GET /api/dossier-sessions/{id}/interaction。返回 action: ask_user 或 confirm_with_user 时，必须把 questions、选项描述和 questionContract 呈现给用户，然后停止工具循环，等待用户回答。用户可以多选、自行输入或组合研究方向。不能为了完成任务而模拟用户、选默认项、跳过后续问题或自动确认。

智能体会话的回答和确认都必须携带：本轮 interactionToken、presentedToUser: true 和 userReply（用户原话或真实选择）。接口的 replyFields 提供格式，示例占位文字必须替换。旧轮次返回409，缺少用户回答返回400。该声明记录交互经过，并不能验证外部智能体是否真的向人展示；调用方必须遵守等待约定。读取详情也会在 interaction 中返回同样的下一步。

回答：POST /api/dossier-sessions/{id}/answers，返回200。questionId 必须来自本轮问题；单选或多选值按问题实际选项填写。

{
  "interactionToken": "替换为本轮返回值",
  "presentedToUser": true,
  "userReply": "用户本轮实际回答",
  "answers": [
    { "questionId": "替换为本轮问题编号", "value": "限定科学问答中的事实正确性与证据可追溯性。" }
  ]
}

正常确认：在 awaiting_confirmation 时，向 POST /api/dossier-sessions/{id}/confirm 提交以下对象，返回200并开始检索。需要调整范围时可额外提交 contract，不可代替使用者虚构范围。

{ "approved": true, "interactionToken": "替换为本轮返回值", "presentedToUser": true, "userReply": "用户明确确认的原话" }

在 awaiting_input 时也可明确结束澄清：同一确认接口提交 approved: true、stopClarification: true 和 contract；其中须有 researchQuestion、researchObject 和非空 inScope。本轮未回答项保持未知，不应默认补全。智能体必须额外提交 userRequestedStop: true 及本轮交互字段，且确为用户明确要求提前结束，不能自行决定。

其他操作成功时返回200：

社交来源的列表检索也可能收费。allowPaidSocialDetails: false 仅禁止自动付费补取正文或评论，不表示所有检索免费。按工具目录的实际状态选择来源，不因配置存在就宣称正文或评论可取。

5. 创建和更新研究时间线

如果卷宗已经返回 timelineId，先读取该时间线，避免重复创建。直接创建仅供导入既有已确认范围的记录，不能代替新科研问题的逐轮澄清。直接创建使用 POST /api/research-timelines，返回201与 { timeline, runtime }；候选检索可能需要等待，超时后先查看列表是否已有记录。

{
  "title": "科学问答中的检索增强与事实核验",
  "questionContract": {
    "rawIntent": "理解检索增强生成如何减少事实错误。",
    "scopedQuestion": "在科学问答中，检索增强与事实核验分别通过哪些机制提高正确性？",
    "inScope": ["检索证据质量", "回答事实正确性", "公开可复现实验"],
    "outOfScope": ["没有科学问答证据的通用聊天体验"],
    "decisionChangingEvidence": ["检索质量控制下的对照实验"]
  },
  "timelineMode": "academic",
  "searchQueries": ["retrieval augmented generation scientific question answering factuality"],
  "limitPerProvider": 5
}

questionContract.scopedQuestion 或顶层 question 必须非空。timelineMode 支持 general、academic、ecosystem、product、social；省略时为 general。limitPerProvider 限制每次来源检索的候选数量，不是总调用次数或总费用限制。

选择关键节点：POST /api/research-timelines/{id}/anchors，返回200。

{
  "nodeIds": ["替换为已有节点一", "替换为已有节点二", "替换为已有节点三"],
  "run": false
}

必须选择3至7个不同的已有节点。这个数量是深入扩展的种子数，不是完整时间线显示材料数。run: false 只保存选择；省略或设为 true 会开始构建。应由使用者核对候选与推荐节点后选择，不要机械取前三项。

刷新内容：POST /api/research-timelines/{id}/refresh，请求体 {}，返回202。至少已有3个关键节点且没有正在构建的任务；刷新执行检索与综合。若明确只需重新综合，可提交：

{ "synthesisOnly": true }

只重新综合仍可能调用模型。用详情接口轮询 runtime.active、runtime.status、runtime.error、runtime.lastRefresh 和 timeline.version；202表示已接受，不是已经完成。不要假定每次刷新都会增加版本号：结构没有变化时版本号可能不变。

没有任意修改时间线的通用 PUT 或 PATCH 契约；“更新”在此指已有关键节点选择与刷新操作。

6. 导出、导入与上传版本的边界

导出当前时间线：先从列表取得编号，将下面的 TIMELINE_ID 替换为该编号。详情导出包含当前内容与运行状态，不等于完整版本仓库。

TIMELINE_ID='替换为时间线编号'
curl --fail-with-body --silent --show-error \
  "$SITE/api/research-timelines/$TIMELINE_ID" -o timeline-response.json
jq '.timeline' timeline-response.json > timeline.json
curl --fail-with-body --silent --show-error \
  "$SITE/api/research-timelines/$TIMELINE_ID/report" -o timeline-report.json
jq -r '.content' timeline-report.json > timeline-report.md

报告接口返回 { timelineId, filename, mediaType, generatedAt, content }，不能将整个 JSON 文件直接当作 Markdown。timeline.version 含 number、previousVersionId、changeSummary、createdAt；历史读取使用下面列出的版本接口。

卷宗导出：完成后使用以下读取接口；尚未生成的产物可能返回404。

由卷宗创建新时间线：创建接口接受 dossier 对象。可从卷宗导出生成请求体，经使用者同意后向 POST /api/research-timelines 提交该 JSON 对象：

DOSSIER_ID='替换为卷宗编号'
curl --fail-with-body --silent --show-error \
  "$SITE/api/dossier-sessions/$DOSSIER_ID/dossier" -o dossier.json
jq --arg question '在科学问答中，哪些证据支持检索增强降低事实错误？' \
  '{question: $question, dossier: .}' dossier.json > create-timeline.json

这会转换卷宗并创建新的时间线编号，通常进入 awaiting_anchor_selection，不是覆盖原时间线，也不是保持原历史的版本恢复。服务还可能自动计算科研时间线，不应将转换视作保证零费用。

上传已有时间线：结构示例见 时间线 JSON 示例。示例是字段说明，须换成用户实际材料，不能直接当作研究结果。

更新前先读取当前记录及版本列表，展示修改内容给使用者确认。下面的两个版本字段必须使用刚读取的实际值，不复制示例值：

{
  "baseVersion": 1,
  "baseUpdatedAt": "2026-10-25T00:00:00.000Z",
  "changeSummary": "补充一篇新论文及其与已有方法的关系。",
  "timeline": {
    "schemaVersion": "0.1",
    "title": "用实际题名替换，并在提交前补齐完整记录",
    "questionContract": {"scopedQuestion": "用用户确认的完整科研问题替换"},
    "sources": [],
    "nodes": [],
    "claims": [],
    "relations": []
  }
}

更新是完整记录替换，不是追加列表。须保留仍然有效的旧材料和关系；上面省略的数组不能直接提交以更新真实记录。收到409先重新读取，比较差异后由使用者决定，不能仅换版本号强制重发。同一时间线正在运行任务时也返回409。没有删除、强制覆盖、自动回滚或分支合并接口。

上传上限10 MiB，节点、来源和关系引用须一致。仅接收公开 HTTP(S) 来源，不接收本地文件路径、内部附件地址或凭据。上传内容保存为待核验候选，不把客户端填写的“已核验”当作专家结论。导入请求本身不调用模型或立即抓取网页；独立运行的后台任务会补取缺失的公开 arXiv 原文，并可能产生新版本。因此每次更新前须重新读取版本号和更新时间；发现自动补抓产生的变化时保留新增资料，不用先前副本覆盖。有需要时另行调用已说明的研究和时间线构建接口。

版本下载不包含服务器原始缓存或全文文件压缩包；已保存的论文附件从阅读资源入口取得。离线记录同步工具独立于这些公开接口，不用于普通用户在线操作。

7. 科研时间线与阅读资源

先读取分析与布局；只有使用者明确要求重新分析时才调用构建接口，不以构建操作探测可用性。

读取布局的示例路径为 /api/transit-maps/{id}?groupBy=route&w=1500&h=820。其他分组值应以实际门户支持为准。

原文优先从第2节的 source-file 接口取得：需要文字时请求 format=text，需要PDF或保存网页时请求 format=original。读取前核对第3节的文件状态，读取后核对实际内容。

部分旧案例另有逐页产物 /api/artifacts/{id}/artifacts/full-papers/manifest.json，可按清单读取分页图片和PDF。旧清单返回404不代表新的 source-file 原文不可用。两种途径都没有正文时，可读取已有摘要和来源链接，但须明确没有读到完整论文。

8. 错误处理与停止条件

读取失败时同时检查响应类型。未知错误可能只包含 error，也可能带 message；不要依赖只有一种错误对象。完成状态、版本号和健康检查都不是研究结论成立的证明，引用仍须回到实际来源与证据。

9. 专家题目审阅与论文材料提交

请优先阅读现有专家材料提交与学习作答指南。这是实际指南正文地址；其中的 /api 在本门户应替换为 /api/annotation/collection，保留后续路径。不要使用文件名猜测其他指南地址。

专家入口为 专家采集页面。无密钥默认提供题目审阅与编辑，不代表拥有论文选择、接受智能体提交或发布主题的权限。审阅内容与学习材料必须分开使用。

以下两个接口要求专家提供的本主题专属 x-submission-token 请求头；不要把凭据放在网址、公开文件、论文或检索请求中。

提交结构以已有指南为准。requestId 必须非空，同一次重试沿用原编号；新改稿使用新编号。每次最多补充60篇候选、建议选择20篇。selectedIds 必须来自真实候选编号，不猜编号；knowledge 只填专家口述或明确确认内容。

提交仅保存为待专家确认，不代表论文被接受、题目已审核或内容已发布。无密钥不能自动选论文或接受提交；智能体提交凭据也不授予自动审核和发布权限。

旧材料标注入口如需使用，应访问 /api/annotation/ 并使用本人获发的个人访问码；它与本节采集接口及学习会话不同，不使用 /annotation/ 作为入口。

10. 免密钥学习与智能体作答

学习入口不需要访问密钥。先读取 GET /api/annotation/collection/topics；普通学习列表只包含已发布主题。空列表表示当前没有可开始的主题，不应使用题目审阅列表绕过发布要求。

创建：POST /api/annotation/collection/sessions，返回201。此操作会保存一条真实作答记录，不要用于健康检查。

{
  "topicId": "替换为已发布主题编号",
  "actor": "agent",
  "familiarity": 0
}

actor 对智能体应填写 agent；familiarity 为0至4。保存返回的会话 id，不要公开或枚举他人的会话编号。

answers 是以字符串 "1" 至 "8" 为键的对象，每项填写自己作答选择的 A、B、C 或 D，必须完成八题；confidence 按题号记录自己的信心，toolsUsed 如实说明所用工具。不要复制一套示例选项当作真实作答。成功提交返回200并进入 done；同一会话重复提交不会覆盖第一次答案，新建会话会独立计数。会话保存的题目版本不随专家之后修改而改变。

答案使用边界：学习会话不返回标准答案与专家误区，但当前匿名题目审阅入口可以读取答案，也允许题目编辑。因此，这个采集与试测入口不能宣称具备正式实验的答案权限隔离。学习与作答不得访问审阅答案、专家导出或其他答案资料，并且不能将它们混入学习材料。标准答案不属于学习来源。

11. 研究者两轮实验

入口：学习与答题。选择实验组与科研问题，完成首轮八题、20篇论文提交、学习口述和第二轮八题。前后成绩在第二轮提交后一起显示；题目与论文标准按开始时版本冻结，后续专家修改不会改变正在作答的记录。草稿题目明确标为试测，未确认论文标准的成绩需专家核对。

通过 GET /api/annotation/collection/experiments/topics 取得可用主题，POST /api/annotation/collection/experiments 创建本人的实验记录。三组分别为 deep_survey、ai、timeline_ai。同一IP只默认上次实验组；浏览器恢复仅使用自己的会话编号，不会按IP恢复别人的作答。

智能体代交时，读取会话的 /api/annotation/collection/experiments/{id}/agent-guide，再通过 /papers 提交论文清单。研究者论文、学习口述和专家标准清单分开保存，不触发专家题目生成。不要泄漏会话编号，不访问审阅答案，不替参与者作答或编造口述。现有专家提交接口继续服务于标准材料收集，与此入口分开。

12. 从材料开始

页面：/research.html?view=explore。可用 tab=paper、scholar、repo、post 直接打开指定入口。

公开接口前缀是 /api/research-maps/explore。探索结果独立于问题卷宗和专家标注；创建会调用检索和模型服务。

论文创建请求：{"kind":"paper","input":"1706.03762"}，也接受题名、DOI或链接。

仓库创建请求：{"kind":"repo","input":"txie-93/cdvae"}，也接受GitHub链接。

学者创建请求：{"kind":"scholar","authorIds":["从候选取得的作者编号"]}，或用 scholarUrl 提供Google Scholar主页。主页受限时先搜索作者并核对身份。

帖子创建请求：{"url":"https://公开帖子地址","text":"可选的正文"}。按返回的 session 阶段，通过 post/{id}/question、answers、confirm 提交用户选择与确认；不要代替用户猜测研究范围。

每3—5秒读取进度即可；断线先读取原任务，避免重复创建。相同输入会复用已完成或仍运行的记录；用户明确要求重做时可在创建请求加 force:true。只有 job.status=done 且 result 存在才表示整理完成；来源失败或未读全文会保留读取状态。

13. 时间线出题与研究解读

独立出题页为 /research.html?view=questions&id={timelineId}。POST /api/annotation/collection/timelines/{timelineId}/questions，请求体为 {}，只使用本服务器已保存的时间线。返回 topicId、status、questionCount、job。读取 /api/annotation/collection/topics/{topicId} 的 jobs.generate 查看进度。已有题目和专家修改保留，只补缺题；新题均为待审核草稿，不自动成为实验标准答案。已有题需要改动时，在题目审核页填写修改意见。前五题面向领域基础、机制、方向、方法差异及适用条件，后三题面向进展、局限及后续验证。

研究解读独立于时间线构建，可在生成时间线后按需调用：

• GET /api/research-maps/{timelineId}/reading：读取全部研究路线的解读状态。
• 在上述路径增加 ?route={routeId}：读取指定路线的解读。路线编号从时间线分析中的 routes 取得。
• POST 同一路径、请求体 {}：开始生成，已有有效结果可复用。明确要求重新生成时使用 {"force":true}。

状态为 idle、running、ready、stale、blocked 或 error。每3—5秒读取一次；仅在 ready 时使用 result。结果的 progress、limitations、directions 分别为进展对比、局限和待验证方向，每段含 text 及 itemIds。引用编号对应原时间线阅读材料，前端可直接打开单篇阅读；原始出处继续在时间线中查阅。

basis 说明实际使用的材料范围。解读依据已有摘要、来源摘录及研究记录，未重新检索或核验全部原文；待验证方向是研究建议。材料或版本变化后缓存失效，不把旧解读套到新版本。生成失败可手动重试，网络断线应先读取原任务状态。

basis.progress 与 basis.frontier 分别列出进展对比、局限与待验证方向使用的材料、日期、选择理由、使用数量和遗漏范围。前者兼顾重要性、历史及研究分支；后者兼顾近期、关键工作和分歧证据。二者均是抽样，模型阅读的是限长片段，不代表读过全库、完整摘要或全文。各段引用须属于其对应组选材。

两项解读分别生成，各自只接收本组选材；全部通过引用与结构校验后返回完整结果。等待期间可以关闭页面再恢复读取。

14. 检索当前时间线与连续问答

无需先生成解读。GET /api/research-maps/{timelineId}/search?q={编码后的检索词}&limit=10&offset=0 检索整条时间线，包括论文、代码仓库和其他来源，返回匹配材料及命中片段。每页最多20项。通过返回的 materialUrl 或 GET /api/research-maps/{timelineId}/materials/{编码后的材料编号}?offset=0&limit=16000 分页读取已存内容，保留来源类型和实际读取范围；不要把摘要或模型概括当原文。外部智能体可以直接使用这两个只读接口。

需要本站问答时：

1. POST /api/research-maps/{timelineId}/qa，请求体 {}，返回 sessionId 和 token。仅保存到自己的会话，不公开令牌。
2. POST /api/research-maps/{timelineId}/qa/{sessionId}/messages，请求头 x-timeline-qa-token: {token}，请求体 {"requestId":"本次唯一编号","message":"自己的问题"}。
3. 每3—5秒 GET /api/research-maps/{timelineId}/qa/{sessionId}，带同一请求头，直到状态为 ready、error 或 interrupted。回答在 messages 中，逐段 materialIds 和 citations 可追溯材料。

提交断线后先读取原会话；相同请求编号不会重复调用模型。错误恢复须由用户明确再次提问，使用新的请求编号。问答检索全部已存材料，并依据本轮命中片段回答；不会访问其他时间线、主动下载缺失全文或搜索外网。材料更新导致当前回答失效时重新提问。未找到依据只表示本次检索未获得支持，不代表外部研究不存在。

15. 合并路线与按主题重新分组

分组保存为独立视图，原时间线、材料和重点评分不变。读取 GET /api/research-maps/{id}/groupings，取得 revision、fingerprint、originalGroups、materialCount 和已有 views。写入都带唯一 requestId、baseRevision、baseFingerprint，使用刚读取的值。

• 合并：POST /api/research-maps/{id}/groupings/merge，再带 routeIds（至少两个不同的已有分组编号）、name。可选 sourceGroupingId 表示在一个已保存视图上继续合并。先向用户展示预期合并与涉及材料，确认后保存；未选分组和共享材料保留。
• 按主题预览：POST /api/research-maps/{id}/groupings/preview，再带 instruction（用户的分组要求）和 name。返回202与任务 id；每5秒读取 /groupings/jobs/{任务id}，直到 ready、error、stale 或 interrupted。主题拟定可取样，归类阶段逐批处理全部材料；依据题名及已有摘要，不表示重新阅读全文。不确定材料保留到“待分类”。
• 用户检查预览后保存：POST /api/research-maps/{id}/groupings/save，带 jobId 及上述版本字段，返回 view.id。预览本身不会应用到原图。
• 打开保存视图：GET /api/transit-maps/{id}?groupBy=custom&groupingId={view.id}。回到原图用 groupBy=route。自定义视图包含全量材料；原研究路线仍可单独读取。

409表示材料、分析或分组版本变化，需重读并重新核对，不能自动覆盖。保留旧视图和版本备份；时间线更新后旧视图可能标为失效，需要针对新材料重新生成。相同请求编号重发相同内容不会重复创建；不要用新编号盲目重试断线写入。