byy/qiming
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
cc55fd819f9c5fbf7960d6f43b345eee5e711419
qiming/qimingcode/CONFIGURATION.zh-CN.md

13 KiB
Raw Blame History

QimingCode 配置指南

安装

首先，请通过 npm 全局安装 QimingCode：

npm install -g qimingcode@latest

ACP Meta 配置

QimingCode 支持通过 ACP (Agent Client Protocol) 的 _meta 字段传入额外的会话配置信息。

自定义 System Prompt

仿照 claude-code 的模式，您可以在初始化 Session 时通过 _meta 传递 systemPrompt。这允许客户端动态设定 Agent 的人设或上下文。

示例 (JSON RPC):

{
  "method": "session/new",
  "params": {
    "_meta": {
      "systemPrompt": "你是 QimingCode，一个强大的 AI 编程助手。请在回答前仔细思考..."
    }
  }
}

QimingCode 会提取该字段并将其作为 System Prompt 注入到底层 LLM 的上下文中。

全局权限配置 (禁用工具)

您可以通过全局配置文件或环境变量来精细控制工具的权限。例如，如果您希望禁用 Agent 的联网能力 (websearch, webfetch)，可以使用以下配置。

方式一：配置文件 (推荐)

在 项目根目录 或 用户全局配置目录 (~/.config/opencode/) 下创建或编辑 opencode.json：

{
  "permission": {
    "websearch": "deny",
    "webfetch": "deny"
  }
}

配置生效后，Agent 将无法调用被拒绝 (deny) 的工具。

方式二：环境变量

您也可以在启动服务时通过设置环境变量 OPENCODE_PERMISSION 来注入权限配置：

export OPENCODE_PERMISSION='{"websearch":"deny","webfetch":"deny"}'

支持的权限选项

permission 对象支持对所有注册工具的控制，常用的包括：

  • websearch: 联网搜索
  • webfetch: 获取网页内容
  • bash: 执行 Shell 命令
  • edit: 文件编辑 (包括 write, patch 等)
  • read: 文件读取

可选值：

  • "allow": 允许 (默认)
  • "deny": 拒绝 (禁用)
  • "ask": 询问用户 (CLI 交互模式下有效)

Zed 编辑器调试配置

要在 Zed 中使用并调试 QimingCode，请修改 Zed 的配置文件 (cmd+, 打开 settings.json)。

1. 配置 Agent Server

添加 qimingcode 到 agent_servers：

示例 1：智谱 GLM-4 (Anthropic 兼容协议)

{
  "agent_servers": {
    "qimingcode": {
      "type": "custom",
      "command": "qimingcode",
      "args": ["acp"],
      "env": {
        "OPENCODE_MODEL": "anthropic-compatible/glm-4.7",
        "ANTHROPIC_BASE_URL": "https://open.bigmodel.cn/api/anthropic",
        "ANTHROPIC_API_KEY": "sk-...",
        "OPENCODE_LOG_DIR": "/path/to/logs/"
      },
      "favorite_models": [],
      "default_config_options": {},
      "favorite_config_option_values": {}
    }
  }
}

示例 2：智谱 GLM-4 (OpenAI 兼容协议)

{
  "agent_servers": {
    "qimingcode": {
      "type": "custom",
      "command": "qimingcode",
      "args": ["acp"],
      "env": {
        "OPENCODE_MODEL": "openai-compatible/glm-4.7",
        "OPENAI_BASE_URL": "https://open.bigmodel.cn/api/paas/v4/",
        "OPENAI_API_KEY": "sk-...",
        "OPENCODE_LOG_DIR": "/path/to/logs/"
      },
      "favorite_models": [],
      "default_config_options": {},
      "favorite_config_option_values": {}
    }
  }
}

注意：请确保 qimingcode 已在您的 PATH 环境中。

2. 查看调试日志

QimingCode (Opencode) 的日志默认存储在 XDG 数据目录中。在 macOS/Linux 上通常位于 ~/.local/share/opencode/log/。

您可以在终端中实时监控日志以进行调试：

# 查看实时日志
tail -f ~/.local/share/opencode/log/qimingcode.log

如果遇到连接问题或 Agent 行为异常，日志通常会包含详细的错误堆栈和运行状态信息。

可观测性与日志参考

