句达使用说明

安装与第一次使用

从官网下载页打开夸克分享，选择 macOS 或 Windows 安装包。安装后打开应用，业务数据保存在本机，不需要单独启动数据库或后台服务。

全新工作空间会进入四个全屏步骤：

1. 连接店铺：选择平台，在弹出的平台窗口登录客服账号并进入聊天页，等待显示「已连接」。
2. 问答检索：设置全店共用的 Embedding。登录云端后向量模型会自动加入可用列表；也可以填写自有向量服务。可暂时跳过。
3. 配置助手：填写对话模型并应用到本店基础助手。
4. 开始接待：用测试会话确认收发正常，再显式开启自动回复。也可以先只做人工接待。

中途离开可以稍后继续。侧栏「上手引导」可随时重开。已有工作空间升级后不会强制重走引导，已有助手和店铺绑定会保留。

日常页面

普通工作空间只需要这几处：

接待中心的店铺筛选只影响会话列表，不会改掉问答库或店铺管理正在看的店。打开某个客户也不会切换当前筛选。

接待中心

接待中心只有一个界面，不用切换「AI 模式 / 人工模式」。会话列表上方用下拉框选择全部店铺或某一家店；列表头像是平台标识。选中会话后，中间是聊天，右侧（窄窗口里通过「客户与订单」打开）是商品、订单和可执行操作。

• 全部 / 待处理 / 我接待的 / 未读：按当前店铺范围筛选。打开未读会清未读，接管后会话进入「我接待的」，当前聊天不会因为筛选结果变化而消失。
• 查看不接管：点进会话、翻历史、查商品订单，都不会暂停 AI。
• 接管与交还：点「接管」、发送人工回复，或确认业务写入（备注、发货、转接等）才会接管。处理完必须点「交还 AI」，离开页面或重启都不会自动交还。
• 发送状态：文本发送后气泡先显示发送中；平台确认后变为已发送。失败或回执未知会标明，不会自动重发。

切换下拉框里的店铺会清空当前聊天，避免上一店的客户和下一店的操作混在一起。

问答库

人工维护的问答保存后立即参与接待，不走学习审批。相似度严格高于阈值、知识有效、且没有未决的商品或业务条件时，会按问答原文或原图直答；其余情况交给当前回复 Agent。

• 所属范围：通用问答所有店可用；店铺专属问答只在该店生效。新建时会带上当前范围，保存前可以改。
• 图片问答：支持 PNG / JPEG / WebP / GIF，单张不超过 8 MB。接待话术里只出现通用和当前会话店铺可用的条目。
• 导入导出：先选「导入到」哪个范围，再选文件、预览后确认。文字可用 JSON；图片问答用带 manifest.json 的 ZIP。
• 删除：删除后不能恢复，会从列表、话术和导出中消失。历史聊天里已经发出的内容不受影响。

学习审核

自动学习是店铺级独立开关，和自动回复分开。开启后，新的买家问题如果得到可验证的 AI 临场回复或人工作答，会生成建议；按问答库原文发出的直答不会再学一遍。

所有建议都必须人工批准、编辑后批准或拒绝。高置信度或内容来自人工，也不能跳过审批。批准后只写入来源店铺，不会自动改成通用问答。关闭学习只停止继续评估，已有待审批条目仍可处理。

店铺与设置

店铺管理左侧选店，右侧分「平台账号 / 客服助手 / 自动接待」。连接成功不等于已经开启自动回复。自动学习、学习模型和直答阈值在自动接待里单独保存。

系统设置管理可复用的模型服务。保存模型不会自动改写已经发布的本店助手；需要「应用到本店」才会更新。开发者模式默认关闭，打开后才出现 Agent Studio、Skills、Toolkit、Workflow、工作绑定和 Agent 执行。关闭开发者模式只隐藏入口，不删除已有配置。

高级工作室

日常接待用默认自动回复即可。只有需要改提示词、挂技能、加工具或换流程时，才打开开发者模式。四类能力分别配置、分别挂到回复 Agent：

学习 Agent 是产品内置的，不能在工作室里新建、挂载或替换。工作绑定只选择「这家店用哪个回复 Agent」，不再另选一条回复策略入口。

编写 Skill

Skill 在应用里完成，不需要打包扩展。

