@tencent-ai/agent-sdk 0.3.99 → 0.3.101

package/cli/dist/web-ui/docs/cn/cli/models.md

@@ -0,0 +1,356 @@
+# models.json 配置指南
+
+## 概述
+
+`models.json` 是一个配置文件，用于自定义模型列表和控制模型下拉列表的显示。该配置支持两个级别：
+
+- **用户级**: `~/.codebuddy/models.json` - 全局配置，适用于所有项目
+- **项目级**: `<workspace>/.codebuddy/models.json` - 项目特定配置，优先级高于用户级
+
+## 配置文件位置
+
+### 用户级配置
+```
+~/.codebuddy/models.json
+```
+
+### 项目级配置
+```
+<project-root>/.codebuddy/models.json
+```
+
+## 配置优先级
+
+配置合并优先级从高到低：
+1. 项目级 models.json
+2. 用户级 models.json
+3. 内置默认配置
+
+项目级配置会覆盖用户级配置中的相同模型定义（基于 `id` 字段匹配）。`availableModels` 字段：项目级完全覆盖用户级，不进行合并。
+
+## 配置结构
+
+```json
+{
+  "models": [
+    {
+      "id": "model-id",
+      "name": "Model Display Name",
+      "vendor": "vendor-name",
+      "apiKey": "sk-actual-api-key-value",
+      "maxInputTokens": 200000,
+      "maxOutputTokens": 8192,
+      "url": "https://api.example.com/v1/chat/completions",
+      "temperature": 0.7,
+      "supportsToolCall": true,
+      "supportsImages": true
+    }
+  ],
+  "availableModels": ["model-id-1", "model-id-2"]
+}
+```
+
+## 配置字段说明
+
+### models
+类型： `Array<LanguageModel>`
+
+定义自定义模型列表。可以添加新模型或覆盖内置模型配置。
+
+#### LanguageModel 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `id` | string | ✓ | 模型唯一标识符 |
+| `name` | string | - | 模型显示名称 |
+| `vendor` | string | - | 模型供应商 （如 OpenAI, Google) |
+| `apiKey` | string | - | API 密钥，支持环境变量引用（见下方安全配置说明） |
+| `maxInputTokens` | number | - | 最大输入 token 数 |
+| `maxOutputTokens` | number | - | 最大输出 token 数 |
+| `url` | string | - | API 端点 URL，支持环境变量引用 (必须是接口完整路径,一般以 `/chat/completions` 结尾） |
+| `temperature` | number | - | 采样温度，范围 0-2，值越高输出越随机，值越低输出越确定 |
+| `supportsToolCall` | boolean | - | 是否支持工具调用 |
+| `supportsImages` | boolean | - | 是否支持图片输入 |
+| `supportsReasoning` | boolean | - | 是否支持推理模式 |
+
+**重要说明：**
+- 目前仅支持 OpenAI 接口格式的 API
+- `url` 字段必须是接口完整路径,一般以 `/chat/completions` 结尾
+- 例如: `https://api.openai.com/v1/chat/completions` 或 `http://localhost:11434/v1/chat/completions`
+
+### 安全配置：使用环境变量引用
+
+为避免 API 密钥明文存储在配置文件中，`apiKey` 和 `url` 字段支持环境变量引用语法 `${VAR_NAME}`。
+
+**语法格式：**
+```
+${环境变量名}
+```
+
+**配置示例：**
+
+```json
+{
+  "models": [
+    {
+      "id": "gpt-4o",
+      "name": "GPT-4o",
+      "vendor": "OpenAI",
+      "apiKey": "${OPENAI_API_KEY}",
+      "url": "https://api.openai.com/v1/chat/completions"
+    }
+  ]
+}
+```
+
+**设置环境变量：**
+
+```bash
+# 在 ~/.zshrc 或 ~/.bashrc 中添加
+export OPENAI_API_KEY="sk-your-actual-api-key"
+
+# 或者在启动时临时设置
+OPENAI_API_KEY="sk-xxx" codebuddy
+```
+
+**使用系统 Keychain（macOS）：**
+
+```bash
+# 存储密钥到 Keychain
+security add-generic-password -a "$USER" -s "openai-api-key" -w "sk-xxx"
+
+# 在 ~/.zshrc 中配置自动导出
+export OPENAI_API_KEY=$(security find-generic-password -s "openai-api-key" -w 2>/dev/null)
+```
+
+**注意事项：**
+- 环境变量在 CLI 启动时解析
+- 如果环境变量不存在，将保留原始占位符（会导致 API 调用失败）
+- 建议将 `models.json` 文件权限设置为 `600`（仅所有者可读写）
+- 不要将包含实际密钥的配置文件提交到版本控制系统
+
+### availableModels
+类型： `Array<string>`
+
+控制模型下拉列表中显示哪些模型。只有在此数组中列出的模型 ID 才会在 UI 中显示。
+
+- 如果未配置或为空数组，则显示所有模型
+- 配置后，只显示列出的模型 ID
+- 可以同时包含内置模型和自定义模型的 ID
+
+## 使用场景
+
+### 1. 添加自定义模型
+
+在用户级或项目级添加新的模型配置：
+
+```json
+{
+  "models": [
+    {
+      "id": "my-custom-model",
+      "name": "My Custom Model",
+      "vendor": "OpenAI",
+      "apiKey": "sk-custom-key-here",
+      "maxInputTokens": 128000,
+      "maxOutputTokens": 4096,
+      "url": "https://api.myservice.com/v1/chat/completions",
+      "supportsToolCall": true
+    }
+  ]
+}
+```
+
+### 2. 覆盖内置模型配置
+
+修改内置模型的默认参数：
+
+```json
+{
+  "models": [
+    {
+      "id": "gpt-4-turbo",
+      "name": "GPT-4 Turbo (Custom Endpoint)",
+      "vendor": "OpenAI",
+      "url": "https://my-proxy.example.com/v1/chat/completions",
+      "apiKey": "sk-your-key-here"
+    }
+  ]
+}
+```
+
+### 3. 限制可用模型列表
+
+只在下拉列表中显示特定模型：
+
+```json
+{
+  "availableModels": [
+    "gpt-4-turbo",
+    "gpt-4o",
+    "my-custom-model"
+  ]
+}
+```
+
+### 4. 项目特定配置
+
+为特定项目使用不同的模型或 API 端点：
+
+**项目 A** (`.codebuddy/models.json`):
+```json
+{
+  "models": [
+    {
+      "id": "project-a-model",
+      "name": "Project A Model",
+      "vendor": "OpenAI",
+      "url": "https://project-a-api.example.com/v1/chat/completions",
+      "apiKey": "sk-project-a-key",
+      "maxInputTokens": 100000,
+      "maxOutputTokens": 4096
+    }
+  ],
+  "availableModels": ["project-a-model", "gpt-4-turbo"]
+}
+```
+
+## 热重载
+
+配置文件支持热重载：
+- 文件变更会被自动检测
+- 使用 1 秒防抖延迟避免频繁重载
+- 配置更新后会自动同步到应用
+
+监听的文件：
+- `~/.codebuddy/models.json` （用户级）
+- `<workspace>/.codebuddy/models.json` （项目级）
+
+## 标签系统
+
+通过 `models.json` 添加的模型会自动标记 `custom` 标签，便于在 UI 中识别和过滤。
+
+## 合并策略
+
+配置使用 `SmartMerge` 策略：
+- 相同 ID 的模型配置会被覆盖
+- 不同 ID 的模型会被追加
+- 项目级配置优先于用户级配置
+- `availableModels` 过滤在所有合并完成后执行
+
+## 示例配置
+
+### API 端点 URL 格式说明
+
+**必须使用完整路径：**
+所有自定义模型的 `url` 字段一般以 `/chat/completions` 结尾。
+
+✅ **正确示例：**
+```
+https://api.openai.com/v1/chat/completions
+https://api.myservice.com/v1/chat/completions
+http://localhost:11434/v1/chat/completions
+https://my-proxy.example.com/v1/chat/completions
+```
+
+❌ **错误示例：**
+```
+https://api.openai.com/v1
+https://api.myservice.com
+http://localhost:11434
+```
+
+### OpenRouter 平台配置示例
+
+使用 OpenRouter 访问多种模型：
+
+```json
+{
+  "models": [
+    {
+      "id": "openai/gpt-4o",
+      "name": "open-router-model",
+      "url": "https://openrouter.ai/api/v1/chat/completions",
+      "apiKey": "sk-or-v1-your-openrouter-api-key",
+      "maxInputTokens": 128000,
+      "maxOutputTokens": 4096,
+      "supportsToolCall": true,
+      "supportsImages": false
+    }
+  ]
+}
+```
+
+### DeepSeek 平台配置示例
+
+使用 DeepSeek 模型：
+
+```json
+{
+  "models": [
+    {
+      "id": "deepseek-chat",
+      "name": "DeepSeek Chat",
+      "vendor": "DeepSeek",
+      "url": "https://api.deepseek.com/v1/chat/completions",
+      "apiKey": "sk-your-deepseek-api-key",
+      "maxInputTokens": 32000,
+      "maxOutputTokens": 4096,
+      "supportsToolCall": true,
+      "supportsImages": false
+    }
+  ]
+}
+```
+
+### 完整示例
+
+```json
+{
+  "models": [
+    {
+      "id": "gpt-4o",
+      "name": "GPT-4o",
+      "vendor": "OpenAI",
+      "apiKey": "sk-your-openai-key",
+      "maxInputTokens": 128000,
+      "maxOutputTokens": 16384,
+      "supportsToolCall": true,
+      "supportsImages": true
+    },
+    {
+      "id": "my-local-llm",
+      "name": "My Local LLM",
+      "vendor": "Ollama",
+      "url": "http://localhost:11434/v1/chat/completions",
+      "apiKey": "ollama",
+      "maxInputTokens": 8192,
+      "maxOutputTokens": 2048,
+      "supportsToolCall": true
+    }
+  ],
+  "availableModels": [
+    "gpt-4o",
+    "my-local-llm"
+  ]
+}
+```
+
+## 故障排查
+
+### 配置未生效
+1. 检查 JSON 格式是否正确
+2. 确认文件路径是否正确
+3. 查看日志输出确认配置是否被加载
+4. 确认环境变量中的 API 密钥是否已设置
+
+### 模型未在列表中显示
+1. 检查模型 ID 是否在 `availableModels` 中列出
+2. 确认 `models` 配置是否正确
+3. 验证必填字段 （`id`, `name`, `provider`) 是否都已提供
+
+### 热重载未触发
+- 配置文件变更有 1 秒防抖延迟
+- 确保文件确实被保存到磁盘
+- 检查文件监听是否正常启动 （查看调试日志）
+

