跳至主要內容

TimechoCLI

大约 40 分钟

TimechoCLI

1. 简介

TimechoCLI 是 Timecho 面向终端用户、自动化脚本和 AI Agent 推出的统一命令行工具，配套官方 Skills，以自然语言打通 TimechoDB、Apache IoTDB 与 Timecho AI 的产品使用链路，降低使用门槛，打通 DB × AI 的最后一公里。

面向 TimechoDB，CLI 提供从部署激活、SQL 执行、数据导入导出到运维诊断的全链条调度能力；面向 Timecho AI，支持数据载入、模型推理调度及结果可视化，并通过配套 Skills 减少命令臆造与参数误用，提升操作准确率。

TimechoCLI 兼容 Codex、Claude Code、Hermes 等主流 Agent 环境，为 Timecho 全产品线提供低门槛的 Agent 操作入口。

2. 下载与安装

2.1 环境要求

  • 目标机：Linux / macOS / Windows（amd64、arm64）
  • 零依赖静态二进制（CGO_ENABLED=0），不需预装 Node/Python/JRE
  • 连库需目标 TimechoDB 实例 RPC 端口可达（默认 6667）

2.2 安装方式

方式 A：快捷安装，把如下这句话发给Agent，Agent会自动安装完成

帮我安装 TimechoCLI：https://timecho.com/timecho-cli/installation-guide.md

方式 B：npm 全局安装（Windows、Mac和linux 跨平台都适用）

npm install -g @timecho/timecho-cli

2.3 验证

timecho-cli version
timecho-cli --help

3. 命令总览

timecho-cli
├── activate         激活管理（machine-code/apply/status）
├── ai               Timecho AI 服务
│   ├── ping         测试 AI 连通性和认证
│   ├── dimensions   列出数据质量评估维度
│   ├── evaluate     评估时序表数据质量
│   └── forecast     序列预测（单/多目标）
├── completion       Shell 补全（bash/zsh/fish/powershell）
├── config           配置管理（get/set/diff/tune/schema）
├── ctx              连接上下文管理（add/list/show/use/update/remove/discover）
├── data             数据导入导出
│   ├── import
│   │   ├── csv      CSV 批量导入（Tree/Table mapping）
│   │   └── tsfile   TsFile 服务端路径 LOAD
│   └── export
├── diagnose         远程+本地脱敏诊断包
├── setup
│   └── skills       安装 Skills 到 Claude/Codex/OpenClaw/Hermes
├── sql              执行 SQL（tree/table 方言，支持 -f/--stdin）
├── status           健康汇总（版本/激活/集群/Region/磁盘）
└── version          显示 CLI 版本号

注：TsFile 导出不在 CLI 原语内，走 tsfile-backup 脚本或 Pipe tsfile-local-sink；AI 子树不读 DB Context。

4. 全局参数

所有子命令均可前缀以下参数：

参数简写说明
--ctx-指定数据库连接上下文名称（不适用于 ai 子命令）
--help-h显示命令帮助信息
--json-输出稳定的 JSON Envelope（含 api_version、kind、data 等字段）
--no-color-禁用彩色输出
--non-interactive-禁止交互式输入（适用于 CI/CD 等自动化脚本）
--output-o指定输出格式：human（默认）、json 或 csv
--sql-dialect-临时覆盖数据库 SQL 方言：tree 或 table（不适用于 ai 子命令）
--timeout-设置命令整体超时时间（如 30s、2m、1h）
--trace-id-在结构化输出中附加自定义 Trace ID，便于链路追踪
--verbose-v启用详细诊断日志，输出到 stderr
--yes-y自动确认高风险操作，无需手动输入确认

说明：

  • --json 等价于选择 JSON 输出；不要同时显式传入冲突的 --output human 或 --output csv。
  • --output csv 主要用于返回结果集的 sql 查询；非查询 SQL 不接受 CSV 输出。
  • 全局参数可以写在子命令前后，但团队脚本建议统一放在一级命令前，便于阅读。
  • --non-interactive 只负责禁止提示，不会自动同意高风险操作；需要授权时仍应传入 --yes。
  • --yes 只表示确认写操作，不会绕过参数、安全、版本或校验和检查。
  • --verbose 的诊断信息写入 stderr，不应与 JSON/CSV stdout 混合。
  • ai 复用输出、超时、自动化和诊断类全局参数，但会拒绝显式传入的 --ctx 与 --sql-dialect。

4.1 全局参数示例

timecho-cli --ctx prod sql "show version"
timecho-cli --ctx prod --json status
timecho-cli --ctx prod --timeout 30s sql "show cluster"
timecho-cli \
  --ctx prod \
  --json \
  --non-interactive \
  --trace-id request-20260721-001 \
  status

临时覆盖 SQL 方言：

timecho-cli --ctx prod --sql-dialect table sql "show databases"

开启详细日志：

timecho-cli --ctx prod --verbose diagnose

JSON 与显式输出格式冲突，以下写法会在连接数据库前失败：

timecho-cli --json --output csv version

5. Skills

#技能名称说明
1timecho-cli-guide统一 timecho-cli 命令指南：运行/编写/解释/调试/验证/自动化任意 timecho-cli 命令前必读，以运行时 --help 为准，不臆造标志与参数。
2timecho-forecast时序预测与绘图：通过 timecho-cli 对 CSV/TSV/JSON 做预测，支持预测步数、历史/未来协变量、模型选择、结果保存与图表生成。
3timechoai-cli-guideTimecho AI 命令指南：ai ping/ai forecast/ai key 的使用、连通性检查、API Key 管理、输出与凭证行为。
4timechodb-backup-restore备份与恢复：schema 导出、TsFile 备份、全量/增量策略、PITR 容灾演练、树/表模型处理。
5timechodb-benchmark基准测试：集成 iot-benchmark，按机器资源自动伸缩规模（写入点/秒、延迟百分位、混合查询），输出结构化指标。
6timechodb-client-ref客户端接入参考：Java、JDBC、C++、Python、REST、Spring Boot、MyBatis、Go、C、MQTT 等接入的选型与审查。
7timechodb-config-advisor配置咨询：按 CPU/内存/磁盘与部署场景（1C1D/3C3D/双活）推荐关键参数并对比差异。
8timechodb-config-manage配置管理：查看/修改/校验配置，支持 --dry-run 预览、不可变参数拦截、高风险操作确认。
9timechodb-data-ops数据运维：批量执行 SQL、初始化测试数据、数据清理、导入 TsFile、TTL、连续查询等。
10timechodb-deploy-2active双活部署：两实例双向 Pipe 同步、断点续传校验。
11timechodb-deploy-cluster集群部署：3C3D 或自定义 Cn/Dn 规模、seed 加入、多副本、跨节点连通。
12timechodb-deploy-dockerDocker 部署：1C1D/1C2D/3C3D Compose 模板、持久卷、端口映射、版本锁定。
13timechodb-deploy-standalone单机部署：1C1D 一键部署，自定义端口/路径/内存，自动校验节点运行状态。
14timechodb-faq-diag故障诊断：启动失败、连接拒绝、OOM、副本不一致、WAL 异常、配置错误等的问答式根因分析。
15timechodb-health-check深度健康检查：磁盘、CPU、内存、WAL 积压、写入吞吐、Pipe 延迟、TsFile 数量、Compaction 队列。
16timechodb-knowledge-base知识库：官方用户手册，查 Release Notes、配置项、错误码、树表差异、SQL 语法、部署运维文档，对比本地与最新版本。
17timechodb-log-analyze日志分析：OOM、GC、WAL flush、Compaction 异常、线程激增、连接池耗尽等 ERROR/WARN 分析并出报告。
18timechodb-monitor-integrate监控集成：Prometheus + Grafana，开启指标、配置端口、导入 dashboard、关联 OS 指标。
19timechodb-node-ops节点运维：扩缩容、数据迁移、Region 均衡、热节点排水、启停顺序、jstack 死锁诊断。
20timechodb-pipe-syncPipe 数据同步：站到中心、全量/增量/级联、网闸穿透、加密压缩、双活镜像、延迟监控。
21timechodb-rn-issue-resolver需求/问题解析：将 Release Notes 或 Issue 转为可执行操作（参数调整、补丁、复现步骤）。
22timechodb-schema-genSchema 生成：按设备层级或表模型生成树/表 DDL（CREATE DATABASE、CREATE TIMESERIES 等）。
23timechodb-sql-devSQL 开发：开发/审查/调试 SQL，明确树表方言边界，查询模板、路径绑定、聚合等。
24timechodb-test-gen测试生成：从知识库生成部署验证、RN 缺陷、性能回归测试用例（步骤+预期+报告）。
25timechodb-text2sql自然语言转 SQL：将自然语言请求转为一条可执行 SQL，处理树/表方言、路径绑定、时间语义。
26timechodb-tier-storage分层存储：热(SSD)→温→冷(对象存储/HDD) 自动分层、访问频率规则、查询调度与参数调优。
27timechodb-tree-table-guide树表模型指南：树模型 vs 表模型选择、层级路径设计、TAG/ATTRIBUTE/FIELD 映射。
28timechodb-upgrade-rollback升级与回滚：下载目标版本、备份配置与元数据、滚动/停机升级、兼容性校验、回滚。

