@tencent-ai/agent-sdk 0.3.99 → 0.3.101

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

@@ -0,0 +1,326 @@
+# Environment Variables Reference
+
+CodeBuddy Code supports environment variables to control its behavior. These variables can be set before startup, or configured in the `env` field of [`settings.json`](./settings.md#available-settings) to apply to every session.
+
+> **Tip**: All environment variables can also be set in the `env` field of `settings.json`, which automatically applies them to every session or rolls out configuration for an entire team.
+
+## Authentication
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_API_KEY` | API key. Set this key for model API calls. Always uses this key in non-interactive mode (`-p`) |
+| `CODEBUDDY_AUTH_TOKEN` | CodeBuddy platform authentication token for all platform API calls |
+| `CODEBUDDY_CUSTOM_HEADERS` | Custom HTTP headers. Format: `Name: Value`, multiple headers separated by newline or `\n` |
+
+## API Endpoints and Proxy
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_BASE_URL` | Override the API endpoint address, typically used with `CODEBUDDY_API_KEY` |
+| `CODEBUDDY_INTERNET_ENVIRONMENT` | Network environment configuration (`internal` for China edition, `ioa` for iOA enterprise edition) |
+| `HTTP_PROXY` / `http_proxy` | HTTP proxy server address |
+| `HTTPS_PROXY` / `https_proxy` | HTTPS proxy server address |
+| `NO_PROXY` / `no_proxy` | List of domains and IPs to bypass proxy (comma-separated, e.g., `localhost,.example.com`) |
+
+## Model Configuration
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_MODEL` | Override the default agent model |
+| `CODEBUDDY_SMALL_FAST_MODEL` | Small, fast model used for background tasks |
+| `CODEBUDDY_BIG_SLOW_MODEL` | Large model used for complex reasoning tasks |
+| `CODEBUDDY_CODE_SUBAGENT_MODEL` | Model used by sub-agents |
+| `MAX_THINKING_TOKENS` | Enable extended thinking and set the token budget for the thinking process. Disabled by default |
+
+## Bash Tool Configuration
+
+| Environment Variable | Description |
+|---------|------|
+| `BASH_DEFAULT_TIMEOUT_MS` | Default timeout for long-running bash commands (default: 120000) |
+| `BASH_MAX_OUTPUT_LENGTH` | Maximum characters of bash output retained in memory (default: 30000, max: 150000). Content exceeding the limit is mid-truncated (keeping head 20% + tail 80%), and the full output is automatically saved to disk |
+| `BASH_MAX_TIMEOUT_MS` | Maximum timeout the model can set for long-running bash commands (default: 600000) |
+
+## Tool Output Externalization
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_TOOL_RESULT_THRESHOLD_KB` | Size threshold (KB) for tool result externalization. Non-bash tool results exceeding this threshold are saved to disk and replaced with a placeholder (default: 50) |
+
+> **Note**: Bash tool output externalization is controlled by `BASH_MAX_OUTPUT_LENGTH`. When output is truncated due to exceeding that value, the full output is automatically streamed to disk. `CODEBUDDY_TOOL_RESULT_THRESHOLD_KB` primarily affects large output handling for other tools (e.g., MCP tools). See the [Tool Output Externalization](#tool-output-externalization-mechanism) section for details.
+
+## Tools and Feature Toggles
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_DISABLE_HOT_RELOAD` | Set to `1` to disable the hot reload system |
+| `CODEBUDDY_SKIP_BUILTIN_MARKETPLACE` | Set to `1` to skip loading the built-in plugin marketplace |
+| `CODEBUDDY_IMAGE_GEN_ENABLED` | Set to `false` or `0` to disable image generation |
+| `CODEBUDDY_IMAGE_EDIT_ENABLED` | Set to `false` or `0` to disable image editing |
+| `CODEBUDDY_DEFER_TOOL_LOADING` | Set to `false` or `0` to disable MCP tool deferred loading |
+| `CODEBUDDY_SHOW_ALL_DEFERRED_TOOLS` | Set to `true` or `1` to show full descriptions for all deferred tools |
+| `CODEBUDDY_DISABLE_CRON` | Set to `1` to disable scheduled tasks |
+
+## Context and Memory
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_AUTOCOMPACT_PCT_OVERRIDE` | Set the context capacity percentage for triggering auto-compaction (1-100). Default is determined by product configuration (typically 70-92%). Use a lower value (e.g., `50`) to compact earlier |
+| `CODEBUDDY_DISABLE_AUTO_MEMORY` | Set to `1` to disable auto memory, set to `0` to enable |
+| `CODEBUDDY_MEMORY_ENABLED` | Set to `true` or `1` to enable memory functionality |
+| `CODEBUDDY_TYPED_MEMORY_ENABLED` | Set to `true` or `1` to enable typed memory mode |
+| `CODEBUDDY_TEAM_MEMORY_ENABLED` | Set to `true` or `1` to enable team memory mode |
+| `CODEBUDDY_USER_ID` | User ID for team memory mode |
+
+## MCP (Model Context Protocol)
+
+| Environment Variable | Description |
+|---------|------|
+| `MCP_TIMEOUT` | Timeout for MCP server connections (milliseconds) |
+| `MCP_TOOL_TIMEOUT` | Timeout for MCP tool execution (milliseconds) |
+| `MAX_MCP_OUTPUT_TOKENS` | Maximum tokens allowed in MCP tool responses (default: 20000) |
+
+## Performance and Output
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_CODE_MAX_OUTPUT_TOKENS` | Set the maximum output tokens for most requests |
+| `CODEBUDDY_CODE_FILE_READ_MAX_OUTPUT_TOKENS` | Override the default token limit for file reads (default: 20000) |
+| `CODEBUDDY_STREAM_TIMEOUT_MS` | Maximum silent time between two data chunks in streaming responses (milliseconds) (default: 120000) |
+| `CODEBUDDY_FIRST_TOKEN_TIMEOUT_MS` | Maximum time to wait for the first model output (milliseconds) (default: 120000) |
+
+## Filesystem and Configuration
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_CONFIG_DIR` | Custom location for CodeBuddy Code to store configuration and data files |
+| `CODEBUDDY_CODE_DEBUG_LOGS_DIR` | Debug log directory |
+| `CODEBUDDY_SANDBOX_IMAGE` | Container sandbox image (default: `node:20-alpine`) |
+| `USE_BUILTIN_RIPGREP` | Set to `0` to use system-installed `rg` instead of the one bundled with CodeBuddy Code |
+
+## Shell Configuration
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_CODE_SHELL` | Override automatic shell detection. Supported values: `bash`, `zsh`, `sh`, `powershell`, `cmd` |
+| `CODEBUDDY_CODE_SHELL_PREFIX` | Command prefix wrapping all shell commands (e.g., for logging or auditing) |
+| `CODEBUDDY_CODE_GIT_BASH_PATH` | Explicitly specify the Git Bash path on Windows |
+| `CODEBUDDY_ENV_FILE` | Path to an environment file that is automatically sourced before executing each shell command |
+
+## UI and Interaction
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_CODE_DISABLE_TERMINAL_TITLE` | Set to `1` to disable automatic terminal title updates |
+| `CODEBUDDY_PROMPT_SUGGESTION_DISABLED` | Set to `true` to disable prompt suggestions |
+| `IS_DEMO` | Set to `true` to enable demo mode: hides email and organization |
+
+## Security and Authentication
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_CODE_CLIENT_CERT` | mTLS client certificate file path ⚠️ *Not yet supported* |
+| `CODEBUDDY_CODE_CLIENT_KEY` | mTLS client private key file path ⚠️ *Not yet supported* |
+| `CODEBUDDY_CODE_CLIENT_KEY_PASSPHRASE` | Passphrase for the mTLS encrypted private key (optional) ⚠️ *Not yet supported* |
+
+## Telemetry and Reporting
+
+| Environment Variable | Description |
+|---------|------|
+| `DISABLE_TELEMETRY` | Set to `1` to disable telemetry |
+| `DISABLE_ERROR_REPORTING` | Set to `1` to disable error reporting |
+| `DISABLE_AUTOUPDATER` | Set to `1` to disable auto-updates |
+| `DISABLE_FEEDBACK_COMMAND` | Set to `1` to disable the `/feedback` command |
+
+## Tasks and Background Work
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_DISABLE_BACKGROUND_TASKS` | Set to `1` to disable all background task functionality |
+
+## Agent Execution Control
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_CODE_MAX_TURNS` | Maximum execution turns for the main Agent. Priority: CLI `--max-turns` > this environment variable > default (500) |
+| `CODEBUDDY_CODE_SUBAGENT_MAX_TURNS` | Maximum execution turns for sub-Agents. Priority: CLI `--max-turns` > this environment variable > model dynamically passed `max_turns` > default (500) |
+
+## Gateway and Remote Access
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_GATEWAY_AUTH` | Gateway authentication mode (`password` or `none`) |
+| `CODEBUDDY_GATEWAY_PASSWORD` | Gateway access password |
+| `CODEBUDDY_GATEWAY_FORCE_TUNNEL` | Set to `1` to force tunnel mode |
+| `SERVER__HOST` | Listen address for `--serve` mode (default: `127.0.0.1`) |
+| `SERVER__PORT` | Listen port for `--serve` mode |
+
+## WeCom Integration
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_GATEWAY_WECHAT_KF_TOKEN` | WeCom Customer Service Token |
+| `CODEBUDDY_GATEWAY_WECHAT_KF_ENCODING_AES_KEY` | WeCom Customer Service Encryption Key |
+| `CODEBUDDY_GATEWAY_WECHAT_KF_CORP_ID` | WeCom Customer Service Corp ID |
+| `CODEBUDDY_GATEWAY_WECHAT_KF_CORP_SECRET` | WeCom Customer Service Corp Secret |
+| `CODEBUDDY_GATEWAY_WECHAT_KF_ACCOUNT_NAME` | WeCom Customer Service Account Name |
+| `CODEBUDDY_GATEWAY_WECOM_TOKEN` | WeCom Token |
+| `CODEBUDDY_GATEWAY_WECOM_ENCODING_AES_KEY` | WeCom Encryption Key |
+| `CODEBUDDY_GATEWAY_WECOM_CORP_ID` | WeCom Corp ID |
+| `CODEBUDDY_GATEWAY_WECOM_CORP_SECRET` | WeCom Corp Secret |
+| `CODEBUDDY_GATEWAY_WECOM_AGENT_ID` | WeCom Agent ID |
+
+## Debugging and Diagnostics
+
+| Environment Variable | Description |
+|---------|------|
+| `CODEBUDDY_DEBUG` | Set to `1` to enable debug mode |
+| `CODEBUDDY_DEBUG_REQUEST` | Set to `1` to enable request debugging |
+| `CODEBUDDY_STARTUP_PROFILE` | Set to `1` to enable startup profiling |
+
+## Miscellaneous
+
+| Environment Variable | Description |
+|---------|------|
+| `SLASH_COMMAND_TOOL_CHAR_BUDGET` | Maximum character count for slash command tool metadata (default: 15000) |
+| `CODEBUDDY_CODE_API_KEY_HELPER_TTL_MS` | Interval for refreshing credentials (milliseconds) (default: 300000) |
+
+## Usage Examples
+
+### Basic Authentication Configuration
+
+```bash
+# Set API key
+export CODEBUDDY_API_KEY="your-api-key"
+
+# Set proxy server
+export HTTP_PROXY="http://proxy.example.com:8080"
+export HTTPS_PROXY="https://proxy.example.com:8080"
+
+# Set proxy bypass list
+export NO_PROXY="localhost,127.0.0.1,.internal.example.com"
+
+# Set custom headers (multiple headers separated by \n)
+export CODEBUDDY_CUSTOM_HEADERS="X-Custom-Header: value1\nX-Another-Header: value2"
+
+# Start CodeBuddy
+codebuddy
+```
+
+### Using Third-Party Model Services
+
+```bash
+# Use a custom API endpoint
+export CODEBUDDY_API_KEY="your-api-key"
+export CODEBUDDY_BASE_URL="https://api.example.com/v1"
+codebuddy --model your-model-name
+```
+
+### China Edition Configuration
+
+```bash
+# Set China edition environment identifier
+export CODEBUDDY_INTERNET_ENVIRONMENT=internal
+
+# Set API key
+export CODEBUDDY_API_KEY="your-api-key"
+
+# Start CodeBuddy
+codebuddy
+```
+
+### Enabling Advanced Features
+
+```bash
+# Enable auto memory
+export CODEBUDDY_DISABLE_AUTO_MEMORY="0"
+
+# Enable extended thinking
+export MAX_THINKING_TOKENS="10000"
+
+# Run in non-interactive mode
+codebuddy -p -y "your query"
+```
+
+### Debugging and Profiling
+
+```bash
+# Enable debug mode
+export CODEBUDDY_DEBUG="1"
+
+# Enable startup profiling
+export CODEBUDDY_STARTUP_PROFILE="1"
+
+# Start CodeBuddy
+codebuddy
+```
+
+## Configuring in settings.json
+
+Environment variables can also be set in the `env` field of `settings.json`:
+
+```json
+{
+  "env": {
+    "CODEBUDDY_API_KEY": "your-api-key",
+    "HTTPS_PROXY": "https://proxy.example.com:8080",
+    "MAX_THINKING_TOKENS": "10000",
+    "CODEBUDDY_DISABLE_AUTO_MEMORY": "0"
+  }
+}
+```
+
+## Tool Output Externalization Mechanism
+
+When tool execution produces output exceeding the threshold, CodeBuddy Code automatically saves the full output to disk and sends only truncated content with a file path pointer to the model, which can read the full content on demand.
+
+### Data Flow
+
+```
+Shell output
+  ├─→ OutputSpiller (full output streamed to disk)
+  └─→ TruncateBuffer (head + tail retained in memory, ~30KB)
+                          ↓
+                  Truncation detected → generate placeholder (~2KB preview + file path)
+                          ↓
+                  Model receives placeholder, can read full file via Read tool on demand
+```
+
+### Data Size at Each Stage (using 1.3MB output as example)
+
+| Stage | Content | Size |
+|------|------|------|
+| Disk file (OutputSpiller) | Full raw output | 1,355,099 bytes |
+| Memory buffer (TruncateBuffer) | head 6KB + tail 24KB | ~30KB |
+| Sent to model (placeholder) | File path + preview | ~2KB |
+
+### Storage Directory
+
+Tool output files are stored in the project data directory:
+
+```
+~/.codebuddy/projects/{projectDir}/
+  └── {sessionId}/
+      ├── tool-results/                          ← Main session tool results
+      │   ├── {callId}.txt
+      │   └── ...
+      └── subagents/                             ← Sub-agent data
+          ├── agent-{agentId}.jsonl              ← Sub-agent conversation history
+          └── agent-{agentId}/
+              └── tool-results/                  ← Sub-agent tool results
+                  ├── {callId}.txt
+                  └── ...
+```
+
+### Related Environment Variables
+
+| Environment Variable | Scope | Default |
+|---------|---------|--------|
+| `BASH_MAX_OUTPUT_LENGTH` | Bash tool memory retention, triggers disk externalization when exceeded | 30000 |
+| `CODEBUDDY_TOOL_RESULT_THRESHOLD_KB` | Session-level externalization threshold for non-bash tools (e.g., MCP) | 50 |
+
+## See Also
+
+- [Settings](./settings.md) - Configure environment variables and other settings in `settings.json`
+- [CLI Reference](./cli-reference.md) - Complete list of command-line arguments
+- [MCP Setup](./mcp.md) - MCP server configuration
+- [Sub-Agents](./sub-agents.md) - Sub-agent storage directory documentation

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

@@ -0,0 +1,357 @@
+# CodeBuddy Code GitLab CI/CD Integration
+
+## Overview
+
+CodeBuddy Code supports deep integration with GitLab CI/CD, enabling you to leverage AI assistance for code review, automated implementation, and intelligent optimization tasks within your CI/CD pipelines. This integration is built on top of the CodeBuddy Code CLI, allowing you to programmatically use AI capabilities in GitLab CI jobs.
+
+
+## How It Works
+
+CodeBuddy Code leverages GitLab CI/CD to run AI tasks in isolated jobs and submit results via MRs:
+
+1. **Event-Driven Orchestration**: GitLab listens for your chosen triggers (e.g., Issues, MRs, or @codebuddy mentions in comments). Jobs collect context and codebase information, build prompts, and run CodeBuddy Code.
+
+2. **Sandboxed Execution**: Each interaction runs in a container with strict network and filesystem rules. CodeBuddy Code enforces workspace-scoped permission constraints on writes. Every change flows through MRs, reviewers can see diffs, and approval workflows still apply.
+
+---
+
+## What Can CodeBuddy Do?
+
+CodeBuddy Code supports powerful CI/CD workflows that transform how you collaborate with code:
+
+- Create and update MRs from Issue descriptions or comments
+- Analyze performance regressions and suggest optimizations
+- Implement features directly in branches, then create MRs
+- Fix bugs and regressions found in tests or comments
+- Respond to follow-up comments to iteratively refine requested changes
+
+---
+
+## Configuration Guide
+
+### Quick Setup
+
+The fastest way to get started is to add a minimal job to .gitlab-ci.yml and set your API key as a protected variable.
+
+**Step 1: Add Protected CI/CD Variables**
+
+Go to your GitLab project's **Settings → CI/CD → Variables** and add the following environment variables:
+
+**Authentication Configuration:**
+
+Add the following environment variables in your GitLab project's **Settings → CI/CD → Variables**:
+
+- **CODEBUDDY_API_KEY** (Required)
+  - API key for model interface calls
+  - When configuring, check: ✅ Protect variable, ✅ Mask variable
+
+**Optional Configuration:**
+
+- **CODEBUDDY_INTERNET_ENVIRONMENT**
+  - Network environment configuration (China version users need to set to `internal`, iOA users set to `iOA`)
+
+- **CODEBUDDY_BASE_URL**
+  - Custom base URL for model service (must be compatible with OpenAI API protocol)
+
+- **GITLAB_ACCESS_TOKEN**
+  - GitLab project access token (requires api scope)
+  - Used for CodeBuddy to create/update MRs and comments
+  - If not configured, defaults to using `CI_JOB_TOKEN`
+  - When configuring, check: ✅ Protect variable, ✅ Mask variable
+
+> 📖 **Complete Configuration Guide**: Based on your account type, refer to the corresponding configuration methods and API KEY retrieval locations:
+> - **iOA Account Users** (internal company): See [Using API KEY with iOA Account](settings.md#ioa-账号使用-api-key)
+> - **China Version Users**: See [Using API KEY with China Version](settings.md#中国版使用-api-key)
+> - **International Version Users**: See [Using API KEY with International Version](settings.md#海外版使用-api-key)
+>
+> Each section includes complete environment variable configuration methods and API KEY retrieval locations.
+
+**Step 2: Add CodeBuddy Job to .gitlab-ci.yml**
+
+```yaml
+stages:
+  - ai
+
+codebuddy:
+  stage: ai
+  image: node:24-alpine3.21
+  # Adjust trigger rules as needed:
+  # - Manual run
+  # - Merge request events
+  # - Triggered via Web/API when comments contain '@codebuddy'
+  rules:
+    - if: '$CI_PIPELINE_SOURCE == "web"'
+    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
+  variables:
+    GIT_STRATEGY: fetch
+    # CODEBUDDY_API_KEY is automatically injected from CI/CD variables
+    # Optional variables: CODEBUDDY_BASE_URL, GITLAB_ACCESS_TOKEN
+  before_script:
+    - apk update
+    - apk add --no-cache git curl bash
+    - npm install -g @tencent-ai/codebuddy-code
+    # Verify CODEBUDDY_API_KEY is set
+    - |
+      if [ -z "$CODEBUDDY_API_KEY" ]; then
+        echo "Error: CODEBUDDY_API_KEY is not set. Please configure it in GitLab CI/CD variables"
+        exit 1
+      fi
+  script:
+    # Optional: Start GitLab MCP server (if provided by your environment)
+    - /bin/gitlab-mcp-server || true
+    # Pass context through web/API trigger when using AI_FLOW_* variables
+    - echo "$AI_FLOW_INPUT for $AI_FLOW_CONTEXT on $AI_FLOW_EVENT"
+    - >
+      codebuddy
+      -p "${AI_FLOW_INPUT:-'Review this MR and implement requested changes'}"
+      --permission-mode acceptEdits
+      --allowedTools "Bash(*) Read(*) Edit(*) Write(*) mcp__gitlab"
+      --debug
+```
+
+After adding the job and API key variable, test by manually running the job through CI/CD → Pipelines, or trigger it from an MR to have CodeBuddy propose updates in the branch and create an MR when needed.
+
+### Manual Configuration (Recommended for Production)
+
+If you need finer control:
+
+1. **Add Project Credentials for GitLab API Operations**:
+   - By default, uses CI_JOB_TOKEN, or create a project access token with api scope
+   - If using PAT, store it as GITLAB_ACCESS_TOKEN (masked)
+
+2. **Add CodeBuddy Job to .gitlab-ci.yml** (see example above)
+
+3. **(Optional) Enable Mention-Driven Triggers**:
+   - Add a project Webhook for "notes" to your event listener (if using)
+   - Have the listener call the pipeline trigger API when comments contain @codebuddy, passing variables like AI_FLOW_INPUT and AI_FLOW_CONTEXT
+
+---
+
+## Usage Examples
+
+### Transform Issue into MR
+
+In an Issue comment:
+```
+@codebuddy Implement this feature based on the Issue description
+```
+
+CodeBuddy analyzes the Issue and codebase, writes changes in a branch, and creates an MR for review.
+
+### Get Implementation Help
+
+In an MR discussion:
+```
+@codebuddy Suggest a specific approach to cache the results of this API call
+```
+
+CodeBuddy proposes changes, adds appropriate caching code, and updates the MR.
+
+### Quick Bug Fix
+
+In an Issue or MR comment:
+```
+@codebuddy Fix the TypeError in the user dashboard component
+```
+
+CodeBuddy locates the bug, implements a fix, and updates the branch or creates a new MR.
+
+---
+
+## Best Practices
+
+### CODEBUDDY.md Configuration
+
+Create a CODEBUDDY.md file in your repository root to define coding standards, review criteria, and project-specific rules. CodeBuddy reads this file during execution and follows your conventions when proposing changes.
+
+Example CODEBUDDY.md:
+```markdown
+# Project Coding Standards
+
+## Code Style
+- Use ESLint and Prettier for code formatting
+- Follow Airbnb JavaScript Style Guide
+- Use TypeScript strict mode
+
+## Commit Conventions
+- Follow Conventional Commits specification
+- Use Chinese for commit messages
+- Each commit should contain only one logical change
+
+## Testing Requirements
+- All new features must include unit tests
+- Test coverage must be at least 80%
+- Use Jest as the testing framework
+
+## MR Review Checklist
+- Code passes all CI checks
+- At least one team member has approved
+- Update relevant documentation
+```
+
+### Security Considerations
+
+**Never commit sensitive information to the repository!** Always use GitLab CI/CD variables:
+
+- Add sensitive configuration as masked variables (mark as protected if needed)
+- Limit job permissions and network egress
+- Review CodeBuddy's MRs as you would any other contributor's
+
+### Performance Optimization
+
+- Keep CODEBUDDY.md concise and clear
+- Provide clear Issue/MR descriptions to reduce iterations
+- Configure reasonable job timeouts to avoid runaway executions
+- Cache npm and package installations in Runners (if possible)
+
+### CI Cost Control
+
+When using CodeBuddy Code with GitLab CI/CD, be aware of associated costs:
+
+**GitLab Runner Time:**
+- CodeBuddy runs on your GitLab Runner and consumes compute minutes
+- Check your GitLab plan's Runner billing details
+
+**Cost Optimization Recommendations:**
+- Use specific @codebuddy commands to reduce unnecessary rounds
+- Set appropriate --max-turns and job timeout values
+- Limit concurrency to control parallel runs
+
+### Security and Governance
+
+- Each job runs in an isolated container with restricted network access
+- CodeBuddy's changes flow through MRs, reviewers can see every diff
+- Branch protection and approval rules apply to AI-generated code
+- CodeBuddy Code uses workspace-scoped permissions to constrain writes
+
+---
+
+## Troubleshooting
+
+### CodeBuddy Doesn't Respond to @codebuddy Commands
+
+- Verify your pipeline is being triggered (manually, MR events, or via note event listener/Webhook)
+- Ensure CI/CD variables exist and are configured correctly
+- Check that comments contain @codebuddy (not /codebuddy) and your mention trigger is configured
+
+### Job Cannot Write Comments or Create MRs
+
+- Ensure CI_JOB_TOKEN has sufficient permissions for the project, or use a project access token with api scope
+- Check that the mcp__gitlab tool is enabled in --allowedTools
+- Confirm the job is running in an MR context or has sufficient context via AI_FLOW_* variables
+
+### Authentication Errors
+
+**Authentication Variables Not Set:**
+- Confirm `CODEBUDDY_API_KEY` is added in your GitLab project's **Settings → CI/CD → Variables**
+- Check the variable name spelling is correct (case-sensitive)
+- If "Protect variable" is set, ensure the job runs on a protected branch
+
+**API Authentication Failed (401 Unauthorized):**
+- Verify the API key is valid and not expired
+- Confirm no extra spaces or newlines were included when copying the API key
+- Check the API key has sufficient permission scopes
+- See [Settings Configuration Documentation](settings.md#认证配置) for detailed configuration methods
+
+**API Connection Failed:**
+- Check `CODEBUDDY_BASE_URL` is configured correctly (if using a custom endpoint)
+- Verify the GitLab Runner can access the CodeBuddy API server
+- Confirm the URL format is correct, including protocol (e.g., `https://api.example.com`)
+
+**Key Visible in Logs:**
+- Ensure ✅ Mask variable is checked when configuring CI/CD variables
+- Avoid directly echoing or printing the API key in scripts
+
+**GitLab Access Token Related Issues:**
+
+- Check that the configured CI/CD variables are set correctly
+- Verify the related access permission configuration
+- Ensure CI_JOB_TOKEN or GITLAB_ACCESS_TOKEN has sufficient permissions (api scope)
+
+### Job Timeout
+
+- Increase the job's timeout configuration
+- Simplify prompts to reduce processing time
+- Consider breaking large tasks into multiple smaller tasks
+
+---
+
+## Advanced Configuration
+
+### Common Parameters and Variables
+
+**Environment Variables:**
+
+CodeBuddy Code uses the following environment variables in CI/CD environments:
+
+**Authentication Configuration:**
+- `CODEBUDDY_API_KEY`: Used for model interface calls, suitable for CI/CD non-interactive environments
+
+**Optional Configuration:**
+- `CODEBUDDY_BASE_URL`: Custom base URL for model service
+- `GITLAB_ACCESS_TOKEN`: GitLab API access token (for MR operations)
+- `CI_JOB_TOKEN`: Job token automatically provided by GitLab CI
+
+**Flow Control Variables:**
+- `AI_FLOW_INPUT`: User input passed through Web/API triggers
+- `AI_FLOW_CONTEXT`: Context information (e.g., Issue ID, MR ID, etc.)
+- `AI_FLOW_EVENT`: Trigger event type (e.g., note, issue, merge_request)
+
+> 📖 For detailed descriptions and configuration examples of each environment variable, please refer to [Settings Configuration Documentation](settings.md#环境变量)
+
+**Command Line Parameters:**
+
+CodeBuddy Code supports these common inputs:
+
+- **prompt** (-p): Provide instructions inline
+- **max-turns**: Limit the number of back-and-forth iterations
+- **permission-mode**: Permission mode (e.g., acceptEdits)
+- **allowedTools**: List of allowed tools
+- **debug**: Enable debug output
+
+**Note:** Exact flags and parameters may vary depending on @tencent-ai/codebuddy-code version. Run `codebuddy --help` in the job to see supported options.
+
+### Customizing CodeBuddy Behavior
+
+You can guide CodeBuddy through two main approaches:
+
+1. **CODEBUDDY.md**: Define coding standards, security requirements, and project conventions. CodeBuddy reads this file during execution and follows your rules.
+
+2. **Custom Prompts**: Pass task-specific instructions via prompt/prompt_file in the job. Use different prompts for different jobs (e.g., review, implementation, refactoring).
+
+### Multi-Environment Configuration
+
+You can configure different CodeBuddy jobs for different environments (development, testing, production):
+
+```yaml
+# Development environment - Auto-trigger
+codebuddy-dev:
+  stage: ai
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "develop"'
+  script:
+    - codebuddy -p "Quick review and auto-merge"
+
+# Production environment - Manual trigger
+codebuddy-prod:
+  stage: ai
+  rules:
+    - if: '$CI_COMMIT_BRANCH == "main"'
+      when: manual
+  script:
+    - codebuddy -p "Detailed review, generate complete change report"
+```
+
+---
+
+## Reference Resources
+
+- [CodeBuddy Code Official Documentation](../README.md)
+- [CLI Reference](cli-reference.md)
+- [Settings Configuration](settings.md)
+- [Common Workflows](common-workflows.md)
+- [Troubleshooting](troubleshooting.md)
+
+---
+
+**Empower your CI/CD pipeline with AI and boost development efficiency!**