使用 CLI

输入模式

TUI 提供多种输入模式：

内置工具

Qoder CN CLI 内置 Grep、Read、Write、Bash 等工具，可用于文件/目录操作和 shell 命令执行。

斜杠命令

通过以下内置斜杠命令可快速访问功能和设置：

更多内置命令、命令类型和自定义命令说明请参见下文的命令章节。

高级启动选项

启动 CLI 时，可使用以下选项控制其行为：

更多权限相关的启动参数与配置，见下文权限章节。

参数

全局参数可用于任意命令：

快速开始

使用 qoderclicn mcp add 添加 stdio MCP 服务。-- 后面的命令是 Qoder CN CLI 需要启动的服务进程。

qoderclicn mcp add playwright -- npx -y @playwright/mcp@latest

Stdio 服务会随 CLI 自动启动。如果 Qoder CN CLI 已在运行，可使用 /mcp reload 重新发现 MCP 服务和工具；新的会话会在启动时自动发现。

服务类型

使用 -t 选择 MCP 传输类型。

如果没有指定类型，本地命令服务应使用默认的 stdio 行为。

作用域

使用 -s 选择 MCP 服务配置的保存位置。

MCP 服务配置会保存在以下文件中：

# 用户级配置
~/.qoder-cn/settings.json

# 本地项目级配置，通常不提交
${project}/.qoder/settings.local.json

# 项目级配置，通常随项目提交
${project}/.mcp.json

管理服务

列出已配置的服务：

qoderclicn mcp list

移除服务：

qoderclicn mcp remove playwright

推荐服务

常见 MCP 服务包括：

qoderclicn mcp add context7 -- npx -y @upstash/context7-mcp@latest
qoderclicn mcp add deepwiki -- npx -y mcp-deepwiki@latest
qoderclicn mcp add chrome-devtools -- npx chrome-devtools-mcp@latest

MCP 权限

MCP 工具仍会经过 Qoder CN CLI 的权限系统。在默认模式下，调用 MCP 工具通常会请求确认。你可以批准某个具体工具、批准某个 MCP 服务下的所有工具，或在 settings 中配置规则。MCP 工具名通常使用以下格式：

mcp__<server>__<tool>

示例：

{
  "permissions": {
    "allow": [
      "mcp__context7__*"
    ],
    "deny": []
  }
}

故障排查

如果 MCP 工具不可用：

• 运行 qoderclicn mcp list，确认服务已经配置。

• 如果 Qoder CN CLI 已在运行，添加或修改服务后执行 /mcp reload。

• 确认 -- 后面的命令可以在终端中正常运行。

• 对于基于 npx 的服务，确认 Node.js 和网络访问可用。

• 如果服务已连接但工具调用被阻止，请检查权限提示。

权限模式

权限模式决定了 Qoder CN CLI 如何处理工具调用——每种模式在"自动化程度"和"安全宽松度"两个维度上定位不同。

Plan 与 Goal 模式

Plan 是独立的工作状态（非权限策略），可与上述任意权限模式共存。通过 /plan 命令进入/退出（toggle）。进入后 Qoder CN CLI 只读探索代码并输出方案，写入受限于计划文件。

Goal 是自主执行状态。通过 /goal set <目标> 进入——自动切换到 auto 模式并锁定 Shift+Tab 切换。使用 /goal clear 或 /goal pause 退出。

在交互式会话中，按 Shift+Tab 在所有权限模式间循环切换；按 Ctrl+Y 可直达 YOLO 模式。

启动参数

使用 --permission-mode 选择当前会话的默认行为：

qoderclicn --permission-mode default
qoderclicn --permission-mode accept_edits
qoderclicn --permission-mode plan           # 兼容旧版本，实际转译为 default + 进入 Plan 工作状态
qoderclicn --permission-mode auto
qoderclicn --permission-mode bypass_permissions
qoderclicn --permission-mode yolo           # 等价于 bypass_permissions
qoderclicn --permission-mode dont_ask