6. 大模型交互使用示例

以下示例均可直接对大模型说：

6.1 前置操作

6.1.1 安装 CLI 并接入 Skills

帮我安装 TimechoCLI：https://timecho.com/timecho-cli/installation-guide.md
帮我更新 TimechoCLI：https://timecho.com/timecho-cli/installation-guide.md

6.1.2 单机 TimechoDB 一键部署 + 激活（安装）

帮我在本机 D:\timecho 部署一套单机版（1C1D）TimechoDB，软件包 D:\TimechoDB\timechodb-2.0.10.2-bin.zip 部署完成后激活授权并确认服务可用。

6.2 多种场景

6.2.1 场景 1：启动 TimechoDB

检查我的 TimechoDB 启动状态，如未启动请帮忙启动，并确认服务可用。

6.2.2 场景 2：连接巡检 + 深度健康检查 + 诊断包（运维·巡检）

帮我做一次 TimechoDB 全面巡检：看整体健康状态、磁盘/内存/WAL/Compaction 有没有异常，并生成巡检报告。

6.2.3 场景 3：配置巡检与调优（运维·配置）

帮我看看当前 TimechoDB 配置和推荐值差在哪，把内存、WAL、Compaction 等关键参数按这台机器的资源调优，但先别真的改。

6.2.4 场景 4：SQL 开发 / Text2SQL + 数据导入导出（运维·数据开发）

帮我把这个 CSV table_metrics.csv 导进 TimechoDB 的表模型中的 test 数据库中。如果表已存在请先删除表，并支持我用自然语言查数据：比如“最近 1 小时每台设备的平均温度，输出 CSV”。

6.2.5 场景 5：SQL 开发 / OBJECT 数据导入

帮我在表模型下创建数据库 object_test，并创建表 device_obj。

建表 DDL 如下：
CREATE TABLE "device_obj" (
  "device_id" STRING TAG,
  "file_name" STRING ATTRIBUTE,
  "file_size" INT32 FIELD,
  "file_data" OBJECT FIELD
) WITH (ttl='INF');

将 D:\TimechoDB 目录下的图片插入到 device_obj 表中。

6.2.6 场景 6：故障诊断 + 日志分析（运维·排障）

我的 DB 报如下错误，帮我定位根因并给出修复步骤。
There is not enough memory to execute current fragment instance, current remaining free memory is 86762854, estimated memory usage for current fragment instance is 270139392
我的 DB 报如下错误，帮我定位根因并给出修复步骤。
2026-08-21 10:12:33.815 [main] ERROR o.a.i.db.service.DataNodeStartUpCheck:70 - Reject DataNode restart.
Please clean the data directory before starting.
org.apache.iotdb.exceptions.StartupException: 203: Start up error. DataNode has been registered to cluster, but data directory is not empty. Please clean the data/datanode/ directory and restart.
at org.apache.iotdb.db.service.DataNodeStartUpCheck.check(DataNodeStartUpCheck.java:68)
at org.apache.iotdb.db.service.IoTDB.startup(IoTDB.java:120)
at org.apache.iotdb.db.service.IoTDBEntryPoint.main(IoTDBEntryPoint.java:45)
2026-08-21 10:12:33.820 [main] ERROR org.apache.iotdb.db.service.IoTDB:152 - Failed to start IoTDB DataNode
because: 203: Start up error. DataNode has been registered to cluster, but data directory is not empty.
我的 DB 报如下错误，帮我定位根因并给出修复步骤。
2026-08-21 14:25:07.332 [pool-3-thread-1] WARN o.a.i.db.mpp.execution.FragmentInstanceManager:218 - Failed to execute fragment instance, instance_id=20260821_142507_00001_00003
org.apache.iotdb.exceptions.QueryProcessException: 709: MPP task execution memory is not enough.
current remaining free memory is 86762854, estimated memory usage for current fragment instance is 270139392.
Please try to reduce the query range or increase the memory allocation.
at org.apache.iotdb.db.mpp.execution.FragmentInstanceManager.checkMemory(FragmentInstanceManager.java:210)
at org.apache.iotdb.db.mpp.execution.FragmentInstanceManager.start(FragmentInstanceManager.java:165)
at org.apache.iotdb.db.mpp.plan.planner.DistributionPlanner.plan(DistributionPlanner.java:98)
at org.apache.iotdb.db.mpp.plan.Planner.planQuery(Planner.java:76)
at org.apache.iotdb.db.mpp.sql.Analyzer.analyzeQuery(Analyzer.java:112)
2026-08-21 14:25:07.335 [pool-3-thread-1] ERROR org.apache.iotdb.db.mpp.plan.PlanProcessor:89 - Failed to process query: SELECT * FROM root.sg_1.d_1.* WHERE time > 2026-08-01T00:00:00.000+08:00
我的 DB 报如下错误，帮我定位根因并给出修复步骤。
2026-08-21 09:03:15.441 [disk-space-monitor-1] WARN o.a.i.db.engine.StorageEngine:342 - Disk space is insufficient. Path: D:\TimechoDB\data\datanode\data,
usage: 89.2%, threshold: 85.0%. System will switch to read-only mode.
2026-08-21 09:03:15.443 [disk-space-monitor-1] ERROR o.a.i.db.engine.StorageEngine:356 - 611: Disk space is insufficient. Triggering system read-only protection.
2026-08-21 09:03:15.445 [disk-space-monitor-1] WARN o.a.i.db.service.IoTDB:430 - System is now in READ_ONLY mode. All write operations will be rejected.
To restore write capability: clean up disk space and execute 'SET SYSTEM TO RUNNING ON CLUSTER;'.
2026-08-21 09:05:22.118 [ClientPool-thread-3] ERROR org.apache.iotdb.db.writelog.WriteLogManager:178 - Failed to write WAL: 600: System is read-only. Write operation rejected.
insert into root.sg_1.d_1(timestamp, s_1) values (2026-08-21T09:05:22.000+08:00, 42.5)

7. 命令行使用示例

7.1 Context 连接上下文管理

7.1.1 ctx add：添加上下文

基本语法

timecho-cli ctx add NAME [flags]

添加远程 Tree 模式数据库

timecho-cli ctx add prod \
  --host db.example.com \
  --port 6667 \
  --user root \
  --dialect tree

如果当前是交互式终端，命令会提示输入密码，直接回车可跳过保存；也可以通过 stdin 输入并保存到系统 Keychain：

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli ctx add prod \
    --host db.example.com \
    --port 6667 \
    --user root \
    --dialect tree \
    --password-stdin

在 --json 或 --non-interactive 模式下不会弹出密码提示。若没有使用 --password-stdin，Context 仍可创建，但凭据状态会是 missing，后续数据库命令需要通过环境变量或 Keychain 提供密码。

添加 Table 模式上下文

timecho-cli ctx add table-prod \
  --host db.example.com \
  --port 6667 \
  --user root \
  --dialect table \
  --database telemetry

添加本地安装上下文 Linux：

timecho-cli ctx add local-dev \
  --kind local \
  --local /opt/timecho \
  --host 127.0.0.1 \
  --port 6667

Windows PowerShell：

timecho-cli ctx add local-dev `
  --kind local `
  --local "D:\timecho" `
  --host 127.0.0.1 `
  --port 6667

添加集群节点

timecho-cli ctx add cluster-prod \
  --host db1.example.com \
  --port 6667 \
  --nodes db1.example.com:6667,db2.example.com:6667,db3.example.com:6667 \
  --user root

