# DataCore CLI

DataCore CLI 将平台能力提供给终端、自动化程序和 AI Agent。
首版覆盖完整电导率预测迭代流程，并沿用当前登录用户的 DataCore 权限。

- 人类文档：https://datacore-cli.dp.cd.mba/
- 命令清单：https://datacore-cli.dp.cd.mba/commands.json
- 基础 Skill：https://datacore-cli.dp.cd.mba/skills/datacore/SKILL.md
- 电导 Skill：https://datacore-cli.dp.cd.mba/skills/datacore-conductivity/SKILL.md


---

Source: /agents/index.md

# 让第三方 Agent 使用 DataCore

DataCore Agent 不是唯一入口。任何能够执行本地命令、读取文本并获得用户确认的 Agent，都可以通过 DataCore CLI 使用同一套平台能力。

## 接入方式

1. 用户安装 CLI 并完成 `datacore setup`；
2. Agent 读取 DataCore Skill 与电导 Skill；
3. Agent 先执行只读状态查询；
4. 对写操作展示目标、影响和下一步，获得确认后再加 `--yes`；
5. 长任务提交后查询状态，不因本地等待中断而重复创建任务。

```bash
datacore --json conductivity status '完整的 DataCore 电导页面 URL'
```

## Skills 在哪里

安装包会把 Skills 同步到 Codex 的 `~/.codex/skills/` 目录。其他 Agent 可以直接读取公开版本：

- [DataCore 基础 Skill](/skills/datacore/SKILL.md)
- [电导工作流 Skill](/skills/datacore-conductivity/SKILL.md)

如果 Agent 不支持 Skill 发现机制，也可以读取 [llms.txt](/llms.txt)、[完整上下文](/llms-full.txt) 和 [commands.json](/commands.json)。

## 为什么统一走 CLI

- **权限一致**：Agent 与网页使用同一 DataCore 用户；
- **业务规则一致**：不在 Prompt、脚本或不同 Agent 中重复实现校验逻辑；
- **错误一致**：稳定错误码会给出明确的恢复动作；
- **可替换**：Agent 可以增加、替换或下线，不影响平台核心工作流。

## 不要这样做

- 不要让用户在聊天中发送 Bohrium AccessKey；
- 不要绕过 DataCore 返回的权限、校验或生命周期错误；
- 不要把本地等待超时当成云任务失败；
- 不要在未确认时上传、训练或开启下一轮。


---

Source: /getting-started/authentication.md

# 身份、授权与权限

## 登录的是 DataCore 平台账号

```bash
datacore auth login
```

命令会打开 DataCore 授权页。用户可以使用平台密码、飞书或 Bohrium 登录；无论入口是什么，最终都解析为同一个 DataCore 用户身份。

CLI 不创建第二套账号，也不拥有独立的数据权限。项目、实验、数据和操作权限全部由 DataCore 后端统一判断。

## 凭据如何保存

- 交互式登录默认把可撤销的短期授权保存到操作系统 Keychain；
- 无桌面环境使用 `DATACORE_TOKEN`，不要写进仓库或命令历史；
- 本地文件保存默认关闭，只有用户明确传入 `--allow-file-credential` 才启用；
- Bohrium AccessKey 不出现在命令参数、日志、Prompt 或导出文件中。

## 查看与撤销

```bash
datacore auth status
datacore auth logout
```

用户也可以在 DataCore 个人中心查看和撤销已经授权的 CLI 客户端。撤销后，本机持有的旧授权不能继续访问平台。

## 写操作确认

查询和校验可以直接执行；上传、推荐、训练、重试、决策和开启下一轮等操作必须先确认目标，再传入 `--yes`。这一约束同时适用于人和 Agent。


---

Source: /getting-started/install.md

# 安装与快速开始

DataCore CLI 需要 Python 3.10 或更高版本。安装程序只写入当前用户目录，不需要管理员权限。

## macOS / Linux

```bash
curl -fsSL https://github.com/dptech-yb/datacore-cli/releases/latest/download/install.sh | sh
```

## Windows PowerShell

```powershell
irm https://github.com/dptech-yb/datacore-cli/releases/latest/download/install.ps1 | iex
```

安装脚本会完成三件事：