1. 打开 Skills → 新建 Skill，填写小写英文名称，以及「什么情况下需要这个技能」。
2. 在 SKILL.md 写处理步骤。规则和案例放到 references/，需要计算时在 scripts/ 加脚本。
3. 选中脚本后可以试运行：填 JSON 参数数组，不调用模型，也不保存或改绑定。只运行你信任的代码。
4. 保存后，到 Agent Studio 的 Skills 区挂载，再试跑买家消息，确认助手会加载技能并调用脚本。
5. 发布 Agent。已绑定该助手的店铺会用到这次发布里冻结的技能副本。

Skill 不会自动变成问答对，也不能替代学习审批。脚本用本机权限执行，不是系统沙箱；订单查询、发消息等平台能力仍应走 Toolkit / 内置客服工具。

编写 Toolkit 与 Workflow

Toolkit 和 Workflow 不能在应用里直接改源码。应用只负责安装 ZIP、填写集合设置、按成员试跑，以及挂到 Agent。编写请到独立仓库 judesk-extensions（与桌面端并列），完整步骤见该仓库 docs/authoring.md。

先分清两者

• Toolkit：一组工具。挂载时按包名跟随本机已启用的最新版本，更新 ZIP 后不必重新发布 Agent。同一轮回复会锁定本轮用到的版本。
• Workflow：一组已提交的流程成员。挂载时选定具体版本，Agent 按当前问题决定调用哪一个成员。

两者都是「集合 + 多个成员」。每个成员有自己的名称、说明、输入 / 输出 schema，以及需要的平台能力。工作绑定仍然只选 Agent。

扩展长什么样

安装包里只接受两个文件：

extension.zip
├── manifest.json
└── index.mjs

manifest.json 声明集合身份、版本、类型、设置项和成员列表。index.mjs 必须导出与清单一致的成员：Toolkit 用 createTools，Workflow 用 createWorkflows。少导出、多导出或成员 ID 重复都会安装失败。

除宿主提供的 @mastra/core/*、zod 和 Node 内置模块外，依赖要在构建时打进 index.mjs。运行时不会下载 npm 包，也不会把源码目录直接当生产扩展执行。

推荐做法

1. 打开 judesk-extensions。Toolkit 复制 toolkits/shop-helpers，Workflow 复制 workflows/reply-polish。
2. 改 assetId（必须是 local/小写名）、名称、成员和实现。同一版本不能用另一份代码覆盖，改完后必须升高语义版本。
3. 在扩展示例仓库根目录执行 pnpm install 和 pnpm build，得到 extensions-dist/*.zip。新建目录下只要有 index.ts，构建会自动扫到。
4. 打开开发者模式，到 Toolkit 或 Workflow 页点「安装」，选择你信任的 ZIP。
5. 填写集合设置，选一个成员，用符合 schema 的 JSON 试跑。试跑使用夹具，不会向真实买家发送。
6. 到 Agent Studio 挂载这个集合，用隔离试运行看助手会不会调用它，再发布。

扩展能用什么，不能做什么

运行时由 JuDesk 注入当前店铺、账号、会话。扩展不能靠输入参数改路由到别的店或别的买家。常见能力：

• 读取本店已生效问答（调试时是夹具）
• 按当前账号实际能力做受限平台查询；缺少能力的成员不会暴露给模型
• 部分写操作（例如订单备注）必须显式声明能力，并由宿主完成发送前检查

SDK 不提供直接给买家发消息、审批知识、发布问答或替换学习 Agent 的接口。最终回复、转人工和发送仍由 Agent 与宿主处理。

扩展在业务进程里以当前用户权限运行。只安装自己写过或审阅过的代码；这不是防止恶意程序的系统沙箱。

挂载、发布与绑定

1. 在 Agent Studio 编辑草稿：提示词、模型、Skill、Toolkit、Workflow、子 Agent。
2. 用隔离试运行验证。这里不写生产发送、学习和正式问答。
3. 发布生成不可变版本。已经绑定该 Agent 的店铺会切到最新发布。
4. 第一次选用、或改绑到另一个 Agent，仍要在「工作绑定」里确认。店铺绑定优先于全局绑定。

保存草稿不影响接待。默认自动回复可以删除，删除后可在设置里一键加回；不会在重启时偷偷重建。

数据与使用边界

• 聊天、问答、配置和附件保存在本机资料库。模型请求会按需把必要文本发到你配置的模型服务。
• 关闭主窗口可以留在托盘；退出应用后停止接待。睡眠或断网期间不工作。
• 系统设置可以备份和恢复。备份不含平台 Cookie 和模型密钥明文。换机器后需要重新登录平台并填写密钥。
• 电脑需要保持唤醒、账号保持登录，对应店铺的自动回复才会继续。

看完编写说明后，从 下载页 安装客户端，或回到 产品首页。