也可以重复指定：

timecho-cli ctx add cluster-prod \
  --nodes db1.example.com:6667 \
  --nodes db2.example.com:6667 \
  --nodes db3.example.com:6667

配置查询参数

timecho-cli ctx add prod \
  --host db.example.com \
  --connect-timeout 10s \
  --query-timeout 2m \
  --fetch-size 4096 \
  --rpc-compression

添加 TLS 上下文

timecho-cli ctx add prod-tls \
  --host db.example.com \
  --port 6667 \
  --tls \
  --ca /etc/timecho/tls/ca.pem \
  --server-name db.example.com

添加双向 TLS 上下文

timecho-cli ctx add prod-mtls \
  --host db.example.com \
  --port 6667 \
  --tls \
  --ca /etc/timecho/tls/ca.pem \
  --cert /etc/timecho/tls/client.pem \
  --key /etc/timecho/tls/client-key.pem \
  --server-name db.example.com

7.1.2 ctx list：列出上下文

timecho-cli ctx list

JSON 输出：

timecho-cli ctx list --json

7.1.3 ctx show：查看上下文

查看当前上下文：

timecho-cli ctx show

查看指定上下文：

timecho-cli ctx show prod

JSON 输出：

timecho-cli ctx show prod --json

输出中不会返回 Keychain 中保存的明文密码。

7.1.4 ctx use：切换当前上下文

timecho-cli ctx use prod

切换后，后续命令可以省略 --ctx prod：

timecho-cli status
timecho-cli sql "show version"

7.1.5 ctx update：更新上下文

只修改显式传入的参数。

修改主机和端口

timecho-cli ctx update prod \
  --host new-db.example.com \
  --port 6668

修改用户名和密码

printf '%s\n' "$NEW_TIMECHODB_PASSWORD" |
  timecho-cli ctx update prod \
    --user admin \
    --password-stdin

修改 SQL 方言

timecho-cli ctx update prod \
  --dialect table \
  --database telemetry

启用 TLS

timecho-cli ctx update prod \
  --tls \
  --ca /etc/timecho/tls/ca.pem \
  --server-name db.example.com

修改超时和 Fetch Size

timecho-cli ctx update prod \
  --connect-timeout 20s \
  --query-timeout 5m \
  --fetch-size 8192

修改集群节点列表

timecho-cli ctx update prod \
  --nodes db1.example.com:6667,db2.example.com:6667

7.1.6 ctx remove：删除上下文

只删除上下文配置，不删除 Keychain 密码，也不要求确认：

timecho-cli ctx remove old-prod

同时删除 Keychain 中保存的密码属于需要确认的操作：

timecho-cli ctx remove old-prod \
  --delete-secret \
  --yes

交互式终端中可以省略 --yes 并按提示确认；JSON 或 --non-interactive 模式下必须显式传入 --yes。

7.1.7 ctx discover：发现本地安装

自动搜索常见安装目录：

timecho-cli ctx discover

指定候选根目录：

timecho-cli ctx discover --root /opt

指定多个目录：

timecho-cli ctx discover \
  --root /opt/timecho \
  --root /srv/iotdb

Windows：

timecho-cli ctx discover `
  --root "C:\Timecho" `
  --root "D:\Apache-IoTDB"

JSON 输出：

timecho-cli ctx discover --json

ctx discover 只发现安装目录，不会自动修改 Context 配置。

7.2 SQL 执行

7.2.1 直接执行 SQL

timecho-cli --ctx prod sql "show version"
timecho-cli --ctx prod sql "show cluster"
timecho-cli --ctx prod sql "select * from root.sg.d1 limit 100"

7.2.2 JSON 输出

timecho-cli --ctx prod --json sql "show version"
timecho-cli --ctx prod --output json sql \
  "select * from root.sg.d1 limit 100"

7.2.3 CSV 输出

输出到终端：

timecho-cli --ctx prod --output csv sql \
  "select * from root.sg.d1 limit 100"

重定向到文件：

timecho-cli --ctx prod --output csv sql \
  "select * from root.sg.d1" > result.csv

7.2.4 从 SQL 文件执行

创建 SQL 文件：

select * from root.sg.d1 limit 100

执行：

timecho-cli --ctx prod sql --file query.sql

简写：

timecho-cli --ctx prod sql -f query.sql

7.2.5 从 stdin 执行

printf '%s\n' "show version" |
  timecho-cli --ctx prod sql --stdin

从文件管道输入：

cat query.sql |
  timecho-cli --ctx prod sql --stdin

PowerShell：

Get-Content .\query.sql -Raw |
  timecho-cli --ctx prod sql --stdin

7.2.6 强制按查询执行

当 SQL 无法自动判断类型时：

timecho-cli --ctx prod sql \
  --query \
  "show cluster"

7.2.7 强制按非查询执行

timecho-cli --ctx prod sql \
  --non-query \
  "create database root.demo"

7.2.8 使用 Table 方言

使用 Context 中配置的 Table 方言：

timecho-cli --ctx table-prod sql "show databases"

临时覆盖方言：

timecho-cli \
  --ctx prod \
  --sql-dialect table \
  sql "show databases"

7.2.9 通过 stdin 输入数据库密码

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod \
    sql "show version" \
    --password-stdin

7.2.10 设置超时

timecho-cli --ctx prod \
  --timeout 2m \
  sql "select * from root.sg.**"

7.2.11 安全显示 BLOB 二进制列

READ_OBJECT(...) 等查询会返回 BLOB。human 模式默认只显示安全的大小摘要，不会把任意二进制字节直接写入终端：

timecho-cli --ctx table-prod sql \
  "select read_object(file_data) from object_test where device_id='pile-img-001'"

需要可复制的内容时，显式选择 Base64 或十六进制：

timecho-cli --ctx table-prod sql \
  --binary-encoding base64 \
  "select read_object(file_data) from object_test where device_id='pile-img-001'"

timecho-cli --ctx table-prod sql \
  --binary-encoding hex \
  "select read_object(file_data) from object_test where device_id='pile-img-001'"

显式选择编码时，human 与 CSV 输出中的二进制值带 base64: 或 hex: 前缀；

未指定编码的 human 模式继续显示大小摘要。JSON 查询输出中的二进制值是不带前缀的编码字符串，并在 data.types 和 data.binary_encoding 中声明列类型与编码；未指定时 JSON/CSV 默认使用 Base64。--binary-encoding 只接受 base64 或 hex。

SQL 命令只允许一个输入来源：位置参数、--file 或 --stdin，不能同时使用。

  • 一次调用只允许一条 SQL；多语句输入会被拒绝。
  • --query 和 --non-query 互斥。
  • --stdin 与 --password-stdin 不能共享 stdin。
  • 通用 sql 命令禁止执行激活 SQL；数据库激活必须使用 activate apply。

7.3 CSV 数据导入

7.3.1 data import csv：导入官方 Tree CSV

CSV 示例：

Time,root.demo.device1.temperature,root.demo.device1.status
2026-07-21T08:00:00Z,25.1,true
2026-07-21T08:01:00Z,25.3,true
2026-07-21T08:02:00Z,25.7,false

导入：

timecho-cli --ctx prod data import csv data.csv

指定批次大小：

timecho-cli --ctx prod data import csv data.csv \
  --batch-size 5000

7.3.2 允许一定数量的错误行

timecho-cli --ctx prod data import csv data.csv \
  --max-bad-rows 10

7.3.3 将错误行写入文件

timecho-cli --ctx prod data import csv data.csv \
  --max-bad-rows 10 \
  --error-file rejected.csv

7.3.4 使用 Mapping 导入 Table 数据

原始 CSV：

ts,host,region,temperature,online
2026-07-21T08:00:00Z,server-01,beijing,25.1,true
2026-07-21T08:01:00Z,server-02,shanghai,26.3,true

mapping.yaml：

dialect: table
timeColumn: ts
database: telemetry
table: server_metrics
columns:
  - name: host
    target: host
    category: TAG
    type: STRING
  - name: region
    target: region
    category: TAG
    type: STRING
  - name: temperature
    target: temperature
    category: FIELD
    type: DOUBLE
  - name: online
    target: online
    category: FIELD
    type: BOOLEAN

导入：

timecho-cli --ctx table-prod data import csv metrics.csv \
  --mapping mapping.yaml

