@tencent-ai/agent-sdk 0.3.99 → 0.3.100

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

@@ -0,0 +1,258 @@
+# 无头模式 （Headless Mode)
+
+> 以编程方式运行 CodeBuddy Code,无需交互式 UI
+
+## 概述
+
+无头模式允许您通过命令行脚本和自动化工具以编程方式运行 CodeBuddy Code,无需任何交互式 UI。
+
+无头模式也支持定时任务相关能力。在脚本、SDK 或服务端集成场景中，可以使用 `CronCreate`、`CronList`、`CronDelete` 等工具来创建、查看和取消定时任务。
+
+ > **⚠️ 重要提示：** `-y` （或 `--dangerously-skip-permissions`) 是非交互模式的必需参数。在使用 `-p/--print` 参数进行非交互式执行时，必须添加此参数才能执行需要授权的操作（文件读写、命令执行、网络请求等）,否则这些操作会被阻止。仅在受信任的环境和明确的任务场景下使用此参数。详见 [CLI 参考](cli-reference.md)。
+
+## 基本用法
+
+CodeBuddy Code 的主要命令行接口是 `codebuddy` （或 `cbc`) 命令。使用 `--print` （或 `-p`) 标志在非交互模式下运行并打印最终结果：
+
+```bash
+codebuddy -p "暂存我的更改并为它们编写一组提交" \
+  --allowedTools "Bash,Read" \
+  --permission-mode acceptEdits
+```
+
+## 配置选项
+
+无头模式利用 CodeBuddy Code 中所有可用的 CLI 选项。以下是用于自动化和脚本编写的关键选项：
+
+| 标志                       | 描述                                                                                            | 示例                                                                                                                   |
+| :------------------------- | :---------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------- |
+| `--print`, `-p`            | 在非交互模式下运行                                                                              | `codebuddy -p "查询"`                                                                                                  |
+| `--output-format`          | 指定输出格式 （`text`, `json`, `stream-json`)                                                    | `codebuddy -p --output-format json`                                                                                    |
+| `--resume`, `-r`           | 通过会话 ID 恢复对话                                                                            | `codebuddy --resume abc123`                                                                                            |
+| `--continue`, `-c`         | 继续最近的对话                                                                                  | `codebuddy --continue`                                                                                                 |
+| `--verbose`                | 启用详细日志记录                                                                                | `codebuddy --verbose`                                                                                                  |
+| `--append-system-prompt`   | 追加到系统提示词 （仅与 `--print` 配合使用）                                                      | `codebuddy --append-system-prompt "自定义指令"`                                                                        |
+| `--allowedTools`           | 允许的工具列表,空格分隔或<br /><br />逗号分隔的字符串                                           | `codebuddy --allowedTools mcp__slack mcp__filesystem`<br /><br />`codebuddy --allowedTools "Bash(npm install),mcp__filesystem"` |
+| `--disallowedTools`        | 拒绝的工具列表,空格分隔或<br /><br />逗号分隔的字符串                                           | `codebuddy --disallowedTools mcp__splunk mcp__github`<br /><br />`codebuddy --disallowedTools "Bash(git commit),mcp__github"`   |
+| `--settings`               | 从 JSON 文件或 JSON 字符串加载额外的设置配置                                                     | `codebuddy -p --settings '{"model":"gpt-5"}' "查询"`                                                                   |
+| `--setting-sources`        | 指定要加载的设置源（可选值: `user`, `project`, `local`）                                         | `codebuddy -p --setting-sources project,local "查询"`                                                                  |
+| `--mcp-config`             | 从 JSON 文件加载 MCP 服务器                                                                     | `codebuddy --mcp-config servers.json`                                                                                  |
+| `--permission-prompt-tool` | 用于处理权限提示的 MCP 工具 （仅与 `--print` 配合使用）                                           | ❌ 不支持                                                                                                              |
+
+> **说明：** `--permission-prompt-tool` 功能当前不支持。
+
+有关 CLI 选项和功能的完整列表，请参阅 [CLI 参考](cli-reference.md) 文档。
+
+## 多轮对话
+
+对于多轮对话，您可以恢复对话或从最近的会话继续：
+
+```bash
+# 继续最近的对话
+codebuddy --continue "现在重构以提高性能"
+
+# 通过会话 ID 恢复特定对话
+codebuddy --resume 550e8400-e29b-41d4-a716-446655440000 "更新测试"
+
+# 在非交互模式下恢复
+codebuddy --resume 550e8400-e29b-41d4-a716-446655440000 "修复所有 linting 问题" -p
+```
+
+## 输出格式
+
+### 文本输出 （默认）
+
+```bash
+codebuddy -p "解释文件 src/components/Header.tsx"
+# 输出： 这是一个 React 组件，显示...
+```
+
+### JSON 输出
+
+返回包含元数据的结构化数据：
+
+```bash
+codebuddy -p "数据层是如何工作的?" --output-format json
+```
+
+响应格式：
+
+```json
+{
+ ...
+}
+```
+
+### 流式 JSON 输出
+
+在收到每条消息时流式传输：
+
+```bash
+codebuddy -p "构建一个应用程序" --output-format stream-json
+```
+
+每个对话都以初始 `init` 系统消息开始,然后是用户和助手消息列表,最后是包含统计信息的最终 `result` 系统消息。每条消息都作为单独的 JSON 对象发出。
+
+### 结构化 JSON 输出
+
+要获得符合特定架构的输出，请使用 `--output-format json` 和 `--json-schema` 以及 [JSON Schema](https://json-schema.org/) 定义。响应包括关于请求的元数据（会话 ID、使用情况等），结构化输出在 `structured_output` 字段中。
+
+此示例从 auth.py 中提取函数名称并将其作为字符串数组返回：
+
+```bash
+codebuddy -p "提取 auth.py 中的主要函数名称" \
+  --output-format json \
+  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
+```
+
+> **提示**：使用 [jq](https://jqlang.github.io/jq/) 之类的工具来解析响应并提取特定字段：
+>
+> ```bash
+> # 提取文本结果
+> codebuddy -p "总结这个项目" --output-format json | jq -r '.result'
+>
+> # 提取结构化输出
+> codebuddy -p "提取 auth.py 中的函数名称" \
+>   --output-format json \
+>   --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
+>   | jq '.structured_output'
+> ```
+
+## 输入格式
+
+### 文本输入 （默认）
+
+```bash
+# 直接参数
+codebuddy -p "解释这段代码"
+
+# 从 stdin
+echo "解释这段代码" | codebuddy -p
+```
+
+### 流式 JSON 输入
+
+通过 `stdin` 提供的消息流,其中每条消息代表一个用户轮次。这允许在不重新启动 `codebuddy` 二进制文件的情况下进行多轮对话，并允许在模型处理请求时向模型提供指导。
+
+每条消息都是一个 JSON "用户消息" 对象,遵循与输出消息模式相同的格式。消息使用 [jsonl](https://jsonlines.org/) 格式进行格式化,其中每行输入都是一个完整的 JSON 对象。流式 JSON 输入需要 `-p` 和 `--output-format stream-json`。
+
+```bash
+echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"解释这段代码"}]}}' | \
+  codebuddy -p --output-format=stream-json --input-format=stream-json --verbose
+
+# 单条消息（包含图片）
+echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"文本提示词，如参考以下图片的文案"},{"type":"image","source":{"type":"base64","media_type":"image/png","data":"原始base64（不含协议前缀）"}}]}}' \
+  | codebuddy -p --input-format stream-json --output-format stream-json
+
+# 多轮对话（多行 JSON，对同一进程持续发送）
+printf '%s\n' \
+  '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"第一问"}]}}' \
+  '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"第二问"}]}}' \
+  | codebuddy -p --input-format stream-json --output-format stream-json --verbose
+```
+
+## Agent 集成示例
+
+### SRE 事件响应机器人
+
+```bash
+#!/bin/bash
+
+# 自动化事件响应 agent
+investigate_incident() {
+    local incident_description="$1"
+    local severity="${2:-medium}"
+
+    codebuddy -p "事件: $incident_description (严重性: $severity)" \
+      --append-system-prompt "你是一名 SRE 专家。诊断问题，评估影响，并提供即时行动项。" \
+      --output-format json \
+      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
+      --mcp-config monitoring-tools.json
+}
+
+# 使用方式
+investigate_incident "支付 API 返回 500 错误" "high"
+```
+
+### 自动化安全审查
+
+```bash
+# PR 的安全审计 agent
+audit_pr() {
+    local pr_number="$1"
+
+    gh pr diff "$pr_number" | codebuddy -p \
+      --append-system-prompt "你是一名安全工程师。审查此 PR 的漏洞、不安全模式和合规问题。" \
+      --output-format json \
+      --allowedTools "Read,Grep,WebSearch"
+}
+
+# 使用并保存到文件
+audit_pr 123 > security-report.json
+```
+
+### 多轮法律助手
+
+```bash
+# 具有会话持久性的法律文档审查
+session_id=$(codebuddy -p "开始法律审查会话" --output-format json | jq -r '.session_id')
+
+# 分多个步骤审查合同
+codebuddy -p --resume "$session_id" "审查 contract.pdf 的责任条款"
+codebuddy -p --resume "$session_id" "检查 GDPR 要求的合规性"
+codebuddy -p --resume "$session_id" "生成风险执行摘要"
+```
+
+## 最佳实践
+
+* **使用 JSON 输出格式** 进行程序化解析响应：
+
+  ```bash
+  # 使用 jq 解析 JSON 响应
+  result=$(codebuddy -p "生成代码" --output-format json)
+  code=$(echo "$result" | jq -r '.result')
+  cost=$(echo "$result" | jq -r '.total_cost_usd')
+  ```
+
+* **优雅地处理错误** - 检查退出代码和 stderr:
+
+  ```bash
+  if ! codebuddy -p "$prompt" 2>error.log; then
+      echo "发生错误:" >&2
+      cat error.log >&2
+      exit 1
+  fi
+  ```
+
+* **使用会话管理** 在多轮对话中维护上下文
+
+* **考虑超时** 对于长时间运行的操作：
+
+  ```bash
+  timeout 300 codebuddy -p "$complex_prompt" || echo "5 分钟后超时"
+  ```
+
+* **遵守速率限制** 在进行多个请求时，通过在调用之间添加延迟
+
+* **使用 `-y`** 在非交互模式下执行需要授权的操作：
+
+  ```bash
+  # 非交互模式下的完整示例
+  codebuddy -p "分析代码并运行测试" \
+    --output-format json \
+    -y \
+    --allowedTools "Bash,Read,Grep"
+  ```
+
+  > **⚠️ 重要提示：** `-y` （或 `--dangerously-skip-permissions`) 是非交互模式的必需参数。在使用 `-p/--print` 参数进行非交互式执行时，必须添加此参数才能执行需要授权的操作（文件读写、命令执行、网络请求等）,否则这些操作会被阻止。仅在受信任的环境和明确的任务场景下使用此参数。详见 [CLI 参考](cli-reference.md)。
+
+## 相关资源
+
+* [CLI 参考](cli-reference.md) - 完整的 CLI 文档
+* [常见工作流](common-workflows.md) - 常见用例的分步指南
+* [交互模式](interactive-mode.md) - 交互式会话功能
+* [IAM 权限](iam.md) - 工具权限和访问控制
+
+---
+
+> **提示**：无头模式非常适合 CI/CD 管道、自动化脚本和 agent 集成。将其与 MCP 服务器结合使用以扩展功能。

package/cli/dist/web-ui/docs/cn/cli/hooks-guide.md

@@ -0,0 +1,9 @@
+# Hooks 入门指南
+
+学习如何通过注册 shell 命令来自定义和扩展 CodeBuddy Code 的行为
+
+> 建议先阅读 [Hook 参考指南](./hooks.md)，了解所有事件、输入输出结构与安全要求。本指南聚焦于实际操作演练与常见示例，帮助你迅速在 CodeBuddy Code 项目中启用 Hooks 功能。
+> **注意**：Hook 功能目前处于 **Beta** 阶段，仍在持续打磨，请留意后续版本更新。
+
+
+现在你已掌握在 CodeBuddy Code 中启用 hooks 的核心流程。更多事件字段细节、决策控制和安全注意事项请查阅 [Hook 参考指南](./hooks.md)。祝你构建出既强大又安全的自动化工作流！