# 本地智能体安装

这个目录下现在有三个本地命令入口：

1. 统一 CLI：`qingflow`
2. 记录/待办优先的 `qingflow-app-user-mcp`
3. 精简 builder 的 `qingflow-app-builder-mcp`

## 本地鉴权推荐方案

本地模式现在推荐优先使用 `credential` 建立会话，而不是直接注入 `token`。

推荐链路：

1. createClaw 或其它本地宿主为当前实例保存 `credential`
2. 本地 MCP 调用 `auth_use_credential`
3. MCP 用该 `credential` 请求 apaas `/mcp/auth/context`
4. 解析并保存 `token / wsId / qfVersion / uid`
5. 业务工具直接使用这份上下文

`auth_use_credential` 是本地唯一鉴权主路径。

补充说明：

- 对 stdio MCP 来说，主路径仍然只有 `auth_use_credential`。
- 如果你是在终端里直接使用 `qingflow` CLI，可以额外使用 `qingflow auth login` 作为“人类登录”入口；默认会提示轻流邮箱和隐藏密码，拿到 `token` 后建立本地 CLI 会话。
- 也就是说，这次新增的是 CLI 的登录入口，不是给 MCP 增加第二套会话模型。

## npm 安装器适用场景

适合这类本地 agent / gateway：

- Claude Desktop
- Cline / Roo / Cursor 这类本地 MCP 客户端
- OpenClaw 风格的本地 agent 容器或本地 gateway
- 任何支持 `command + args + env` 的 stdio MCP 客户端

## 前置条件

- Node.js >= 16.16
- Python >= 3.11
- 安装过程中可以访问 PyPI

如果机器上没有默认 `python3` / `python`，可以先设置：

```bash
export QINGFLOW_MCP_PYTHON=/path/to/python3.11
```

## 安装方式

### 方式 1：在源码目录预热运行环境

```bash
cd qingflow-support/mcp-server
npm install
```

这个模式适合你已经有源码 checkout，只想让当前目录具备本地 agent 可调用的运行时。

### 方式 2：全局安装到当前机器

```bash
cd qingflow-support/mcp-server
npm install -g .
```

### 方式 3：安装到某个本地 agent workspace

```bash
npm install /absolute/path/to/qingflow-support/mcp-server
```

### 方式 4：离线分发 tgz 安装包

先在源码目录打包：

```bash
cd qingflow-support/mcp-server
npm run pack:npm
```

会生成：

```bash
dist/npm/qingflow-tech-qingflow-cli-<version>.tgz
dist/npm/qingflow-cli-<version>.tgz
dist/npm/qingflow-tech-qingflow-app-user-mcp-<version>.tgz
dist/npm/qingflow-tech-qingflow-app-builder-mcp-<version>.tgz
```

然后在目标机器安装：

```bash
npx -y -p /absolute/path/to/dist/npm/qingflow-cli-<version>.tgz qingflow-cli install --package /absolute/path/to/dist/npm/qingflow-tech-qingflow-cli-<version>.tgz
npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-cli-<version>.tgz
npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-user-mcp-<version>.tgz
npm install /absolute/path/to/dist/npm/qingflow-tech-qingflow-app-builder-mcp-<version>.tgz
```

线上官网入口对应：

```bash
npx qingflow-cli@latest install
```

安装器只安装真实 CLI 包 `@qingflow-tech/qingflow-cli`。它会先检查 Node.js、npm 和 Python 3.11+；如果 `npm install -g` 因本机全局目录权限失败，安装器会自动 fallback 到用户目录（macOS/Linux 为 `~/.local`，Windows 为当前用户 AppData npm 目录），但不会修改 shell 配置文件；PATH 缺失时会打印需要执行的 shell / PowerShell 命令。排障可加 `--verbose`；如需禁止 fallback 可加 `--no-fallback`。

安装时会自动：

