ZTAI-CLI

ZTAI-CLI 是 AutoResearch 平台的可分发 skill。它把平台任务、workspace、仓库同步和运行时控制能力封装成一组本地脚本与参考文档，供支持 skill 目录的智能体或自动化环境调用。

它只通过公开 HTTP API 与平台通信；正常使用不需要 SSH 到服务器，也不读取服务器本地文件。

一键初始化

面向普通用户，首选先用 npm 全局安装：

npm install -g @xinzhu-ai/[email protected]

安装后运行零参数 ztai。它会先检查本地是否已经具备 Python、必要 Python 依赖、平台凭据和 agent skill；缺少配置时自动进入交互式向导：

ztai

临时试用时，也可以用 npx 一次性运行同一个入口：

npx -y @xinzhu-ai/[email protected]

每次运行 ztai 时会轻量检查 npm 最新版本。发现新版时，交互式终端会询问是否立即更新；非交互环境只提示更新命令并继续执行原命令。也可以主动运行：

ztai update

如果当前网络不能访问 npm，自动检查会静默跳过。需要禁用自动检查时设置 ZTAI_SKIP_UPDATE_CHECK=1。

本地验证发布包前，可以先用 tarball：

npm pack
npx -y ./xinzhu-ai-ztai-0.1.4.tgz
npx -y ./xinzhu-ai-ztai-0.1.4.tgz init --project . --skip-token
npx -y --package ./xinzhu-ai-ztai-0.1.4.tgz ztai setup --base-url https://your-platform.example --token-stdin --no-verify

交互式向导会列出候选 skills 根目录，可输入 1,2 多选、a 全选、c 自定义。目标目录不存在时会自动创建。默认候选包含 .codex/skills、.agent/skills、.claude/skills；也会合并 ZTAI_SKILL_DIRS、CODEX_HOME/skills 和用户级目录。

向导只配置两类 secret：

• 平台 CLI token：保存到 ~/.agent/ZTAI-CLI/token.json，用于平台 API。
• Gitea token：写入 Git credential helper，用于 Git clone、pull、push。

不要求平台账号或平台密码。Git credential helper 内部需要 username 字段时，CLI 会从 GITEA_USERNAME 或 Gitea remote owner 推断，不作为交互式必填项。 如果当前目录没有发现 Gitea HTTPS remote，向导会允许手动输入 remote；回车跳过时只配置平台凭据。

任务卡命令需要 Python 依赖 PyYAML。第一次运行 ztai 时如果检测到缺少该依赖，会询问是否自动执行 python -m pip install --user PyYAML；非交互环境可以设置 ZTAI_AUTO_INSTALL_PYTHON_DEPS=1 自动安装。

脚本化时仍可以使用子命令：

• ztai init --check-only：只检查环境，不写文件。
• ztai init --project <项目路径>：把 <项目路径> 当作项目根目录，安装到 <项目路径>/.codex/skills/ztai-cli。
• ztai init --skill-dir <skills目录>：把 <skills目录> 当作 skills 根目录，安装到 <skills目录>/ztai-cli；可重复传入多个目录。
• ztai init --interactive：强制进入初始化向导。

平台 token 也可以使用 setup 单独保存。为了避免 token 出现在命令行历史里，推荐从标准输入传入：

read -r -s ZTAI_TOKEN
printf '%s\n' "$ZTAI_TOKEN" | ztai setup --base-url https://your-platform.example --token-stdin
unset ZTAI_TOKEN

使用者不需要 npm 登录；只有发布新版本的人需要 npm 发布权限。

手工安装

把整个 ztai-cli 目录放到目标运行环境约定的 skills 目录下即可。目录根需要保留：

• SKILL.md：skill 入口和路由说明。
• scripts/：可直接执行的 CLI、配置脚本和仓库凭据脚本。
• references/：按需读取的 API、配置、Gitea、安全和工作流说明。

如果从 Git 安装，可以克隆到目标 skills 目录：

git clone <ztai-cli.git> <skills-dir>/ztai-cli

