DotCraft

简体中文

English

简体中文

English

外观

渠道配置参考 ​

本页记录 TypeScript 渠道在 Desktop 托管和独立部署两种模式下的注册方式，以及各适配器配置文件的字段与默认值。

注册模式 ​

Desktop 托管的内置模块 ​

当 DotCraft 负责托管内置模块进程时，使用下面的形态：

json
{
  "ExternalChannels": {
    "qq": {
      "enabled": true,
      "transport": "managedWebsocket",
      "builtinModule": "channel-qq"
    }
  }
}

Desktop 会为内置模块写入该注册信息，并在运行时把 AppServer 端点注入适配器配置。

独立适配器 ​

当你自己运行适配器进程时，使用下面的形态：

json
{
  "AppServer": {
    "Mode": "WebSocket",
    "WebSocket": {
      "Host": "127.0.0.1",
      "Port": 9100,
      "Token": ""
    }
  },
  "ExternalChannels": {
    "qq": {
      "enabled": true,
      "transport": "websocket"
    }
  }
}

独立适配器会从自身适配器配置文件读取 dotcraft.wsUrl 和 dotcraft.token。

内置模块名称 ​

渠道内置模块适配器配置
QQchannel-qq.craft/qq.json
企业微信 / WeComchannel-wecom.craft/wecom.json
飞书 / Larkchannel-feishu.craft/feishu.json
Telegramchannel-telegram.craft/telegram.json
微信 / Weixinchannel-weixin.craft/weixin.json

适配器配置文件 ​

每个 TypeScript 渠道配置都有一个 dotcraft 段和一个平台段。Desktop UI 会隐藏 dotcraft.* 字段，并在托管模块运行时自动提供这些值。

QQ ​

json
{
  "dotcraft": {
    "wsUrl": "ws://127.0.0.1:9100/ws",
    "token": ""
  },
  "qq": {
    "host": "127.0.0.1",
    "port": 6700,
    "accessToken": "",
    "adminUsers": [123456789],
    "whitelistedUsers": [],
    "whitelistedGroups": [],
    "approvalTimeoutMs": 60000,
    "requireMentionInGroups": true
  }
}
字段说明默认值
dotcraft.wsUrl独立适配器使用的 AppServer WebSocket 端点。Desktop 托管运行时会覆盖该值。ws://127.0.0.1:9100/ws
dotcraft.token独立适配器使用的 AppServer WebSocket token。Desktop 托管运行时会覆盖该值。空
qq.hostOneBot 反向 WebSocket 监听 host。127.0.0.1
qq.portOneBot 反向 WebSocket 监听端口。6700
qq.accessToken可选 OneBot access token。设置后必须与 NapCat 一致。空
qq.adminUsers拥有管理员权限的 QQ 用户 ID。[]
qq.whitelistedUsers允许与 DotCraft 对话的 QQ 用户 ID。[]
qq.whitelistedGroups允许群成员与 DotCraft 对话的 QQ 群 ID。[]
qq.approvalTimeoutMs审批超时时间，单位毫秒。60000
qq.requireMentionInGroupsQQ 群聊是否需要 @ 机器人。true

企业微信 / WeCom ​

json
{
  "dotcraft": {
    "wsUrl": "ws://127.0.0.1:9100/ws",
    "token": ""
  },
  "wecom": {
    "host": "0.0.0.0",
    "port": 9000,
    "scheme": "http",
    "robots": [
      {
        "path": "/dotcraft",
        "token": "wecom-token",
        "aesKey": "wecom-encoding-aes-key"
      }
    ],
    "adminUsers": ["zhangsan"],
    "whitelistedUsers": [],
    "whitelistedChats": [],
    "approvalTimeoutMs": 60000
  }
}
字段说明默认值
dotcraft.wsUrl独立适配器使用的 AppServer WebSocket 端点。Desktop 托管运行时会覆盖该值。ws://127.0.0.1:9100/ws
dotcraft.token独立适配器使用的 AppServer WebSocket token。Desktop 托管运行时会覆盖该值。空
wecom.host回调服务监听 host。0.0.0.0
wecom.port回调服务监听端口。9000
wecom.scheme回调服务协议。只有配置 TLS 证书和 key 路径时才直接使用 https。http
wecom.tls.certPath直接提供 HTTPS 回调服务时使用的 TLS 证书路径。空
wecom.tls.keyPath直接提供 HTTPS 回调服务时使用的 TLS 私钥路径。空
wecom.robots机器人回调凭据：path、token 和 aesKey。[]
wecom.defaultRobot某个机器人条目省略 token 或 AES key 时使用的默认值。空
wecom.adminUsers拥有管理员权限的企业微信 UserId。[]
wecom.whitelistedUsers允许与 DotCraft 对话的企业微信 UserId。[]
wecom.whitelistedChats允许与 DotCraft 对话的企业微信 ChatId。[]
wecom.approvalTimeoutMs审批超时时间，单位毫秒。60000

飞书 / Lark ​