为了方便调试、审计和性能分析，QimingCode 提供了详细的结构化日志（Structured Logging）。日志文件默认以 key=value 的形式记录，关键字段采用 JSON 格式以保留层级结构。

启用日志

方式一：CLI 参数

在启动 CLI 时，使用 --log-dir 参数指定日志存储目录：

qimingcode run "hello" --log-dir ./logs

方式二：环境变量 (默认配置)

设置环境变量 OPENCODE_LOG_DIR：

export OPENCODE_LOG_DIR="./logs"
qimingcode run "hello"

日志文件将按日期和时间生成，例如 qimingcode_2026_01_22_132601_1gq4r9.log。其命名规则为：qimingcode_YYYY_MM_DD_HHmmss_随机后缀.log。

核心日志事件一览表

以下是日志中常见的事件名称（Event Name）及其含义，便于快速检索：

分类 事件名称 (Event) 含义与关键信息
System system.env 系统启动时的完整环境变量快照（用于诊断环境差异）。
敏感信息（如 API Key, Token 等）已自动脱敏为 ******。
Config config.load 最终加载的完整配置对象 (已脱敏)。
包含了从文件、环境变量及默认值合并后的所有设置（如模型、键位映射等）。
ACP acp.initialize ACP 协议初始化握手。
记录 clientCapabilities, clientInfo (客户端名称及版本，如 Zed)。
acp.shutdown.success/error ACP 服务正常关闭或异常退出。
标志着连接周期的结束。
acp.message.part 双向消息/内容更新。
包含用户输入 (text)、模型生成 (delta)、快照信息 (snapshot) 及工具状态。
acp.permission.result 权限请求结果。
记录 permissionID, outcome (allow/reject)。
acp.tool.update 工具调用状态更新。
记录 toolCallId, status (pending/in_progress/completed/error)。
Session session.create / .result 会话创建请求与结果。
记录 sessionId, cwd, 以及初始化的 model 配置。
session.load / .result 会话加载请求与结果。
用于恢复旧会话。
session.context 会话上下文详情。
包含 systemPrompt, model, mcpServers 等完整上下文快照。
LLM llm.prompt 发送给 LLM 的完整提示词消息数组。
包含 System Prompt、对话历史及工具调用结果。
llm.config 当前 LLM 请求的配置参数。
记录 provider, model, temperature 以及其他 API 特定参数。
MCP mcp.tool.execute / mcp.stderr MCP 工具执行。记录工具名称、参数、耗时以及標準错误输出。
mcp.stderr 对调试自定义 MCP Server 极其关键。
Skill skill.load / skill.execute 技能（Skill）的加载与执行事件。
记录技能路径、名称以及执行时的参数。
Performance provider.state 核心 Provider 状态初始化耗时。
provider.getSDK 动态加载 Provider SDK 耗时。
plugin.load 插件（Plugin）加载耗时（包含 bun install 和导入过程）。
bun.run / bun.install 内部执行 Bun 命令或安装依赖的详细信息及耗时。

日志内容示例

[2026-01-20T08:50:48.712Z] INFO  llm.prompt content="You are an interactive CLI tool..."

[2026-01-20T08:50:48.713Z] INFO  llm.config provider=opencode model=big-pickle temperature=N/A options={"reasoningEffort":"minimal"}

[2026-01-20T08:50:48.715Z] INFO  system.env PATH=/usr/bin:/bin NODE_ENV=development ...

[2026-01-20T08:51:12.334Z] INFO  mcp.tool.execute status=completed duration=150ms tool=list_files

模型连接配置 (环境变量)

QimingCode 支持通过环境变量配置默认的模型连接参数，方便在不同环境（如 Docker、CI/CD）中快速切换。

环境变量 说明 示例
OPENCODE_MODEL 默认此模型 ID。当 CLI 未指定 -m 时生效。 openai/gpt-4o

OpenAI 及其兼容协议 (OpenAI, DeepSeek, Ollama, openai-compatible 等)

环境变量 说明 示例
OPENCODE_OPENAI_API_BASE OpenAI 兼容接口 Base URL https://api.deepseek.com/v1
OPENCODE_OPENAI_API_KEY API Key sk-proj-...

多种环境变量名支持

为了兼容不同的使用习惯和第三方工具，以下环境变量名互相等效（按优先级排序，靠前的优先级更高）：