7.3.5 使用 Mapping 导入 Tree 数据

原始 CSV：

ts,temperature,status
2026-07-21T08:00:00Z,25.1,true
2026-07-21T08:01:00Z,25.3,false

tree-mapping.yaml：

dialect: tree
timeColumn: ts
device: root.demo.device1
columns:
  - name: temperature
    target: temperature
    type: DOUBLE
  - name: status
    target: status
    type: BOOLEAN

导入：

timecho-cli --ctx prod data import csv device1.csv \
  --mapping tree-mapping.yaml

7.3.6 通过 stdin 输入数据库密码

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod data import csv data.csv \
    --password-stdin

7.3.7 JSON 输出导入结果

timecho-cli --ctx prod --json data import csv data.csv \
  --batch-size 1000 \
  --max-bad-rows 10 \
  --error-file rejected.csv

7.4 CSV 数据导出

7.4.1 data export csv：导出到文件

timecho-cli --ctx prod data export csv \
  --sql "select * from root.demo.device1" \
  --out device1.csv

7.4.2 导出到 stdout

timecho-cli --ctx prod data export csv \
  --sql "select * from root.demo.device1" \
  --out -

也可以省略 --out，默认写到 stdout：

timecho-cli --ctx prod data export csv \
  --sql "select * from root.demo.device1"

通过 Shell 重定向到文件：

timecho-cli --ctx prod data export csv \
  --sql "select * from root.demo.device1" > device1.csv

7.4.3 导出 Table 查询

timecho-cli --ctx table-prod data export csv \
  --sql "select * from server_metrics limit 1000" \
  --out server-metrics.csv

7.4.4 导出 BLOB 列

CSV 中的二进制值默认使用带 base64: 前缀的 Base64；也可以选择十六进制：

timecho-cli --ctx table-prod data export csv \
  --sql "select read_object(file_data) from object_test" \
  --binary-encoding hex \
  --out object-content.csv

此时单元格使用 hex: 前缀。--binary-encoding 只接受 base64 或 hex。

若需要恢复一个 OBJECT 的原始文件，不要经过 CSV，请使用下一节的 data export object。

7.4.5 通过 stdin 输入数据库密码

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod data export csv \
    --sql "select * from root.demo.device1" \
    --out device1.csv \
    --password-stdin

CSV 写入 stdout 时不能与 JSON 输出模式同时使用。

7.5 OBJECT 文件导入导出

OBJECT 是 TimechoDB 企业版 Table 模型能力。导入前先确认数据库版本、授权状态、目标表 DDL、所有 TAG 列以及 OBJECT FIELD 列；不要把 Apache IoTDB 开源版的 BLOB 与企业版 OBJECT 混用。

7.5.1 data import object：写入本地文件

以下命令把一个本地普通文件按 4 MiB（默认值）分段写入同一个 Table 行，并在最后一段设置 EOF：

timecho-cli --ctx table-prod data import object ./photo.png \
  --table telemetry.object_test \
  --object-column file_data \
  --timestamp 1700000000000 \
  --tag device_id=pile-img-001 \
  --tag file_type=image/png \
  --verify

规则与边界：

  • Context 必须使用 table 方言；--table 接受 table 或 database.table。使用 database.table 时，该数据库用于本次导入连接。
  • --timestamp 是必填的毫秒时间戳；每个 TAG 列重复传入一个 --tag name=value；--object-column 指向 OBJECT FIELD。
  • --chunk-size 默认 4194304 字节，允许范围为 1 到 256 MiB。
  • --verify 默认启用，写完后分块读回并比较字节数与 SHA-256。仅在明确接受不校验时使用 --verify=false。
  • 本地校验只接受普通文件。若中途某段写入失败，服务端已经写入的分段无法由 CLI 自动回滚；应先检查或删除目标行，再决定是否重试。

JSON 自动化示例：

timecho-cli --ctx table-prod --json --non-interactive data import object ./photo.png \
  --table telemetry.object_test \
  --object-column file_data \
  --timestamp 1700000000000 \
  --tag device_id=pile-img-001

7.5.2 data export object：恢复原始文件

单次查询必须通过 READ_OBJECT(...) 返回恰好一行、一列、非 NULL 的 BLOB：

timecho-cli --ctx table-prod data export object \
  --sql "select read_object(file_data) from object_test where device_id='pile-img-001' and time=1700000000000" \
  --out ./photo-restored.png

大对象可以使用包含且只包含一个 {{offset}} 和一个 {{length}} 占位符的分块查询模板：

timecho-cli --ctx table-prod data export object \
  --sql-template "select read_object(file_data, {{offset}}, {{length}}) from object_test where device_id='pile-img-001' and time=1700000000000" \
  --chunk-size 4194304 \
  --out ./photo-restored.png

导出必须使用 --out FILE，禁止把原始二进制写到 stdout。目标已存在时默认返回冲突；只有显式传入 --force 才替换。CLI 先写同目录临时文件，完整成功后再原子发布，并返回字节数和 SHA-256；查询失败不会发布半截目标文件。

7.6 TsFile 导入

7.6.1 data import tsfile

timecho-cli --ctx prod data import tsfile \
  "/data/import/2026-07-21.tsfile"

Windows 数据库服务端路径：

timecho-cli --ctx prod data import tsfile `
  "D:\timecho-data\import\2026-07-21.tsfile"

JSON 输出：

timecho-cli --ctx prod --json data import tsfile \
  "/data/import/2026-07-21.tsfile"

通过 stdin 输入数据库密码：

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod data import tsfile \
    "/data/import/2026-07-21.tsfile" \
    --password-stdin

参数是数据库服务器能够访问的路径，不是执行 CLI 的客户端本地路径。

CLI 首版不支持 TsFile 导出。

7.7 数据库激活

7.7.1 activate machine-code：查询机器码

timecho-cli --ctx prod activate machine-code

JSON 输出：

timecho-cli --ctx prod --json activate machine-code

通过 stdin 输入数据库密码：

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod activate machine-code \
    --password-stdin

7.7.2 activate apply：应用激活码

推荐通过 stdin 输入激活码：

printf '%s' "$ACTIVATION_CODE" |
  timecho-cli --ctx prod activate apply --stdin

PowerShell：

$env:ACTIVATION_CODE |
  timecho-cli --ctx prod activate apply --stdin

直接通过参数传入：

timecho-cli --ctx prod activate apply \
  --code "YOUR-ACTIVATION-CODE"

JSON 输出：

printf '%s' "$ACTIVATION_CODE" |
  timecho-cli --ctx prod --json activate apply --stdin

推荐使用 --stdin，避免激活码进入 Shell 历史。

激活成功后，CLI 会再次查询激活状态，只有后置状态为 ACTIVATED 才判定成功。

激活码和数据库密码不能同时从同一个 stdin 管道读取；此时数据库密码应预先保存在 Keychain，或通过 TIMECHODB_PASSWORD 环境变量提供。

7.7.3 activate status：查看激活状态

timecho-cli --ctx prod activate status

JSON 输出：

timecho-cli --ctx prod --json activate status

通过 stdin 输入数据库密码：

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod activate status \
    --password-stdin

7.8 本地配置管理

配置命令只操作本地安装目录、显式配置文件或 kind: local 的 Context，不通过 SSH 修改远程服务器文件。

7.8.1 config get：读取配置

通过本地 Context 读取

timecho-cli --ctx local-dev config get dn_rpc_port \
  --db-version 2.0.6.1

如果 Context 配置文件中已经存在准确的 versionHint，可以省略 --db-version。当前 ctx add/update 暂无设置 versionHint 的命令参数，因此普通 CLI 流程建议显式传入数据库版本。

通过安装目录读取

timecho-cli config get dn_rpc_port \
  --home /opt/timecho \
  --db-version 2.0.6.1

通过指定 Properties 文件读取

timecho-cli config get dn_rpc_port \
  --file /opt/timecho/conf/iotdb-system.properties \
  --db-version 2.0.6.1

读取所有已有配置项

timecho-cli config get \
  --all \
  --home /opt/timecho \
  --db-version 2.0.6.1

JSON 输出：

timecho-cli --json config get \
  --all \
  --home /opt/timecho \
  --db-version 2.0.6.1

7.8.2 config set：修改配置

只校验并查看 Diff

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --dry-run

确认后正式写入交互式：

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1

非交互式：

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --yes

修改时间精度

timecho-cli config set timestamp_precision ms \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --yes

修改数据目录

timecho-cli config set dn_data_dirs "/data1/iotdb,/data2/iotdb" \
  --file /opt/timecho/conf/iotdb-system.properties \
  --db-version 2.0.6.1 \
  --yes

Windows：

timecho-cli config set dn_data_dirs "D:\data1,D:\data2" `
  --home "D:\timecho" `
  --db-version 2.0.6.1 `
  --yes

