CLI操作指南

1 概述

1.1 产品简介

金山云码CLI为一款AI 终端编程助手。用户用自然语言描述需求，AI终端自主完成分析理解、读取代码库、代码编写、文件操作、命令执行、网络搜索等开发任务，如对结果不满意，继续对话调整即可。

1.2 功能特性

1.3 环境要求

2 安装与启动

以下安装方式任选其一。

2.1 一键安装

Mac 系统

1. 打开终端

   • 方式一：搜索「终端」或「Terminal」，回车打开

   • 方式二：打开「访达」→「应用程序」→「实用工具」→「终端」

2. 执行安装命令

npm i -g @企业识别码/ksoc --registry=http://npmhub.ksyun.com

如果提示 Node.js 未安装，请先安装 Node.js 21+。

Windows 系统

1. 打开 PowerShell（管理员）

   • 按 Win + X，选择「Windows PowerShell（管理员）」

2. 执行安装命令

npm i -g @企业识别码/ksoc --registry=http://npmhub.ksyun.com

2.2 登录

首次使用需登录金山云账号。CLI 支持两种登录方式：

方式一：扫码登录（推荐）

适用于对接了企业sso登录且在组织架构内的成员。

系统会在终端中输出二维码，使用企业内部协作 APP 扫码即可完成登录。登录成功后会自动：

• 保存认证令牌到 ~/.local/share/opencode/auth.json

• 配置 ksc-local-mcp MCP 服务器到 ~/.config/opencode/opencode.jsonc

方式二：SK 密钥登录

适用于未接入企业sso登录的所有成员，或对接企业sso登录但是不在组织架构内、由管理员在控制台手动添加的成员。

在管理员手动添加成员后，该成员的 SK 会发送至其添加成员时填写的邮箱内。若无法找到之前的 SK 邮件，也可向管理员申请重发 SK。

在终端中配置环境变量后再启动 CLI：

Mac/Linux：

export KSCC_AUTH_TOKEN=你的sk

Windows CMD：

set KSCC_AUTH_TOKEN=你的sk

Windows PowerShell：

$env:KSCC_AUTH_TOKEN="你的sk"

配置完成后直接运行 ksoc 即可。

退出登录

/logout

2.3 启动

交互式终端（TUI）— 日常开发推荐选择

# 在项目目录下启动
ksoc

# 指定项目路径
ksoc /path/to/project

# 带初始提示启动
ksoc --prompt "帮我检查这个项目的依赖是否有安全漏洞"

启动后进入全屏交互界面，你可以像聊天一样与 AI 对话，AI 会实时展示操作过程和结果。

非交互式运行 — CI/CD 和脚本场景

# 发送一条消息，流式输出，完成后自动退出
ksoc run "修复 auth.test.ts 中失败的测试"

# 以 JSON 格式输出事件流（适合程序解析）
ksoc run --format json "重构用户模块"

# 继续上次会话
ksoc run -c

# 指定模型
ksoc run -m glm-5.1 "分析性能瓶颈"

# 附加文件
ksoc run -f src/auth.ts -f src/auth.test.ts "修复这些测试"

# 自动模式（自动批准非拒绝的权限请求）
ksoc run --auto "自动修复所有 lint 错误"

2.4 VSCode 插件

CLI 可与 VSCode 等 IDE 集成使用：

1. 在终端启动 CLI：

ksoc

1. 在 VSCode 内置终端中运行 CLI 即可获得完整的 TUI 体验。

2. 也可以使用 ACP 协议集成：

ksoc acp --cwd /path/to/project

2.5 升级与卸载

升级

# 启动会自动升级到最新版本
ksoc

CLI 的升级流程会从内部 npm registry 拉取最新版本：

npm install -g "@企业识别码/ksoc" --registry "http://npmhub.ksyun.com"

卸载

npm uninstall -g "@企业识别码/ksoc"

3 输入方式

CLI 支持多种输入方式，适用于不同场景。

3.1 自然语言输入

直接用自然语言描述你的需求：

帮我在 src/utils/ 下创建一个日期格式化工具函数

请分析这个项目的依赖关系

这个文件的认证逻辑有问题吗？

3.2 斜杠命令

在输入框中输入 / 可查看可用命令。斜杠命令用于快速执行特定操作。

常用斜杠命令示例：

