本手册面向威云 Forge 的日常使用者与管理员，按“登录与导航 → AI 服务使用 → 模型与网关管理 → 账户与安全 → 系统与支持”的顺序组织，并在第 7 章汇总主流 Agent 的接入流程。所有界面说明和截图均来自实际控制台；截图中的密钥、内部地址和节点标识已做脱敏处理，账号为演示账号。
适用版本：0.12 系列。不同版本的入口位置可能略有调整，以控制台实际显示为准。
权限说明：普通成员只看到自己有权使用的应用、令牌和调用记录；管理员可以管理模型、渠道、用户和全量调用记录。页面不显示或按钮不可用，通常表示当前角色没有该权限，而不是服务故障。
¶ 文档分块类别
| 序号 | 类别 | 文件 | 主要内容 | 主要读者 |
|---|---|---|---|---|
| 1 | 快速开始 | 01-quick-start.md | 产品定位、登录、桌面导航、角色边界、首次配置全流程（网关 → 模型广场 → 令牌 → 聊天 → Agent） | 所有用户 |
| 2 | AI 服务使用 | 02-ai-services.md | AI 服务面板、聊天、模型广场、API 令牌、接口调用、调用日志、积分 | 所有用户 |
| 3 | 模型与网关管理 | 03-models-and-gateway.md | 模型市场/下载/上传/更新/预热、AI模式控制（运行模式）、渠道配置、连通性测试、模型映射 | 管理员 |
| 4 | 账户、安全与权限 | 04-account-and-security.md | 个人资料、修改密码、用户管理、分组、登录设置、令牌安全 | 所有用户、管理员 |
| 5 | 系统运行与支持 | 05-system-and-support.md | 活动日志、系统设置、备份入口、支持信息准备、故障判断 | 管理员、支持人员 |
| 6 | 常见问题与附录 | 06-faq-and-appendix.md | 常见故障、HTTP 状态码、接口清单、术语表 | 所有用户 |
| 7 | 主流 Agent 接入 | 07-agent-integration.md | WorkBuddy、Marvis、Cherry Studio 的接入准备、配置流程和排查 | 所有用户 |
¶ AI 服务功能使用（重点章节）
第 2 章是手册的重点，按实际使用路径拆分：
| 小节 | 内容 | 关键截图 |
|---|---|---|
| 2.1 AI服务面板 | 网关、模型、令牌、调用四步状态；调用示例与趋势指标 | 四步状态、cURL 示例、趋势图表 |
| 2.2 聊天 | 选择模型、发起对话、停止/重新生成/编辑、参数设置、会话保存 | 模型菜单、生成中停止、参数设置、清空确认 |
| 2.3 模型广场 | 按分组/供应商/渠道筛选，查看模型详情与 API 能力 | 卡片/列表视图、性能/API/积分页签 |
| 2.4 API 令牌与接口调用 | 创建令牌、鉴权方式、cURL/Python 示例、状态码 | 令牌列表、高级设置、行尾操作 |
| 2.5 调用日志与用量 | 时间范围、筛选、业务/HTTP 视图、字段解释、导出 | 调用日志、HTTP 明细、展开详情 |
| 2.6 积分服务 | 余额、兑换码、积分流水与负余额说明 | 积分钱包 |
| 2.7 应用入口 | 聊天与织影入口 | - |
¶ 主流 Agent 支持
以下客户端都通过 OpenAI 兼容接口接入威云 Forge，可以共用同一枚 API 令牌，也可以按 Agent 分别创建。完整的配置截图和排查步骤见第 7 章。
 WorkBuddy 设置 → 模型 → 添加模型 查看配置流程 |
 Marvis 设置 → 模型管理 → + 配置模型 查看配置流程 |
 Cherry Studio 设置 → 模型服务 → 添加服务商 查看配置流程 |
¶ 推荐阅读路径
- 第一次使用：按 1.5 节走完“配置本地网关 → 模型广场确认 → 创建 API 令牌 → 聊天验证 → Agent 接入”，再读第 2 章补充细节。
- 要把模型接入桌面 Agent：读第 7 章，按客户端选择 WorkBuddy、Marvis 或 Cherry Studio。
- 要把模型接入自己的应用：读 2.3（选择模型）和 2.4（令牌与 API 调用）。
- 要排查调用失败或消耗异常：读 2.5（调用日志）和第 6 章（常见问题与状态码）。
- 管理员首次配置：读第 3 章，再回到 2.1 核对四步状态。
- 账号、密码、权限问题：读第 4 章；需要提交问题时读 5.2。
¶ 文档约定
- “控制台地址”指浏览器访问威云 Forge 时使用的地址，例如
https://forge.example.com或http://<设备IP>。 - “网关地址”与“控制台地址”默认相同；若部署时单独暴露了网关端口，以管理员提供的地址为准。
- 文中
sk-ans-...、<API_KEY>、forge.example.com均为占位符，请替换为实际值。 - 截图仅用于说明界面结构，不代表截图中的模型、渠道或账号一定在当前设备上存在。
- 维护级界面由厂商在设备本地完成确认后临时展开，不属于日常用户操作范围；需要现场维护时请联系厂商支持。