@researai/deepscientist 1.5.9 → 1.5.11

package/docs/zh/11_LICENSE_AND_RISK.md

@@ -0,0 +1,256 @@
+# 11 协议与风险说明
+
+这篇文档只做两件事：
+
+1. 明确 DeepScientist 的开源协议与责任边界
+2. 明确你在实际部署和使用时需要自己承担的主要风险
+
+这不是法律意见。如果你要把 DeepScientist 用在公司环境、生产环境、真实业务系统或对外服务中，请让你自己的法务、安全或运维团队再审一次。
+
+## 1. 开源协议与责任边界
+
+DeepScientist 采用 Apache 2.0 开源协议发布。
+
+你可以在仓库根目录查看完整协议文本：
+
+- [LICENSE](../../LICENSE)
+
+需要明确的是：
+
+- DeepScientist 按 Apache 2.0 协议发布
+- DeepScientist 按“现状”提供，不提供任何明示或暗示担保
+- 因使用、部署、修改、二次开发、共享或暴露 DeepScientist 而产生的任何直接或间接后果，项目作者与维护者概不负责
+- 你需要自行负责运行环境、权限设置、对外暴露、第三方账号绑定、结果审查、数据处理和合规问题
+
+换句话说，DeepScientist 是一个高能力自动化系统，不是托管服务，也不是安全审计后的托底产品。你必须自己控制边界。
+
+## 2. 你需要重点关注的风险
+
+下面这些风险都是真实存在的，而且彼此会叠加。
+
+### 2.1 主机与服务器破坏风险
+
+DeepScientist 可以驱动模型执行命令、修改文件、安装依赖、运行脚本、读写项目目录。
+
+这意味着它可能：
+
+- 删除、覆盖或破坏文件
+- 修改 Git 状态、分支或工作区内容
+- 安装错误依赖、污染运行环境
+- 误删日志、缓存、实验结果或中间产物
+- 错误占用 GPU、CPU、磁盘或网络资源
+- 干扰你机器上的其他服务，甚至导致服务器不可用
+
+如果你把它直接运行在高权限宿主机、生产机、共享研发机或带关键数据的服务器上，风险会显著放大。
+
+### 2.2 结果伪造、错误结论与学术风险
+
+DeepScientist 是基于模型的自动化系统，不保证结论真实。
+
+它可能：
+
+- 伪造实验结果、日志、指标或表格
+- 编造引用、论文结论或对比基线
+- 错误理解任务要求，导致实验协议偏移
+- 生成看起来合理、但实际上不可复现的分析
+- 在没有充分证据时写出过强结论
+
+因此，任何实验结果、论文文本、图表、引用、结论或审稿回复，都必须由人复核，不能直接当成可信事实发布。
+
+### 2.3 数据损坏、丢失与不可逆修改风险
+
+即使没有明显“攻击行为”，自动化执行也可能造成不可逆损失。
+
+例如：
+
+- quest 内文件被覆盖
+- 未提交的本地改动被后续流程污染
+- 自动生成文件混入正式结果目录
+- 错误脚本批量改坏数据集或实验目录
+- 外部 connector 收到不应发送的中间结果
+
+如果你的数据、项目或论文草稿没有备份，这类损失可能很难恢复。
+
+### 2.4 密钥、凭据与隐私泄露风险
+
+DeepScientist 会接触很多敏感信息，例如：
+
+- API key
+- 环境变量
+- 私有仓库地址
+- 研究数据
+- connector token
+- 微信、QQ、Lingzhu 等外部账号绑定信息
+
+如果你：
+
+- 把站点公开暴露到外网
+- 直接共享你的 DeepScientist 页面
+- 让不受信任的人访问你的运行环境
+- 把含密钥的配置、日志、截图或 quest 文件发给别人
+
+就可能导致：
+
+- 模型凭据泄露
+- connector 身份被盗用
+- 微信、QQ 等对外沟通能力被滥用
+- 项目数据、实验材料或隐私内容被第三方获取
+
+尤其是 connector 绑定后，风险不再只是“网页能不能打开”，而是“外部账号能不能被接管”。
+
+### 2.5 外网暴露与未授权访问风险
+
+如果你使用 `0.0.0.0`、公网 IP、反向代理、隧道服务或域名把 DeepScientist 暴露到外部，你实际上是在暴露一个具备自动化执行能力的系统。
+
+这会带来：
+
+- 未授权用户访问
+- 会话被探测或重放
+- connector 回调或轮询上下文被滥用
+- 项目页面、配置页面、日志页面被外部看到
+- 通过错误配置暴露内部路径、端口和服务结构
+
+如果还同时绑定了微信、QQ 或其他 connector，风险会进一步扩大。
+
+因此，除非你完全清楚自己在做什么，否则不要轻易公开分享站点地址，也不要把可操作界面直接暴露给不受控用户。
+
+### 2.6 第三方平台与账号合规风险
+
+DeepScientist 可以与 QQ、微信、Lingzhu 等外部平台结合使用。
+
+你需要自己承担：
+
+- 第三方平台服务条款风险
+- 账号被封禁、限制或审计的风险
+- 不当消息发送导致的投诉或滥用风险
+- 数据同步、内容转发或文件发送带来的隐私与合规问题
+
+项目维护者不会替你保证这些平台侧行为一定符合当地法律、组织政策或平台规则。
+
+### 2.7 恶意输入、提示注入与供应链风险
+
+DeepScientist 会读：
+
+- 仓库内容
+- 论文
+- 网页
+- issue / PR / README
+- 上传的附件
+- connector 发来的文本和文件
+
+这些内容里都可能混入：
+
+- 恶意命令
+- 提示注入
+- 误导性说明
+- 伪造 benchmark
+- 带后门的依赖安装指令
+
+如果模型信了这些内容，可能进一步触发更危险的行为。
+
+### 2.8 资源、费用与滥用风险
+
+DeepScientist 可能持续运行、多轮调用模型、下载依赖、执行实验、生成文件。
+
+你需要自己承担：
+
+- API 费用增长
+- GPU/CPU 被长时间占用
+- 磁盘被日志、缓存、artifact、数据集填满
+- 长时间运行导致的系统负载、过热或服务争用
+
+## 3. 强烈建议的最低安全实践
+
+如果你打算真正长期使用 DeepScientist，至少做到下面这些：
+
+### 3.1 优先使用 Docker 或其他隔离环境
+
+强烈建议优先在 Docker 容器、虚拟机或同等级隔离环境中运行 DeepScientist，而不是直接在宿主机高权限环境里裸跑。
+
+目标很简单：
+
+- 把文件系统影响范围缩小
+- 把进程权限降下来
+- 把网络暴露面缩小
+- 把出问题时的恢复成本降下来
+
+### 3.2 一律使用非 root 账号启动
+
+强烈建议：
+
+- 使用专门的非 root 用户运行
+- 不要直接用 root 启动 DeepScientist
+- 不要让它默认拿到全盘写权限
+- 不要让它默认接触宿主机敏感目录
+
+如果你必须在服务器上运行，更要坚持最小权限原则。
+
+### 3.3 不要直接跑在生产机或关键资产机器上
+
+避免把 DeepScientist 直接放到这些环境：
+
+- 生产数据库所在机器
+- 在线业务服务器
+- 保存核心源代码和密钥的主控机
+- 共享跳板机
+- 带重要个人资料或商业数据的桌面环境
+
+### 3.4 不要轻易分享站点地址或公网入口
+
+除非你已经做好完整访问控制，否则不要：
+
+- 把 DeepScientist 页面地址发到公开群
+- 把 `0.0.0.0` 绑定后的端口直接映射到公网
+- 把无鉴权的反向代理地址公开出去
+- 把绑定了 connector 的页面开放给其他人直接操作
+
+这不仅是页面浏览风险，也是账号与 connector 权限泄露风险。
+
+### 3.5 最小化凭据与 connector 权限
+
+建议：
+
+- 用单独的测试账号绑定 QQ / 微信 / Lingzhu
+- 不要把高价值主账号直接暴露给实验环境
+- 不要把所有 token 都放进同一个共享 home
+- 定期轮换密钥和 connector token
+- 对外发送能力尽量只给最小必需范围
+
+### 3.6 任何结果都要人工复核
+
+不要把以下内容直接视为可信：
+
+- 实验指标
+- 图表
+- 论文段落
+- related work
+- 引用列表
+- 消融结论
+- “已复现成功”这类状态
+
+正确做法是：
+
+- 看原始文件
+- 看运行日志
+- 看脚本和配置
+- 重跑关键实验
+- 抽查引用和数字
+
+### 3.7 做好备份与回滚准备
+
+至少建议：
+
+- 把关键 quest 放进 Git
+- 定期备份 `~/DeepScientist`
+- 对重要数据目录做快照
+- 把生产数据与实验数据分开
+
+## 4. 最短结论
+
+最短版本只有五句话：
+
+1. DeepScientist 采用 Apache 2.0 协议发布。
+2. 项目作者与维护者不对你使用 DeepScientist 造成的任何后果负责。
+3. 它可能破坏服务器、删除文件、泄露凭据、对外发送错误内容，也可能伪造结果。
+4. 强烈建议优先使用 Docker 或同等级隔离环境，并始终使用非 root 账号运行。
+5. 不要轻易共享站点地址，也不要把绑定了微信、QQ 等 connector 的运行环境暴露给不受控用户。