/models            切换模型
/init              初始化项目 AGENTS.md
/compact           压缩上下文
/undo              撤销上一条消息
/redo              重做
/new               新建会话（别名 /clear）
/sessions          列出会话
/themes            选择主题
/export            导出会话
/logout            退出登录
/my-page           跳转个人页 

有别名映射的命令列表

3.3 Shell 透传

以 ! 开头输入命令可直接执行 Shell 命令，输出会自动加入对话上下文：

!git status

!npm install axios

再次输入 ! 可关闭 Shell 透传模式。

3.4 文件引用

使用 @ 引用文件、目录或 Git 引用，文件内容会自动加入对话：

帮我优化这段代码 @src/utils/helper.ts

把这个目录的结构说明一下 @src/components/

对比这两个文件 @file1.js @file2.js

@main 最新的提交改了什么？

@ 支持模糊搜索，输入 @ 后输入文件名关键词即可快速定位文件。

3.5 混合输入

以上输入方式可在同一轮对话中组合使用：

!git branch                             先查看当前分支
 @src/api/user.ts 这个文件需要改进       引用文件并提需求
/compact                                压缩上下文

4 Skills

4.1 什么是 Skills

Skills 是可复用的指令包，通过 SKILL.md 文件定义。CLI 会在需要时自动发现和加载相关 Skill，Agent 看到可用的 Skills 列表并按需加载完整内容。

与直接在 AGENTS.md 中写指令不同，Skills 是按需加载的，不会一直占用上下文空间。

4.2 安装 Skills

方式一：从 Skills 广场安装

CLI 支持从金山云内部 Skills 平台安装 Skill。安装的 Skill 默认为全局 Skill，仅本人可使用，可跨项目使用。

https://kscc.ksyun.com/#/skills/square?cc=kc

方式二：手动放置

Skill 文件存放位置：

4.3 自定义 Skills

创建一个 Skill 需要新建目录并放入 SKILL.md 文件：

.opencode/skills/git-release/
└── SKILL.md

SKILL.md 必须以 YAML frontmatter 开头：

---
name: git-release
description: 创建一致的发布和变更日志
license: MIT
---

## 功能
- 从已合并的 PR 生成发布说明
- 提出版本号建议
- 提供可复制的 `gh release create` 命令

## 何时使用
在准备标记版本发布时使用此 Skill。

Frontmatter 字段：

名称规则：

• 1-64 个字符

• 仅小写字母、数字和单个连字符

• 不能以 - 开头或结尾

• 不能包含连续的 --

• 必须与包含 SKILL.md 的目录名一致

4.4 Skill 权限配置

在 opencode.json 中配置 Skill 权限：

{
  "permission": {
    "skill": {
      "*": "allow",
      "pr-review": "allow",
      "internal-*": "deny",
      "experimental-*": "ask"
    }
  }
}

支持通配符：internal-* 匹配 internal-docs、internal-tools 等。

可以为特定 Agent 覆盖 Skill 权限：

{
  "agent": {
    "plan": {
      "permission": {
        "skill": {
          "internal-*": "allow"
        }
      }
    }
  }
}

5 Agent（子代理）

5.1 什么是 Agent

Agent 是专门化的 AI 助手，可在独立的上下文窗口中处理特定类型的任务。

Agent 类型：

• Primary Agent（主代理） — 你直接交互的主助手，使用 Tab 键切换

• Subagent（子代理） — 主代理可调用的专门化助手，也可通过 @ 引用

核心特性：

• 上下文隔离 — 每个子代理拥有独立的上下文窗口，与主对话分离

• 自动委派 — CLI 根据子代理的 description 字段决定何时委派任务

• 工具限制 — 通过权限配置限制可用工具

• 权限继承 — 子代理继承父级权限，但可覆盖

• @ 引用 — 可通过 @agent-name 手动调用子代理

5.2 内置 Agent

CLI 提供以下内置 Agent：

主代理

按 Tab 键在主代理之间切换。

子代理

子代理可被主代理自动调用，也可通过 @general、@explore 等方式手动引用。

隐藏系统 Agent

5.3 自定义 Agent

文件位置

Agent 定义文件为 Markdown 格式（.md），文件名即为 Agent 名称。

文件格式

使用 Markdown frontmatter 格式：

---
description: 代码审查专家，在代码变更后主动审查代码质量
mode: subagent
model: inherit
permission:
  edit: deny
  bash: deny