正式写入时会显示 Diff、创建备份、检查并发变更并执行同目录原子替换。

7.8.3 config diff：比较配置差异

与 Schema 默认值比较

timecho-cli config diff \
  --home /opt/timecho \
  --db-version 2.0.6.1

比较两个 Properties 文件

timecho-cli config diff \
  --file /opt/timecho/conf/iotdb-system.properties \
  --against ./iotdb-system.expected.properties \
  --db-version 2.0.6.1

JSON 输出：

timecho-cli --json config diff \
  --home /opt/timecho \
  --db-version 2.0.6.1

7.8.4 config tune：查看调优建议

timecho-cli config tune \
  --home /opt/timecho \
  --db-version 2.0.6.1

JSON 输出：

timecho-cli --json config tune \
  --home /opt/timecho \
  --db-version 2.0.6.1

当前实现不自动应用调优建议。即使传入 --apply，也会返回稳定错误 tune_apply_unavailable：

timecho-cli config tune \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --apply \
  --yes

正确流程是先查看建议，再对确认过的配置逐项使用 config set：

timecho-cli config tune \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --json

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --dry-run

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --yes

内置保守 Schema 不包含猜测的硬件调优值；没有权威建议时，recommendations 为空并返回说明性 notice。

7.9 配置 Schema 管理

7.9.1 config schema list：列出 Schema 字段

使用默认数据库版本：

timecho-cli config schema list

指定数据库版本：

timecho-cli config schema list \
  --db-version 2.0.6.1

JSON 输出：

timecho-cli --json config schema list \
  --db-version 2.0.6.1

7.9.2 config schema show：查看 Schema

查看完整 Schema：

timecho-cli config schema show \
  --db-version 2.0.6.1

查看指定配置项：

timecho-cli config schema show \
  --db-version 2.0.6.1 \
  --key dn_rpc_port

查看时间精度定义：

timecho-cli config schema show \
  --db-version 2.0.6.1 \
  --key timestamp_precision

JSON 输出：

timecho-cli --json config schema show \
  --db-version 2.0.6.1 \
  --key dn_rpc_port

7.9.3 config schema update：更新 Schema

从默认发布地址更新：

timecho-cli config schema update \
  --version 1.0.0

指定自定义发布地址：

timecho-cli config schema update \
  --version 1.0.0 \
  --base-url https://downloads.example.com/timecho-schemas

JSON 输出：

timecho-cli --json config schema update \
  --version 1.0.0

CLI 将下载：

timechodb-schema-1.0.0.tar.gz
checksums.txt

并执行 HTTPS、SHA-256、归档路径和 Schema 内容校验。SHA-256 证明资产相对于 checksums.txt 未发生变化，但当前协议不宣称独立完成发布者身份或签名真实性验证。

7.10 数据库状态检查

7.10.1 status

检查当前 Context：

timecho-cli status

检查指定 Context：

timecho-cli --ctx prod status

JSON 输出：

timecho-cli --ctx prod --json status

增加超时：

timecho-cli --ctx prod \
  --timeout 1m \
  status

通过 stdin 输入数据库密码：

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod status \
    --password-stdin

自动化调用：

timecho-cli \
  --ctx prod \
  --json \
  --non-interactive \
  --timeout 30s \
  --trace-id health-check-001 \
  status

状态结果包含数据库版本、激活、集群、Region、运行变量和磁盘占用等检查项，每项返回：

pass
warn
fail
skip

磁盘占用检查会按 Context 的 SQL 方言选择查询：树模型使用SHOW DISK_USAGE FROM root.**，表模型使用SELECT * FROM information_schema.table_disk_usage。两种模型的语法不能混用。

7.11 诊断命令

7.11.1 远程数据库诊断

timecho-cli --ctx prod diagnose

JSON 输出：

timecho-cli --ctx prod --json diagnose

7.11.2 生成脱敏诊断包

timecho-cli --ctx prod diagnose \
  --bundle ./timecho-diagnose.zip

7.11.3 在远程诊断基础上包含本地诊断

timecho-cli --ctx local-dev diagnose \
  --local

7.11.4 指定本地安装目录

timecho-cli --ctx prod diagnose \
  --local \
  --home /opt/timecho

Windows：