package/cli/dist/web-ui/docs/cn/cli/overview.md

@@ -0,0 +1,100 @@
+# 概述
+
+**腾讯云智能编程助手 - 让代码开发更智能、更高效**
+
+CodeBuddy Code 是基于腾讯云 AI 技术的智能编程工具，深度集成腾讯云生态，提供从代码编写到项目部署的全链路 AI 辅助。
+
+## 为什么选择 CodeBuddy Code？
+
+### 🚀 用自然语言驱动整个开发运维生命周期
+
+CodeBuddy Code 让您能够用自然语言描述需求，自动化完成从代码编写、测试、调试到部署的全链路开发任务，实现极致的自动化效率提升。无论是简单的代码修改还是复杂的架构重构，都能通过对话式交互轻松完成。
+
+### 🔧 终端原生，无缝集成
+
+* **熟悉的环境**：直接在您熟悉的命令行环境中获得 AI 辅助，无需切换开发工具或学习新界面
+* **原生体验**：完美融入现有的开发工作流，支持所有主流操作系统和终端
+* **零学习成本**：保持原有的开发习惯，AI 助手静默工作在后台
+
+### ⚡ 开箱即用的强大能力
+
+* **内置工具链**：集成文件编辑、命令运行、Git 操作、测试执行等核心开发工具
+* **智能提交**：自动生成规范的提交信息，支持代码审查和变更管理
+* **灵活扩展**：通过 MCP (模型上下文协议) 轻松集成第三方工具和服务
+* **自定义开发工具**：根据项目需求定制专属的开发助手
+
+### 🛠️ Unix 哲学的 AI 集成
+
+* **管道友好**：像 `grep` 和 `awk` 一样，原生支持管道输入进行智能分析
+
+* **脚本集成**：完美融入 shell 脚本和自动化工具链
+
+* **组合能力**：与现有 Unix 工具无缝组合，构建强大的 AI 驱动工作流
+
+* **标准输入输出**：遵循 Unix 标准，支持重定向和管道操作
+  
+  ```bash
+  # 管道集成示例
+  
+  git log --oneline | codebuddy "分析这些提交，找出可能的问题"
+  cat error.log | codebuddy "帮我分析这些错误日志"
+  ```
+
+## 快速体验
+
+### 环境要求
+
+* Node.js 18.0+
+
+### 一键安装
+
+```bash
+npm install -g @tencent-ai/codebuddy-code
+```
+
+### 开始使用
+
+```bash
+# 进入项目目录
+cd my-project
+
+# 启动 CodeBuddy
+codebuddy
+cbc
+
+# 或直接提问
+codebuddy "帮我优化这个函数的性能"
+cbc "帮我优化这个函数的性能"
+```
+
+## 下一步操作
+
+### 📚 深入了解
+
+* [快速入门指南](./quickstart.md) - 详细的设置和使用指南
+* [常见工作流](./common-workflows.md) - 扩展思考、图片粘贴、--resume 等功能
+* [IDE 集成](./ide-integrations.md) - 在你喜欢的编辑器中使用
+
+### 🔧 配置和扩展
+
+* [MCP 集成](./mcp.md) - 模型上下文协议集成
+* [斜杠命令](./slash-commands.md) - 内置命令参考
+* [设置配置](./settings.md) - 配置文件、环境变量、工具设置
+
+### 🚀 高级用法
+
+* **GitHub Actions** - CI/CD 集成
+* **SDK 开发** - 扩展和自定义
+* **企业部署** - 容器化部署
+
+### 🆘 获取帮助
+
+* [故障排除](./troubleshooting.md) - 常见问题解决
+* [CLI 参考](./reference.md) - 完整命令行参考
+* **交互模式** - 键盘快捷键和技巧
+
+## 反馈和支持
+
+* 📧 技术支持：codebuddy@tencent.com
+* 🌐 [国内官方网站](https://copilot.tencent.com/cli)
+* 🌐 [海外官方网站](https://www.codebuddy.ai/cli)