1. 创建 `.npm-python/`
2. 在其中建立 Python 虚拟环境
3. 执行 `pip install .`
4. 在安装位置暴露对应入口：CLI 包暴露 `qingflow` / `qingflow-skills`；app-user 包暴露 `qingflow-app-user-mcp` / `qingflow-app-user-mcp-skills`；app-builder 包暴露 `qingflow-app-builder-mcp` / `qingflow-app-builder-mcp-skills`
5. 携带 `skills/<skill-name>/SKILL.md`，但不在 `postinstall` 阶段自动覆盖本机 agent skills

## Skills 挂载

显式查看包内 skills：

```bash
qingflow-skills list
```

独立 MCP split 包使用包专属 skills 命令，避免全局安装多个包时发生 bin 覆盖：

```bash
qingflow-app-user-mcp-skills list
qingflow-app-builder-mcp-skills list
```

显式挂载到 Codex 用户目录：

```bash
qingflow-skills install --agent codex --scope user
```

如果通过一次性 `npx -p <package>` 执行安装，请加 `--copy`，避免 symlink 指向 npm 临时执行缓存：

```bash
npx -y -p @qingflow-tech/qingflow-cli qingflow-skills install --agent codex --scope user --copy
```

也可以挂载到项目级 agent 目录：

```bash
qingflow-skills install --agent claude-code --scope project
qingflow-skills install --agent cursor --scope project --copy
qingflow-skills install --agent all --scope project
```

默认行为：

- `--mode symlink`：使用 symlink，让 npm 包版本成为单一来源
- `--scope user`：安装到用户级 agent skills 目录
- `--agent codex`：目标 agent 为 Codex
- 不覆盖已有同名 skill；需要替换时显式加 `--force`
- 每次安装会在目标 skills 目录下写入 `.qingflow-skill-sources/<skill>.json`，记录 package、version、source、destination、agent、scope、mode

## 本地验证

如果你在源码目录执行了 `npm install`，可直接这样启动：

```bash
cd qingflow-support/mcp-server
node ./npm/bin/qingflow.mjs --help
node ./npm/bin/qingflow-skills.mjs list
node ./npm/bin/qingflow-app-user-mcp.mjs
node ./npm/bin/qingflow-app-builder-mcp.mjs
```

如果你是全局安装对应包：

```bash
qingflow --help
qingflow-skills list
qingflow-app-user-mcp
qingflow-app-user-mcp-skills list
qingflow-app-builder-mcp
qingflow-app-builder-mcp-skills list
```

如果你是把包安装到了某个本地 agent workspace，安装对应包后命令通常位于：

```bash
/absolute/path/to/agent-workspace/node_modules/.bin/qingflow
/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-skills
/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-user-mcp
/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-user-mcp-skills
/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-builder-mcp
/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-builder-mcp-skills
```

如果你是从 tgz 安装到某个空目录，命令通常位于：

```bash
/absolute/path/to/install-dir/node_modules/.bin/qingflow
/absolute/path/to/install-dir/node_modules/.bin/qingflow-app-user-mcp
/absolute/path/to/install-dir/node_modules/.bin/qingflow-app-builder-mcp
```

这是 stdio MCP server，正常情况下不会输出欢迎信息，而是等待客户端连接。

## 客户端配置

### 通用 stdio MCP 客户端

如果你直接使用源码 checkout：

```json
{
  "mcpServers": {
    "qingflow": {
      "command": "node",
      "args": [
        "/absolute/path/to/qingflow-support/mcp-server/npm/bin/qingflow-app-user-mcp.mjs"
      ],
      "env": {
        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp",
        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
      }
    }
  }
}
```

如果你已经全局安装：

```json
{
  "mcpServers": {
    "qingflow": {
      "command": "qingflow-app-user-mcp",
      "args": [],
      "env": {
        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp",
        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
      }
    }
  }
}
```

如果你把包安装到了某个本地 agent workspace：