package/docs/zh/12_GUIDED_WORKFLOW_TOUR.md

@@ -0,0 +1,423 @@
+# 12 引导式工作流教程：从首页到真实工作区
+
+这篇文档的目标，是让你在安装完成之后，真正理解 DeepScientist 的使用路径。
+
+适合你在这些情况下阅读：
+
+- 你已经成功启动过一次 DeepScientist
+- 你已经能打开首页
+- 你想知道每一步该点什么、该怎么填、每个界面到底是干什么的
+
+如果你还没有完成启动，请先看 [00 快速开始](./00_QUICK_START.md)。
+
+如果你想进一步理解 `Start Research` 弹窗背后的精确字段合同，再看 [02 Start Research 参考](./02_START_RESEARCH_GUIDE.md)。
+
+## 1. 先分清两种使用方式
+
+DeepScientist 常见有两种使用方式：
+
+1. 真实项目模式
+2. 引导教程模式
+
+真实项目模式会创建一个真正的本地 quest 仓库，并开始真实工作。
+
+引导教程模式会进入一个演示用的项目工作区，界面布局与真实项目一致，但内容是为学习而准备的。
+
+如果你的目标是立即做真实任务，就用真实项目模式。
+
+如果你的目标是先理解界面，再决定是否投入真实时间、算力和 connector 资源，就先用引导教程模式。
+
+## 2. 从首页开始
+
+首页不是一个普通聊天框，而是一个研究工作区的启动面。
+
+最核心的两个入口是：
+
+- `Start Research`
+- `Open Project`
+
+当你要开始一个全新的 quest 时，点击 `Start Research`。
+
+当 quest 已经存在、你只是要继续推进时，点击 `Open Project`。
+
+第一次使用时，优先点击 `Start Research`。
+
+## 3. 先理解这个弹窗到底在做什么
+
+`Start Research` 弹窗有两个同样重要的任务：
+
+- 左侧定义项目合同
+- 右侧展示真正会写入工作区的 kickoff prompt
+
+所以不要把它当成“随便填两句就行”的表单。
+
+你在这里实际上是在决定：
+
+- quest 到底要解决什么问题
+- 已经有哪些可用参考和 baseline
+- 第一轮自动研究要推进到什么程度
+- 是否需要把进展发到网页之外
+
+如果右侧生成出来的 kickoff prompt 看起来不对，就不要急着创建项目，先回到左侧修正。
+
+## 4. 按步骤填写 `Start Research`
+
+### 4.1 Project title
+
+这里填写一个给人看的项目标题。
+
+推荐写法：
+
+- 任务名称
+- benchmark 或仓库名
+- 研究方向
+
+示例：
+
+`Mandela-Effect Reproduction and Truth-Preserving Collaboration`
+
+标题的作用，是让你以后在项目列表里快速认出它。
+
+### 4.2 Project ID
+
+大多数时候直接留空。
+
+只有在这些场景下才建议手动填写：
+
+- 教程演示
+- 固定复现实验编号
+- 团队内部有命名规范
+
+否则让 runtime 自动分配下一个顺序 quest id 即可。
+
+### 4.3 Primary research request
+
+这是整个弹窗里最重要的字段。
+
+这里要写清楚：
+
+- 研究目标
+- 成功标准
+- 证据要求
+- 最关键的限制条件或评测规则
+
+不好的写法：
+
+- 太泛的 brainstorming
+- 只写实现细节，不写研究问题
+- 没说清楚什么算验证成功
+
+好的写法通常包含四层：
+
+1. 要复现或研究什么
+2. 研究问题是什么
+3. 哪些协议和边界不能乱改
+4. 可以往什么方向改进
+
+### 4.4 Baseline links 和 Reference papers
+
+这两栏的目的，是在第一轮开始前尽量减少歧义。
+
+把仓库放进 `Baseline links`，适合这些情况：
+
+- baseline 必须来自某个特定官方仓库
+- quest 需要先恢复指定实现
+
+把论文或关键材料放进 `Reference papers / repos`，适合这些情况：
+
+- 任务由某篇论文定义
+- 评测协议来自某个明确来源
+- 系统应该优先阅读某篇参考资料
+
+如果你已经知道 baseline 和论文，不要把它们藏在主请求正文里，应该放进专门字段。
+
+### 4.5 Reusable baseline
+
+只有当你已经把某个可信 baseline 导入了 registry，才需要选择它。
+
+一旦这里选中：
+
+- 第一轮会优先 attach 已存在 baseline
+- 而不是从原始 URL 再重新恢复
+
+如果你是第一次做这个任务，留空是完全正常的。
+
+### 4.6 Connector delivery
+
+这一栏是可选的。
+
+建议在这些情况下保持 `Local only`：
+
+- 第一次使用
+- 想让流程最简单
+- 不需要网页之外的提醒
+
+只有在以下情况下才选择一个 connector：
+
+- 你希望在浏览器外也收到进展或里程碑
+- 该 connector 已经配置正确
+
+当前 DeepScientist 对每个 quest 只绑定一个外部 connector 目标。
+
+### 4.7 Research paper、Research intensity、Decision mode、Launch mode
+
+这些项会真实改变第一轮研究的形状。
+
+如果你暂时拿不准，推荐默认这样选：
+
+- `Research paper`: `On`
+- `Research intensity`: `Balanced`
+- `Decision mode`: `Autonomous`
+- `Launch mode`: `Standard`
+
+原因很简单：
+
+- `Balanced` 足够做真实工作，又不会让第一轮过重
+- `Autonomous` 可以减少无谓阻塞
+- `Standard` 让 quest 按普通研究主线启动
+- `Research paper = On` 可以把分析与写作保持在范围内
+
+### 4.8 Runtime constraints
+
+这一栏应该写“硬规则”，而不是写愿望。
+
+适合写进去的内容：
+
+- 必须使用哪个模型或推理端点
+- 是否必须自动重试
+- 是否必须保持与 baseline 对齐
+- 是否必须如实记录失败
+- 硬件或运行边界
+
+不适合写进去的内容：
+
+- 已经在主请求里说过的泛目标
+- 冗长文献综述
+- 本该写进 references 的信息
+
+### 4.9 Goals
+
+这一栏适合写更具体的阶段目标。
+
+好的目标应当：
+
+- 明确
+- 可验证
+- 方便后续复盘
+
+推荐写法：
+
+1. 恢复 baseline
+2. 验证关键指标
+3. 提出一个有依据的新方向
+4. 产出足够支撑后续分析或写作的证据
+
+### 4.10 一定要检查右侧 kickoff prompt
+
+在点击 `Create project` 之前，一定读一遍右侧生成的 kickoff prompt。
+
+重点检查：
+
+- scope 是否错了
+- baseline 信息是否丢了
+- runtime constraints 是否遗漏
+- connector 目标是否错误
+- 语气和任务是否已经不一致
+
+这是整个流程里成本最低、收益最高的纠错点。
+
+## 5. 点击 `Create project`
+
+在真实项目模式下，这一步会创建真实的本地 quest，并打开真实工作区。
+
+在引导教程模式下，这一步会进入一个演示用 quest，用来让你熟悉工作区界面。
+
+最重要的心态切换是：
+
+- 在点击前，它只是一个任务想法
+- 在点击后，它已经变成一个有文件、图谱、memory 和执行历史的持久工作区
+
+## 6. 用正确顺序认识工作区
+
+推荐顺序是：
+
+1. 顶栏
+2. Explorer
+3. 打开一个真实文件
+4. Canvas
+5. Details
+6. Memory
+7. Copilot / Studio
+
+### 6.1 顶栏
+
+顶栏是全局控制条。
+
+你应该用它来判断：
+
+- 当前在哪个 quest 里
+- 当前是不是在预期分支上
+- 如何返回、重播教程或做全局导航
+
+### 6.2 Explorer
+
+Explorer 是 quest 的文件视角。
+
+它回答的是一个非常实际的问题：
+
+`这个项目现在到底已经有哪些持久文件了？`
+
+当你想确认 quest 是否真的产出了可复用内容时，就应该先看这里。
+
+不要把图谱当作唯一真相来源。文件树本身就是非常重要的证据面。
+
+### 6.3 ArXiv 和 Files 两个 tab
+
+这两个 tab 分工不同：
+
+- `ArXiv` 是文献书架
+- `Files` 是工作树
+
+正常使用中，你会在这两个视图之间反复切换。
+
+一个用来读文献，一个用来打开计划、实验文件、笔记与产物。
+
+### 6.4 打开一个真实文件
+
+当你在 Explorer 里看到一个有价值的文件时，直接点开它。
+
+这一步意味着你从“看结构”进入“看真实内容”。
+
+常见文件类型包括：
+
+- Markdown 笔记
+- 计划
+- 实验总结
+- 结果报告
+- 论文草稿
+
+很多用户会把 quest 里的 Markdown 文件当作一个本地优先、类似 Notion 的私有笔记本，用来记录：
+
+- 笔记
+- 计划
+- handoff
+- 发现
+- 协作信息
+
+### 6.5 Canvas
+
+Canvas 会把研究地图直接展示出来。
+
+一个健康的 quest，不应该像一段无限滚动聊天记录。
+
+Canvas 应该帮助你看到：
+
+- baseline 工作
+- 新想法
+- 失败分支
+- 成功路径
+- 后续分析和写作
+
+它最重要的价值，是展示 quest 是怎样长出来的，而不只是停在了哪里。
+
+### 6.6 点击 Canvas 上的节点
+
+不要只看形状。
+
+点开一个节点，去看它到底代表什么。
+
+一个有价值的节点应该把你带到：
+
+- 分支摘要
+- 关联文件
+- stage 状态
+- 持久证据
+
+这样 Canvas 才不是装饰，而是真正可检查的研究地图。
+
+### 6.7 Details
+
+当你想最快回答下面这个问题时，就看 `Details`：
+
+`这个 quest 现在到底是什么状态？`
+
+特别适合这些场景：
+
+- 你离开一段时间后回来
+- quest 已经运行了一阵子
+- 你想先看总结，再决定是否介入
+
+### 6.8 Memory
+
+Memory 是让 quest 能持续生长的关键。
+
+你可以在这里理解：
+
+- 哪些经验已经变成可复用知识
+- 哪些弱路径以后不该再重复
+- 哪些稳定事实已经从论文或实验中沉淀下来
+
+没有 memory，每一轮都容易变成一次性消耗品。
+
+### 6.9 Copilot / Studio
+
+如果你希望持续贴着 quest 的执行过程，就把这个面板一直开着。
+
+它适合做这些事情：
+
+- 看执行过程
+- 中途介入
+- 请求状态总结
+- 改路线
+- 过一段时间再回来继续
+
+这里是 quest 从“自动运行”变成“可协作工作坊”的地方。
+
+## 7. 一个实用的一轮操作节奏
+
+当 quest 已经开始运行后，最有用的节奏通常是：
+
+1. 先让第一轮动起来
+2. 不要只盯着聊天，去打开 workspace
+3. 看 1 到 2 个关键文件
+4. 用 Canvas 看分支结构
+5. 用 Details 看当前状态
+6. 再决定是否介入
+
+这样可以避免两个常见错误：
+
+- 介入太早
+- 还没看证据就过度相信总结
+
+## 8. 常见误区
+
+### 8.1 把 `Start Research` 当成随便聊天
+
+它不是聊天框，而是项目合同。
+
+### 8.2 目标写得太空
+
+如果目标里没有验证要求，第一轮通常会更弱。
+
+### 8.3 重要参考都塞在一段正文里
+
+baseline 和 references 应该写在专门字段里。
+
+### 8.4 不看右侧 kickoff prompt
+
+这是整个流程里最便宜的纠错位置。
+
+### 8.5 把 Canvas 当成漂亮图片
+
+真正有价值的用法，是点节点、看文件、查证据。
+
+### 8.6 只盯着工作区实时输出，不看文件
+
+文件树本身就是系统的主要真相面之一。
+
+## 9. 下一步建议阅读
+
+- [02 Start Research 参考](./02_START_RESEARCH_GUIDE.md)
+- [06 Runtime 与 Canvas](./06_RUNTIME_AND_CANVAS.md)
+- [07 Memory 与 MCP](./07_MEMORY_AND_MCP.md)
+- [13 核心架构说明](./13_CORE_ARCHITECTURE_GUIDE.md)