timecho-cli --ctx prod diagnose `
  --local `
  --home "D:\timecho" `
  --bundle ".\timecho-diagnose.zip"

7.11.5 同时进行远程和本地诊断

timecho-cli --ctx local-dev diagnose \
  --local \
  --bundle ./timecho-full-diagnose.zip

7.11.6 通过 stdin 输入数据库密码

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod diagnose \
    --password-stdin \
    --bundle ./timecho-diagnose.zip

诊断结果会脱敏密码、Token、激活码等敏感信息。单个采集项失败时，其他采集项仍可继续执行，并返回 partial success。

当前 diagnose 总会先解析 Context、创建数据库 Session 并执行远程只读查询；--local 和 --home 只是附加本地 OS/JDK/配置/日志采集，不是离线诊断模式。即使只关心本地目录，也必须存在可连接的数据库 Context。

7.12 Timecho AI

Timecho AI 是统一 timecho-cli 下的命令组，不存在单独的 timechoai-cli 可执行文件。当前对外可用的是 ping、forecast 和 key。

evaluate、dimensions 仍注册在迁移契约中，但已隐藏并返回 service_not_open，服务端开放前不得按可用能力调用或宣称支持；运行时帮助是最终命令契约。

7.12.1 查看 AI 命令

timecho-cli ai --help
timecho-cli ai ping --help
timecho-cli ai forecast --help
timecho-cli ai key --help
timecho-cli ai key set --help
timecho-cli ai key show --help
timecho-cli ai key remove --help

7.12.2 检查连通性与鉴权

export TIMECHOAI_API_KEY="your-api-key"
timecho-cli ai ping
timecho-cli ai ping --name World

优先避免把 API Key 写入 shell history：

printf '%s\n' "$TIMECHOAI_API_KEY" |
  timecho-cli ai ping --api-key-stdin

7.12.3 预测一个目标序列

输入支持 CSV、TSV 和 JSON。Forecast 契约只接受一个 --input，同一张表中同时包含时间、目标以及可选的协变量列。

参数说明：

  • --input：输入 CSV、TSV 或 JSON 文件。
  • --target：目标列名，必须且只能传一次。
  • --time-col：时间列名；省略时自动识别大小写不敏感的 time 列。
  • --output-start-time：预测起始时间。 time < boundary 的行作为历史数据，time >= boundary 的行提供未来协变量。
  • --output-length：预测步数。省略时由服务根据未来协变量或模型默认值推断。
  • --model / --model-id：指定模型或使用兼容别名。
  • --history-cov：历史协变量列，可重复或使用逗号分隔。
  • --future-cov：未来协变量列，可重复或使用逗号分隔，必须是历史协变量的子集。
  • --no-auto-adapt：严格拒绝协变量长度不匹配，不自动补齐或截断。
timecho-cli ai forecast \
  --input ./data.csv \
  --target OT \
  --output-start-time 2024-01-17T00:00:00 \
  --output-length 96

例如，显式指定模型：

timecho-cli --json ai forecast \
  --input ./data.json \
  --target load \
  --output-start-time 2024-01-17T00:00:00 \
  --model Timer-3.5 \
  --output-length 24

例如，指定历史和未来协变量：

timecho-cli ai forecast \
  --input ./data.csv \
  --target OT \
  --history-cov temperature,humidity \
  --history-cov holiday \
  --future-cov temperature,holiday \
  --output-start-time 2024-01-17T00:00:00 \
  --output-length 48 \
  --no-auto-adapt

时间列严格对齐 Python SDK：只接受 ISO 日期或日期时间格式；整列必须使用一致的精度、时区表示和固定采样间隔。数值时间戳、重复时间、混用日期/日期时间、混用时区表示和不规则间隔都会在联网前失败。

结果可以输出为 human、JSON envelope 或纯 CSV，也可以写入 CSV/JSON 文件：

timecho-cli --output csv ai forecast \
  --input ./data.csv \
  --target OT \
  --output-start-time 2024-01-17T00:00:00 \
  --output-length 96

timecho-cli ai forecast \
  --input ./data.csv \
  --target OT \
  --output-start-time 2024-01-17T00:00:00 \
  --output-length 96 \
  --out ./prediction.csv

timecho-cli --json ai forecast \
  --input ./data.csv \
  --target OT \
  --output-start-time 2024-01-17T00:00:00 \
  --out ./prediction.json

7.12.4 管理 Timecho AI API Key

只查看状态不会回显 Key；设置/轮换优先从 stdin 读取，避免把密钥写入命令参数或 shell history：

printf '%s\n' "$TIMECHOAI_API_KEY" |
  timecho-cli ai key set --api-key-stdin

timecho-cli ai key show
timecho-cli ai key remove

ai key 使用系统 Keychain 的 service timecho-cli、account ai/api-key。

set 的解析顺序为 --api-key-stdin、TIMECHOAI_API_KEY、兼容变量 TIMER_CLIENT_API_KEY，最后才是在可交互终端中的安全提示；JSON 或非交互模式不会提示输入。

7.12.5 尚未开放的 AI 服务

evaluate 和 dimensions 仍可由已安装二进制识别，但已从 ai --help 隐藏，直接调用会返回类型化错误 service_not_open。服务端开放前不要把以下命令当作成功路径或提供可用性承诺：

timecho-cli ai evaluate
timecho-cli ai dimensions

AI 专属参数是 --api-key-stdin 和 --base-url。API Key 顺序为 stdin、TIMECHOAI_API_KEY、兼容变量 TIMER_CLIENT_API_KEY、系统 keychain。根级 --timeout、--json、--output、--non-interactive、--verbose 和--trace-id 继续复用。AI JSON 与其他命令使用同一个 timecho.com/timecho-cli/v1alpha1，Forecast 使用 TimechoAIForecast kind；

MCP 仍不属于本期迁移，也不要根据规划文档拼造 MCP 调用。

7.12.6 使用 Forecast Agent Skill

需要 Agent 自动完成“检查数据 → 选择路由 → 预测 → 绘图 → 汇报”时，安装内置 timecho-forecast 工作流：

timecho-cli setup skills \
  --agent codex \
  --skill timecho-forecast \
  --dry-run

timecho-cli setup skills \
  --agent codex \
  --skill timecho-forecast

选择该工作流时，若来源中存在，安装器会自动把 timechoai-cli-guide 和公共 timecho-cli-guide 加入计划。工作流先检查统一 CLI 的根/AI 帮助，执行只走 timecho-cli ai，运行时 --help 优先于静态示例。

7.13 Skills 安装与上传包导出

timecho-cli setup skills 同时承担两类交付：

  1. 文件系统安装：Codex、Claude、CodeBuddy、OpenClaw、Hermes、TRAE、TRAE CN；
  2. 上传包导出：TRAE Work、WorkBuddy。

上传包导出不会调用平台私有 API，也不会自动完成远端导入。

7.13.1 默认行为：安装二进制内置 Skills

不传 --source、--bundle、--version 时，使用构建进二进制的离线 Skills catalog：

timecho-cli setup skills

默认参数等价于：

--agent all --scope user

其中 all 只展开为以下文件系统 Agent：

claude
codex
codebuddy
openclaw
hermes
trae
trae-cn

all 不包含 trae-work 和 workbuddy，避免在未指定导出目录时意外生成上传包。

先查看内置 catalog 的安装计划：

timecho-cli --json setup skills \
  --agent codex \
  --dry-run

输出中的关键字段：

字段含义
source_mode: embedded使用二进制内置 catalog
bundle_version: embedded-<digest>构建时 catalog 摘要标签
sha256_verified: false没有使用外部 checksums.txt
delivery_mode: filesystem直接写入 Agent Skills 目录
delivery_status: plannedDry Run，仅生成计划

内置 catalog 是构建时快照，不代表官网或远程 Release 的最新版本。需要指定发布版本时使用 --version。

7.13.2 从官方 Release 安装

指定 --version 且不传 --source/--bundle 时，从 Release 下载：

timechodb-skills-1.0.0.tar.gz
checksums.txt

安装到 Codex 用户目录：

timecho-cli setup skills \
  --version 1.0.0 \
  --agent codex

使用 JSON 输出：

timecho-cli --json setup skills \
  --version 1.0.0 \
  --agent codex

使用自定义 HTTPS Release 地址：

timecho-cli setup skills \
  --version 1.0.0 \
  --base-url https://downloads.example.com/timechodb-skills \
  --agent codex

实际下载地址由以下部分组成：

<base-url>/<version>/timechodb-skills-<version>.tar.gz
<base-url>/<version>/checksums.txt

远程下载只允许 HTTPS，并在安全解包前验证 SHA-256。校验和只能证明资产与 checksums.txt 一致，不等于独立的发布者签名认证。

7.13.3 从仓库 Skills 目录安装

本地开发时可直接使用规范源目录：

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --dry-run

确认计划后正式安装：

timecho-cli setup skills \
  --source ./skills \
  --agent codex

Windows PowerShell：

timecho-cli setup skills `
  --source .\skills `
  --agent codex `
  --dry-run

本地目录模式不会要求外部 checksum，输出为：

source_mode: directory
sha256_verified: false
bundle_version: local

如果同时传入 --source 和 --version，--version 只作为 manifest 中的本地 bundle 标签，不会触发远程下载：

timecho-cli setup skills \
  --source ./skills \
  --version dev-20260729 \
  --agent codex

--source 和 --bundle 互斥。

7.13.4 从本地 Bundle 安装

本地 .tar.gz bundle 必须同时提供包含该文件摘要的 checksums.txt：

timecho-cli setup skills \
  --bundle ./timechodb-skills-local.tar.gz \
  --checksums ./checksums.txt \
  --agent codex \
  --dry-run

正式安装：

timecho-cli setup skills \
  --bundle ./timechodb-skills-local.tar.gz \
  --checksums ./checksums.txt \
  --agent codex

此模式的输出应包含：

source_mode: bundle
sha256_verified: true

Bash：生成只包含 Skill 目录的测试 Bundle

stage="$(mktemp -d)"
cp -R skills/timechodb-* skills/timechoai-* skills/timecho-cli-guide skills/timecho-forecast "$stage/"
tar -czf timechodb-skills-local.tar.gz -C "$stage" .
sha256sum timechodb-skills-local.tar.gz > checksums.txt
rm -rf "$stage"

PowerShell：生成只包含 Skill 目录的测试 Bundle

$stage = Join-Path $env:TEMP ("timechodb-skills-stage-" + [guid]::NewGuid())
New-Item -ItemType Directory -Path $stage | Out-Null

Get-ChildItem -LiteralPath .\skills -Directory |
  Where-Object { $_.Name -like 'timechodb-*' -or $_.Name -like 'timechoai-*' -or $_.Name -eq 'timecho-cli-guide' -or $_.Name -eq 'timecho-forecast' } |
  ForEach-Object {
    Copy-Item -LiteralPath $_.FullName -Destination $stage -Recurse
  }

tar -czf .\timechodb-skills-local.tar.gz -C $stage .

$asset = (Resolve-Path .\timechodb-skills-local.tar.gz).Path
$hash = (Get-FileHash -Algorithm SHA256 -LiteralPath $asset).Hash.ToLowerInvariant()
"$hash  $([IO.Path]::GetFileName($asset))" |
  Set-Content -LiteralPath .\checksums.txt -Encoding ascii

Remove-Item -LiteralPath $stage -Recurse -Force

不要直接把整个仓库根目录打入 Skills bundle。若从本仓库的 skills/ 打包，也建议只选择 timechodb-*、timechoai-*、timecho-cli-guide 与 timecho-forecast 规范目录，避免把 embed.go、测试文件或其他非 Skill 资产混入发布包。

7.13.5 选择部分 Skill

--skill 可重复，也可以使用逗号分隔：

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --skill timechodb-knowledge-base \
  --skill timechodb-sql-dev

Forecast 工作流可以单独选择：

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --skill timecho-forecast \
  --dry-run

等价写法：

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --skill timechodb-knowledge-base,timechodb-sql-dev

