Console 管理路径：在浏览器里管理运行中的 Bot
Console 是 Zhin 的网页管理后台。不用登录服务器，你就能看 Bot 是否在线、收发消息、查看 AI 每一步做了什么、排查报错。
做完后你会：
- 知道每类任务该去哪个页面；
- 能从一条消息追到 AI 的执行步骤和日志；
- 分清只读的 Demo token 和可管理的 Full token。
Console 和 Bot 是分开的
Console 是独立的网页应用（console.zhin.dev），你的 Bot 进程（Host）只提供受 token 保护的接口。所以同一个 Console 可以连接不同机器上的 Bot。
1. 连接 Host
- 启动 Bot，并复制终端打印的 API Base。
- 打开 console.zhin.dev。
- Token 使用项目
.env中的HTTP_TOKEN。
用脚手架新建的项目默认端口是 8068，但请以终端输出或配置里的 http.port 为准。连不上时先运行 npx zhin doctor。
2. 按任务选择页面
| 任务 | 页面 | 看到的事实 |
|---|---|---|
| 判断系统是否健康 | 工作台 | Endpoint、日志、Agent 与待处理事项摘要 |
| 收发消息或处理请求 | 渠道与会话 | Endpoint、会话、消息、通知与请求 |
| 查看 AI 处理一条消息的过程 | Agent 概览 | 每次执行的步骤、工具结果、取消与重试入口 |
| 管理多 Agent 协作项目 | Workroom | 项目内的任务、分派、审核与放行关卡 |
| 确认某个命令或工具真的加载了 | 运行时能力 | 命令、中间件、组件、Tool、Prompt Section 与 MCP |
| 排查失败 | 日志 | 级别、来源、时间线和详情 |
| 修改系统 | 配置、环境变量、文件、数据库 | 仅 full scope 开放的管理面 |
配置里写了不等于已经生效。 判断某个能力是否可用，以“运行时能力”页面显示的当前加载结果为准。
3. 收发消息
在“渠道与会话”中选择一个 Endpoint（Bot 在某个平台上登录的账号）和会话，就能查看和发送消息。新消息实时推送；刷新页面后，已保存的历史消息仍在。
为什么有些平台看不到更早的历史？
页面通过 SSE 接收实时事件，通过 HTTP 拉取历史；断线重连后如果中间有缺口，会重新拉取当前会话。如果某个平台的适配器不提供历史消息接口，Console 只能显示 Bot 运行期间自己保存下来的那部分。
4. 查看 AI 的执行过程
“Agent 概览”列出每一次 AI 执行（Run），点开能看到模型的每一步、调用了哪些工具、结果是什么，以及是否被取消。也可以在这里取消正在执行的任务，或导出一份执行报告。
工作台里还可以开实验会话：启动时指定工作目录和安全策略，会话由 Host 保存，刷新后仍在。
怎么确定一次执行对应哪条消息？
每次执行以 runtimeId + turnId 唯一标识，不要靠时间或消息文本去猜。执行开始时用到的工具、Prompt Section 和 MCP 会被固定下来，中途保存代码不会影响这一次执行。
5. 管理 Workroom
Workroom 是多个 Agent 协作完成任务的空间，绑定一个群、频道或 GitHub 仓库；同一个 Bot 账号可以服务多个 Workroom。概念介绍见 Agent 深入。
- “Workroom 配置”：新建或修改 Workroom，保存后立即生效，不用重启。成员里的 Agent 必须是
ai.agents中已经配置的。 - 看板：查看任务、分派、审核人和放行关卡的当前状态。
配置存在哪？看板上能直接改任务状态吗？
Console 里的 Workroom 配置保存在持久化的 Runtime Catalog 中，不会写回 zhin.config.yml 的 ai.workrooms。看板内容是 Workroom Journal（事件日志）的只读视图；Console 不能直接改写任务状态，所有修改都要通过经过认证的控制接口提交。
6. Full token 与 Demo token
| Full token | Demo token | |
|---|---|---|
| 查看状态、能力列表、执行过程 | ✅ | ✅ |
| 发送消息、修改配置/环境变量/文件/数据库 | ✅（按 Host 策略） | ❌ |
| 读取原始 YAML 配置 | ✅ | ❌ |
Token 就是密码：不要放进 URL、截图或公开的前端配置里。
远程部署时连不上？
在配置中设置 http.corsOrigins 允许 Console 的域名；如果前面有反向代理，要同时转发 API、SSE、WebSocket 和页面资源，只转发普通 HTTP 请求会导致实时消息或页面加载失败。详见 生产部署与运维。
用表单编辑配置
配置页默认按 Host 提供的 Schema 显示全部字段；尚未写入文件的 HTTP、数据库、语音等区块也能直接配置。对象、数组、字典和联合类型按结构编辑，已有值及环境变量引用原样回显。日历、提醒、复读和短链接的静态 Schema 随包发布，插件停用时也能编辑配置，无需先启用。
每项配置的“此项源码”是当前草稿的 JSON 视图，与表单共用内容，切换无需保存。格式错误会保留文本并阻止保存；修正后可切回表单。跨配置项切换也会保留未保存草稿。完整 YAML/JSON 文件可通过“完整源码”打开，支持高亮；它基于已保存文件，各项未保存草稿不会自动混入。
任意 JSON 或无法展开的递归、外部引用仅在对应字段使用 JSON 编辑器，其余字段继续使用表单。第三方插件确实没有声明 Schema 时会明确提示；Console 不根据当前值猜字段类型。plugins、disable_plugins 等实例声明在插件管理中调整。
核对配置是否已应用
插件配置表单会显示已读取的文件版本；编辑中的内容是草稿，不代表文件或 Runtime 已变化。保存成功后，按真实回执区分“系统配置需要重启”和“插件配置待核对”，不会直接宣布业务可用。整页源码编辑同样显示实际文件版本，不将所有变更一律说成需要重启。
在已声明插件的表单内点击“读取应用证据”，可对照同一文件版本、插件包版本与当前运行代。只有证据与已读取文件匹配、没有未保存草稿且 Host 允许应用时，才能申请应用已保存配置。确认申请后，页面通过只读查询核对结果；回执丢失或查询失败显示未知，不能据此重复申请。先读取证据，仍无法确认时查看运行日志。
“当前代配置语义一致”只表示该插件的已保存配置与运行代一致，包括声明的默认值；格式变化可以使文件版本不同而语义相同。它不表示整个文件已应用、平台在线或业务验收通过。查询期间文件或运行代变化时，Host 要求重新读取，不把旧结果标成新版本的证据。
此处不展示未经可靠脱敏的最终配置值，也不从当前文件猜测旧运行代的默认值来源。环境校验与业务验证各有自己的时点和边界；缺少 Schema 时仍使用源码编辑回退。
查看字段来源与当前代是否一致
在插件配置页点击“读取已保存版本解释”。它读取页面已载入的文件版本，不解释未保存草稿；需要 full scope，并分别升级提供此接口的 Host 与独立 Console。
file 表示该静态字段写在文件中，schema-default 表示本次已保存候选由声明的默认值补齐，unset 表示仍未设置。equal 只证明读取时该字段与当前实例运行代一致，不证明旧运行代也来自同一文件或默认值；运行代历史来源始终为未知。敏感字段及环境引用隐藏且不比较，不展示最终值、默认值或环境变量名。
首版支持静态对象/标量 Schema，例如当前 Reminder、Repeater 的声明。Schema 含数组、字典、组合分支或引用时整份解释不支持；当前 Calendar 的 union 属于此类，GroupSuite、RSS 尚未声明 Schema。继续使用“查看完整源码”，原有源码回退不会丢字段。解释读取不改变保存或生效状态，也不会自动申请应用；文件或运行代在读取中变化时须重新读取。协议边界见 Console 协议说明。
7. 出问题时按这个顺序查
如果能在会话中找到那条入站消息，先打开消息的“诊断”。它按完整会话与平台消息 ID 查询，显示实际观测到的来源分类、前缀检查、中间件、指令状态及回复投递；不会重新执行消息。
completed只表示本次入站处理已结束；交给 Agent 不等于 Agent 已完成。- 投递
sent表示 Endpoint 返回了消息 ID，不保证远端客户端已经展示；deliveryUnknown表示结果不确定，应先核实原会话，不自动重发。 - 每个 IM Runtime 仅在内存保留最近 15 分钟、最多 500 条记录；重启、过期或容量淘汰后查不到，不代表处理成功或从未收到。
- 诊断须显式配置并验证 full scope Token，未配置 Token 的 Host 也不能匿名读取；不另存正文、发送者资料或原始异常。单条记录最多保留 32 个步骤与 32 次投递；超出时
truncated: true表示记录不完整，不替代完整审计日志。单个身份字段最多 2048 字符，完整会话 JSON 最多 8192 字符；超限不截断身份，不收录该诊断。
Host 查询入口为 GET /api/messages/diagnostics：id 查询一条记录，或用 conversation（完整 ConversationRef JSON）、messageId 精确筛选，limit 为 1–100。按实际结果继续阅读消息处理排查；新版 Console 也会在诊断内提供对应问题的链接。找不到记录时，再按下面的路径排查。旧版 Host 不提供此接口，需分别更新 Host 与独立 Console。
- 工作台：Bot 连上了吗？各 Endpoint 在线吗？
- 渠道与会话：用户的消息到达 Bot 了吗？
- 运行时能力：相关的命令、工具或 Prompt Section 加载了吗？
- Agent 概览：AI 执行到哪一步、以什么状态结束？
- 日志：按同一时间段和来源筛选，找具体报错。
管理员任务中心
「任务中心」（/tasks）先按“我想做什么”展示用途，再读取当前运行实例实际提供的任务服务。没有安装或加载提醒插件时，页面提供安装入口；同一个包有多个实例时须选择具体实例。旧版 Host 不支持任务接口，需要单独升级 Host 和 Console。
首版支持持久提醒插件的管理员任务。配置 Database Host 后，在页面选择已加载的提醒实例、投递账号、会话种类及 ID；有父容器或话题时也要完整填写。账号来自实际 Endpoint 列表；平台不提供会话目录时手动填写精确目标，不能用显示名替代身份。确认目标、含时区的绝对时间、内容及未来发送效果后再创建；创建成功表示任务已保存，不表示平台在线或消息已经发送。
管理员任务与聊天个人任务分开存储和限额。聊天创建的提醒继续归真实发送者，任务中心不会冒充平台用户，也不展示或取消其个人提醒。管理任务必须使用显式配置且验证通过的 full scope Bearer Token，未配置 Token 和 demo Token 均不能使用。
任务可用操作由插件返回：待执行任务可暂停，暂停后才可编辑或恢复；取消不能撤回已经开始的发送。投递结果为 unknown 时只允许核实后取消，不提供重试或恢复。固定周期表示间隔秒数，不等于按本地日历“每天同一时间”。管理员时间字段仍要求带 offset 的 ISO 时间；聊天个人提醒的有限自然时间和补问见提醒指南。RSS 实例满足持久状态、精确出站和调度条件时，也会提供独立管理员订阅；首次与恢复只建立基线，详见订阅更新指南。其他任务来源需逐项接入。
页面保留提交时的运行代与任务版本，冲突时保留草稿，不静默覆盖。请求超时或响应丢失时保留操作 ID 并冻结写入，只读取插件持久回执核对；没有找到回执不能推断操作未执行。换登录后需明确确认原操作身份才能核对，不会自动重发。页面临时保存的核对信息不包含任务正文、参数或凭据。
Host 接口为 GET /api/tasks/use-cases、GET /api/tasks/providers、POST /api/tasks/create 和 POST /api/tasks/change。任务事实、并发版本及操作回执由插件持久化，Host 不另建调度器。参见持久提醒插件与 CLI 用途指南。
按用途配置群欢迎
在「任务中心 → 按用途开始」选择“配置新成员欢迎”，进入 /use-cases/group-welcome。页面读取 Host 指定的包和可管理实例；同包多实例必须明确选择，不按包名猜实例。尚未安装时进入市场查看具体版本和原安装计划，已有实例继续使用原配置表单、精确会话范围编辑器和插件详情应用流程。用途页只衔接导航与只读事实，不自动保存、应用或发送。
返回流程后，分别核对当前代配置语义、非空欢迎文案及范围，再选择完整测试群。真实成员加入后可明确记录一次人工观察；记录不是平台自动验收，系统也不自动归因到某个实例。它仅在本页内存有效，连接、实例、配置、运行代或目标变化及重读失败后失效。空文案、空列表和未应用配置不能视为欢迎已可用；原始环境引用也不能证明展开后的文案或实际范围。详见群欢迎配置与人工核验。
命令权限说明
从运行时能力的命令目录进入“查看权限说明”，或打开 /permissions。使用当前 Host 有效的 full scope Token 读取命令目录，按命令名、说明或插件实例搜索；列表分页，不需要一次展开全部指令。
选择命令后，页面逐项解释真实声明的 permit 和单独的 adapter 约束。规则数组为 AND，单项括号内的逗号为 OR。可以选填假设会话、发送者与角色，检查内置条件；账号从当前 Host 的完整 Endpoint 列表选择，不会通过平台查询角色。
“条件符合”不表示已授权或可执行。缺少角色时显示“缺少依据”，平台与自定义 checker 显示“未评估”，不会执行命令、动态参数默认值或 checker。内置 group(id)、private(id)、channel(id) 只检查类型与 ID，不能限制具体 Bot、父容器或话题；完整身份回显也不等于这些维度受规则约束。
修改假设会清除旧结果，运行代变化后须刷新目录重新检查。换 Host、凭据或退出后不沿用之前的命令和结果。没有接口的旧 Host 会明确提示升级，不伪造权限结论。
需要限制实际群欢迎的范围时，使用精确欢迎白名单。它通过现有配置校验、保存和应用流程生效，不由权限说明页面写入。
下一步
- Console 概览：Console 与 Host 如何分工、页面扩展
- Agent 深入 · Workroom Kernel：Workroom 的规则与配置
- 多平台社区 Bot：一个多平台生产案例