---

你是一位资深代码审查员，确保代码质量和安全性的高标准。
重点关注：安全漏洞、性能问题、代码异味、缺失测试、文档缺陷。

配置选项

也可以在 JSON 中配置

{
  "agent": {
    "code-reviewer": {
      "description": "代码审查专家",
      "mode": "subagent",
      "model": "ksyun/deepseek-r1",
      "prompt": "你是一位资深代码审查员...",
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

示例：只读数据库查询代理

---
description: 只读数据库查询专家
mode: subagent
model: inherit
permission:
  edit: deny
  bash: ask
---

你是一位数据库查询专家，只拥有只读访问权限。

权限配置示例

支持对特定 bash 命令设置权限：

{
  "agent": {
    "build": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow",
          "git push *": "deny",
          "grep *": "allow"
        }
      }
    }
  }
}

规则按顺序匹配，最后匹配的规则生效。

5.4 Agent 管理命令

创建 Agent

ksoc agent create \
  --description "专注前端代码审查" \
  --mode primary \
  --permissions read,grep,glob \
  --model ksyun/deepseek-r1

列出 Agent

ksoc agent list

在 TUI 中管理

按 Ctrl+X A 打开 Agent 选择器。

子代理会话导航

子代理创建的子会话可通过快捷键导航：

6 MCP 服务器

6.1 什么是 MCP

MCP（Model Context Protocol）是一个开源的 AI 工具集成标准，为 AI 代理连接外部工具、数据库和 API 提供统一协议。

核心概念：

• MCP 服务器是一个进程或远程服务，暴露工具（tools）、资源（resources）和提示（prompts）

• CLI 作为 MCP 客户端，连接服务器并将工具调用路由到对应服务器

• MCP 服务器暴露的工具与 CLI 内置工具并列显示，AI 以相同方式调用

• MCP 工具命名遵循 <服务器名>_<工具名> 的模式

何时添加 MCP 服务器： 当你发现自己频繁将其他工具的数据复制到对话中时，应通过 MCP 连接该系统，让 CLI 直接读取和操作。

CLI 登录成功后会自动配置 ksc-local-mcp MCP 服务器，提供金山云内部服务接入能力。

6.2 传输方式

CLI 支持两种传输方式：

Local（本地进程）

服务器作为本地子进程，通过 stdin/stdout 通信：

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path"],
      "enabled": true,
      "environment": {
        "MY_ENV_VAR": "value"
      }
    }
  }
}

Remote（远程服务器）

通过 HTTP 连接远程 MCP 服务器：

{
  "mcp": {
    "my-remote-mcp": {
      "type": "remote",
      "url": "https://my-mcp-server.com",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer MY_API_KEY"
      }
    }
  }
}

6.3 添加 MCP 服务器

方式一：交互式添加

ksoc mcp add

此命令会引导你添加本地或远程 MCP 服务器。

方式二：配置文件添加

在 opencode.json 或 opencode.jsonc 中配置：

{
  "mcp": {
    "filesystem": {
      "type": "local",
      "command": ["npx", "-y", "@modelcontextprotocol/server-filesystem", "/path"],
      "enabled": true
    },
    "remote-api": {
      "type": "remote",
      "url": "https://example.com/mcp",
      "oauth": { "clientId": "..." },
      "enabled": true
    }
  }
}

方式三：变量替换

支持环境变量和文件内容替换：

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "{env:CONTEXT7_API_KEY}"
      }
    }
  }
}

6.4 管理 MCP 服务器

列出服务器

ksoc mcp list

在 TUI 中输入 /mcp 可查看交互式 MCP 面板，显示工具数量、连接状态、认证状态。

全局/按 Agent 管理

可通过配置禁用特定 MCP 工具：

{
  "tools": {
    "my-mcp*": false
  }
}

支持通配符：my-mcp* 匹配 my-mcp_search、my-mcp_list 等。

也可以为特定 Agent 启用：

{
  "tools": {
    "my-mcp*": false
  },
  "agent": {
    "my-agent": {
      "tools": {
        "my-mcp*": true
      }
    }
  }
}

7 配置系统

7.1 配置文件位置与优先级

配置文件按优先级从低到高合并（后者覆盖前者）：

1. 全局配置 — ~/.config/opencode/opencode.json

2. 自定义配置 — OPENCODE_CONFIG 环境变量指定的路径

