yingmi-skill-cli 0.0.1

package/README.md

@@ -0,0 +1,194 @@
+# `yingmi-cli`
+
+一个面向 Agent 的 CLI，用来统一盈米 MCP 能力发现、初始化配置、远端 skill 管理和版本升级。
+
+## 当前状态
+
+当前公开命令聚焦 5 个核心模块：
+
+- `init`
+- `mcp`
+- `remote-skill`
+- `help`
+- `upgrade`
+
+## 设计目标
+
+CLI 聚焦 5 个核心模块：
+
+- `init`：让 CLI 首次可用，负责配置写入、环境检查和连通性验证
+- `mcp`：浏览 MCP 摘要、查看某个工具的完整 OpenAPI 定义，并发起工具调用
+- `remote-skill`：列出可用 skill，进入某个 skill 上下文查看目录结构，并可在该目录执行脚本
+- `help`：提供显式帮助入口，并保持与 `--help` 同源
+- `upgrade`：检查版本并升级 CLI
+
+这套划分的核心原则是：先初始化，再发现能力，再查看定义，再执行调用或远端脚本，让命令树围绕统一心智模型组织。
+
+## 安装
+
+```bash
+npm install -g yingmi-cli
+```
+
+安装后可通过 `yingmi-cli` 命令使用。
+
+## 命令树
+
+```bash
+yingmi-cli init setup
+yingmi-cli init setup --api-key <value>
+yingmi-cli init setup --phone <value>
+yingmi-cli init setup --verify-code <value>
+yingmi-cli init status
+yingmi-cli init doctor
+
+yingmi-cli mcp list
+yingmi-cli mcp schema <toolName>
+yingmi-cli mcp call <toolName> --input <json>
+
+yingmi-cli remote-skill list
+yingmi-cli remote-skill enter <skillName>
+yingmi-cli remote-skill exec --script <script>
+yingmi-cli remote-skill exec --script-file <path>
+
+yingmi-cli help [command]
+
+yingmi-cli upgrade
+yingmi-cli upgrade --check-only
+```
+
+## 模块说明
+
+### `init`
+
+`init` 负责“把 CLI 跑起来”，而不是生成项目脚手架。
+
+常用命令：
+
+```bash
+yingmi-cli init setup --api-key <value>
+yingmi-cli init setup --phone <手机号>
+yingmi-cli init setup --verify-code <验证码>
+yingmi-cli init status
+yingmi-cli init doctor
+```
+
+行为约束：
+
+- `setup` 是统一初始化入口：空参数返回引导，`--api-key` 直接写入，`--phone` 发起验证码登录，`--verify-code` 完成 API Key 申请
+- `status` 输出当前初始化状态，例如配置是否存在、依赖是否齐全、连接是否可用
+- `doctor` 用于排障，输出问题、原因和修复建议
+- 任何敏感信息都必须脱敏显示
+
+### `mcp`
+
+`mcp` 负责“发现能力、理解能力、执行能力”三个阶段。
+
+常用命令：
+
+```bash
+yingmi-cli mcp list
+yingmi-cli mcp schema getFundCampisiIndicator
+yingmi-cli mcp call getFundCampisiIndicator --input '{"fundCode":"000001","timePeriod":"LAST_YEAR"}'
+```
+
+行为约束：
+
+- `mcp list`：展示工具摘要，默认优先结构化结果
+- `mcp schema <toolName>`：展示某个工具的完整 OpenAPI 定义
+- `mcp call <toolName>`：调用目标工具，支持 `--input` 和 `--input-file`
+- 输出协议必须稳定，stdout 只承载结果，stderr 承载提示与错误
+
+### `remote-skill`
+
+`remote-skill` 面向远端 skill 运行服务，核心是“发现 skill 并进入 skill 上下文工作”。
+
+常用命令：
+
+```bash
+yingmi-cli remote-skill list
+yingmi-cli remote-skill enter fund-analyzer
+yingmi-cli remote-skill exec --script 'node index.js'
+yingmi-cli remote-skill exec --script-file ./scripts/run.sh
+```
+
+行为约束：
+
+- `list`：调用远端 `/api/get-skills` 接口，使用本地 `apiKey` 作为请求头
+- `enter <skillName>`：每次都会重新调用远端 `/api/get-skill-by-name` 获取压缩包地址，下载并解压到 `~/.yingmi-cli/skills/<skillName>` 后输出本地工作目录和文件清单，并把当前 skill 上下文写入本地配置
+- `exec --script/--script-file`：只能在最近一次成功 `enter` 后使用，在当前 skill 目录执行脚本，并输出执行状态、退出码、stdout 和 stderr
+- 远端服务地址默认读取 `https://stargate-staging.yingmi-inc.com/`，也可在 `~/.yingmi-cli/config.json` 里手工设置 `remoteSkillServerBaseUrl`
+
+### `help`
+
+`help` 是显式帮助入口，用来补足 `--help` 之外的可发现性。
+
+常用命令：
+
+```bash
+yingmi-cli help
+yingmi-cli help mcp
+yingmi-cli mcp --help
+```
+
+约束：
+
+- `help` 和 `--help` 必须共用同一套命令元数据
+- 每个命令帮助都应包含 2 到 3 个最常见示例
+
+### `upgrade`
+
+`upgrade` 负责版本检查与升级。
+
+常用命令：
+
+```bash
+yingmi-cli upgrade
+yingmi-cli upgrade --check-only
+```
+
+约束：
+
+- `--check-only` 只检查版本，不执行安装
+- 真正执行升级前，应明确告知副作用
+- 非 TTY 场景下不能依赖确认交互
+
+## 输出协议
+
+为了让 CLI 更适合 Agent 和脚本消费，协议约束如下：
+
+- 结构化结果只输出到 stdout
+- 提示、进度、告警、错误只输出到 stderr
+- 默认优先稳定 JSON；如需人类可读格式，显式提供 `--format`
+- 所有命令都必须支持非交互运行
+- 有副作用的命令优先支持 `--dry-run`、`--check-only`、`--non-interactive`
+
+## 推荐交互流程
+
+推荐使用方式如下：
+
+1. 先执行 `yingmi-cli init setup`，让 CLI 进入可用状态。
+2. 用 `yingmi-cli mcp list` 浏览可用工具。
+3. 用 `yingmi-cli mcp schema <toolName>` 查看完整定义。
+4. 用 `yingmi-cli mcp call <toolName>` 发起调用。
+5. 需要处理远端 skill 时，先用 `yingmi-cli remote-skill list` 发现 skill，再用 `yingmi-cli remote-skill enter <skillName>` 刷新并查看目录，最后用 `yingmi-cli remote-skill exec` 在该上下文执行脚本。
+6. 需要查看帮助或升级时，分别使用 `help` 和 `upgrade`。
+
+## 当前代码组织
+
+当前实现已经按模块目录继续收口，避免核心流程散落在 `src` 根目录：
+
+- `src/commands/init/`：`init setup/status/doctor` 的命令注册与服务实现，`src/commands/init/x-sign/` 承接验证码初始化所需的 `x-sign` 捕获能力
+- `src/commands/mcp/`：`mcp list/schema/call` 的命令注册，`src/commands/mcp/openapi.ts` 与 `src/commands/mcp/common/` 共同承接 OpenAPI 读取、输入拆分和本地校验
+- `src/commands/upgrade/`：`upgrade` 命令入口，`src/commands/upgrade/service/` 负责版本检查、比较和安装执行
+- `src/shared/`：跨命令共享的配置与失败出口，目前包含 `config.ts` 与 `fail.ts`
+
+## 开发约束
+
+在继续实现这套 CLI 时，优先遵守：
+
+- 命令按模块组织，避免再新增散列顶层命令
+- 参数必须有长参数名
+- 输出协议必须稳定且可机读
+- 非 TTY / CI 环境下不能依赖交互
+- 修改命令协议时，必须同步更新 `ARCHITECTURE.md`、`docs/agent-cli-guidelines.md` 和 `.cursor/rules/agent-cli-commands.mdc`