# 快捷方式
qoderclicn --yolo                         # 等价于 --permission-mode bypass_permissions
qoderclicn --dangerously-skip-permissions # 同上

支持多种命名格式（大小写不敏感），常用别名包括 accept_edits / acceptEdits、bypass_permissions / bypassPermissions / yolo、dont_ask / dontAsk。

非默认模式只会在可信目录中生效。如果当前目录未被信任，Qoder CN CLI 会回退到 default。

权限如何决策

Qoder CN CLI 在每次工具调用前做权限检查。权限结果只有三种：allow（立即执行）、ask（需要外部确认）、deny（阻止执行）。

决策顺序：

1. 先检查 deny 规则——命中即拒绝。

2. 工具自身的安全检查（如危险命令检测、敏感路径检测）。

3. ask 规则——命中则标记为需要确认。

4. 工具级 allow 规则和模式带来的自动允许行为。

5. 如果最终结果仍是 ask，由运行环境决定如何消费。

配置来源与优先级

规则从多个来源合并，按优先级从低到高，共 8 层：

高优先级来源的规则覆盖低优先级。如果组织策略开启了 allowManagedPermissionRulesOnly，则只使用策略托管的规则。

模式配置

设置默认模式——在 ~/.qoder-cn/settings.json 中配置 general.defaultPermissionMode：

{
  "general": {
    "defaultPermissionMode": "accept_edits"
  }
}

禁用 YOLO 模式——组织管理员可通过以下配置阻止用户进入 bypass_permissions 模式：

{
  "security": {
    "disableYoloMode": true
  }
}

禁用 Plan 模式——如果不需要 Plan 工作流，可以关闭：

{
  "general": {
    "plan": {
      "enabled": false
    }
  }
}

Auto 模式分类器配置——通过自然语言规则引导 AI 分类器的判断倾向：

{
  "autoMode": {
    "allow": [
      "running npm/yarn/pnpm scripts defined in package.json",
      "creating or editing test files"
    ],
    "soft_deny": [
      "deleting files outside the test directory",
      "modifying CI/CD configuration"
    ],
    "environment": [
      "This is a Node.js monorepo with pnpm workspaces",
      "The project uses Vitest for testing"
    ]
  }
}

这些规则是软引导——注入到分类器 prompt 作为参考，最终决策仍由 AI 分类器做出。autoMode 只从可信来源（用户全局 settings 和 localSettings）读取，项目 settings 被排除以防止恶意权限提升。

权限规则配置

Qoder CN CLI 通过三种核心策略进行权限控制：Allow、Deny 和 Ask。相关配置文件按优先级递增如下：

~/.qoder-cn/settings.json
${project}/.qoder/settings.json
${project}/.qoder/settings.local.json（通常添加到 .gitignore）

规则按 allow、ask 和 deny 分组：

{
  "permissions": {
    "allow": [
      "Read(/src/**)",
      "Edit(/src/**)",
      "Bash(npm run test:*)"
    ],
    "ask": [
      "Bash(npm publish:*)",
      "WebFetch"
    ],
    "deny": [
      "Read(*.pem)",
      "Bash(rm -rf:*)"
    ]
  }
}

规则语法：

使用规范工具名：Read、Edit、Write、Bash、Grep、Glob、WebFetch、WebSearch、Agent，以及 mcp__github__create_issue 这类 MCP 工具名。

命令行覆盖：

qoderclicn --allowed-tools 'Read,Grep,Bash(git status)'
qoderclicn --disallowed-tools 'Bash(rm -rf:*),mcp__github__delete_repo'
qoderclicn --tools 'Read,Grep,Edit'

信任目录

Qoder CN CLI 将启动时的当前工作目录（CWD）视为主信任目录。在信任目录内：文件读取默认 allow；文件写入在 accept_edits 和 auto 模式下可自动批准；非默认权限模式（auto、bypass 等）才能生效。