脚本配置回退

Linux/macOS:

cd <skills-dir>/ztai-cli
./scripts/setup_unix.sh --base-url https://your-platform.example

Windows PowerShell:

Set-Location <skills-dir>\ztai-cli
.\scripts\setup_windows.ps1 -BaseUrl https://your-platform.example

配置脚本会把凭据保存到 ~/.agent/ZTAI-CLI/token.json 并执行访问检查。Windows 脚本不再安装 PowerShell 版 ztai 包装器；正式 ztai 命令由 npm 全局安装提供。

更多 token、PATH 和 ztai 命令发现说明见 references/configuration.md。

配置完成后，先验证 ztai 已绑定到当前 shell：

ztai doctor
ztai me

如果是通过 npm 全局安装，产品级帮助入口是：

ztai
ztai --help
ztai env
ztai init --help
ztai setup --help

能力范围

• 验证平台访问：doctor、overview、me。
• 查看平台能力：员工、execution profiles、workspace preflight。
• 管理任务：初始化任务卡、校验、提交、查看状态、消息、日志、产物、诊断、收口和比较。
• 启动 workspace：通过 execution profile 提交 GPU 或非 GPU 工作。
• 处理仓库：配置 Gitea Git 凭据，发布本地 repo，并触发平台同步。
• 控制运行时：在权限允许时暂停、恢复或终止任务。
• 排查本地命令发现：ztai env 显示当前入口、PATH 命中和 Windows subprocess 建议命令。
• 更新 CLI：ztai update 从 npm 安装最新版本。

常用命令

ztai doctor
ztai env
ztai overview
ztai update
ztai task
ztai execution-profiles
ztai workspace
ztai task inspect repo/employee/workspace
ztai task submit -f task.yaml --format text
ztai detail repo/employee/workspace --follow
ztai run-yaml show repo/employee/workspace --format markdown
ztai run-yaml facts --status running --format json

ztai task 默认等价于 ztai task list --format table。常用只读命令优先输出终端友好的表格或文本；需要机器读取时再显式加 --format json。

如果当前 Linux/macOS shell 还没有配置 PATH，可以临时在 skill 根目录执行 ./scripts/ztai ...。Windows 上请优先使用 npm 安装后的 ztai.cmd；底层 Python 脚本只作为维护调试回退，不作为常规入口。

远端 run.yaml 事实

run-yaml 通过平台任务 API 读取运行事实。平台应优先读取运行中 worker/container 的 live workspace 文件；只有 live 来源不可用时，才回退到 materialized workspace snapshot。

ztai run-yaml show repo/employee/workspace --format markdown
ztai run-yaml show repo/employee/workspace --format json
ztai run-yaml facts --status running --format markdown
ztai run-yaml facts --repo fusion-control --employee YangJie --format json

run-yaml show 返回单个任务归一化后的 run.yaml 事实，包括来源、摘要、指标变化、决策、下一步和证据指针。

run-yaml facts 按过滤条件返回可见任务的紧凑事实，便于本地 Codex 横向分析多次运行。批量读取由平台限流，以保护远端 live 文件读取。

Gitea 仓库凭据

平台 API token 和 Gitea Git 凭据是两类东西。克隆、拉取、推送或执行 repo publish 前，需要先在本机配置按路径区分的 Gitea 凭据。 公开 skill 不内置私有 Gitea host 或仓库路径；它会从已有 workspace 发现 HTTPS remote，或读取 ~/.agent/ZTAI-CLI/gitea_repos.json。

ztai gitea init-config
ztai gitea configure
ztai gitea verify

它使用 Git credential helper，并避免把 token 打到命令输出里。 本地配置格式和智能体工作流见 references/gitea.md。

安全

不要把平台 token 粘贴到聊天、仓库文件、截图或日志里。 CLI 按以下优先级读取凭据：命令参数、环境变量、~/.agent/ZTAI-CLI/token.json。

正常路径使用 /api/agent/* 和 /api/tasks/*；不需要 SSH 或服务器本地文件。