SAG CLI

简体中文 | English

此仓库同时维护两个独立发布包：@zleap-ai/sag-sdk 和 @zleap-ai/sag-cli。SDK 承载 SAG 与企业 Knowledge 的 HTTP 调用、认证刷新和文件上传； CLI 只负责命令解析、Profile/凭据适配、确认和终端输出。

@zleap-ai/sag-cli 是面向 zleap Platform 企业版和 SAG 个人版的命令行工具。它既可以直接 在终端中使用，也可以把知识库能力接入 Codex、Claude Code 和 WorkBuddy。SDK 的 Node.js 用法见 SDK API。

版本变更记录见 CHANGELOG.md。

安装

需要 Node.js ≥ 20.19。

npm install --global @zleap-ai/sag-cli
sag version

企业版快速上手

企业版提供两种独立的接入方式：Knowledge Skill 和平台开放的 MCP。按你的使用场景选择即可。

方式一：通过 Agent 接入 Knowledge Skill

适合让第三方 Agent 使用开放链接已授权的企业知识库。复制平台生成的命令并交给当前 Agent 执行；命令会准备最新的 Skill ZIP，并保存该开放链接的 Origin 与令牌：

npx @zleap-ai/sag-cli@latest skill prepare \
  --origin https://sag.example.com \
  --link-token <open-link-token> \
  --yes \
  --output ndjson

CLI 不再猜测 Agent 类型或安装目录。它只覆盖 ~/.sag/skill-packages/sag-knowledge/sag-knowledge.zip 这一份最新包，并返回绝对路径、版本、 SHA-256、授权状态和下一步动作；Agent 根据自身规则解压到自己的 Skill 目录。令牌只写入 ~/.sag/config.json，不会进入 ZIP 或命令输出。随 Skill 安装的运行程序不提供浏览器授权 命令，不能打开 SAG 授权页面。

授权后，Agent 可以使用以下知识库能力：

• 查看知识库和文档列表；
• 在全部知识库或指定知识库中问答，并保留 SAG 返回的引用；
• 上传一个或多个文件，或目录第一层中受支持的文档，并查询处理进度；
• 重命名文档；
• 将文档移入可恢复的回收站。

也可以直接在终端调用这些能力：

sag skill knowledge list --output ndjson
sag skill knowledge documents --knowledge-base <name-or-id> --output ndjson
sag skill knowledge ask "如何接入企业知识库？" --output ndjson
sag skill knowledge ask "总结这个知识库" --knowledge-base <name-or-id> --output ndjson
sag skill knowledge upload ./document.pdf --knowledge-base <name-or-id> --output ndjson
sag skill knowledge upload-status <import-id> --knowledge-base <name-or-id> --output ndjson

上传支持一个或多个普通文件及目录输入，只扫描目录第一层，最多 100 项。每个文件的有效上限取 25 MiB 与服务端限额的较小值。单个普通文件不需要额外确认；多个文件以及任何目录输入（即使目录内只有一个文件）都需要先预览计划、取得确认，再传入 --yes 执行：

sag skill knowledge upload ./guide.md ./manual.pdf --knowledge-base Engineering --dry-run --output ndjson
sag skill knowledge upload ./guide.md ./manual.pdf --knowledge-base Engineering --yes --output ndjson
sag skill knowledge upload ./guides --knowledge-base Engineering --dry-run --output ndjson
sag skill knowledge upload ./guides --knowledge-base Engineering --yes --output ndjson

目录预览会列出支持的文件和忽略项，不会递归扫描。预览只检查本地条件，执行时会重新检查文件及服务端限制。重命名和删除需要文档当前版本，避免覆盖并发修改：

sag skill knowledge rename <document-id> \
  --knowledge-base <name-or-id> \
  --expected-version <version> \
  --title "新标题" \
  --output ndjson

sag skill knowledge delete <document-id> \
  --knowledge-base <name-or-id> \
  --expected-version <version> \
  --output ndjson

方式二：接入企业 MCP

适合使用企业平台生成的标准 mcpServers JSON。执行连接命令后，按提示粘贴完整 JSON；CLI 会先验证连接，再保存配置。