如果当前目录不被信任，Qoder CN CLI 会强制回退到 default 模式。通过 --add-dir、/add-dir 命令或 permissions.additionalDirectories 增加额外可信工作目录：

qoderclicn --add-dir ../shared

{
  "permissions": {
    "additionalDirectories": ["../shared"]
  }
}

受保护路径：部分路径受到保护，例如 .git、.vscode、.idea、.husky、大多数 .qoder 配置文件、.bashrc/.zshrc 等 shell 启动文件、Git 配置、.mcp.json、.ripgreprc。在常规交互式模式下，这些路径需要明确批准；在 auto 模式下会被拒绝。

文件访问规则

读取与编辑（Read & Edit） 读取规则适用于所有读文件的工具（如 Grep、Glob 等）；编辑规则适用于 Edit、Write 和 NotebookEdit。文件规则使用 gitignore 风格匹配。

Bash 规则

Bash(...) 规则可以匹配精确命令、命令前缀或通配模式：

• Bash(npm run build) 精确匹配 npm run build

• Bash(npm run test:*) 匹配以 npm run test 开头的命令

• Bash(git log *) 使用 glob 风格通配匹配

Shell 匹配是保守的：deny 和 ask 规则会穿透常见 wrapper 和环境变量前缀；前缀和通配 allow 规则不会静默批准复合命令；危险命令（如破坏性删除或 force push），即使存在宽泛 allow 规则，也可能强制确认。在 auto 模式下，危险 Shell 命令会被拒绝。

Web 和 MCP 规则

WebFetch 限制网络抓取工具可访问的域名。例如 WebFetch(domain:example.com) 将抓取限制为 example.com。

MCP MCP 工具使用完整限定名 mcp__<server>__<tool>；可用 mcp__github__* 匹配某个 server 的所有工具，或使用 mcp__* 匹配所有 MCP 工具。若需限定本次运行只启用指定 MCP server，可使用 --allowed-mcp-server-names：

qoderclicn --allowed-mcp-server-names context7,github

Hook 与权限

Qoder CN CLI 的 Hook 系统在权限决策链路中有两个注入点：PreToolUse（工具执行前）和 PermissionRequest（权限管道产出 ask 之后、弹窗前）。Hook 的权限决策优先级高于权限模式——即使在 bypass_permissions 模式下，PreToolUse Hook 返回 deny 仍然会阻止执行。详见钩子。

在 worktree 中启动

qoderclicn --worktree feature-a
qoderclicn --worktree feature-a "Implement the login fix"
qoderclicn --worktree

如果不传 worktree 名称，Qoder CN CLI 会自动生成一个名称。worktree 准备完成后，Qoder CN CLI 会切换到该 worktree 并正常启动会话。

会话结束时，Qoder CN CLI 会打印 worktree 路径和恢复该会话的命令：

cd <worktree-path> && qoderclicn --resume <session-id>

手动删除 worktree

如需手动删除 worktree，执行：

git worktree remove <worktree-path>

AGENTS.md 常用位置

~/.qoder-cn/AGENTS.md
${project}/AGENTS.md
${project}/AGENTS.local.md
${project}/.qoder/rules/*.md

如果需要使用其他文件名，可以通过 context.fileName 设置单个文件名或文件名数组。默认值是 AGENTS.md。

加载逻辑

启动或刷新记忆时，Qoder CN CLI 的项目记忆会向上查找，并检查每一层的项目规则目录：

• 用户级记忆：加载用户配置目录中的 AGENTS.md。

• 项目和本地项目记忆：在可信工作区内，从当前工作区目录向父目录查找 AGENTS.md、AGENTS.local.md 和 .qoder/rules/**/*.md，默认到 .git 所在目录为止。