配置项 支持的环境变量名（按优先级）
Base URL OPENCODE_OPENAI_API_BASE > OPENCODE_API_BASE > OPENAI_BASE_URL
API Key OPENCODE_OPENAI_API_KEY > OPENCODE_API_KEY > OPENAI_API_KEY

示例场景：使用 openai-compatible 连接 DeepSeek

# 使用任意一种环境变量名均可
export OPENCODE_MODEL="openai-compatible/deepseek-chat"
export OPENAI_BASE_URL="https://api.deepseek.com/v1"   # 或 OPENCODE_OPENAI_API_BASE
export OPENAI_API_KEY="sk-..."                         # 或 OPENCODE_OPENAI_API_KEY

qimingcode run "Hello DeepSeek"

Anthropic 及其兼容协议 (Claude, GLM-4 等)

环境变量 说明 示例
OPENCODE_ANTHROPIC_API_BASE Anthropic 兼容接口 Base URL https://your-proxy.com/v1
OPENCODE_ANTHROPIC_API_KEY API Key sk-ant-...

多种环境变量名支持

为了兼容不同的使用习惯和第三方工具，以下环境变量名互相等效（按优先级排序，靠前的优先级更高）：

配置项 支持的环境变量名（按优先级）
Base URL OPENCODE_ANTHROPIC_API_BASE > OPENCODE_API_BASE > ANTHROPIC_BASE_URL
API Key OPENCODE_ANTHROPIC_API_KEY > OPENCODE_API_KEY > ANTHROPIC_API_KEY

⚠️ 注意: Anthropic 环境变量与 OpenAI 环境变量是独立的。例如，使用 anthropic-compatible 模型时，会优先读取 OPENCODE_ANTHROPIC_* 或 ANTHROPIC_* 系列变量，不会使用 OPENAI_* 变量。

示例场景：连接智谱 GLM-4 (Anthropic 兼容模式)

# 使用任意一种环境变量名均可
export OPENCODE_MODEL="anthropic-compatible/glm-4.7"
export ANTHROPIC_BASE_URL="https://open.bigmodel.cn/api/anthropic"  # 或 OPENCODE_ANTHROPIC_API_BASE
export ANTHROPIC_API_KEY="your_api_key"                             # 或 OPENCODE_ANTHROPIC_API_KEY

qimingcode run "Hello GLM"

上下文限制配置 (max_context_tokens)

除了输出限制，您还可以配置 max_context_tokens 来限制模型的上下文窗口大小 (Context Window)。这对于使用代理或自定义模型时非常有用，可以强制截断过长的上下文，避免超出模型限制。

配置优先级：Model Options > Provider Options > Environment Variable > Default

示例配置

{
  "provider": {
    "openai-compatible": {
      "options": {
        "max_context_tokens": 16000 // 为该 provider 的所有模型设置上下文上限
      },
      "models": {
        "deepseek-chat": {
            "options": {
                "max_context_tokens": 32000 // 仅为该模型设置上下文上限，覆盖 provider 设置
            }
        }
      }
    }
  }
}

Token 限制配置 (max_tokens)

对于 openai-compatible 和 anthropic-compatible 等自定义模型，您可以通过配置文件覆盖默认的 Token 输出限制。默认情况下，系统使用 4096 作为输出后的最大 token 数限制，您可以通过 options.max_tokens 来修改此值。

示例配置

修改 ~/.config/opencode/opencode.json：

{
  "provider": {
    "openai-compatible": {
      "options": {
        "max_tokens": 16000
      }
    },
    "anthropic-compatible": {
      "options": {
        "max_tokens": 8000
      }
    }
  }
}

配置后，相应 Provider 的所有模型输出上限将更新为您指定的值。

使用环境变量配置 (推荐用于 Docker/CI)

您也可以通过环境变量来设置全局或特定 Provider 的 max_tokens，优先级低于 opencode.json 配置。

环境变量 说明
OPENCODE_MAX_TOKENS 全局最大 Token 限制 (所有自定义 Provider)
OPENCODE_MAX_CONTEXT_TOKENS 全局上下文窗口限制 (所有自定义 Provider)

示例：

export OPENCODE_MAX_TOKENS=12000
qimingcode run "hello"
Reference in New Issue View Git Blame Copy Permalink