sag mcp connect
sag mcp list
sag mcp tools

查看工具后，可以在终端调用：

sag mcp call <tool-name> --arguments-json '{"key":"value"}'

如果工具不是明确只读、带有破坏性标记或缺少安全注解，CLI 会要求确认。只有检查过目标连接、工具、参数和影响后，才使用 --yes 跳过该次确认。

也可以把已验证的企业 MCP 接入 Agent：

sag mcp attach codex
sag mcp attach claude-code
sag mcp attach workbuddy
sag mcp status

常用管理命令：

sag mcp use <connection-name>
sag mcp detach <agent>
sag mcp disconnect

需要预览本地配置变更时加 --dry-run。企业 MCP 与 Knowledge Skill 相互独立，安装或移除其中一种不会改写另一种。

仅为本次成功接入的所选 Agent 默认安装 sag-mcp Skill；不选 Agent 时只保存连接，不安装 Skill。也可以单独管理：

sag mcp skill install --agent claude-code
sag mcp skill status --agent claude-code
sag mcp skill uninstall --agent claude-code

SAG 个人版快速上手

个人版支持通过 HTTP API 管理远程或本机 SAG，也支持免 Token 接入本机 Docker SAG。

方式一：通过 HTTP API 使用 SAG

# 1. 添加并选择 SAG 实例
sag profile add local http://localhost:8000
sag profile use local

# 2. 登录
sag auth login --name "你的名字"
sag auth status

# 3. 检查服务并浏览知识内容
sag doctor
sag source list
sag document status --source <source-id>

# 4. 检索
sag search "MCP 如何接入" --source <source-id> --top-k 5

Profile URL 只需填写 scheme://host[:port]，不要附加 /api/v1。

个人版 HTTP API 支持：

• Profile 和登录状态管理；
• SAG 服务诊断；
• 查看信源及其状态；
• 查看文档及处理状态；
• 搜索、目录浏览、文本匹配、内容读取和实体查询。

查看完整命令：

sag --help
sag <command> --help

方式二：本机 Docker 免 Token 接入

前提是本机已安装 Docker，并运行着支持 SAG MCP 的 API 容器。

# 验证本机 SAG MCP
sag mcp test

# 接入 Agent
sag agent connect codex
sag agent connect claude-code

# 查看状态
sag agent status

只操作某个信源时添加 --source-id <source-id>；预览接入计划时添加 --dry-run。

sag mcp test --source-id <source-id>
sag agent connect codex --source-id <source-id> --dry-run
sag agent disconnect codex

输出与自动化

完整 CLI 支持以下全局参数：

--profile <name>         选择个人版 Profile
--url <origin>           临时指定个人版 SAG Origin
--json                   输出 sag.cli.v1 JSON
--output human|ndjson    选择人类可读或逐行 JSON 输出
--quiet                  只输出核心值
--yes                    跳过当前操作要求的确认

企业 Knowledge Skill 推荐使用 --output ndjson。标准输出每行都是一个 sag.skill.ndjson.v1 事件，便于 Agent 和脚本稳定解析。

配置与安全

• 个人版 HTTP 登录凭据保存在操作系统凭据存储中；自动化场景可以使用 SAG_TOKEN。
• 企业 Knowledge Skill 的浏览器账号授权或开放链接令牌按 Origin 保存，不会写入已安装的 Skill 文件。
• 企业 MCP 连接、个人版 Profile 和本机 Docker Agent 接入分别存储，互不覆盖。
• CLI 不会在正常输出、JSON、NDJSON、日志或错误信息中展示 Token。
• --yes 不会代替浏览器授权或跳过配置冲突检查；调用企业 MCP 工具时，仅在确认远端操作影响后使用。

个人版环境变量的优先级为：命令行参数 > 环境变量 > 当前 Profile > 本地默认探测。

SAG_URL=http://localhost:8000
SAG_TOKEN=<jwt>
SAG_PROFILE=local

深入阅读

• CHANGELOG.md — 版本变更记录
• 架构与退出码：中文 / English
• 开发指南：中文 / English
• 兼容性矩阵：中文 / English
• SECURITY.md