• 没有 paths frontmatter 的规则会随项目记忆一起加载；带 paths frontmatter 的规则只会在 Qoder CN CLI 访问匹配文件后按需加载。

• 子目录记忆：启动时不预加载。只有 Qoder CN CLI 成功读取子目录里的文件后，才会从该文件所在目录向上补充此前未加载的记忆文件。

规则（Rules）

规则是放在 rules/ 目录下、按主题拆分的指令文件，用来替代单个臃肿的 AGENTS.md。规则有两种作用域：

规则可选的 paths frontmatter 决定它何时加载：没有 paths 时始终生效；带 paths 时按路径生效。示例：

---
paths:
  - src/api/**
  - "**/*.test.ts"
---

# API 规则

- 使用 `src/api/schema/` 下的共享 schema 校验请求体。
- 每个 handler 必须返回标准错误结构。

管理与自动记忆

在 TUI 中输入 /memory 打开记忆概览，管理用户级、项目级和本地记忆文件；执行 /init 会在项目目录中生成 AGENTS.md。

自动记忆只在交互式会话中运行，通过环境变量启用：

QODER_MEMORY=1 qoderclicn

如果还想启用跨项目的用户级自动记忆根目录，同时设置：

QODER_MEMORY=1 QODER_MEMORY_USER=1 qoderclicn

项目级自动记忆保存在 ~/.qoder-cn/projects/<project>/memory/；启用用户级后还会使用 ~/.qoder-cn/memory/。启用后可在 /memory 面板打开 auto-memory folder，也可输入 /memory manage 管理自动保存的记忆文件。

导入其他文件

AGENTS.md 可以用 @path/to/file 引入其他文件。相对路径基于当前 AGENTS.md 所在目录解析。支持相对路径、绝对路径和 ~/ 路径；行内代码或代码块中的 @... 不会被识别为导入。

See @README.md for the high-level architecture.
Use @docs/testing.md for test data setup.

命令类型

在无头模式下执行命令示例：

# 执行命令（包含额外指令）
qoderclicn -p '/review 重点检查注释覆盖情况'

# 执行自定义 Prompt 命令
qoderclicn -p '/git-commit'

内置命令

Qoder CN CLI 提供的常用内置命令：

创建自定义命令

Qoder CN CLI 支持创建 Prompt 类型的自定义命令，通过配置文件定义命令的名称、描述和系统提示词。命令配置文件为 Markdown 格式，包含 frontmatter 元数据和系统提示词：

---
name: command-name
description: 命令的作用描述，将在 TUI 命令清单中显示
---

这里是命令的系统提示词内容。当用户执行该命令时，这段提示词会被提交到对话中，指导 CLI 完成特定任务。

字段说明：name（必填）——命令的唯一名称，用于 /command-name 调用；description（必填）——命令的功能描述，支持多行文本（使用 YAML 语法）。

命名规范：使用小写字母和连字符（例如 git-commit）；避免使用空格或特殊字符；建议文件名与 name 字段保持一致；子目录中的命令使用 : 作为命名空间分隔符（例如 commands/git/commit.md 注册为 /git:commit）；同目录下若存在 SKILL.md，该目录会注册为单个命令，其它兄弟 .md 文件会被忽略。

存储位置与优先级

命令配置文件可以存储在项目级或用户级目录中：

优先级：如果项目级和用户级存在同名命令，项目级命令优先生效。在 Qoder CN CLI 已启动的情况下，新增或修改命令配置文件后，运行 /commands 即可重新加载。

示例

按以下方式定义一个命令，并将其保存到 ~/.qoder-cn/commands/quest.md 中。

---
name: quest
description: "Intelligent workflow orchestrator that guides users through feature development using specialized subagents"
---

先使用 design subagent 完成系统设计，再使用 code-review subagent 继续完成代码 review

在 TUI 模式下，输入 /quest 触发命令，命令执行过程中会按照提示词先后调用两个子代理完成任务。