@zleap-ai/sag-cli 0.4.1 → 0.6.0

package/README.en.md

@@ -38,7 +38,7 @@ sag version
 
 ## Quick start: pick the path that fits you
 
-The CLI offers two independent paths. Pick one based on your situation.
+The CLI offers three independent paths. Pick one based on your situation.
 
 ### Path A: Local Docker, no token required (recommended for local dev)
 
@@ -99,18 +99,83 @@ sag search "how to wire MCP" --source <source-id> --top-k 5
 
 A profile stores only `scheme://host[:port]`. The `/api/v1` prefix is added by the CLI — do not put it in the URL yourself.
 
+### Path C: Connect an enterprise MCP published by the platform
+
+After the enterprise platform generates standard `mcpServers` JSON, no Profile or environment label is required. Run the command below and paste the complete JSON when prompted. The CLI validates `initialize` and `tools/list` before saving it:
+
+```bash
+sag mcp connect
+sag mcp list
+sag mcp tools
+```
+
+The connection name comes from the key inside `mcpServers`, for example `sag-847674ad`. Use `sag mcp use <name>` to select another default connection. Inspect tool inputs before calling one:
+
+```bash
+sag mcp tools
+sag mcp call <tool-name> --arguments-json '{"key":"value"}' --yes
+```
+
+Attach the connection through each Agent's own MCP configuration command:
+
+```bash
+sag mcp attach codex
+sag mcp attach claude-code
+sag mcp attach workbuddy
+sag mcp status
+```
+
+Add `--dry-run` to preview changes. Use `sag mcp detach <agent>` to remove an Agent entry and `sag mcp disconnect` to remove the local connection. Enterprise connections, credentials, and managed state are stored separately from personal Profiles, JWTs, and Docker stdio integration.
+
 ## Use with the Skill
 
-The Skill files (`skill/`) ship alongside this CLI. Copy them into your Agent's skills directory:
+`sag-knowledge` ships in this package. Install it for an explicit Agent target;
+an explicit target is useful in automation even when its host cannot be
+auto-detected:
+
+```bash
+sag skill install --origin https://sag.example.com --agent codex --yes --output ndjson
+sag skill status --agent codex --output ndjson
+sag skill update --agent codex --yes --output ndjson
+```
+
+`update` resolves a newly downloaded `@zleap-ai/sag-cli@latest` bundle; it does
+not silently reuse the running or cached bundle. `--yes` only skips the local
+install/update/remove confirmation. It never bypasses browser approval, drift
+checks, or conflict checks.
+
+Installation only copies the verified bundle and is not authorization.
+`--origin` saves the enterprise SAG address in shared `~/.sag/config.json`.
+A manually installed ZIP asks for the full HTTP or HTTPS address on first use.
+Authorization covers the current SAG account, not an Agent, device, capability
+set, or one Knowledge Base:
 
 ```bash
-# Claude Code
-SKILL_SRC="$(npm root -g)/@zleap-ai/sag-cli"
-cp -r "$SKILL_SRC/skill" ~/.claude/skills/sag-knowledge
+sag skill auth login --origin https://sag.example.com --output ndjson
+sag skill auth status --origin https://sag.example.com --output ndjson
+sag skill auth logout --origin https://sag.example.com --output ndjson
+```
+
+The browser asks only to allow or deny. The CLI stores and refreshes the account
+session as plaintext JSON but never emits credentials. Machine-readable output
+uses NDJSON v1 (`sag.skill.ndjson.v1`), one JSON event per stdout line.
 
-# Codex
-SKILL_SRC="$(npm root -g)/@zleap-ai/sag-cli"
-cp -r "$SKILL_SRC/skill" ~/.codex/skills/sag-knowledge
+`sag skill knowledge` lists Knowledge Bases and documents, asks globally or in
+one Knowledge Base, uploads one file with progress, renames, and soft-deletes.
+Global questions omit the Knowledge Base identifier and use SAG's current
+strategy. Writes require an exact ID, alias, or unique name. Upload accepts one
+regular file with an effective limit of at most 25 MiB, never a folder or batch.
+
+Enterprise MCP uses the separate, compatible `skills/sag-mcp` Skill;
+`sag-knowledge` uses the account Knowledge API. The two integration paths are
+independent, and installing either one does not remove or rewrite the other.
+Only selected, successfully attached Agents get the default `sag-mcp` Skill. With no Agent selected, connect saves only the connection and installs no Skill.
+You can also manage it directly:
+
+```bash
+sag mcp skill install --agent claude-code
+sag mcp skill status --agent claude-code
+sag mcp skill uninstall --agent claude-code
 ```
 
 ## Command reference
@@ -124,6 +189,9 @@ sag source list | get | status
 sag document list | get | status
 sag search <query>
 sag mcp test
+sag skill install | status | update | uninstall
+sag skill auth login | status | logout
+sag skill knowledge list | documents | ask | upload | upload-status | rename | delete
 sag agent list
 sag agent connect <codex | claude-code>
 sag agent status [codex | claude-code]

package/README.md

@@ -38,7 +38,7 @@ sag version
 
 ## 快速上手：选一条适合你的路径
 