3. 项目配置 — 项目根目录 opencode.json 或 opencode.jsonc

4. .opencode 目录 — agents、commands、plugins

5. 内联配置 — OPENCODE_CONFIG_CONTENT 环境变量

6. 托管配置 — macOS /Library/Application Support/opencode/、Linux /etc/opencode/

配置文件是合并的，不是替换的。非冲突的设置会从所有配置中保留。

7.2 常用配置

{
  "$schema": "https://opencode.ai/config.json",

  // 模型选择
  "model": "ksyun/deepseek-r1",
  "small_model": "ksyun/glm-5.1",
  "default_agent": "build",

  // Agent 自定义
  "agent": {
    "build": {
      "model": "ksyun/deepseek-r1"
    }
  },

  // 权限
  "permission": {
    "bash": "ask",
    "edit": { "*.env": "ask" }
  },

  // 会话分享
  "share": "manual",

  // 自动更新
  "autoupdate": true,

  // LSP
  "lsp": true,

  // 上下文压缩
  "compaction": { "auto": true, "tail_turns": 2 },

  // 工具输出截断
  "tool_output": { "max_lines": 2000 },

  // MCP 服务器
  "mcp": {},

  // 插件
  "plugin": [],

  // 指令文件
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md"]
}

7.3 .opencode 目录结构

.opencode/
├── opencode.json      # 项目配置
├── tui.json           # TUI 快捷键和外观配置
├── agents/            # 自定义 Agent (.md)
├── skills/            # 自定义 Skill (SKILL.md)
├── commands/          # 自定义斜杠命令 (.md)
├── plugins/           # 自定义插件 (.ts/.js)
├── tools/             # 自定义工具 (.ts/.js)
├── themes/            # 自定义主题
└── plans/             # 规划模式生成的方案

.opencode 和 ~/.config/opencode 目录使用复数子目录名（agents、commands、plugins、skills、tools、themes）。单数名（如 agent/）也兼容。

7.4 环境变量

7.5 权限系统

CLI 执行敏感操作时会请求你的许可。三种策略：

配置示例

{
  "permission": {
    "*": "allow",           // 默认允许所有
    "bash": "ask",          // Shell 命令每次询问
    "edit": {
      "*.env": "ask",      // 编辑 .env 文件时询问
      "*.env.example": "allow"  // 示例文件允许
    }
  }
}

粒度规则

支持对 bash 命令使用对象语法进行细粒度控制：

{
  "permission": {
    "bash": {
      "*": "ask",
      "git *": "allow",
      "git push *": "deny",
      "npm *": "allow",
      "rm *": "deny",
      "grep *": "allow"
    }
  }
}

规则按顺序匹配，最后匹配的规则生效。

权限键一览

默认值

大部分权限默认为 allow。doom_loop 和 external_directory 默认为 ask。read 默认为 allow，但 .env 文件默认为 deny。

交互中遇到权限请求时

• Once — 本次允许

• Always — 一直允许（保存规则）

• Reject — 拒绝

自动模式

使用 --auto 启动可自动批准非显式拒绝的权限请求：

ksoc --auto
ksoc run --auto "重构这个模块"

显式 deny 规则仍然生效。

7.6 项目规则（AGENTS.md）

在项目根目录创建 AGENTS.md 文件，为 CLI 提供项目特定指令。类似于 Cursor 的规则文件，包含在 LLM 上下文中以自定义行为。

初始化

ksoc

在 TUI 中输入 /init，CLI 会扫描项目并生成或更新 AGENTS.md。

示例

# TypeScript 项目规则

## 项目结构
- `packages/` - 所有工作区包
- `infra/` - 基础设施定义
- `sst.config.ts` - 主配置

## 代码规范
- 使用 TypeScript 严格模式
- 使用 bun workspaces 管理依赖
- 共享代码放在 `packages/core/`

## 构建命令
- 构建: `bun run build`
- 测试: `bun test`
- 类型检查: `bun typecheck`

规则文件位置

优先级：AGENTS.md > CLAUDE.md

引用外部文件

在 opencode.json 中引用额外指令文件：

{
  "instructions": ["CONTRIBUTING.md", "docs/guidelines.md", ".cursor/rules/*.md"]
}

8 自定义命令

8.1 创建命令文件

在 commands/ 目录下创建 .md 文件定义自定义命令：

