@tencent-ai/agent-sdk 0.3.99 → 0.3.101

package/cli/dist/web-ui/docs/cn/cli/env-vars.md

@@ -0,0 +1,326 @@
+# 环境变量参考
+
+CodeBuddy Code 支持通过环境变量来控制其行为。这些变量可以在启动前设置，也可以在 [`settings.json`](./settings.md#可用设置) 的 `env` 字段中配置以应用到每个会话。
+
+> **提示**：所有环境变量也可以在 `settings.json` 的 `env` 字段中设置，这样可以自动为每个会话应用，或为整个团队推出配置。
+
+## 认证相关
+
+| 环境变量 | 说明 |
+|---------|------|
+| `CODEBUDDY_API_KEY` | API 密钥。设置此密钥用于模型接口调用。在非交互模式 (`-p`) 下始终使用此密钥 |
+| `CODEBUDDY_AUTH_TOKEN` | CodeBuddy 平台认证令牌，用于所有平台接口调用 |
+| `CODEBUDDY_CUSTOM_HEADERS` | 自定义 HTTP 请求头。格式：`Name: Value`，多个请求头用换行符或 `\n` 分隔 |
+
+## API 端点和代理
+
+| 环境变量 | 说明 |
+|---------|------|
+| `CODEBUDDY_BASE_URL` | 覆盖 API 端点地址，通常与 `CODEBUDDY_API_KEY` 配合使用 |
+| `CODEBUDDY_INTERNET_ENVIRONMENT` | 网络环境配置（`internal` 用于中国版，`ioa` 用于 iOA 企业版） |
+| `HTTP_PROXY` / `http_proxy` | HTTP 代理服务器地址 |
+| `HTTPS_PROXY` / `https_proxy` | HTTPS 代理服务器地址 |
+| `NO_PROXY` / `no_proxy` | 绕过代理的域和 IP 列表（逗号分隔，如 `localhost,.example.com`） |
+
+## 模型配置
+
+| 环境变量 | 说明 |
+|---------|------|
+| `CODEBUDDY_MODEL` | 覆盖默认代理模型 |
+| `CODEBUDDY_SMALL_FAST_MODEL` | 后台任务使用的小型快速模型 |
+| `CODEBUDDY_BIG_SLOW_MODEL` | 复杂推理任务使用的大型模型 |
+| `CODEBUDDY_CODE_SUBAGENT_MODEL` | 子代理使用的模型 |
+| `MAX_THINKING_TOKENS` | 启用扩展思考并设置思考过程的 token 预算。默认禁用 |
+
+## Bash 工具配置
+
+| 环境变量 | 说明 |
+|---------|------|
+| `BASH_DEFAULT_TIMEOUT_MS` | 长时间运行 bash 命令的默认超时（默认：120000） |
+| `BASH_MAX_OUTPUT_LENGTH` | bash 输出在内存中保留的最大字符数（默认：30000，上限：150000）。超出部分会被中间截断（保留 head 20% + tail 80%），完整输出会自动保存到磁盘 |
+| `BASH_MAX_TIMEOUT_MS` | 模型可为长时间运行的 bash 命令设置的最大超时（默认：600000） |
+
+## 工具输出外部化
+
+| 环境变量 | 说明 |
+|---------|------|
+| `CODEBUDDY_TOOL_RESULT_THRESHOLD_KB` | 工具结果外部化的大小阈值（KB），超过此阈值的非 bash 工具结果会被保存到磁盘并替换为占位符（默认：50）|
+
+> **说明**：Bash 工具的输出外部化由 `BASH_MAX_OUTPUT_LENGTH` 控制，当输出超过该值发生截断时，完整输出自动流式写入磁盘。`CODEBUDDY_TOOL_RESULT_THRESHOLD_KB` 主要影响其他工具（如 MCP 工具）的大输出处理。详见[工具输出外部化](#工具输出外部化机制)章节。
+
+## 工具和功能开关
+
+| 环境变量 | 说明 |
+|---------|------|
+| `CODEBUDDY_DISABLE_HOT_RELOAD` | 设置为 `1` 禁用热更新系统 |
+| `CODEBUDDY_SKIP_BUILTIN_MARKETPLACE` | 设置为 `1` 跳过内置插件市场加载 |
+| `CODEBUDDY_IMAGE_GEN_ENABLED` | 设置为 `false` 或 `0` 禁用图片生成功能 |
+| `CODEBUDDY_IMAGE_EDIT_ENABLED` | 设置为 `false` 或 `0` 禁用图片编辑功能 |
+| `CODEBUDDY_DEFER_TOOL_LOADING` | 设置为 `false` 或 `0` 禁用 MCP 工具延迟加载 |
+| `CODEBUDDY_SHOW_ALL_DEFERRED_TOOLS` | 设置为 `true` 或 `1` 显示所有延迟工具的完整描述 |
+| `CODEBUDDY_DISABLE_CRON` | 设置为 `1` 禁用计划任务 |
+
+## 上下文和内存
+
+| 环境变量 | 说明 |
+|---------|------|
+| `CODEBUDDY_AUTOCOMPACT_PCT_OVERRIDE` | 设置自动压缩触发的上下文容量百分比（1-100）。默认由产品配置决定（通常 70-92%）。使用更低的值（如 `50`）来更早压缩 |
+| `CODEBUDDY_DISABLE_AUTO_MEMORY` | 设置为 `1` 禁用自动内存，设置为 `0` 启用 |
+| `CODEBUDDY_MEMORY_ENABLED` | 设置为 `true` 或 `1` 启用记忆功能 |
+| `CODEBUDDY_TYPED_MEMORY_ENABLED` | 设置为 `true` 或 `1` 启用分类记忆模式 |
+| `CODEBUDDY_TEAM_MEMORY_ENABLED` | 设置为 `true` 或 `1` 启用团队记忆模式 |
+| `CODEBUDDY_USER_ID` | 团队记忆模式下的用户 ID |
+
+## MCP (Model Context Protocol)
+
+| 环境变量 | 说明 |
+|---------|------|
+| `MCP_TIMEOUT` | MCP 服务器连接的超时时间（毫秒） |
+| `MCP_TOOL_TIMEOUT` | MCP 工具执行的超时时间（毫秒） |
+| `MAX_MCP_OUTPUT_TOKENS` | MCP 工具响应中允许的最大 token 数（默认：20000） |
+
+## 性能和输出
+
+| 环境变量 | 说明 |
+|---------|------|
+| `CODEBUDDY_CODE_MAX_OUTPUT_TOKENS` | 设置大多数请求的最大输出 token 数 |
+| `CODEBUDDY_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | 覆盖文件读取的默认 token 限制（默认：20000） |
+| `CODEBUDDY_STREAM_TIMEOUT_MS` | 流式响应中两个数据块之间允许的最大静默时间（毫秒）（默认：120000） |
+| `CODEBUDDY_FIRST_TOKEN_TIMEOUT_MS` | 等待第一个模型输出的最大时间（毫秒）（默认：120000） |
+
+## 文件系统和配置
+
+| 环境变量 | 说明 |
+|---------|------|
+| `CODEBUDDY_CONFIG_DIR` | 自定义 CodeBuddy Code 存储配置和数据文件的位置 |
+| `CODEBUDDY_CODE_DEBUG_LOGS_DIR` | 调试日志目录 |
+| `CODEBUDDY_SANDBOX_IMAGE` | 容器沙箱镜像（默认：`node:20-alpine`） |
+| `USE_BUILTIN_RIPGREP` | 设置为 `0` 使用系统安装的 `rg` 而不是 CodeBuddy Code 附带的 `rg` |
+
+## Shell 配置
+
+| 环境变量 | 说明 |
+|---------|------|
+| `CODEBUDDY_CODE_SHELL` | 覆盖自动 shell 检测。支持的值：`bash`、`zsh`、`sh`、`powershell`、`cmd` |
+| `CODEBUDDY_CODE_SHELL_PREFIX` | 包装所有 shell 命令的命令前缀（如用于日志或审计） |
+| `CODEBUDDY_CODE_GIT_BASH_PATH` | Windows 下显式指定 Git Bash 路径 |
+| `CODEBUDDY_ENV_FILE` | 在执行每个 shell 命令前自动 source 的环境文件路径 |
+
+## UI 和交互
+
+| 环境变量 | 说明 |
+|---------|------|
+| `CODEBUDDY_CODE_DISABLE_TERMINAL_TITLE` | 设置为 `1` 禁用自动终端标题更新 |
+| `CODEBUDDY_PROMPT_SUGGESTION_DISABLED` | 设置为 `true` 禁用提示建议 |
+| `IS_DEMO` | 设置为 `true` 启用演示模式：隐藏邮箱和组织 |
+
+## 安全和认证
+
+| 环境变量 | 说明 |
+|---------|------|
+| `CODEBUDDY_CODE_CLIENT_CERT` | mTLS 客户端证书文件路径 ⚠️ *暂未支持* |
+| `CODEBUDDY_CODE_CLIENT_KEY` | mTLS 客户端私钥文件路径 ⚠️ *暂未支持* |
+| `CODEBUDDY_CODE_CLIENT_KEY_PASSPHRASE` | mTLS 加密私钥的密码（可选）⚠️ *暂未支持* |
+
+## 遥测和报告
+
+| 环境变量 | 说明 |
+|---------|------|
+| `DISABLE_TELEMETRY` | 设置为 `1` 禁用遥测 |
+| `DISABLE_ERROR_REPORTING` | 设置为 `1` 禁用错误报告 |
+| `DISABLE_AUTOUPDATER` | 设置为 `1` 禁用自动更新 |
+| `DISABLE_FEEDBACK_COMMAND` | 设置为 `1` 禁用 `/feedback` 命令 |
+
+## 任务和后台工作
+
+| 环境变量 | 说明 |
+|---------|------|
+| `CODEBUDDY_DISABLE_BACKGROUND_TASKS` | 设置为 `1` 禁用所有后台任务功能 |
+
+## Agent 执行控制
+
+| 环境变量 | 说明 |
+|---------|------|
+| `CODEBUDDY_CODE_MAX_TURNS` | 主 Agent 的最大执行轮次。优先级：CLI `--max-turns` > 此环境变量 > 默认值 (500) |
+| `CODEBUDDY_CODE_SUBAGENT_MAX_TURNS` | 子 Agent 的最大执行轮次。优先级：CLI `--max-turns` > 此环境变量 > 模型动态传入的 `max_turns` > 默认值 (500) |
+
+## Gateway 和远程访问
+
+| 环境变量 | 说明 |
+|---------|------|
+| `CODEBUDDY_GATEWAY_AUTH` | Gateway 认证模式（`password` 或 `none`） |
+| `CODEBUDDY_GATEWAY_PASSWORD` | Gateway 访问密码 |
+| `CODEBUDDY_GATEWAY_FORCE_TUNNEL` | 设置为 `1` 强制使用 tunnel 模式 |
+| `SERVER__HOST` | `--serve` 模式监听地址（默认：`127.0.0.1`） |
+| `SERVER__PORT` | `--serve` 模式监听端口 |
+
+## 企业微信集成
+
+| 环境变量 | 说明 |
+|---------|------|
+| `CODEBUDDY_GATEWAY_WECHAT_KF_TOKEN` | 企业微信客服 Token |
+| `CODEBUDDY_GATEWAY_WECHAT_KF_ENCODING_AES_KEY` | 企业微信客服加密密钥 |
+| `CODEBUDDY_GATEWAY_WECHAT_KF_CORP_ID` | 企业微信客服企业 ID |
+| `CODEBUDDY_GATEWAY_WECHAT_KF_CORP_SECRET` | 企业微信客服企业密钥 |
+| `CODEBUDDY_GATEWAY_WECHAT_KF_ACCOUNT_NAME` | 企业微信客服账户名 |
+| `CODEBUDDY_GATEWAY_WECOM_TOKEN` | 企业微信 Token |
+| `CODEBUDDY_GATEWAY_WECOM_ENCODING_AES_KEY` | 企业微信加密密钥 |
+| `CODEBUDDY_GATEWAY_WECOM_CORP_ID` | 企业微信企业 ID |
+| `CODEBUDDY_GATEWAY_WECOM_CORP_SECRET` | 企业微信企业密钥 |
+| `CODEBUDDY_GATEWAY_WECOM_AGENT_ID` | 企业微信应用 ID |
+
+## 调试和诊断
+
+| 环境变量 | 说明 |
+|---------|------|
+| `CODEBUDDY_DEBUG` | 设置为 `1` 启用调试模式 |
+| `CODEBUDDY_DEBUG_REQUEST` | 设置为 `1` 启用请求调试 |
+| `CODEBUDDY_STARTUP_PROFILE` | 设置为 `1` 启用启动性能分析 |
+
+## 其他
+
+| 环境变量 | 说明 |
+|---------|------|
+| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | 斜杠命令工具元数据的最大字符数（默认：15000） |
+| `CODEBUDDY_CODE_API_KEY_HELPER_TTL_MS` | 刷新凭证的间隔（毫秒）（默认：300000） |
+
+## 使用示例
+
+### 基础认证配置
+
+```bash
+# 设置 API 密钥
+export CODEBUDDY_API_KEY="your-api-key"
+
+# 设置代理服务器
+export HTTP_PROXY="http://proxy.example.com:8080"
+export HTTPS_PROXY="https://proxy.example.com:8080"
+
+# 设置代理绕过列表
+export NO_PROXY="localhost,127.0.0.1,.internal.example.com"
+
+# 设置自定义请求头（多个 header 使用 \n 分隔）
+export CODEBUDDY_CUSTOM_HEADERS="X-Custom-Header: value1\nX-Another-Header: value2"
+
+# 启动 CodeBuddy
+codebuddy
+```
+
+### 使用第三方模型服务
+
+```bash
+# 使用自定义 API 端点
+export CODEBUDDY_API_KEY="your-api-key"
+export CODEBUDDY_BASE_URL="https://api.example.com/v1"
+codebuddy --model your-model-name
+```
+
+### 中国版配置
+
+```bash
+# 设置中国版环境标识
+export CODEBUDDY_INTERNET_ENVIRONMENT=internal
+
+# 设置 API 密钥
+export CODEBUDDY_API_KEY="your-api-key"
+
+# 启动 CodeBuddy
+codebuddy
+```
+
+### 启用高级功能
+
+```bash
+# 启用自动内存
+export CODEBUDDY_DISABLE_AUTO_MEMORY="0"
+
+# 启用扩展思考
+export MAX_THINKING_TOKENS="10000"
+
+# 非交互模式运行
+codebuddy -p -y "你的查询"
+```
+
+### 调试和性能分析
+
+```bash
+# 启用调试模式
+export CODEBUDDY_DEBUG="1"
+
+# 启用启动性能分析
+export CODEBUDDY_STARTUP_PROFILE="1"
+
+# 启动 CodeBuddy
+codebuddy
+```
+
+## 在 settings.json 中配置
+
+环境变量也可以在 `settings.json` 的 `env` 字段中设置：
+
+```json
+{
+  "env": {
+    "CODEBUDDY_API_KEY": "your-api-key",
+    "HTTPS_PROXY": "https://proxy.example.com:8080",
+    "MAX_THINKING_TOKENS": "10000",
+    "CODEBUDDY_DISABLE_AUTO_MEMORY": "0"
+  }
+}
+```
+
+## 工具输出外部化机制
+
+当工具执行产生的输出超过阈值时，CodeBuddy Code 会自动将完整输出保存到磁盘，给模型只发送截断后的内容和文件路径指针，模型可按需读取完整内容。
+
+### 数据流
+
+```
+Shell 输出
+  ├─→ OutputSpiller（完整输出流式写入磁盘）
+  └─→ TruncateBuffer（内存中保留 head + tail，约 30KB）
+                          ↓
+                  检测到截断 → 生成 placeholder（~2KB preview + 文件路径）
+                          ↓
+                  模型收到 placeholder，可通过 Read 工具按需读取完整文件
+```
+
+### 各阶段数据大小（以 1.3MB 输出为例）
+
+| 阶段 | 内容 | 大小 |
+|------|------|------|
+| 磁盘文件（OutputSpiller） | 完整原始输出 | 1,355,099 bytes |
+| 内存缓冲（TruncateBuffer） | head 6KB + tail 24KB | ~30KB |
+| 发给模型（placeholder） | 文件路径 + preview | ~2KB |
+
+### 存储目录
+
+工具输出文件存储在项目数据目录中：
+
+```
+~/.codebuddy/projects/{projectDir}/
+  └── {sessionId}/
+      ├── tool-results/                          ← 主 session 的工具结果
+      │   ├── {callId}.txt
+      │   └── ...
+      └── subagents/                             ← 子代理数据
+          ├── agent-{agentId}.jsonl              ← 子代理对话历史
+          └── agent-{agentId}/
+              └── tool-results/                  ← 子代理的工具结果
+                  ├── {callId}.txt
+                  └── ...
+```
+
+### 相关环境变量
+
+| 环境变量 | 影响范围 | 默认值 |
+|---------|---------|--------|
+| `BASH_MAX_OUTPUT_LENGTH` | Bash 工具内存保留量，超出则截断并触发磁盘外部化 | 30000 |
+| `CODEBUDDY_TOOL_RESULT_THRESHOLD_KB` | 非 bash 工具（如 MCP）在 session 层的外部化阈值 | 50 |
+
+## 另见
+
+- [Settings](./settings.md) - 在 `settings.json` 中配置环境变量和其他设置
+- [CLI Reference](./cli-reference.md) - 命令行参数完整列表
+- [MCP Setup](./mcp.md) - MCP 服务器配置
+- [子代理](./sub-agents.md) - 子代理存储目录说明

package/cli/dist/web-ui/docs/cn/cli/gitlab-ci-cd.md

@@ -0,0 +1,357 @@
+# CodeBuddy Code GitLab CI/CD 集成
+
+## 概述
+
+CodeBuddy Code 支持与 GitLab CI/CD 深度集成，让您能够在 CI/CD 流水线中使用 AI 辅助完成代码审查、自动化实现和智能优化等任务。该集成基于 CodeBuddy Code CLI 构建，可在 GitLab CI 作业中以编程方式使用 AI 能力。
+
+
+## 工作原理
+
+CodeBuddy Code 利用 GitLab CI/CD 在隔离的作业中运行 AI 任务，并通过 MR 提交结果：
+
+1. **事件驱动编排**: GitLab 监听您选择的触发器（例如 Issue、MR 或评论中提及 @codebuddy)。作业收集上下文和代码库信息，构建提示并运行 CodeBuddy Code。
+
+2. **沙箱执行**：每次交互都在具有严格网络和文件系统规则的容器中运行。CodeBuddy Code 强制执行工作区范围的权限约束写入。每个变更都通过 MR 流转，审查者可以看到差异，审批流程仍然适用。
+
+---
+
+## CodeBuddy 能做什么？
+
+CodeBuddy Code 支持强大的 CI/CD 工作流，改变您与代码的协作方式：
+
+- 从 Issue 描述或评论创建和更新 MR
+- 分析性能回归并提出优化建议
+- 直接在分支中实现功能，然后创建 MR
+- 修复测试或评论中发现的 Bug 和回归问题
+- 响应后续评论以迭代完善请求的变更
+
+---
+
+## 配置指南
+
+### 快速配置
+
+最快的入门方式是在 .gitlab-ci.yml 中添加一个最小化的作业，并将 API 密钥设置为受保护的变量。
+
+**步骤 1：添加受保护的 CI/CD 变量**
+
+进入 GitLab 项目的 **设置 → CI/CD → 变量**，添加以下环境变量：
+
+**认证配置：**
+
+在 GitLab 项目的 **设置 → CI/CD → 变量** 中添加以下环境变量：
+
+- **CODEBUDDY_API_KEY** （必需）
+  - 用于模型接口调用的 API 密钥
+  - 配置时勾选： ✅ 受保护 （Protect variable)、✅ 已屏蔽 （Mask variable)
+
+**可选配置：**
+
+- **CODEBUDDY_INTERNET_ENVIRONMENT**
+  - 网络环境配置（中国版用户需要设置为 `internal`,iOA 用户设置为 `iOA`)
+  
+- **CODEBUDDY_BASE_URL**
+  - 自定义模型服务的基础 URL（需兼容 OpenAI 接口协议）
+
+- **GITLAB_ACCESS_TOKEN**
+  - GitLab 项目访问令牌（需具有 api 范围）
+  - 用于 CodeBuddy 创建/更新 MR 和评论
+  - 如不配置，默认使用 `CI_JOB_TOKEN`
+  - 配置时勾选： ✅ 受保护、✅ 已屏蔽
+
+> 📖 **完整配置指南**：根据您的账号类型，查看对应的配置方法和 API KEY 获取地址：
+> - **iOA 账号用户**（公司内部）：参考 [iOA 账号使用 API KEY](settings.md#ioa-账号使用-api-key)
+> - **中国版用户**：参考 [中国版使用 API KEY](settings.md#中国版使用-api-key)
+> - **海外版用户**：参考 [海外版使用 API KEY](settings.md#海外版使用-api-key)
+> 
+> 每个章节包含完整的环境变量配置方法和 API KEY 获取地址。
+
+**步骤 2：在 .gitlab-ci.yml 中添加 CodeBuddy 作业**
+
+```yaml
+stages:
+  - ai
+
+codebuddy:
+  stage: ai
+  image: node:24-alpine3.21
+  # 根据需要调整触发规则：
+  # - 手动运行
+  # - 合并请求事件
+  # - 当评论包含 '@codebuddy' 时通过 Web/API 触发
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "web"'
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+  variables:
+    GIT_STRATEGY: fetch
+    # CODEBUDDY_API_KEY 从 CI/CD 变量中自动注入
+    # 可选变量： CODEBUDDY_BASE_URL, GITLAB_ACCESS_TOKEN
+  before_script:
+    - apk update
+    - apk add --no-cache git curl bash
+    - npm install -g @tencent-ai/codebuddy-code
+    # 验证 CODEBUDDY_API_KEY 已设置
+    - |
+      if [ -z "$CODEBUDDY_API_KEY" ]; then
+        echo "错误: CODEBUDDY_API_KEY 未设置。请在 GitLab CI/CD 变量中配置"
+        exit 1
+      fi
+  script:
+    # 可选： 启动 GitLab MCP 服务器（如果您的环境提供）
+    - /bin/gitlab-mcp-server || true
+    # 使用 AI_FLOW_* 变量时通过 web/API 触发器传递上下文
+    - echo "$AI_FLOW_INPUT for $AI_FLOW_CONTEXT on $AI_FLOW_EVENT"
+    - >
+      codebuddy
+      -p "${AI_FLOW_INPUT:-'审查此 MR 并实现请求的变更'}"
+      --permission-mode acceptEdits
+      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
+      --debug
+```
+
+添加作业和 API 密钥变量后，通过 CI/CD → 流水线手动运行作业进行测试，或从 MR 触发它，让 CodeBuddy 在分支中提出更新并在需要时创建 MR。
+
+### 手动配置（推荐用于生产环境）
+
+如果您需要更精细的控制：
+
+1. **添加 GitLab API 操作的项目凭据**:
+   - 默认使用 CI_JOB_TOKEN,或创建具有 api 范围的项目访问令牌
+   - 如果使用 PAT,将其存储为 GITLAB_ACCESS_TOKEN（已屏蔽）
+
+2. **在 .gitlab-ci.yml 中添加 CodeBuddy 作业**（参见上面的示例）
+
+3. **（可选）启用提及驱动的触发器**:
+   - 为"评论(notes)"添加项目 Webhook 到您的事件监听器（如果使用）
+   - 让监听器在评论包含 @codebuddy 时调用流水线触发 API,传递 AI_FLOW_INPUT 和 AI_FLOW_CONTEXT 等变量
+
+---
+
+## 使用示例
+
+### 将 Issue 转化为 MR
+
+在 Issue 评论中：
+```
+@codebuddy 根据 Issue 描述实现此功能
+```
+
+CodeBuddy 分析 Issue 和代码库，在分支中编写变更，并创建 MR 供审查。
+
+### 获取实现帮助
+
+在 MR 讨论中：
+```
+@codebuddy 建议一个具体的方法来缓存此 API 调用的结果
+```
+
+CodeBuddy 提出变更方案，添加适当的缓存代码，并更新 MR。
+
+### 快速修复 Bug
+
+在 Issue 或 MR 评论中：
+```
+@codebuddy 修复用户仪表板组件中的 TypeError
+```
+
+CodeBuddy 定位 Bug,实现修复，并更新分支或创建新的 MR。
+
+---
+
+## 最佳实践
+
+### CODEBUDDY.md 配置
+
+在仓库根目录创建 CODEBUDDY.md 文件，定义编码标准、审查标准和项目特定规则。CodeBuddy 在运行期间会读取此文件，并在提出变更时遵循您的约定。
+
+示例 CODEBUDDY.md:
+```markdown
+# 项目编码规范
+
+## 代码风格
+- 使用 ESLint 和 Prettier 进行代码格式化
+- 遵循 Airbnb JavaScript 风格指南
+- 使用 TypeScript 严格模式
+
+## 提交规范
+- 遵循 Conventional Commits 规范
+- 提交信息使用中文
+- 每个提交只包含一个逻辑变更
+
+## 测试要求
+- 所有新功能必须包含单元测试
+- 测试覆盖率不低于 80%
+- 使用 Jest 作为测试框架
+
+## MR 审查清单
+- 代码通过所有 CI 检查
+- 至少一名团队成员审查通过
+- 更新相关文档
+```
+
+### 安全考虑
+
+**永远不要将敏感信息提交到仓库！** 始终使用 GitLab CI/CD 变量：
+
+- 将敏感配置添加为已屏蔽的变量（如有需要，标记为受保护）
+- 限制作业权限和网络出口
+- 像审查其他贡献者一样审查 CodeBuddy 的 MR
+
+### 性能优化
+
+- 保持 CODEBUDDY.md 简洁明了
+- 提供清晰的 Issue/MR 描述以减少迭代
+- 配置合理的作业超时以避免失控运行
+- 在 Runner 中缓存 npm 和包安装（如果可能）
+
+### CI 成本控制
+
+使用 CodeBuddy Code 与 GitLab CI/CD 时，请注意相关成本：
+
+**GitLab Runner 时间：**
+- CodeBuddy 在您的 GitLab Runner 上运行并消耗计算分钟
+- 查看您的 GitLab 计划的 Runner 计费详情
+
+**成本优化建议：**
+- 使用具体的 @codebuddy 命令以减少不必要的轮次
+- 设置适当的 --max-turns 和作业超时值
+- 限制并发以控制并行运行
+
+### 安全与治理
+
+- 每个作业在具有受限网络访问的隔离容器中运行
+- CodeBuddy 的变更通过 MR 流转，审查者可以看到每个差异
+- 分支保护和审批规则适用于 AI 生成的代码
+- CodeBuddy Code 使用工作区范围的权限约束写入
+
+---
+
+## 故障排除
+
+### CodeBuddy 不响应 @codebuddy 命令
+
+- 验证您的流水线正在被触发（手动、MR 事件或通过备注事件监听器/Webhook)
+- 确保 CI/CD 变量存在且配置正确
+- 检查评论是否包含 @codebuddy（不是 /codebuddy)并且您的提及触发器已配置
+
+### 作业无法写入评论或创建 MR
+
+- 确保 CI_JOB_TOKEN 对项目有足够的权限，或使用具有 api 范围的项目访问令牌
+- 检查 mcp__gitlab 工具在 --allowedTools 中已启用
+- 确认作业在 MR 上下文中运行或通过 AI_FLOW_* 变量有足够的上下文
+
+### 身份验证错误
+
+**认证变量未设置：**
+- 确认已在 GitLab 项目的 **设置 → CI/CD → 变量** 中添加 `CODEBUDDY_API_KEY`
+- 检查变量名称拼写是否正确（区分大小写）
+- 如果设置了"受保护"选项，确保作业在受保护的分支上运行
+
+**API 认证失败（401 Unauthorized）:**
+- 验证 API 密钥是否有效且未过期
+- 确认复制 API 密钥时没有包含额外的空格或换行符
+- 检查 API 密钥的权限范围是否足够
+- 查看 [设置配置文档](settings.md#认证配置) 了解详细配置方法
+
+**API 连接失败：**
+- 检查 `CODEBUDDY_BASE_URL` 是否配置正确（如使用自定义端点）
+- 验证 GitLab Runner 能否访问 CodeBuddy API 服务器
+- 确认 URL 格式正确，包含协议（如 `https://api.example.com`）
+
+**密钥在日志中可见：**
+- 确保在 CI/CD 变量配置时勾选了 ✅ 已屏蔽 （Mask variable)
+- 避免在脚本中直接 echo 或打印 API 密钥
+
+**GitLab Access Token 相关问题：**
+
+- 检查配置的 CI/CD 变量是否正确设置
+- 验证相关的访问权限配置
+- 确保 CI_JOB_TOKEN 或 GITLAB_ACCESS_TOKEN 具有足够的权限(api 范围）
+
+### 作业超时
+
+- 增加作业的 timeout 配置
+- 简化提示以减少处理时间
+- 考虑将大任务拆分为多个小任务
+
+---
+
+## 高级配置
+
+### 常用参数和变量
+
+**环境变量：**
+
+CodeBuddy Code 在 CI/CD 环境中使用以下环境变量：
+
+**认证配置：**
+- `CODEBUDDY_API_KEY`：用于模型接口调用，适合 CI/CD 非交互环境
+
+**可选配置：**
+- `CODEBUDDY_BASE_URL`：自定义模型服务的基础 URL
+- `GITLAB_ACCESS_TOKEN`: GitLab API 访问令牌（用于 MR 操作）
+- `CI_JOB_TOKEN`: GitLab CI 自动提供的作业令牌
+
+**流程控制变量：**
+- `AI_FLOW_INPUT`：通过 Web/API 触发器传递的用户输入
+- `AI_FLOW_CONTEXT`：上下文信息（如 Issue ID、MR ID 等）
+- `AI_FLOW_EVENT`：触发事件类型（如 note、issue、merge_request）
+
+> 📖 关于各环境变量的详细说明和配置示例，请参考 [设置配置文档](settings.md#环境变量)
+
+**命令行参数：**
+
+CodeBuddy Code 支持这些常用输入：
+
+- **prompt** (-p)：内联提供指令
+- **max-turns**：限制来回迭代的次数
+- **permission-mode**：权限模式（如 acceptEdits)
+- **allowedTools**：允许使用的工具列表
+- **debug**：启用调试输出
+
+**注意：** 确切的标志和参数可能因 @tencent-ai/codebuddy-code 版本而异。在作业中运行 `codebuddy --help` 查看支持的选项。
+
+### 自定义 CodeBuddy 行为
+
+您可以通过两种主要方式指导 CodeBuddy:
+
+1. **CODEBUDDY.md**：定义编码标准、安全要求和项目约定。CodeBuddy 在运行期间读取此文件并遵循您的规则。
+
+2. **自定义提示**：通过作业中的 prompt/prompt_file 传递特定于任务的指令。对不同的作业使用不同的提示（例如审查、实现、重构）。
+
+### 多环境配置
+
+您可以为不同的环境（开发、测试、生产）配置不同的 CodeBuddy 作业：
+
+```yaml
+# 开发环境 - 自动触发
+codebuddy-dev:
+  stage: ai
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "develop"'
+  script:
+    - codebuddy -p "快速审查并自动合并"
+
+# 生产环境 - 手动触发
+codebuddy-prod:
+  stage: ai
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: manual
+  script:
+    - codebuddy -p "详细审查，生成完整的变更报告"
+```
+
+---
+
+## 参考资源
+
+- [CodeBuddy Code 官方文档](../README.md)
+- [CLI 参考](cli-reference.md)
+- [设置配置](settings.md)
+- [常见工作流](common-workflows.md)
+- [故障排除](troubleshooting.md)
+
+---
+
+**让 AI 赋能您的 CI/CD 流水线，提升开发效率！**