# 测试通道配置

通过 `list_channel_instances` 与 `test_channel_configuration`（Go 为 `ListChannelInstances` 与 `TestChannelConfiguration`）查看工作区已有的通道实例并预检尚未保存的通道配置，预检不会创建通道实例。下文以企业微信邮箱（`wecom_mail`）为例演示完整步骤。

(sdk-ai-studio-channels-flow)=
## 任务流程

```text
查询提供方下已有的通道实例列表
              │
              ▼
构造未保存的通道配置与凭据请求
              │
              ▼
执行连通性预检并核对测试结果与诊断信息
```

(sdk-ai-studio-channels-prepare)=
## 准备

1. 已完成 [使用 SDK](../../../quickstart/ai-studio/sdk.md) 中的服务地址、个人访问令牌与工作区配置。
2. 登录待接入的企业微信邮箱，开启 **IMAP/SMTP** 服务并生成邮箱客户端专用密码（授权码，独立于邮箱网页登录密码与个人访问令牌）；控制台完整准备说明可参考 [企业微信邮箱配置](../../../../guides/ai-studio/agents/tools/configuration/wecom/mail.md)。
3. 在终端导出邮箱完整地址与客户端专用密码：

```bash
export WECOM_MAIL_EMAIL='<wecom-mail-address>'
export WECOM_MAIL_PASSWORD='<client-specific-password>'
```

(sdk-ai-studio-channels-s1)=
## 列出实例并测试配置

示例先按提供方 `"wecom"` 列出当前工作区已保存的通道实例（结果可能包含企业微信下的其他通道类型，无需预先存在邮箱实例），随后提交 `wecom_mail` 邮箱地址与客户端专用密码执行实时连通性测试。

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
import os

import moi_product_sdk as sdk


def main():
    client = sdk.new_with_personal_access_token(
        os.environ["PRODUCT_API_BASE_URL"],
        os.environ["PRODUCT_API_KEY"],
    )
    service = client.workspace(os.environ["WORKSPACE_ID"]).agents()

    instances = service.list_channel_instances("wecom")
    print("Total instances:", instances.total)
    for instance in instances.items:
        print(instance.id, instance.name, instance.channel_type, instance.last_test_status)

    request = sdk.ChannelInstanceCreateRequest(
        channel_type="wecom_mail",
        config={
            "email": os.environ["WECOM_MAIL_EMAIL"],
            "timeout_seconds": "30",
        },
        secrets={
            "password": os.environ["WECOM_MAIL_PASSWORD"],
        },
    )
    result = service.test_channel_configuration("wecom", request)
    print("OK:", result.ok, "Status:", result.status)
    print("Last test status:", result.last_test_status, "Tested at:", result.last_tested_at)
    if not result.ok or result.last_test_status != "succeeded":
        print("Failure reason:", result.last_test_error)
        print("Error code:", result.error_code, "Suggestion:", result.suggestion)
        raise SystemExit(1)
    print("Mail connection test passed; configuration is not saved.")


if __name__ == "__main__":
    main()
```

::::

::::{tab-item} Go
:sync: go

```go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func requiredEnv(name string) string {
	value := os.Getenv(name)
	if value == "" {
		log.Fatalf("missing environment variable: %s", name)
	}
	return value
}

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		requiredEnv("PRODUCT_API_BASE_URL"),
		requiredEnv("PRODUCT_API_KEY"),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	workspace, err := client.Workspace(requiredEnv("WORKSPACE_ID"))
	if err != nil {
		log.Fatal(err)
	}
	service := workspace.Agents()

	instances, err := service.ListChannelInstances(ctx, "wecom")
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("Total instances:", instances.Total)
	for _, instance := range instances.Items {
		fmt.Println(instance.ID, instance.Name, instance.ChannelType, instance.LastTestStatus)
	}

	request := sdk.ChannelInstanceCreateRequest{
		ChannelType: "wecom_mail",
		Config: map[string]string{
			"email":           requiredEnv("WECOM_MAIL_EMAIL"),
			"timeout_seconds": "30",
		},
		Secrets: map[string]string{
			"password": requiredEnv("WECOM_MAIL_PASSWORD"),
		},
	}
	result, err := service.TestChannelConfiguration(ctx, "wecom", request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println("OK:", result.OK, "Status:", result.Status)
	fmt.Println("Last test status:", result.LastTestStatus, "Tested at:", result.LastTestedAt)
	if !result.OK || result.LastTestStatus != "succeeded" {
		fmt.Println("Failure reason:", result.LastTestError)
		fmt.Println("Error code:", result.ErrorCode, "Suggestion:", result.Suggestion)
		os.Exit(1)
	}
	fmt.Println("Mail connection test passed; configuration is not saved.")
}
```

::::

:::::

(sdk-ai-studio-channels-action-2)=
(sdk-ai-studio-channels-test-result)=
## 查看测试结果

- 当 `ok` 为 `True`（Go 为 `true`）且 `last_test_status` 为 `succeeded` 时，表示目标外部通道凭据与网络连通性校验通过。
- 校验未通过时，返回对象中的 `last_test_error`、`error_code` 和 `suggestion` 提供具体的失败原因与修复提示。

(sdk-ai-studio-channels-limit)=
## 限制和注意事项

- `test_channel_configuration` 会向外部邮箱服务器发起实际连接验证，但不会保存配置或修改已有通道实例列表中的 `last_test_status`。测试通过后，可在控制台按 [企业微信邮箱配置](../../../../guides/ai-studio/agents/tools/configuration/wecom/mail.md) 创建并绑定实例。

(sdk-ai-studio-channels-next)=
## 下一步

- [连接消息通道](连接消息通道.md)
