@researai/deepscientist 1.5.9 → 1.5.12

package/docs/zh/10_WEIXIN_CONNECTOR_GUIDE.md

@@ -0,0 +1,144 @@
+# 10 微信连接器指南：把个人微信绑定到 DeepScientist
+
+这篇文档只讲 DeepScientist 内置的微信连接器，不讲 OpenClaw 安装。
+
+DeepScientist 已经内置了微信 iLink 运行时，因此你不需要再额外执行：
+
+- `npx`
+- 单独安装 OpenClaw
+- 再起一个本地桥接程序
+- 配置公网 webhook
+
+真正需要的绑定动作只有这四步：
+
+1. 打开 `Settings > Connectors > WeChat`
+2. 点击 `绑定微信`
+3. 用微信扫码
+4. 在手机微信里确认登录
+
+确认完成后，DeepScientist 会自动保存微信 connector，并开始长轮询。
+
+## 1. 这个连接器现在能做什么
+
+绑定成功后，DeepScientist 现在可以：
+
+- 接收微信文本消息
+- 接收微信图片、视频、文件附件
+- 把入站附件复制到当前 quest 的 `userfiles/weixin/...`
+- 把文本回复发回同一个微信上下文
+- 在 agent 提供真实本地文件时，发送微信原生图片、视频、文件
+
+入站媒体不会只留在临时缓存里，而是会被复制进 quest。本地落盘路径形态如下：
+
+```text
+~/DeepScientist/quests/<quest_id>/userfiles/weixin/<message_batch>/
+```
+
+这意味着微信附件现在已经比较接近 QQ 的处理方式了：quest 能拿到真实、持久化的本地文件。
+
+![DeepScientist 微信绑定总览](../images/weixin/weixin-settings-bind.svg)
+
+## 2. 绑定前先确认
+
+开始前请先确认：
+
+- DeepScientist 的 daemon 和网页已经正常启动
+- 你可以打开 `Settings > Connectors > WeChat`
+- 手机上已经登录了一个真实的个人微信账号，准备用它扫码
+
+这张参考图只用于帮助你确认扫码时应使用已经登录目标微信账号的手机。真正的绑定动作仍然是在 DeepScientist 页面里弹出二维码后扫码完成，而不是去跑额外的 `npx` 工具。
+
+![微信客户端参考图](../images/weixin/weixin-plugin-entry.png)
+
+## 3. 从 Settings 页面直接绑定
+
+打开：
+
+- [Settings > Connectors > WeChat](/settings/connectors#connector-weixin)
+
+然后按顺序做：
+
+1. 点击 `绑定微信`
+2. 等待 DeepScientist 生成二维码
+3. 用微信扫码
+4. 在手机上确认登录
+
+这里有几个关键点：
+
+- 弹窗里只保留二维码这一张图，因为 DeepScientist 已经内置了完整的 iLink 登录流程
+- 绑定过程中不需要手填 `bot_token`
+- 二维码弹窗里不需要额外再点一次保存
+- 平台一旦返回 `bot_token` 和账号信息，DeepScientist 会自动持久化
+
+成功后，微信卡片里会显示：
+
+- `机器人账号`
+- `扫码账号`
+
+这两项就是当前保存下来的微信绑定信息。
+
+![二维码扫码确认流程](../images/weixin/weixin-qr-confirm.svg)
+
+## 4. 绑定后怎么验证文本和多媒体
+
+二维码登录成功后，建议按这个最短路径验证：
+
+1. 在 `Start Research` 或项目界面把 quest 绑定到微信 connector
+2. 从微信发一条文本、图片、视频或文件
+3. 等待 DeepScientist 把它接入到 quest
+4. 确认回复回到了同一条微信会话里
+
+当前行为是：
+
+- 入站文本会直接进入 quest，作为用户消息
+- 入站图片、视频、文件会被下载并复制进 quest 本地 `userfiles/weixin/...`
+- 纯媒体消息不会再被直接丢弃
+- 出站文本会沿用运行时维护的 `context_token`
+- 出站图片、视频、文件在 agent 提供真实本地文件路径时可以正常发送
+
+![Quest 本地多媒体流转](../images/weixin/weixin-quest-media-flow.svg)
+
+## 5. agent 发送微信多媒体时应怎么做
+
+对用户来说，规则其实很简单：
+
+- 只回文本时，正常回复即可
+- 要发微信原生图片、视频、文件时，agent 必须给出一个真实的 quest 本地文件
+
+所以 agent 最好优先使用这些目录中的真实文件：
+
+```text
+artifacts/...
+experiments/...
+paper/...
+userfiles/...
+```
+
+而不是默认依赖一个任意的外链。
+
+## 6. 常见问题
+
+### 二维码一直在等待
+
+优先检查：
+
+- 是否用的是你真正想绑定的那个微信账号扫码
+- 手机里是否已经完成“确认登录”
+- 等待期间 DeepScientist 是否持续在线
+
+如果二维码过期，DeepScientist 会自动刷新。
+
+### 为什么我只看到文本，没有看到入站多媒体
+
+请用真实图片、视频或文件重测一次。成功后，quest 目录里应该能看到：
+
+```text
+userfiles/weixin/<message_batch>/manifest.json
+```
+
+以及旁边被复制下来的实际媒体文件。
+
+## 7. 参考
+
+- 菜鸟教程个人微信接入说明：https://www.runoob.com/ai-agent/openclaw-weixin.html
+- 上游微信协议文档：https://github.com/hao-ji-xing/openclaw-weixin/blob/main/weixin-bot-api.md

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 的运行环境暴露给不受控用户。