---
description: 代码审查
agent: plan
model: ksyun/deepseek-r1
---
请审查以下代码中的 bug、安全问题和改进点。
重点关注：{{selection}}

文件存放位置：

• 全局：~/.config/opencode/commands/

• 项目级：.opencode/commands/

文件名即为命令名。例如 test.md 对应 /test 命令。

8.2 命令配置选项

也可以在 opencode.json 中用 JSON 定义命令：

{
  "command": {
    "test": {
      "template": "运行完整测试套件并显示失败结果。重点关注失败的测试并建议修复。",
      "description": "运行测试并报告覆盖率",
      "agent": "build",
      "model": "ksyun/deepseek-r1"
    }
  }
}

8.3 命令模板语法

参数

使用 $ARGUMENTS 占位符传递参数：

---
description: 创建新组件
---
创建一个名为 $ARGUMENTS 的 React 组件，使用 TypeScript。

执行：/component Button — $ARGUMENTS 替换为 Button。

也支持位置参数：$1、$2、$3...

Shell 输出注入

使用 !`command` 注入 bash 命令输出：

---
description: 审查最近变更
---
最近的 git 提交：
!`git log --oneline -10`
审查这些变更并建议改进。

文件引用

使用 @ 引用文件：

---
description: 审查组件
---
审查 @src/components/Button.tsx 中的性能问题并建议改进。

9 插件

9.1 什么是插件

插件是 JavaScript/TypeScript 模块，用于扩展 CLI 的自定义功能。一个插件可以：

• 订阅事件并执行自定义逻辑

• 添加自定义工具

• 修改工具行为

• 注入环境变量

• 自定义上下文压缩

9.2 安装插件

从本地文件安装

将 JS/TS 文件放入插件目录：

• 项目级：.opencode/plugins/

• 全局：~/.config/opencode/plugins/

文件会自动加载。

从 npm 安装

在 opencode.json 中配置：

{
  "plugin": ["opencode-helicone-session", "@my-org/custom-plugin"]
}

npm 插件在启动时自动安装，缓存在 ~/.cache/opencode/node_modules/。

加载顺序

1. 全局配置 (~/.config/opencode/opencode.json)

2. 项目配置 (opencode.json)

3. 全局插件目录 (~/.config/opencode/plugins/)

4. 项目插件目录 (.opencode/plugins/)

10 主题与快捷键

10.1 主题

CLI 内置了多种主题，包括自定义主题：

在 TUI 中切换主题：

/themes

或按 Ctrl+X T 打开主题选择器。

在 tui.json 中配置：

{
  "theme": "tokyonight"
}

基本操作

11 ACP 协议

ACP（Agent Client Protocol）是一种标准化的通信协议，允许 IDE 和其他客户端通过 stdin/stdout 与 AI Agent 进行结构化交互。CLI 实现了 ACP 服务端，IDE 可通过 NDJSON 流接入。

11.1 启动 ACP 服务器

ksoc acp [--hostname=0.0.0.0] [--port=4096] [--cwd=/path/to/project]

启动后，CLI 在 stdin/stdout 上监控 NDJSON 消息，IDE 可直接连接。

工作原理：

IDE  <-- NDJSON/stdin/stdout -->  ksoc acp 进程  <-- HTTP -->  ksoc 服务器

1. IDE 向 stdin 写入 JSON 请求

2. CLI 解析请求，路由到内部 SDK 调用

3. CLI 向 stdout 写入 JSON 响应和流式更新

11.2 支持的操作

12自动压缩（Compaction）

12.1介绍

当对话上下文接近模型 context window 上限时，opencode 会自动调用 LLM 对历史对话生成结构化摘要，替换旧消息，同时保留最近几轮原始对话，释放空间让会话继续。

触发条件：总 token 数 >= usable，其中 usable = context - reserved，reserved 默认 20,000。

12.2配置

在 opencode.json 中：

{
  "compaction": {
    "auto": true,                    // 启用自动压缩（默认 true）
    "prune": false,                  // 裁剪旧工具输出（默认 false）
    "tail_turns": 2,                 // 保留最近几轮原始对话（默认 2）
    "preserve_recent_tokens": 4000, // 保留部分的 token 预算（默认 2000~8000 动态）
    "reserved": 20000                // context 预留缓冲（默认 min(20000, maxOutputTokens)）
  }
}

12.3环境变量