选择不存在或名称格式非法的 Skill 会在写入目标目录前失败。

若被选中的 Skill 在 SKILL.md 中调用 timecho-cli，并且来源中包含 timecho-cli-guide，安装器会自动把该指南加入安装或导出计划；显式选择 timecho-forecast 时，来源中存在 timechoai-cli-guide 也会自动加入。这样 Agent 在执行依赖 Skill 前可以先通过运行时 --help 和分层命令参考确认当前语法。无关 Skill 不会被注入指南，显式选择指南本身也不会重复。

因此，自动化脚本应以 dry-run 或正式结果中的 plan.install / plan.export 为最终选择集合，而不是假定它与命令行 --skill 参数完全一一对应。

7.13.6 文件系统 Agent 与默认目录

User Scope

Agent目标目录
claude~/.claude/skills
codex~/.agents/skills
codebuddy~/.codebuddy/skills
openclaw~/.openclaw/skills
hermes~/.hermes/skills
trae~/.trae/skills
trae-cn~/.trae-cn/skills

示例：

timecho-cli setup skills --agent claude
timecho-cli setup skills --agent codex
timecho-cli setup skills --agent codebuddy
timecho-cli setup skills --agent openclaw
timecho-cli setup skills --agent hermes
timecho-cli setup skills --agent trae
timecho-cli setup skills --agent trae-cn

Project Scope

Agent目标目录
claude<project>/.claude/skills
codex<project>/.agents/skills
codebuddy<project>/.codebuddy/skills
openclaw<project>/.agents/skills
hermes<project>/.agents/skills
trae<project>/.trae/skills
trae-cn<project>/.trae/skills

Codex 项目级安装：

timecho-cli setup skills \
  --agent codex \
  --scope project \
  --project-dir /workspace/my-project

Windows PowerShell：

timecho-cli setup skills `
  --agent codex `
  --scope project `
  --project-dir "D:\projects\my-project"

若省略 --project-dir，project scope 使用当前工作目录。自动化脚本仍建议显式传入项目根目录。

OpenClaw 项目级默认复用 .agents/skills。如需 OpenClaw 原生项目目录：

timecho-cli setup skills \
  --agent openclaw \
  --scope project \
  --project-dir /workspace/my-project \
  --native-target

目标将变为：

<project>/skills

--native-target 只适用于 OpenClaw。

Hermes project scope 安装完成后，如果 Hermes 没有自动发现目录，CLI 会提示把目标目录加入 Hermes external_dirs。

7.13.7 同时安装到多个文件系统 Agent

--agent 可重复或使用逗号分隔：

timecho-cli setup skills \
  --source ./skills \
  --agent codex,claude,codebuddy \
  --scope project \
  --project-dir /workspace/my-project \
  --dry-run

等价写法：

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --agent claude \
  --agent codebuddy \
  --scope project \
  --project-dir /workspace/my-project

CLI 会先为全部目标生成计划，再开始逐目标应用；但当前多目标执行不是跨目录的全局事务。如果后续目标写入失败，已经成功的前序目标不会自动整体回滚。

7.13.8 覆盖一个文件系统 Agent 的目标目录

--target-dir 只允许与一个文件系统 Agent 配合：

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --target-dir ./tmp/codex-skills \
  --dry-run

以下组合会失败：

timecho-cli setup skills \
  --agent codex,claude \
  --target-dir ./shared-skills

CLI 不会把一个自定义目录暗中复用给多个 Agent。

7.13.9 Dry Run、冲突与 --force

Dry Run 只生成计划，不创建 Skill、manifest、备份或导出包：

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --dry-run

文件系统安装使用目标目录下的：

.timechodb-skills-manifest.json

记录 bundle 版本与文件 SHA-256。

如果已安装 Skill 的内容和 manifest 记录不一致，默认报告 conflict 并保留用户修改：

timecho-cli setup skills \
  --source ./skills \
  --agent codex

明确允许替换时：

timecho-cli setup skills \
  --source ./skills \
  --agent codex \
  --force

当前 --force 也可能替换同名但未被 manifest 管理的 Skill 目录。使用前必须先运行 --dry-run 并确认目标路径。

单个文件系统目标的安装会在目标文件系统中 staging，并在 Skill/manifest 提交失败时尝试回滚。

7.13.10 为 TRAE Work 导出上传包

TRAE Work 是上传型目标，必须显式选择并提供 --export-dir：

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work \
  --export-dir ./dist/trae-work-skills \
  --dry-run

正式导出 ZIP：

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work \
  --export-dir ./dist/trae-work-skills \
  --package-format zip

导出 .skill 包：

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work \
  --export-dir ./dist/trae-work-skills \
  --package-format skill

auto 对 TRAE Work 当前解析为 zip。

7.13.11 为 WorkBuddy 导出上传包

timecho-cli setup skills \
  --source ./skills \
  --agent workbuddy \
  --export-dir ./dist/workbuddy-skills

WorkBuddy 当前只接受 ZIP：

timecho-cli setup skills \
  --source ./skills \
  --agent workbuddy \
  --export-dir ./dist/workbuddy-skills \
  --package-format zip

以下写法会失败：

timecho-cli setup skills \
  --source ./skills \
  --agent workbuddy \
  --export-dir ./dist/workbuddy-skills \
  --package-format skill

7.13.12 Workspace 级上传包

workspace scope 只用于 TRAE Work / WorkBuddy 上传型导出，并要求 --workspace：

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work \
  --scope workspace \
  --workspace telemetry-team \
  --export-dir ./dist/trae-workspace-skills
timecho-cli setup skills \
  --source ./skills \
  --agent workbuddy \
  --scope workspace \
  --workspace telemetry-team \
  --export-dir ./dist/workbuddy-workspace-skills

文件系统 Agent 不接受 workspace scope；上传型 Agent 不接受 project scope。

7.13.13 同时为 TRAE Work 和 WorkBuddy 导出

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work,workbuddy \
  --export-dir ./dist/upload-skills

当同时选择两个上传型 Agent 时，输出分别写入：

./dist/upload-skills/trae-work
./dist/upload-skills/workbuddy

因为 WorkBuddy 不接受 .skill，同时导出时应使用默认 auto 或显式 zip：

timecho-cli setup skills \
  --source ./skills \
  --agent trae-work,workbuddy \
  --export-dir ./dist/upload-skills \
  --package-format zip

7.13.14 同时执行文件系统安装和上传包导出

混合目标必须提供 --export-dir。由于文件系统和上传目标共同接受的 scope 只有 user，混合执行应使用默认 user scope：

timecho-cli setup skills \
  --source ./skills \
  --agent codex,workbuddy \
  --export-dir ./dist/workbuddy-skills \
  --dry-run

正式执行：

timecho-cli setup skills \
  --source ./skills \
  --agent codex,workbuddy \
  --export-dir ./dist/workbuddy-skills

7.13.15 上传包内容与状态

每个 Skill 生成一个独立包，包根目录直接包含：

SKILL.md
scripts/       # 仅当原 Skill 存在references/    # 仅当原 Skill 存在assets/        # 仅当原 Skill 存在

导出目录还包含：

export-manifest.json
checksums.txt
IMPORT.md
<skill-name>.zip 或 <skill-name>.skill

正常导出后的状态是：

delivery_mode: import-package
delivery_status: awaiting-import

这表示包已经生成，仍需在 TRAE Work 或 WorkBuddy 中人工完成导入。当前实现不进行浏览器自动上传、私有 API 调用、远端状态查询、启停或回滚。

已存在且由 export-manifest.json 管理的导出目录，如果内容完全一致会跳过；内容不同默认冲突，可使用 --force 替换。非空但没有 manifest 的目录视为 unmanaged，即使传入 --force 也不会覆盖。

7.13.16 Agent 名称与别名

正式名称：

claude
codex
codebuddy
openclaw
hermes
trae
trae-cn
trae-work
workbuddy
all

当前保留以下兼容别名：

输入归一化结果
claude-codeclaude
code-buddycodebuddy
traeworktrae-work
work-buddyworkbuddy

名称不区分大小写，但文档和自动化脚本建议始终使用正式小写名称。

7.13.17 安全与行为边界

  • Skill 名称只能包含小写字母、数字和连字符，长度 1–64，且不能以连字符开头或结尾。
  • 目录名必须与 SKILL.md frontmatter 中的 name 一致。
  • SKILL.md 必须包含 name 和 description。
  • Skill 源或包中的 symlink 会被拒绝。
  • 安装器只复制/打包文件，不执行 Skill 中的脚本。
  • 归档会检查 traversal、绝对路径、链接、大小限制和异常 entry。
  • --dry-run 不产生安装或导出副作用。
  • 上传包采用确定性文件顺序、固定时间戳和权限，便于稳定校验。

7.14 版本信息

7.14.1 version

timecho-cli version

JSON 输出：

timecho-cli version --json

也可以写成：

timecho-cli --json version

输出内容包括：

  • CLI 版本。
  • Git Commit。
  • 构建日期。
  • 发布渠道。
  • Go 版本。
  • 操作系统和 CPU 架构。

7.15 Shell Completion

7.15.1 Bash

当前终端临时启用：

source <(timecho-cli completion bash)

永久安装：

timecho-cli completion bash \
  > ~/.local/share/bash-completion/completions/timecho-cli

7.15.2 Zsh

timecho-cli completion zsh \
  > "${fpath[1]}/_timecho-cli"

然后重新启动 Zsh：

exec zsh

7.15.3 Fish

mkdir -p ~/.config/fish/completions

timecho-cli completion fish \
  > ~/.config/fish/completions/timecho-cli.fish

7.15.4 PowerShell

当前会话临时启用：

timecho-cli completion powershell |
  Out-String |
  Invoke-Expression

写入 PowerShell Profile：

timecho-cli completion powershell |
  Out-File -Append -Encoding utf8 $PROFILE

如果 Profile 不存在：

New-Item -ItemType File -Force $PROFILE
timecho-cli completion powershell |
  Out-File -Append -Encoding utf8 $PROFILE

7.16 结构化输出、退出码与自动化

7.16.1 JSON 成功 Envelope

timecho-cli --json \
  --trace-id build-check-001 \
  version

输出结构：

{
  "ok": true,
  "api_version": "timecho.com/timecho-cli/v1alpha1",
  "command": "timecho-cli version",
  "data": {
    "version": "1.0.0",
    "commit": "0123456789ab",
    "date": "2026-07-29T00:00:00Z",
    "channel": "stable",
    "go": "go1.25.0",
    "os": "linux",
    "arch": "amd64"
  },
  "meta": {
    "trace_id": "build-check-001",
    "duration_ms": 1
  },
  "notices": []
}

data 的具体字段由命令决定；脚本应先判断 ok，再解析命令数据。

7.16.2 JSON 错误 Envelope

构造一个本地参数错误：

timecho-cli --json sql

错误写入 stderr，结构类似：

{
  "ok": false,
  "api_version": "timecho.com/timecho-cli/v1alpha1",
  "command": "timecho-cli sql",
  "error": {
    "type": "validation",
    "code": "sql_source",
    "message": "exactly one SQL source is required",
    "hint": "pass one positional SQL, --file, or --stdin",
    "retryable": false,
    "param": "sql"
  },
  "meta": {},
  "notices": []
}

自动化逻辑应优先判断 error.type 和 error.code，不要依赖完整英文 message。

7.16.3 stdout 与 stderr

  • JSON 成功：stdout；
  • JSON 失败：stderr；
  • CSV 查询结果：纯 stdout；
  • human 最终数据：stdout；
  • human 错误、提示和 verbose 诊断：stderr。

Bash 分离输出：

timecho-cli --json version \
  >result.json \
  2>error.json

PowerShell：

timecho-cli --json version `
  1> .\result.json `
  2> .\error.json

7.16.4 退出码

退出码含义
0成功
1数据库操作错误，或未映射到专用退出码的一般错误
2参数或输入校验错误
3配置、凭据或一般冲突
4网络或协议错误
5内部错误
6不支持或策略拒绝
7Partial，已有部分结果但部分采集/处理失败
10缺少写操作确认
130操作被中断

Bash：

timecho-cli --json version
code=$?
echo "$code"

PowerShell：

timecho-cli --json version
$code = $LASTEXITCODE
Write-Output $code

7.16.5 非交互式配置写入

先执行 Dry Run：

timecho-cli --json \
  --non-interactive \
  config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --dry-run

审查通过后显式确认：

timecho-cli --json \
  --non-interactive \
  --yes \
  config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1

如果正式写入时没有 --yes，命令返回 confirmation_required，不会提示或修改文件。

7.16.6 CI 中安装内置 Skills

使用临时目标，避免写入执行器真实 Agent 目录：

target="$(mktemp -d)"

timecho-cli --json \
  --non-interactive \
  setup skills \
  --agent codex \
  --target-dir "$target" \
  --dry-run

timecho-cli --json \
  --non-interactive \
  setup skills \
  --agent codex \
  --target-dir "$target"

PowerShell：

$target = Join-Path $env:TEMP ("timechodb-ci-skills-" + [guid]::NewGuid())

timecho-cli --json `
  --non-interactive `
  setup skills `
  --agent codex `
  --target-dir $target `
  --dry-run

