已开启
docs: 重写中英文 README，并把 run 子命令补进英文部署指南 #132
chendanyang创建于 9月17日
docs: 重写中英文 README，并把 run 子命令补进英文部署指南 #132
已开启
共 5 个文件变更+192-84
| @@ -1,54 +1,100 @@ | |||
| 1 | +<div align="center"> | ||
| 2 | + | ||
| 1 | # ScienceDiscovery | 3 | # ScienceDiscovery |
| 2 | 4 | ||
| 3 | -ScienceDiscovery是专为科学研究打造的一站式AI科研工作台。依托该平台，科研人员能够一站式高效完成“文献阅读、假设提出、代码编写、实验试错、参数调优”这一极为繁琐的科研探索流程。 | 5 | +**专为科研打造的一站式 AI 科研工作台。** |
| 4 | 6 | ||
| 5 | -[English](README.md) | 中文 | 7 | +文献阅读、假设提出、代码编写、实验试错、参数调优 —— 在同一个环境里完成，每一步都留痕。 |
| 8 | + | ||
| 9 | +[](LICENSE) | ||
| 10 | +[](https://github.com/openJiuwen-ai/sciencediscovery/releases/tag/0.2.0) | ||
| 11 | +[](#环境要求) | ||
| 12 | +[](docs/README.md) | ||
| 13 | + | ||
| 14 | +[下载](#安装) · [快速开始](docs/zh/tutorial/01-quick-start.md) · [文档](docs/README.md) · [贡献指南](CONTRIBUTING.md) · [English](README.md) | ||
| 15 | + | ||
| 16 | +<img src="docs/images/task.png" width="920" alt="ScienceDiscovery 工作区：项目与会话导航、输入框，以及产物、审阅与溯源面板" /> | ||
| 17 | + | ||
| 18 | +</div> | ||
| 19 | + | ||
| 20 | +## 简介 | ||
| 21 | + | ||
| 22 | +ScienceDiscovery 是一个本地运行的科研工作台：智能体阅读文献、在沙箱中编写并运行代码，并记录每一项结果的来源。全部过程在你自己的机器上执行，处理你自己的文件，使用你自己的模型密钥。 | ||
| 23 | + | ||
| 24 | +## 安装 | ||
| 25 | + | ||
| 26 | +从 [release 0.2.0](https://github.com/openJiuwen-ai/sciencediscovery/releases/tag/0.2.0) 下载与宿主架构匹配的构建： | ||
| 27 | + | ||
| 28 | +```bash | ||
| 29 | +curl -LO https://github.com/openJiuwen-ai/sciencediscovery/releases/download/0.2.0/ScienceDiscovery-0.2.0-linux-x86_64 | ||
| 30 | +chmod +x ScienceDiscovery-0.2.0-linux-x86_64 | ||
| 31 | +./ScienceDiscovery-0.2.0-linux-x86_64 serve | ||
| 32 | +``` | ||
| 33 | + | ||
| 34 | +打开 `serve` 输出的 **`Open to sign in`** 链接，浏览器将自动保存本地服务访问令牌，无需手动复制。该令牌不同于模型 API Key；此链接可访问本机工作区，请勿外传。Web 界面位于 <http://127.0.0.1:4310>，终端窗口仅运行服务进程。 | ||
| 35 | + | ||
| 36 | +arm64 请使用 [`ScienceDiscovery-0.2.0-linux-aarch64`](https://github.com/openJiuwen-ai/sciencediscovery/releases/download/0.2.0/ScienceDiscovery-0.2.0-linux-aarch64)。宿主唯一依赖是 Bubblewrap。本地源码模式（Linux 与 macOS）和 Docker 参见[部署指南](docs/zh/how-to/deployment.md)。 | ||
| 37 | + | ||
| 38 | +## 配置模型 | ||
| 39 | + | ||
| 40 | +ScienceDiscovery 不内置模型，需接入你自己的 API。打开左侧栏底部的**系统配置**，完成两处配置： | ||
| 41 | + | ||
| 42 | +1. **模型注册表** —— 选择预置服务商或手动填写**基础 URL**，填入 **API Key**，然后添加需要使用的模型。 | ||
| 43 | +2. **全局默认值** —— 将上一步添加的模型设为**任务模型**。 | ||
| 44 | + | ||
| 45 | +各字段的含义，以及可改用环境变量配置的项，参见[配置参考](docs/zh/reference/configuration.md)。 | ||
| 46 | + | ||
| 47 | +## 第一个任务 | ||
| 48 | + | ||
| 49 | +新建 Project 与 Session，将 CSV 或 PDF 拖入工作区，并描述分析目标。首次执行代码前会出现权限卡片，批准后即可在时间线中查看工具调用与产物。完整步骤参见[快速开始](docs/zh/tutorial/01-quick-start.md)。 | ||
| 50 | + | ||
| 51 | +## 核心能力 | ||
| 52 | + | ||
| 53 | +| 能力 | 说明 | 参考 | | ||
| 54 | +|---|---|---| | ||
| 55 | +| **文献与数据接入** | 内置连接器直达文献库与数据库；PDF 被解析为可引用的证据 | [文献调研案例](docs/zh/how-to/literature-research-case-guide.md) · [自定义 MCP](docs/zh/how-to/configure-custom-mcp.md) | | ||
| 56 | +| **沙箱内代码执行** | 智能体在 fail-closed 沙箱中编写、调试并运行 Python、R 与 Shell | [沙箱执行](docs/zh/explanation/sandbox-execution.md) | | ||
| 57 | +| **复杂任务拆解** | 任务规划与多智能体协同将任务分发给子智能体和跨领域 Skill 库 | [子智能体编排](docs/zh/explanation/subagent-orchestration.md) · [Skill](docs/zh/explanation/skill-progressive-disclosure.md) | | ||
| 58 | +| **全链路溯源** | 代码、环境、日志与引用证据按产物记录；开启记忆图谱后整条链路可点击追溯 | [审阅与溯源](docs/zh/explanation/review-provenance.md) · [ScienceMemory](docs/zh/how-to/science-memory-setup.md) | | ||
| 59 | + | ||
| 60 | +## 命令行 | ||
| 61 | + | ||
| 62 | +已启动的 `serve` 同样可以从终端驱动： | ||
| 63 | + | ||
| 64 | +```bash | ||
| 65 | +./ScienceDiscovery run "总结这些结果" > answer.md | ||
| 66 | +cat prompt.txt | ./ScienceDiscovery run --stdin --auto-approve | jq . | ||
| 67 | +``` | ||
| 68 | + | ||
| 69 | +`run` 连接与浏览器相同的控制面，并从数据目录读取访问令牌，因此只要与 `serve` 共用 `--data-dir` 即无需额外配置。在终端中直接运行时，答案输出到 stdout、进度输出到 stderr；在管道中则输出 JSONL，且非交互运行必须显式传入 `--auto-approve`，因为此时无法响应权限询问。完整选项参见 `./ScienceDiscovery run --help`。 | ||
| 70 | + | ||
| 71 | +## 环境要求 | ||
| 72 | + | ||
| 73 | +| 路径 | 宿主要求 | | ||
| 74 | +|---|---| | ||
| 75 | +| **预打包二进制** | Linux x86_64/aarch64、Bubblewrap | | ||
| 76 | +| **本地源码模式** | Linux x86_64/aarch64 或 macOS x64/arm64；Node.js 22.19+、pnpm 11.1.2、Python 3、uv 0.9+、Git；Linux 用 Bubblewrap，macOS 用系统内置 Seatbelt | | ||
| 77 | +| **Docker** | Linux x86_64/aarch64、Docker Engine 24+、Compose v2、可用的无特权用户命名空间 | | ||
| 78 | + | ||
| 79 | +托管科学环境基于固定版本的 micromamba 运行，无需在系统中安装 Python、R 或 conda。 | ||
| 80 | + | ||
| 81 | +## 架构概览 | ||
| 82 | + | ||
| 83 | +浏览器 UI 与 Node 控制 API 通信；每次智能体运行由 Python Gateway 驱动，而工作区工具、沙箱执行、科研连接器、PDF 抽取、权限、溯源与审阅校验由 Node 控制面统一管控。 | ||
| 6 | 84 | ||
| 7 | > [!WARNING] | 85 | > [!WARNING] |
| 8 | > ScienceDiscovery 不是多用户生产服务。API、runner 与 gateway 默认只监听回环；API 使用一个 bearer token 且不终止 TLS。监听其他网卡必须是可信、受保护网络中的显式部署选择。Python、R 和 shell 命令在 fail-closed 的平台沙箱中运行（Linux 使用 Bubblewrap，macOS 源码模式使用 Seatbelt）；控制 API、gateway、PDF worker 以及发往已配置模型/数据提供方的请求在沙箱外作为受信任控制面操作执行。 | 86 | > ScienceDiscovery 不是多用户生产服务。API、runner 与 gateway 默认只监听回环；API 使用一个 bearer token 且不终止 TLS。监听其他网卡必须是可信、受保护网络中的显式部署选择。Python、R 和 shell 命令在 fail-closed 的平台沙箱中运行（Linux 使用 Bubblewrap，macOS 源码模式使用 Seatbelt）；控制 API、gateway、PDF worker 以及发往已配置模型/数据提供方的请求在沙箱外作为受信任控制面操作执行。 |
| 9 | 87 | ||
| 10 | -## 项目定位 | 88 | +## 文档 |
| 11 | 89 | ||
| 12 | -ScienceDiscovery是专为科学研究打造的一站式AI科研工作台。依托该平台，科研人员能够一站式高效完成“文献阅读、假设提出、代码编写、实验试错、参数调优”这一极为繁琐的科研探索流程。 | 90 | +| 分类 | 文档 | |
| 13 | - | ||
| 14 | -## 特性 | ||
| 15 | - | ||
| 16 | -- **海量资源一键配置与高效接入**：通过平台内置的科研数据库 Connector，实现文献库与数据库的一键快速配置，快速获取海量前沿文献与核心试验数据； | ||
| 17 | -- **安全沙箱环境下的自主代码探索**：支持智能体在安全隔离的沙箱环境中自主编写、调试并运行 Python、R 或 Shell 代码，为复杂科学数据处理提供稳定环境； | ||
| 18 | -- **复杂科研任务的自动拆解与动态执行**：凭借强大的任务规划与多智能体协同能力，系统可自动拆解复杂科研任务，动态编排并调用 300+ 跨领域 Skills； | ||
| 19 | -- **科研流程全链路可溯源**：平台将完整展现全流程工作流，并提供包含代码、环境和日志在内的全链路产物溯源，确保科研全流程的高可信度。 | ||
| 20 | - | ||
| 21 | -## 相关文档 | ||
| 22 | - | ||
| 23 | -- [文档导航](docs/README.md) — 完整的中英文 Tutorial / How-to / Reference / Explanation 入口。 | ||
| 24 | -- [贡献指南](CONTRIBUTING.md) — 开发环境与测试命令。 | ||
| 25 | - | ||
| 26 | -## 环境要求 | ||
| 27 | - | ||
| 28 | -预打包二进制是主要用户路径，其他部署方式单独记录在部署指南中。 | ||
| 29 | - | ||
| 30 | -| 路径 | 宿主要求 | | ||
| 31 | |---|---| | 91 | |---|---| |
| 32 | -| 预打包二进制 | Linux x86_64/aarch64、bubblewrap | | 92 | +| **教程** | [快速开始](docs/zh/tutorial/01-quick-start.md) | |
| 33 | -| 本地源码模式 | Linux x86_64/aarch64 或 macOS x64/arm64、Node.js 22.19+、pnpm 11.1.2、Python 3、uv 0.9+、Git；Linux 另需 Bubblewrap，macOS 使用系统内置 Seatbelt | | 93 | +| **How-to** | [部署](docs/zh/how-to/deployment.md) · [自定义 MCP](docs/zh/how-to/configure-custom-mcp.md) · [网络代理](docs/zh/how-to/configure-network-proxy.md) · [ScienceMemory](docs/zh/how-to/science-memory-setup.md) | |
| 34 | -| Docker | Linux x86_64/aarch64、Docker Engine 24+、Compose v2，以及可用的无特权用户命名空间 | | 94 | +| **参考** | [配置](docs/zh/reference/configuration.md) · [REST API](docs/zh/reference/rest-api.md) · [内置工具](docs/zh/reference/builtin-tools.md) · [运行时行为](docs/zh/reference/runtime-behavior.md) | |
| 95 | +| **解释** | [整体架构](docs/zh/explanation/architecture.md) 及[完整索引](docs/zh/explanation/README.md) | | ||
| 35 | 96 | ||
| 36 | -源码模式下 Gateway 要求 Python 3.12，`uv` 会在需要时将其安装到服务环境。托管科学环境使用应用固定版本的 micromamba，不要求系统安装 Python、R 或 conda。预打包二进制与 Docker 仍仅支持 Linux；本地源码模式同时支持 macOS，具体见部署指南。 | 97 | +完整中英文导航参见 [docs/README.md](docs/README.md)；开发环境与测试命令参见 [CONTRIBUTING.md](CONTRIBUTING.md)。 |
| 37 | - | ||
| 38 | -## 安装 | ||
| 39 | - | ||
| 40 | -准备与宿主架构匹配的 ScienceDiscovery 可执行文件。二进制打包、本地源码模式与 Docker 流程见[部署指南](docs/zh/how-to/deployment.md)。 | ||
| 41 | - | ||
| 42 | -## 快速开始 | ||
| 43 | - | ||
| 44 | -在 `ScienceDiscovery` 可执行文件所在目录启动服务： | ||
| 45 | - | ||
| 46 | -```bash | ||
| 47 | -chmod +x ./ScienceDiscovery | ||
| 48 | -./ScienceDiscovery serve | ||
| 49 | -``` | ||
| 50 | - | ||
| 51 | -另开终端执行 `curl -fsS http://127.0.0.1:4310/health`。随后打开启动日志中的 `Open to sign in` 链接，浏览器会自动保存本地服务访问令牌；它与外部模型 API Key 不同，请勿分享该链接。然后在 **系统配置 → Global defaults** 配置任务模型。第一次任务见[快速开始教程](docs/zh/tutorial/01-quick-start.md)；二进制打包、本地源码模式与 Docker 见[部署指南](docs/zh/how-to/deployment.md)。 | ||
| 52 | 98 | ||
| 53 | ## 许可证 | 99 | ## 许可证 |
| 54 | 100 | ||
| @@ -80,6 +80,7 @@ To inspect the UI without sandbox execution, start with `--skip-sandbox-check`; | |||
| 80 | 80 | ||
| 81 | ```text | 81 | ```text |
| 82 | ScienceDiscovery serve [options] Start the Web UI, control API and sandbox runner | 82 | ScienceDiscovery serve [options] Start the Web UI, control API and sandbox runner |
| 83 | +ScienceDiscovery run [input] [options] Run an agent task against a running serve, as a CLI client | ||
| 83 | ScienceDiscovery extract --to <dir> Extract the embedded runtime without starting it | 84 | ScienceDiscovery extract --to <dir> Extract the embedded runtime without starting it |
| 84 | ScienceDiscovery version Print the version and embedded Node, CPython, and micromamba versions | 85 | ScienceDiscovery version Print the version and embedded Node, CPython, and micromamba versions |
| 85 | ScienceDiscovery help Show help | 86 | ScienceDiscovery help Show help |
| @@ -98,6 +99,21 @@ ScienceDiscovery help Show help | |||
| 98 | 99 | ||
| 99 | The variables in [Configuration reference](../reference/configuration.md#environment-variables-local-mode) also apply and can be exported or placed in `--env-file`. The API and the runner bind to loopback by default. To expose the API, first replace `SCIENCE_AGENT_AUTH_TOKEN`, then explicitly use `--host 0.0.0.0` only on a trusted, protected network. | 100 | The variables in [Configuration reference](../reference/configuration.md#environment-variables-local-mode) also apply and can be exported or placed in `--env-file`. The API and the runner bind to loopback by default. To expose the API, first replace `SCIENCE_AGENT_AUTH_TOKEN`, then explicitly use `--host 0.0.0.0` only on a trusted, protected network. |
| 100 | 101 | ||
| 102 | +### The run subcommand (CLI client) | ||
| 103 | + | ||
| 104 | +The Web UI is the recommended surface for interactive work (open `http://127.0.0.1:4310` and sign in with the token `serve` printed). `run` is the command-line front end to that same `serve`: identical behaviour, meant for driving a task straight from a terminal or from a pipe or script. It loads the same token as `serve` (from `.env` or `--data-dir`), so nothing has to be passed explicitly. Files the agent produces land under `projects/<id>/sessions/<id>/workspace/` inside `--data-dir`, not in the current working directory; reach them there or through the Artifact panel in the Web UI. | ||
| 105 | + | ||
| 106 | +Start `serve` first, then run the client from a second terminal: | ||
| 107 | + | ||
| 108 | +```bash | ||
| 109 | +./ScienceDiscovery serve # terminal 1: the resident stack | ||
| 110 | +./ScienceDiscovery run "Write me a quicksort" # terminal 2: one agent task as a client | ||
| 111 | +``` | ||
| 112 | + | ||
| 113 | +It connects to `http://127.0.0.1:4310` by default and reads the token `serve` generated from `--data-dir` (default `./.sciencediscovery-data`), so sharing a `--data-dir` between `run` and `serve` needs no further setup. Typed directly at a terminal it defaults to **text mode** — the answer on stdout, progress on stderr, and a 1/2/3 choice when a permission card appears. In a pipe or a script it defaults to **jsonl mode** and requires an explicit `--auto-approve`, because a non-interactive run cannot answer a permission prompt and refuses to start instead. Full options: `./ScienceDiscovery run --help`. | ||
| 114 | + | ||
| 115 | +> In local source mode there is no `ScienceDiscovery` binary; run the client as `node services/launcher/dist/main.js run ...`, pointed at the `serve` that `start-stack.sh` started (same default address and data directory, so again no extra configuration). In Docker mode, do not run `run` inside the container; from the host, pass `--data-dir ./data` to point at the bind-mounted data directory (or give `--token` explicitly), and leave the rest at their defaults. | ||
| 116 | + | ||
| 101 | ### What the binary contains | 117 | ### What the binary contains |
| 102 | 118 | ||
| 103 | | Component | Description | | 119 | | Component | Description | |
| @@ -77,7 +77,7 @@ Once Neo4j is running, all configuration happens in System configuration → Mem | |||
| 77 | ### 2.1 Open settings | 77 | ### 2.1 Open settings |
| 78 | 78 | ||
| 79 | 1. Open the ScienceDiscovery Web UI (default <http://127.0.0.1:4310>) and sign in. | 79 | 1. Open the ScienceDiscovery Web UI (default <http://127.0.0.1:4310>) and sign in. |
| 80 | -2. Click the System configuration button (top right) to open the settings dialog. | 80 | +2. Click the System configuration button at the bottom of the left sidebar to open the settings dialog. |
| 81 | 3. Select Memory in the left-hand group list. | 81 | 3. Select Memory in the left-hand group list. |
| 82 | 82 | ||
| 83 | ### 2.2 Fill in the fields | 83 | ### 2.2 Fill in the fields |
| @@ -77,7 +77,7 @@ Neo4j 跑起来后，配置全部在 系统设置 → 记忆（Memory）里完 | |||
| 77 | ### 2.1 打开设置 | 77 | ### 2.1 打开设置 |
| 78 | 78 | ||
| 79 | 1. 打开 ScienceDiscovery Web UI（默认 <http://127.0.0.1:4310>）并登录。 | 79 | 1. 打开 ScienceDiscovery Web UI（默认 <http://127.0.0.1:4310>）并登录。 |
| 80 | -2. 点右上角 系统配置（System configuration）按钮，打开系统设置对话框。 | 80 | +2. 点左侧栏底部的 系统配置（System configuration）按钮，打开系统设置对话框。 |
| 81 | 3. 左侧分组列表里选 记忆（Memory）。 | 81 | 3. 左侧分组列表里选 记忆（Memory）。 |
| 82 | 82 | ||
| 83 | ### 2.2 填写四项 | 83 | ### 2.2 填写四项 |