json
{
  "dotcraft": {
    "wsUrl": "ws://127.0.0.1:9100/ws",
    "token": ""
  },
  "feishu": {
    "appId": "cli_your_app_id",
    "appSecret": "your_app_secret",
    "brand": "feishu",
    "cardTitle": "DotCraft",
    "approvalTimeoutMs": 120000,
    "groupMentionRequired": true,
    "ackReactionEmoji": "GLANCE",
    "streaming": {
      "enabled": true
    },
    "cli": {
      "enabled": false
    }
  }
}
字段说明默认值
dotcraft.wsUrl独立适配器使用的 AppServer WebSocket 端点。Desktop 托管运行时会覆盖该值。ws://127.0.0.1:9100/ws
dotcraft.token独立适配器使用的 AppServer WebSocket token。Desktop 托管运行时会覆盖该值。空
feishu.appId飞书 / Lark 应用 ID。必填
feishu.appSecret飞书 / Lark 应用 Secret。必填
feishu.verificationToken需要校验事件 payload 时使用的可选 verification token。空
feishu.encryptKey加密事件 payload 使用的可选 encrypt key。空
feishu.brand服务环境：feishu 或 lark。feishu
feishu.cardTitle回复、进度和审批卡片上显示的标题。DotCraft
feishu.approvalTimeoutMs审批超时时间，单位毫秒。120000
feishu.groupMentionRequired飞书群聊是否需要 @ 机器人。true
feishu.ackReactionEmoji标记已处理消息的 emoji 类型。GLANCE
feishu.downloadDir下载附件使用的本地目录。workspace 临时目录
feishu.cli.enabled是否向此 Channel 创建的 Thread 提供内置官方飞书 CLI。false
feishu.cli.userScopes授权账号只读访问个人资源时请求的飞书 scope。留空则所有命令都以机器人身份运行。空
feishu.debug.adapterStream是否启用 adapter stream 调试日志。false
feishu.debug.textMerge是否启用文本合并调试日志。false

启用 feishu.cli.enabled 后，飞书来源的 Thread 会获得 FeishuCli 工具，每次调用都需要审批。适配器会使用配置的应用凭据换取并缓存 tenant access token，再以机器人身份运行内置 CLI。CLI 子进程只接收 App ID 和一个 access token，不接收 App Secret。

适配器会向飞书 Thread context 注入一份调用策略。已知该用哪个 Skill 时直接读取，不确定时才先调用 skills list。Skill 链接了参考文件时，先用 skills read <skill-name> <relative-path> 加载，再执行业务命令。身份来自工具的 identity 入参而非 --as，后者会被适配器拒绝。whoami 可以查看当前生效的身份和 token 状态。

feishu.cli.userScopes 列出要请求的飞书 user scope，默认为空，需要操作者主动开启；只有应用后台已开通的 scope 才能授权成功。DotCraft 会追加 offline_access 并自行完成设备码授权，因此 CLI 自带的 auth 和 config 命令仍然不可用。一个授权账号服务于整个 Channel，所以 identity: "user" 只接受只读命令。授权信息以明文保存在 Channel 的模块状态目录，与已经存放在那里的 App Secret 同级。操作者一侧的流程见个人资源访问。

内置 CLI 只能通过 FeishuCli 调用，不能从 Shell 启动。CLI 的文件参数必须位于 workspace 内。文档、知识库、文件、媒体和分页 token 属于业务资源标识，可以正常传入。api 原始命令、CLI 的 auth/config/profile 管理、--profile、调用方传入的 --yes、运行时安装和自更新都不可用。只有 DotCraft 审批通过、且固定版本 CLI 的风险分类判定操作为 high-risk-write 时，适配器才会追加 --yes。--help 不获取 tenant token，直接返回纯文本帮助。业务命令仍返回结构化 JSON。

Telegram ​

json
{
  "dotcraft": {
    "wsUrl": "ws://127.0.0.1:9100/ws",
    "token": ""
  },
  "telegram": {
    "botToken": "123456:telegram-bot-token",
    "httpsProxy": "",
    "approvalTimeoutMs": 120000,
    "pollTimeoutMs": 30000
  }
}
字段说明默认值
dotcraft.wsUrl独立适配器使用的 AppServer WebSocket 端点。Desktop 托管运行时会覆盖该值。ws://127.0.0.1:9100/ws
dotcraft.token独立适配器使用的 AppServer WebSocket token。Desktop 托管运行时会覆盖该值。空
telegram.botTokenBotFather 签发的 bot token。必填
telegram.httpsProxyTelegram Bot API 请求使用的可选 HTTPS proxy。空
telegram.approvalTimeoutMs审批超时时间，单位毫秒。120000
telegram.pollTimeoutMsTelegram long-poll 超时时间，单位毫秒。30000

微信 / Weixin ​

json
{
  "dotcraft": {
    "wsUrl": "ws://127.0.0.1:9100/ws",
    "token": ""
  },
  "weixin": {
    "apiBaseUrl": "https://ilinkai.weixin.qq.com",
    "pollIntervalMs": 3000,
    "pollTimeoutMs": 30000,
    "approvalTimeoutMs": 120000,
    "botType": "3"
  }
}
字段说明默认值
dotcraft.wsUrl独立适配器使用的 AppServer WebSocket 端点。Desktop 托管运行时会覆盖该值。ws://127.0.0.1:9100/ws
dotcraft.token独立适配器使用的 AppServer WebSocket token。Desktop 托管运行时会覆盖该值。空
weixin.apiBaseUrl腾讯 iLink API 基础地址。https://ilinkai.weixin.qq.com
weixin.pollIntervalMs轮询周期之间的等待时间，单位毫秒。3000
weixin.pollTimeoutMslong-poll 超时时间，单位毫秒。30000
weixin.approvalTimeoutMs审批超时时间，单位毫秒。120000
weixin.botType传给二维码登录 API 的 Bot 类型值。3

相关文档 ​

Copyright © DotHarness