1. 从官方 GitHub Release 下载 wheel；
2. 用同一 Release 的 `SHA256SUMS` 校验文件；
3. 安装 CLI、同步 Skills，并打开 DataCore 授权页。

安装完成后检查：

```bash
datacore setup
datacore doctor
datacore auth status
```

`datacore setup` 会同步 DataCore Skills，并在浏览器中打开平台授权页。密码、飞书和 Bohrium 登录最终都绑定到当前 DataCore 平台账号。

## 固定版本

生产环境可以固定到明确版本：

```bash
curl -fsSL https://github.com/dptech-yb/datacore-cli/releases/latest/download/install.sh \
  | sh -s -- --version v0.1.0 --no-setup
```

也可以从 [GitHub Releases](https://github.com/dptech-yb/datacore-cli/releases) 下载 wheel、校验和、SBOM 和 Sigstore bundle。

## 更新与卸载

```bash
datacore update
datacore uninstall --yes
```

更新会同步 CLI 与 Skills。卸载会撤销当前设备授权，并清理 CLI 与 DataCore Skills。


---

Source: /reference/commands.md

# CLI 命令参考

> 本页由 CLI 参数定义自动生成。命令变更后，文档构建会同步更新并检查差异。

## `datacore setup`

安装 Skills 并登录 DataCore

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |
| `--no-browser` | — |
| `--allow-file-credential` | — |

## `datacore doctor`

检查 CLI、Skills、网络和授权状态

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |

## `datacore update`

升级 CLI 并同步 Skills

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |
| `--version` | — |

## `datacore uninstall`

撤销授权并卸载 CLI 与 Skills

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |
| `--yes` | — |

## `datacore auth login`

在浏览器中授权当前设备

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |
| `--no-browser` | — |
| `--allow-file-credential` | — |

## `datacore auth logout`

撤销当前设备授权

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |

## `datacore auth status`

查看当前登录身份与授权状态

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |

## `datacore skills install`

将内置 Skills 同步到本机

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |
| `--force` | — |

## `datacore skills list`

列出 CLI 自带的 Skills

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |

## `datacore conductivity status`

查看轮次状态与下一步动作

### 参数

| 名称 | 必填 | 可选值 |
| --- | --- | --- |
| `target` | 是 | — |

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |

## `datacore conductivity recommend`

提交本轮推荐配方计算

### 参数

| 名称 | 必填 | 可选值 |
| --- | --- | --- |
| `target` | 是 | — |

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |
| `--yes` | — |
| `--wait` | — |
| `--timeout` | — |

## `datacore conductivity export`

导出 UniLab、称量单或示例文件

### 参数

| 名称 | 必填 | 可选值 |
| --- | --- | --- |
| `target` | 是 | — |

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |
| `--format` | — |
| `--output` | — |
| `--total-mass-g` | — |

## `datacore conductivity train`

提交五折训练并跟踪状态

### 参数

| 名称 | 必填 | 可选值 |
| --- | --- | --- |
| `target` | 是 | — |

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |
| `--yes` | — |
| `--wait` | — |
| `--timeout` | — |

## `datacore conductivity compare`

比较当前模型与推荐基线

### 参数

| 名称 | 必填 | 可选值 |
| --- | --- | --- |
| `target` | 是 | — |

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |

## `datacore conductivity next`

确认并开启下一轮

### 参数

| 名称 | 必填 | 可选值 |
| --- | --- | --- |
| `target` | 是 | — |

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |
| `--yes` | — |

## `datacore conductivity validate`

只读校验实测 CSV

### 参数

| 名称 | 必填 | 可选值 |
| --- | --- | --- |
| `target` | 是 | — |
| `file` | 是 | — |

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |

## `datacore conductivity upload`

校验并上传实测 CSV

### 参数

| 名称 | 必填 | 可选值 |
| --- | --- | --- |
| `target` | 是 | — |
| `file` | 是 | — |

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |
| `--yes` | — |
| `--no-merge` | — |

## `datacore conductivity retry-fold`

只重试一个未完成训练折

### 参数

| 名称 | 必填 | 可选值 |
| --- | --- | --- |
| `target` | 是 | — |

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |
| `--fold` | — |
| `--yes` | — |

## `datacore conductivity decide`

记录继续或停止的轮次结论

### 参数

| 名称 | 必填 | 可选值 |
| --- | --- | --- |
| `target` | 是 | — |
| `decision` | 是 | continue / stop |

### 选项

| 选项 | 说明 |
| --- | --- |
| `--base-url` | — |
| `--json` | — |
| `--request-id` | 为本次调用指定可追踪请求 ID |
| `--timeout` | HTTP 请求超时秒数 |
| `--version` | show program's version number and exit |
| `--reason` | — |
| `--yes` | — |


---

Source: /reference/output-contract.md

# 结构化输出约定

自动化程序和 Agent 应始终加全局选项 `--json`。

## 成功

```json
{
  "ok": true,
  "command": "conductivity.status",
  "summary": "当前轮次状态已获取",
  "data": {},
  "artifacts": [],
  "warnings": []
}
```

- `summary`：可直接展示给用户的简短结论；
- `data`：命令相关结构化结果；
- `artifacts`：生成文件的路径、大小和类型；
- `warnings`：不阻断操作但需要用户知道的信息。

## 失败

```json
{
  "ok": false,
  "error": {
    "code": "permission_denied",
    "message": "当前用户无权访问目标实验",
    "action": "请确认项目成员关系或联系项目管理员。",
    "retryable": false,
    "details": {}
  }
}
```

Agent 应优先遵循 `action`，并根据 `retryable` 判断是否能做有限重试。权限、校验和生命周期错误不是可绕过的客户端限制。

## 请求追踪

```bash
datacore --request-id my-run-20260828 --json conductivity status TARGET
```

为自动化调用设置稳定请求 ID，便于把客户端日志与 DataCore 服务端审计关联起来。


---

Source: /security.md

# 安全与发布可信度

## 权限边界

CLI 是 DataCore 的确定性执行层，不是权限代理。每个请求都以当前登录用户身份进入平台，后端继续执行项目、实验和操作权限判断。

## 凭据保护

- DataCore 授权优先保存在系统 Keychain；
- Bohrium AccessKey 由平台按用户加密管理，不进入 CLI 参数；
- 无桌面自动化使用可撤销的 `DATACORE_TOKEN`；
- 日志、Prompt、导出文件和错误详情不得包含秘密。

## 发布产物

每个 GitHub Release 提供：

- Python wheel 与源码包；
- SHA256 校验清单；
- CycloneDX SBOM；
- Sigstore 签名 bundle；
- GitHub Artifact Attestation 构建来源证明。

一键安装脚本会在安装前校验 wheel 的 SHA256。发布工作流从仓库标签自动构建，不使用开发者本机产物。

## 报告漏洞

请使用 GitHub 的私密漏洞报告，不要公开提交可能涉及凭据泄露、越权、命令注入或供应链篡改的问题。详见仓库 [SECURITY.md](https://github.com/dptech-yb/datacore-cli/blob/main/SECURITY.md)。


---

Source: /troubleshooting.md

# 故障恢复

先运行：

```bash
datacore doctor
datacore auth status
datacore --json conductivity status TARGET
```

## 登录或授权失效

重新运行 `datacore auth login`。不要借用或索取其他人的 Token。

## 权限不足

当前 DataCore 用户没有目标项目或实验权限。确认项目成员关系；不要切换身份或绕过后端判断。

## 实测文件校验失败

先执行只读的 `validate`。根据返回的行、列、推荐编号或数值问题修正文件，再上传。上传时服务端还会复检。

## Bohrium 凭据错误

由用户在 DataCore 中管理自己的 AccessKey 与项目号。CLI 不使用平台默认凭据，也不会要求在聊天或命令行中输入密钥。

## 本地等待超时

云端任务可能仍在执行。先查询 `status`，不要直接重复提交。

## 五折只有部分失败

状态会分别显示五折。使用 `retry-fold --fold N --yes` 只补交失败或未启动的折，已完成的折不会重建。

## 临时服务错误或限流

查看错误中的 `retryable` 和 `action`。可重试错误使用有限次数的退避重试，重试前仍需先查状态，避免重复创建任务。


---

Source: /workflows/conductivity.md

# 电导率预测迭代

首版 CLI 覆盖 DataCore 大装置电导率预测迭代。推荐使用完整页面 URL 作为 `TARGET`，它同时保留实验、链路和轮次身份。

## 1. 查看当前状态

```bash
datacore --json conductivity status TARGET
```

以服务端返回的 `nextAction` 为准，不根据页面位置或本地记录猜测下一步。

## 2. 生成并导出本轮推荐

```bash
datacore conductivity recommend TARGET --wait --yes
datacore conductivity export TARGET --format unilab --output task.xls
```

推荐计算使用当前用户在 DataCore 中保存的 Bohrium 凭据和项目号。CLI 不接受命令行 AccessKey，也不会退回平台自带凭据。

## 3. 校验并上传实测结果

```bash
datacore conductivity validate TARGET measured.csv
datacore conductivity upload TARGET measured.csv --yes
```

`validate` 只读；`upload` 会在服务端再次校验，并按推荐编号把 UniLab 回传值与本轮推荐配方关联。默认顺便合并训练数据，只有明确需要时才使用 `--no-merge`。

## 4. 五折训练

```bash
datacore conductivity train TARGET --wait --yes
```

状态查询会分别显示五折。若某一折失败，只重试未完成的折：

```bash
datacore conductivity retry-fold TARGET --fold 3 --yes
```

服务端保留已经完成的折，不重复提交。

## 5. 比较、决策和下一轮

```bash
datacore conductivity compare TARGET
datacore conductivity decide TARGET continue --reason "继续优化" --yes
datacore conductivity next TARGET --yes
```

`next` 使用链路尾部冻结的配置，不接受 Agent 临时生成的实验参数。

## 长任务

`--wait` 只是本地观察。关闭终端、断网或本地超时不会取消云端工作；再次执行 `status` 即可继续跟踪。


---

Source: /skills/datacore/SKILL.md

---
name: datacore
description: "Use DataCore platform capabilities through the datacore CLI. Apply when a user asks to inspect or operate DataCore projects, experiments, conductivity optimization, reports, tools, reservations, reagents, or other DataCore resources. The CLI always acts as the signed-in DataCore user and preserves platform permissions."
---

# DataCore

Use `datacore` as the deterministic execution layer. Do not reproduce DataCore business rules in shell, Python, or the model.

1. Run read-only discovery or status commands before proposing a write.
2. Use `--json` when another program or agent will consume the result.
3. For a write or cloud-compute command, show the resolved target and action, obtain explicit confirmation, then pass `--yes`.
4. Never request, print, log, or pass Bohrium AccessKeys on the command line. Compute commands use the current user's encrypted credential already managed by DataCore.
5. Treat permission, validation, and lifecycle errors as authoritative platform decisions. Follow the returned `action`; do not bypass them.
6. If the task concerns conductivity optimization, read the sibling `datacore-conductivity/SKILL.md` and follow it.

Read [CLI conventions](references/cli-conventions.md) only when authentication, JSON output, files, or error recovery matters.


---

Source: /skills/datacore-conductivity/SKILL.md

---
name: datacore-conductivity
description: "Inspect and operate DataCore's conductivity Bayesian-optimization loop through the datacore CLI. Apply for conductivity round status, recommendations, UniLab exports, measured-result validation/upload, five-fold training, fold recovery, model comparison, stop/continue decisions, or opening the next round."
---

# Datacore Conductivity

Accept the full DataCore conductivity page URL as the preferred target. It preserves experiment, chain, and round identity; a raw `round...` identifier is acceptable only for round-scoped actions.

Follow the lifecycle instead of guessing:

1. Run `datacore --json conductivity status TARGET`.
2. Execute only the next valid action reported by DataCore.
3. Validate a returned CSV before upload. Validation is read-only.
4. Before recommend, upload, train, retry, decide, or next, summarize the exact action and obtain explicit confirmation; only then pass `--yes`.
5. After submitting cloud work, report that it is queued/running and use status polling. Never treat a local timeout as task failure.
6. Show all five fold states when training. Retry only unfinished work; completed folds must not be duplicated.
7. Use the user's own remembered Bohrium credential. Never substitute a platform credential and never ask for a secret in chat.

Read [commands](references/commands.md) for exact syntax. Read [recovery](references/recovery.md) only when a command returns an error or a long-running operation stalls.