-CLI 提供两条互相独立的路径，按你的场景选。
+CLI 提供三条互相独立的路径，按你的场景选。
 
 ### 路径 A：本机 Docker，免 Token（推荐给本地开发者）
 
@@ -99,18 +99,73 @@ sag search "MCP 如何接入" --source <source-id> --top-k 5
 
 Profile URL 只保存 `scheme://host[:port]`。API 前缀 `/api/v1` 由 CLI 自动补齐，不要自己写。
 
+### 路径 C：接入企业平台开放的 MCP
+
+企业平台生成标准 `mcpServers` JSON 后，不需要创建 Profile，也不需要区分开发或生产环境。执行下面的命令并按中文提示粘贴完整 JSON，CLI 会验证 `initialize` 和 `tools/list`，然后保存连接：
+
+```bash
+sag mcp connect
+sag mcp list
+sag mcp tools
+```
+
+连接名称来自平台 JSON 中的 `mcpServers` 键，例如 `sag-847674ad`。需要切换默认连接时使用 `sag mcp use <连接名>`；调用工具前可先查看参数：
+
+```bash
+sag mcp tools
+sag mcp call <工具名> --arguments-json '{"key":"value"}' --yes
+```
+
+将连接接入 Agent 时，CLI 会调用 Agent 自己的 MCP 配置能力写入 URL 和 Header：
+
+```bash
+sag mcp attach codex
+sag mcp attach claude-code
+sag mcp attach workbuddy
+sag mcp status
+```
+
+可以先加 `--dry-run` 查看计划。移除 Agent 配置用 `sag mcp detach <agent>`，彻底删除本地连接用 `sag mcp disconnect`。企业连接、凭据和受管状态与个人版 Profile、JWT 及 Docker stdio 接入分别存放，互不覆盖。
+
 ## 搭配 Skill 使用
 
-Skill 文件（`skill/`）随本 CLI 一起发布。安装 CLI 后复制到 Agent 的 skills 目录：
+`sag-knowledge` 随本包发布。可显式指定 Agent 安装；即使自动探测不到宿主，这也适合自动化场景：
+
+```bash
+sag skill install --origin https://sag.example.com --agent codex --yes --output ndjson
+sag skill status --agent codex --output ndjson
+sag skill update --agent codex --yes --output ndjson
+```
+
+`update` 会新下载并解析 `@zleap-ai/sag-cli@latest`，不会静默复用当前运行中或缓存中的
+Bundle。`--yes` 只跳过本地安装、更新、删除确认；不会跳过浏览器授权、漂移检查或冲突检查。
+
+安装只复制已校验 Bundle，**不等于已授权**。`--origin` 会把企业 SAG 地址保存到共享的
+`~/.sag/config.json`；手动安装 ZIP 时，Agent 会在首次使用时询问完整的 HTTP/HTTPS 地址。
+授权使用当前 SAG 登录账号，不绑定 Agent、设备、能力集合或单个知识库：
 
 ```bash
-# Claude Code
-SKILL_SRC="$(npm root -g)/@zleap-ai/sag-cli"
-cp -r "$SKILL_SRC/skill" ~/.claude/skills/sag-knowledge
+sag skill auth login --origin https://sag.example.com --output ndjson
+sag skill auth status --origin https://sag.example.com --output ndjson
+sag skill auth logout --origin https://sag.example.com --output ndjson
+```
+
+浏览器页面只要求用户允许或拒绝；CLI 把账号会话以明文 JSON 保存并自动刷新，不在输出中
+展示凭据。供程序读取的 Skill 输出为 NDJSON v1（`sag.skill.ndjson.v1`），stdout 每行一个
+JSON event。
 
-# Codex
-SKILL_SRC="$(npm root -g)/@zleap-ai/sag-cli"
-cp -r "$SKILL_SRC/skill" ~/.codex/skills/sag-knowledge
+`sag skill knowledge` 提供知识库列表、文档列表、全局/指定知识库问答、单文件上传与进度、
+重命名和软删除。全局问答不传知识库标识，沿用 SAG 当前检索策略。写操作要求精确的知识库
+ID、alias 或唯一名称。上传只接受一个普通文件，有效上限不超过 25 MiB；不支持文件夹或批量。
+
+企业 MCP 使用独立且兼容的 `skills/sag-mcp` Skill；`sag-knowledge` 使用账号级知识库
+接口。两种接入方式彼此独立，安装其中一种不会移除或改写另一种。
+仅为本次成功接入的所选 Agent 默认安装 `sag-mcp` Skill；不选 Agent 时只保存连接，不安装 Skill。也可以单独管理：
+
+```bash
+sag mcp skill install --agent claude-code
+sag mcp skill status --agent claude-code
+sag mcp skill uninstall --agent claude-code
 ```
 
 ## 命令一览
@@ -124,6 +179,9 @@ sag source list | get | status
 sag document list | get | status
 sag search <query>
 sag mcp test
+sag skill install | status | update | uninstall
+sag skill auth login | status | logout
+sag skill knowledge list | documents | ask | upload | upload-status | rename | delete
 sag agent list
 sag agent connect <codex | claude-code>
 sag agent status [codex | claude-code]