docs: Updated documentation and optimized installation and configuration guide

(cherry picked from commit 2bd56580d8ef7f4823dd931ac5a85352d96d3ddf)

Author: innsd

docs/content/1.introduction/1.overview.md

@@ -6,11 +6,13 @@ AgentKit 是火山引擎推出的企业级 AI Agent 开发平台，为开发者
 
 ## 核心优势
 
-- **声明式应用定义**：通过简洁的 YAML 文件定义智能体应用的核心组件和配置，实现“一次定义，处处运行”。
+- **声明式应用定义**：通过简洁的 YAML 文件定义智能体应用的核心组件和配置，实现"一次定义，处处运行"。
 - **模块化与可扩展**：内置丰富的 **Tool**（工具）、**Memory**（记忆）、**Knowledge**（知识库）等模块，并提供标准化的接口，方便开发者自定义和扩展。
 - **云原生部署**：与 **AgentKit Platform** 无缝集成，支持一键将应用部署到云端，并提供弹性伸缩、持续集成和高可用保障。
-- **多智能体协作（MCP）**：支持构建多个 **Agent** 协同工作的复杂系统，实现任务的分解、协作和汇总。
+- **多智能体协作**：支持构建多个 **Agent** 协同工作的复杂系统，实现任务的分解、协作和汇总，支持 A2A 协议 Agent。
 - **全面的生命周期管理**：提供从项目初始化、本地调试、云端部署到线上运维的全套 `agentkit` CLI 工具链。
+- **多语言支持**：支持 Python 和 Golang 开发，满足不同技术栈需求。
+- **丰富的项目模板**：提供多种预置模板，包括基础应用、流式输出、A2A 协议等，快速启动开发。
 
 ## 架构理念
 
@@ -26,7 +28,7 @@ AgentKit 的核心设计理念是将 **Agent App** 的**定义**与**执行**分
 - **智能问答机器人**：快速构建集成知识库的智能问答服务。
 - **自动化工作流**：创建能够自动执行一系列任务（如发送邮件、生成报告、调用 API）的自动化流程。
 - **复杂数据分析**：构建能够理解用户意图、查询数据库、分析数据并生成可视化报告的数据分析 **Agent**。
-- **多智能体系统**：设计和部署多个 **Agent** 协同完成复杂任务的系统，例如“研究员-分析师-报告员”模式。
+- **多智能体系统**：设计和部署多个 **Agent** 协同完成复杂任务的系统，例如"研究员-分析师-报告员"模式。
 
 ## 开始使用
 

docs/content/1.introduction/2.installation.md

@@ -110,14 +110,34 @@ agentkit --version
 
 在使用 `agentkit` CLI 与 AgentKit Platform 交互之前，您需要配置访问凭证（AK/SK）。
 
-将您的凭证设置为环境变量：
+### 推荐方式：使用全局配置
+
+使用 AgentKit 的全局配置功能来安全地存储您的凭证：
+
+```bash
+# 初始化全局配置
+agentkit config --global --init
+
+# 设置您的访问凭证
+agentkit config --global --set volcengine.access_key="YOUR_ACCESS_KEY"
+agentkit config --global --set volcengine.secret_key="YOUR_SECRET_KEY"
+
+# 验证配置
+agentkit config --global --show
+```
+
+这种方式将凭证安全地存储在 `~/.agentkit/config.yaml` 文件中，避免在 shell 历史记录中暴露敏感信息。
+
+### 环境变量方式（开发调试）
+
+对于临时开发调试，您可以设置环境变量：
 
 ```bash
 export VOLCENGINE_ACCESS_KEY="YOUR_ACCESS_KEY"
 export VOLCENGINE_SECRET_KEY="YOUR_SECRET_KEY"
 ```
 
-为方便起见，您可以将以上命令添加到 Shell 的配置文件中（如 `~/.bashrc` 或 `~/.zshrc`）。
+⚠️ **注意**：出于安全考虑，不建议将包含敏感信息的 `export` 命令添加到 shell 配置文件（如 `~/.bashrc` 或 `~/.zshrc`）中，因为这可能导致凭证泄露。
 
 ## 下一步
 

docs/content/1.introduction/3.quickstart.md

@@ -1,6 +1,6 @@
 # 快速入门
 
-本指南将引导您使用 “Basic Agent App” 模板开发一个简单的 **Agent**，快速体验 **AgentKit** 从开发、部署到测试的全流程。
+本指南将引导您使用 “Basic Agent App” 模板开发一个简单的 **Agent**，快速体验 **AgentKit** 从开发、部署到测试的全流程。AgentKit 提供多种模板，包括基础应用、流式输出、A2A 协议等，支持 Python 和 Golang 开发。
 
 ## 准备工作
 