```json
{
  "mcpServers": {
    "qingflow": {
      "command": "/absolute/path/to/agent-workspace/node_modules/.bin/qingflow-app-user-mcp",
      "args": [],
      "env": {
        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
        "QINGFLOW_MCP_HOME": "/absolute/path/to/.qingflow-mcp",
        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
      }
    }
  }
}
```

### 使用 npx

如果不做全局安装，也可以直接运行独立包：

```json
{
  "mcpServers": {
    "qingflow-user": {
      "command": "npx",
      "args": [
        "-y",
        "@qingflow-tech/qingflow-app-user-mcp"
      ],
      "env": {
        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
      }
    },
    "qingflow-builder": {
      "command": "npx",
      "args": [
        "-y",
        "@qingflow-tech/qingflow-app-builder-mcp"
      ],
      "env": {
        "QINGFLOW_MCP_DEFAULT_BASE_URL": "https://qingflow.com/api",
        "QINGFLOW_MCP_CREDIT_METER_ENABLED": "true",
        "QINGFLOW_MCP_CREDIT_APAAS_BASE_URL": "https://apaas.internal.example.com",
        "QINGFLOW_MCP_CREDIT_APAAS_PATH": "/user/credit/usage"
      }
    }
  }
}
```

说明：
- 源码目录 `npm install` 不会把命令加到全局 PATH；这种模式请用 `node ./npm/bin/qingflow.mjs`、`node ./npm/bin/qingflow-app-user-mcp.mjs` 或 `node ./npm/bin/qingflow-app-builder-mcp.mjs`
- `npx` 方式适合临时安装或容器化本地 agent
- 全局安装方式更适合长期固定使用的本机开发环境
- 计费接口使用当前登录会话的 `token` 与 `wsId` 请求头，可通过 `QINGFLOW_MCP_CREDIT_APAAS_BASE_URL/PATH` 覆盖调用记录接口地址

## 排障

如果安装失败，优先检查：

1. `node -v`
2. `python3 --version`
3. `pip` 是否能访问 PyPI
4. 是否设置了错误的 `QINGFLOW_MCP_PYTHON`

如果需要重装 Python 侧运行环境，可以删掉：

```bash
rm -rf .npm-python
```

然后重新执行：

```bash
npm install
```

如果 MCP 客户端一调用工具就报 `Transport closed`，优先检查这几件事：

1. 不要混用不同版本的 `@qingflow-tech/qingflow-cli`、`@qingflow-tech/qingflow-app-user-mcp`、`@qingflow-tech/qingflow-app-builder-mcp`
2. 删除安装目录下的 `.npm-python`
3. 重新执行 `npm install` 或重新安装对应 tgz/npm 包
4. 再启动 MCP 客户端

现在 stdio MCP 入口会拒绝在启动瞬间“边启动边重建 Python 运行时”，因为安装日志一旦写进 stdout，就会破坏 MCP 握手并表现成 `Transport closed`。如果运行时缺失或版本不一致，入口会直接报错并提示重装，而不是静默自修复。

## createClaw 本地接入示例

如果 createClaw 已经为当前本地实例保存了 `credential`，推荐在首次建链时调用：

```bash
qingflow auth use-credential \
  --base-url https://qingflow.com/api \
  --credential-stdin
```

然后把 `credential` 写到 stdin。

等价 MCP 工具调用参数：

```json
{
  "profile": "default",
  "base_url": "https://qingflow.com/api",
  "credential": "1602853_277941",
  "persist": false
}
```

说明：

- 本地会把解析后的 `token` 和原始 `credential` 写入 profile 文件，用于后续 CLI 命令恢复会话
- `persist=true` 时，本地还会优先把解析后的 `token` 和原始 `credential` 同步写入系统 keychain
- 当前工作区以 `/mcp/auth/context` 返回的 `wsId` 为准，不再通过本地 MCP 显式切换