FAQ
本页回答常见产品、设置、身份、runtime 和文档问题。
产品
AgentHub 是 CLI 替代品吗？
不是。AgentHub 可以通过 runtime adapter 使用 Claude Code、Codex、OpenCode 等 CLI，但产品目标是让 Desktop、Web、Hub、Edge、审查面、审批、集成和审计组成可见的工作流。
AgentHub 已经生产可用了吗？
公开官网和文档已上线。Desktop + Local Edge 本地预览链路和产品架构正在积极开发。飞书/Lark 生产集成、Remote/Cloud Edge、完整 Web + Hub + Edge 路由、稳定的公开 Adapter SDK 仍在开发中。
最小可用 demo 应该展示什么？
先用 Desktop 连接 Local Edge，并使用 mock runtime。它应展示任务、结构化运行事件、聊天输出、文件或 diff 状态、审批入口、主题/语言行为，以及清晰的成功或失败状态。这条链路健康后，再把一个 runtime adapter 切到真实 CLI。
为什么官网展示 Desktop mock？
mock 用来表达预期 Desktop UI 模型：聊天、文件、diff、预览、终端、runtime 选择器、主题、语言和审批。它不是假的独立产品，应持续对齐当前 AgentHub Desktop 设计。
支持哪些操作系统？
公开文档聚焦 Windows、macOS 和 Linux 上的本地开发与预览。涉及差异时会单独说明，例如 PowerShell curl.exe、端口检查、shell profile 差异和 loopback 网络。面向最终用户的一键安装包还不能算作通用可用。
设置
应该先读哪一页？
先读 安装与本地环境 设置工作站，再读 快速上手 跑通最小 Desktop -> Local Edge -> Runtime Adapter 链路。
一开始应该用 Claude Code 还是 Codex？
先用 mock runtime。Desktop、Edge、事件和 diff 面板健康后，再切换一个已经在本地 shell 安装并鉴权的真实 runtime。
Desktop 为什么连不上？
检查 Local Edge URL、端口、健康端点、工作区白名单和 runtime profile。Desktop 和 Edge 使用不同端口，不要把 UI dev-server 端口当成 Edge API 端口。
端口被占用怎么办？
先确认占用端口的进程，再停止冲突进程，或把 AgentHub 组件换到另一个端口并同步修改依赖 URL。不要把首页 dev-server 端口当成 Local Edge API 端口。Windows 先用 netstat -ano | findstr :3210；macOS/Linux 用 lsof -i :3210 或 ss -ltnp。
本地预览到底要开几个进程？
最小链路通常是两个进程：Local Edge 和 Desktop dev server。真实 runtime CLI 由 Edge adapter 拉起或调用。需要 Hub/Web 协作时才额外启动 Hub Server 和 Web；一开始就打开所有服务，定位失败会更困难。
为什么要先用 mock runtime？
mock runtime 可以排除 provider 凭据、CLI 登录、quota、网络和 runtime 输出格式问题。只有 mock 链路能稳定展示事件、diff、产物和审批后，真实 runtime 的失败才更容易归因。
为什么 docs 本地构建正常，线上看起来还是旧的？
静态导出、CDN/浏览器缓存、语言路由规范化和旧部署目录都可能造成这个现象。先用 cache-busting URL、渲染关键词、sitemap、llms.txt 和部署 artifact 版本验证，再判断是不是源分支问题。
身份
AgentHub 自己做 GitHub、Google 或飞书登录吗？
不做。TokenDance ID 是身份权威。第三方 provider OAuth 和账号绑定属于 TokenDance ID。AgentHub 消费 TokenDance ID 身份，并执行产品本地授权。
TokenDance API key 能登录 AgentHub 吗？
不能。TokenDance API key 用于通过 TokenDance Gateway 调用模型 API。AgentHub 浏览器登录使用 TokenDance ID 和 AgentHub 产品会话。
公开官网登录是 Hub 授权边界吗？
不是。公开官网登录只是低风险的产品站个性化。Hub API 授权必须由 Hub Server 基于 TokenDance ID 会话和产品权限执行。
更多 callback、浏览器状态、返回路径、UI 和授权边界细节见 身份与登录。
Runtime
什么是 Agent Profile？
Agent Profile 是编码 Agent 的产品侧定义：标签、图标、能力、目标、审批策略和 adapter。真正执行仍由 adapter 负责。
为什么 mock 正常但真实 runtime 失败？
先按本地 CLI、鉴权、provider quota、工作区策略或 adapter profile 问题排查。不要把 provider key 放进浏览器或公开文档。
本地预览时数据会离开我的机器吗？
Desktop + Local Edge 是 local-first 链路。本地工作区读取、runtime 执行、diff 和产物默认都在本地 Edge 边界内；只有你明确接入 provider/runtime 或 Hub-backed 工作流时，数据才可能进入对应外部边界。公开文档和截图仍应使用合成路径和脱敏内容。
Web 能直接启动本地 CLI 吗？
不能。Web 是 Hub-backed。它应创建或查看 Hub 状态，并通过授权 Edge 目标路由。直接本地文件和 CLI 访问属于 Desktop + Local Edge。
Runtime adapter 现在是稳定公开 SDK 吗？
还不是。Adapter 契约、能力词汇、运行生命周期、事件信封和示例正在成型，但第三方打包和提交流程还不稳定，不能当成公开生态发布。
Agent Profile 和 runtime adapter 为什么要分开？
Profile 是产品侧选择项，描述标签、图标、能力、审批策略和默认行为；adapter 是执行侧进程边界，负责解析 Claude Code、Codex、OpenCode 等 runtime 输出。分开后，团队可以分别讨论“用哪个 Agent”和“底层怎么执行”两个问题，而不是把权限、UI 和 CLI 实现混在一起。
集成
飞书/Lark 已经是登录系统了吗？
不是。飞书/Lark 是协作入口：bot 事件、卡片、H5/工作台和任务上下文。TokenDance ID 仍是登录和账号绑定权威。
为什么卡片回调要快速响应？
飞书/Lark 卡片回调应在 3 秒内响应。耗时的 AgentHub 工作应排队并异步处理。
飞书/Lark 消息里能放完整 AgentHub 任务上下文吗？
不能。IM 负载应只携带紧凑 ID、操作名称和安全摘要。完整 prompt、provider 凭据、私有文件内容和本地路径不能进入卡片负载或公开日志。
Gateway 已经上线，为什么 AgentHub 文档还说模型 API key 不归 AgentHub？
因为这是两个凭据面。TokenDance Gateway 管理模型 API key、provider 路由、quota 和模型访问；AgentHub 管理产品会话、工作区、运行、审批和协作审计。AgentHub 可以让 runtime 使用本地或服务端安全配置的 provider 凭据，但不能把 TokenDance API key 当作 AgentHub 登录凭据。
文档与发布
为什么文档状态措辞这么谨慎？
因为公开文档不能把预览或开发中能力写成正式上线。应根据证据使用已上线、可预览、契约已定、进行中或开发中。
新增 docs 页面必须同步什么？
同步英文和中文 MDX、路由注册、导航、TOC 标题、metadata、搜索文本、sitemap、llms.txt、README 路由清单、changelog，以及必要时的测试。
文档里为什么有很多“开发中”？
这是故意的。AgentHub 仍在把 Desktop、Edge、Hub、Web、IM 和 runtime adapter 收敛到同一套产品契约里。公开文档宁可把边界写窄，也不能把还没有 E2E、截图、smoke 或失败态证据的能力说成已上线。
文档页为什么不放“在 GitHub 上编辑此页”？
AgentHub Home 的公开文档由本仓库维护，但页面不应把读者导向一个未设计好的编辑入口。贡献流程通过 贡献指南、GitHub issue/PR 和公开路由清单管理。
私有部署细节应该写在哪里？
私有部署路径、SSH alias、web root、backup 名称、rollback 命令、provider key 和 admin token 属于私有 server workspace，不属于公开文档站。
用户应该在哪里反馈问题？
不包含密钥或私有基础设施的信息，可以发到公开 GitHub 仓库。请写清路由、语言、浏览器或系统、预期行为、实际行为、脱敏错误码和复现步骤。不要在 issue 里贴 provider key、原始 prompt、私有文件内容、本机绝对路径或 callback 负载。