@@ -30,7 +30,35 @@ export VOLCENGINE_SECRET_KEY=<your_secret_key>
   ![API Key管理](../../public/images/model_apikey.jpg)
 
 请记录下您的 **Endpoint ID** 如`ep-20250520174054-xxxxx`（也可以是模型ID如 `deepseek-v3-1-terminus`）和 **API Key**，后续将通过环境变量`MODEL_AGENT_NAME`和`MODEL_AGENT_API_KEY`配置给 **Agent**
-> 如果您不提供这些信息，**AgentKit Platform** 将在云端部署时自动为您注入一个内置的 `doubao-seed-1-6` 模型，本地调试也默认使用该内置模型。
+> 如果您不提供这些信息，**AgentKit Platform** 将在云端部署时自动为您注入一个内置的 `doubao-seed-1-6` 模型。
+
+### 3. 本地调试凭证配置 (Local 模式必读)
+
+如果您计划在本地 (Local 模式) 运行和调试 Agent，由于本地环境无法自动注入云端凭证，您**必须**手动配置访问凭证，否则 Agent 将无法调用大模型。
+
+您可以通过以下两种方式之一配置凭证：
+
+**方式一：配置方舟模型凭证**
+
+直接指定要使用的模型接入点和 API Key：
+
+```bash
+# 在 config 时通过 --runtime_envs (-e) 设置
+agentkit config -e MODEL_AGENT_NAME=<your_endpoint_id> -e MODEL_AGENT_API_KEY=<your_api_key>
+```
+
+**方式二：配置火山引擎访问密钥**
+
+如果配置了火山引擎的 AK/SK，veADK 会尝试自动获取您的模型访问权限：
+
+```bash
+# 在 config 时通过 --runtime_envs (-e) 设置
+agentkit config -e VOLCENGINE_ACCESS_KEY=<your_access_key> -e VOLCENGINE_SECRET_KEY=<your_secret_key>
+```
+
+> **注意**：
+> 1. 在 Local 模式下，直接在宿主机 shell 中 `export` 环境变量对容器内无效，必须使用 `agentkit config -e` 将其写入 `agentkit.yaml` 的 `runtime_envs` 中。
+> 2. 在 Cloud 模式下，Runtime 会自动注入相关凭证，通常无需手动配置上述环境变量。
 
 ## 开始使用
 
@@ -47,7 +75,18 @@ mkdir simple-agent && cd simple-agent
 agentkit init
 ```
 
-执行后会显示可用模板列表，选择模板 `1` (Basic Agent App)：
+执行后会显示可用模板列表，选择模板 `1` (Basic Agent App)。您也可以使用 `--template` 参数直接指定模板：
+
+```bash
+# 使用基础模板
+agentkit init --template basic
+
+# 使用流式输出模板
+agentkit init --template basic_stream
+
+# 查看所有可用模板
+agentkit init --list-templates
+```
 
 命令执行后，将在当前目录生成模板代码和配置文件：
 ```txt
@@ -70,19 +109,19 @@ agentkit config
 配置向导会引导您完成以下设置：
 
 **通用配置**（按 回车 使用默认值）：
-- **1.应用名称**：Agent 应用名称（模板1，默认值为 `simple_agent`，如接纳直接回车即可（下同））
-- **2.入口文件**：应用入口文件（模板1，默认值为 `simple_agent.py`）
+- **1.应用名称**：Agent 应用名称（默认值为 `simple_agent`，可直接按回车使用默认值）
+- **2.入口文件**：应用入口文件（默认值为 `simple_agent.py`）
 - **3.应用描述**：应用描述信息（可选）
-- **4.Python 版本**：默认 3.12
-- **5.依赖文件**：默认 `requirements.txt`
+- **4.编程语言**：Python 或 Golang（默认 Python）
+- **5.依赖文件**：默认 `requirements.txt` 或 `go.mod`
 - **6.Agent应用内部Runtime常用环境变量**：
   - `MODEL_AGENT_NAME`：方舟模型接入点 ID（可选）
   - `MODEL_AGENT_API_KEY`：方舟模型 API Key（可选）
 - **7.部署模式**：选择 `cloud`（云端构建和部署）
 
 **云端部署配置**：
 - **1.服务区域**：默认 `cn-beijing`
-- **2.镜像标签**：默认 `latest`
+- **2.镜像标签**：默认 `{{timestamp}}`, 会自动渲染为时间戳，格式如20251218154940
 - **3.CR 镜像仓库**：CLI 会自动生成CR实例名称、CR命名空间和CR仓库名，用户也可手动指定（建议自动即可）
 
 完成配置后，执行 `launch` 命令即可一键部署：