timecho-cli --json `
  --non-interactive `
  setup skills `
  --agent codex `
  --target-dir $target

7.17 密码使用示例

CLI 的密码读取顺序为：

  1. --password-stdin
  2. TIMECHODB_PASSWORD
  3. 操作系统 Keychain

7.17.1 使用环境变量

Bash：

export TIMECHODB_PASSWORD='your-password'
timecho-cli --ctx prod status

PowerShell：

$env:TIMECHODB_PASSWORD = "your-password"
timecho-cli --ctx prod status

使用完成后清除：

unset TIMECHODB_PASSWORD

PowerShell：

Remove-Item Env:TIMECHODB_PASSWORD

7.17.2 使用 stdin

Bash：

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli --ctx prod status --password-stdin

PowerShell：

$env:TIMECHODB_PASSWORD |
  timecho-cli --ctx prod status --password-stdin

7.17.3 使用 Keychain

添加 Context 时写入：

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli ctx add prod \
    --host db.example.com \
    --password-stdin

后续直接使用：

timecho-cli --ctx prod status
timecho-cli --ctx prod sql "show version"

7.18 完整操作流程示例

7.18.1 添加连接

printf '%s\n' "$TIMECHODB_PASSWORD" |
  timecho-cli ctx add prod \
    --host db.example.com \
    --port 6667 \
    --user root \
    --dialect tree \
    --password-stdin

7.18.2 切换上下文

timecho-cli ctx use prod

7.18.3 检查版本

timecho-cli sql "show version"

7.18.4 查看状态

timecho-cli status

7.18.5 查询数据

timecho-cli --json sql \
  "select * from root.demo.device1 limit 100"

7.18.6 导入 CSV

timecho-cli data import csv data.csv \
  --batch-size 1000 \
  --max-bad-rows 10 \
  --error-file rejected.csv

7.18.7 导出 CSV

timecho-cli data export csv \
  --sql "select * from root.demo.device1" \
  --out device1.csv

7.18.8 获取机器码

timecho-cli activate machine-code

7.18.9 应用激活码

printf '%s' "$ACTIVATION_CODE" |
  timecho-cli activate apply --stdin

7.18.10 验证激活状态

timecho-cli activate status

7.18.11 检查本地配置

timecho-cli config get \
  --all \
  --home /opt/timecho \
  --db-version 2.0.6.1

7.18.12 修改配置

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --dry-run

确认后写入：

timecho-cli config set dn_rpc_port 6668 \
  --home /opt/timecho \
  --db-version 2.0.6.1 \
  --yes

7.18.13 生成诊断包

timecho-cli diagnose \
  --local \
  --home /opt/timecho \
  --bundle ./timecho-diagnose.zip

7.18.14 安装 Codex Skills

timecho-cli setup skills \
  --version 1.0.0 \
  --agent codex \
  --scope user

8. MCP server

IoTDB MCP Server 是一个基于模型上下文协议（Model Context Protocol, MCP）的服务器实现，通过 IoTDB 提供数据库交互和商业智能能力。该服务器支持执行 SQL 查询，并可以通过不同的 SQL 方言（树模型和表模型）与 IoTDB 进行交互。

MCP 已开源，可直接从 GitHub iotdb-mcp-server 下载。

最近更新:

Copyright © 2026 Timecho Limited All rights reserved.
Apache IoTDB and the Apache IoTDB project logo are trademarks of The Apache Software Foundation.