@@ -142,4 +181,5 @@ Using default headers: {'user_id': 'agentkit_user', 'session_id': 'agentkit_samp
 
 接下来您可以：
 - 探索其他应用模板（MCP、A2A 等）
-- 集成 Memory、Knowledge 等 Platform 服务，开发更强大的 **Agent**
+- 集成 Memory、Knowledge、Tools 等 Platform 服务，开发更强大的 **Agent**
+- 使用 `agentkit memory`、`agentkit knowledge`、`agentkit tools` 等命令管理平台服务

docs/content/1.introduction/4.troubleshooting.md

@@ -28,9 +28,10 @@
         source .venv/bin/activate
         uv pip install agentkit-sdk-python
         ```
-    - 强制重新安装: 如果不想使用虚拟环境，可以尝试强制重新安装 AgentKit 及其依赖。
+    - 清理环境重新安装: 如果必须使用现有环境，建议先卸载再重新安装：
         ```bash
-        pip install --force-reinstall agentkit-sdk-python
+        pip uninstall agentkit-sdk-python
+        pip install agentkit-sdk-python
         ```
 ## 配置问题
 
@@ -39,7 +40,7 @@
 - **现象**：提示无法连接到 AgentKit Platform 或认证失败。
 - **原因**：可能未传入环境变量或传入了错误的环境变量名称
 - **解决方案**：
-    -  确认已设置必需的环境变
+    -  确认已设置必需的环境变量
     ```bash
     echo $VOLCENGINE_ACCESS_KEY
     echo $VOLCENGINE_SECRET_KEY

docs/content/2.agentkit-cli/1.overview.md

@@ -14,6 +14,7 @@
 
 `agentkit` CLI 提供了一系列直观的命令来管理您的 **Agent** 应用：
 
+### 核心命令
 | 命令 | 功能描述 |
 | :--- | :--- |
 | `agentkit init` | 初始化一个新的 **Agent** 项目，可选择不同的模板。 |
@@ -25,6 +26,14 @@
 | `agentkit status` | 查看 **Agent** 的运行状态和 Endpoint。 |
 | `agentkit destroy` | 停止并销毁 **Agent** 实例，释放相关资源。 |
 
+### 平台服务命令
+| 命令 | 功能描述 |
+| :--- | :--- |
+| `agentkit memory` | 管理 AgentKit Memory 记忆集合。 |
+| `agentkit knowledge` | 管理 AgentKit Knowledge 知识库。 |
+| `agentkit tools` | 管理 AgentKit Tools 工具和 Sessions 会话。 |
+| `agentkit runtime` | 管理 AgentKit Runtime 运行时实例。 |
+
 > 想要了解每个命令的详细用法？请查阅 [命令详解](./2.commands.md)。
 
 ## 三种部署模式
@@ -84,6 +93,10 @@ launch_types:
 mkdir my-first-agent && cd my-first-agent
 agentkit init my-first-agent
 
+# 或者指定特定模板
+agentkit init my-first-agent --template basic_stream  # 流式输出模板
+agentkit init my-first-agent --template a2a           # A2A 协议模板
+
 # 2. 配置应用 (通过交互式向导)
 agentkit config
 
@@ -100,23 +113,49 @@ agentkit status
 agentkit destroy
 ```
 
+### 探索更多功能
+
+```bash
+# 查看可用模板
+agentkit init --list-templates
+
+# 管理平台服务
+agentkit memory list      # 查看记忆集合
+agentkit knowledge list   # 查看知识库
+agentkit tools list       # 查看工具列表
+agentkit runtime list     # 查看运行时实例
+```
+
 ## 环境要求
 
 ### ✅ 基础环境（所有模式）
-- Python 3.12 或更高版本
+- Python 3.10 或更高版本
 - pip 包管理器
 - 已安装 AgentKit SDK
 
+### 🐍 Python 开发环境
+- Python 3.10, 3.11, 3.12, 3.13 版本支持
+- 推荐使用 `requirements.txt` 管理依赖
+
+### 🐹 Golang 开发环境
+- Golang 1.24 版本支持
+- 使用 `go.mod` 管理依赖
+- 适用于高性能场景
+
 ### 🐳 本地开发（Local/Hybrid 模式）
 - Docker Desktop 或 Docker Engine 20.10+
 - 确保 Docker 服务已启动
 
 ### ☁️ 云端部署（Cloud/Hybrid 模式）
 - 火山引擎账号
-- 配置好 AK/SK 环境变量：
+- 配置访问凭证（AK/SK），推荐使用安全的全局配置方式：
   ```bash
-  export VOLC_ACCESSKEY="your_access_key"
-  export VOLC_SECRETKEY="your_secret_key"
+  # 初始化全局配置
+  agentkit config --global --init
+  
+  # 设置访问凭证
+  agentkit config --global --set volcengine.access_key="your_access_key"
+  agentkit config --global --set volcengine.secret_key="your_secret_key"
   ```
 
 ## 下一步