# TOTEM AI 企业数字化工作台全功能深度使用指南与系统配置手册

> **文档版本**: v1.0.0 Enterprise Edition  
> **适用平台**: TOTEM AI 桌面客户端 (Windows / macOS / Linux)  
> **维护团队**: TOTEM AI 数字化办公效能中枢  
> **更新时间**: 2026年10月  
> **内置直达**: 客户端左下角🧭指南针图标直接在应用内呼出高保真使用手册（零跳出浏览器）  
> **在线备用**: [TOTEM AI 飞书在线使用指南](https://xcnz1gbs567j.feishu.cn/docx/KPCZd8FWzoNZEyxjljPc8ArNnXg?from=from_copylink) (即改即生效 / 独立纯净版)  

---

## 📖 前言与阅读导引

欢迎使用 **TOTEM AI 企业数字化工作台**（Totem Agent Desktop Platform）。本手册专为企业数字化转型团队、项目负责人、工程技术人员及日常办公协同人员打造，旨在提供全景式的功能解构、场景化的高频实操、企业级后台命令体系以及深度系统配置说明。

通过本指南，您将全面掌握 TOTEM AI 从基础对话、空间隔离、自动化调度到复杂项目全自主执行的核心能力。

---

## 目录 (Table of Contents)

1. [第一章：产品定位与核心架构](#第一章产品定位与核心架构)
   - 1.1 产品愿景与角色定位
   - 1.2 对比传统 Copilot 的本质演进
   - 1.3 核心技术栈与架构分层
2. [第二章：工作台界面总览与交互规范](#第二章工作台界面总览与交互规范)
   - 2.1 全局视窗与布局体系
   - 2.2 一体化侧边栏 (Unified Sidebar) 深度解析
   - 2.3 中央工作台与全能输入框 (Omnibox)
   - 2.4 右侧多维产物面板 (Artifact Inspector)
3. [第三章：企业高频业务场景实战操作](#第三章企业高频业务场景实战操作)
   - 3.1 复杂任务拆解与全自主闭环执行
   - 3.2 项目空间 (Spaces) 与本地代码库隔离
   - 3.3 定时任务 (Cron) 与企业自动化调度
   - 3.4 资料库 (Artifacts) 与数字化资产交付
   - 3.5 技能中心 (Capabilities) 与扩展生态
4. [第四章：企业级后台命令体系 (Command System)](#第四章企业级后台命令体系-command-system)
   - 4.1 交互式斜杠指令 (Slash Commands)
   - 4.2 会话长程记忆与上下文压缩机制
   - 4.3 自动化与深度研究指令
   - 4.4 TOTEM AI 后台系统指令
5. [第五章：系统配置与企业级环境部署](#第五章系统配置与企业级环境部署)
   - 5.1 多模型接入体系 (LLM Providers)
   - 5.2 API 密钥与安全认证管理
   - 5.3 企业内网代理与网关路由 (Proxy & Gateway)
   - 5.4 桌面客户端更新与热补丁运维
6. [第六章：企业安全合规与数据保护准则](#第六章企业安全合规与数据保护准则)
   - 6.1 本地优先安全原则 (Local-First)
   - 6.2 敏感信息防泄露与权限隔离
   - 6.3 零风险原子化修改与安全回滚机制
7. [第七章：常见问题排查与运维指南 (FAQ)](#第七章常见问题排查与运维指南-faq)

---

## 第一章：产品定位与核心架构

### 1.1 产品愿景与角色定位

**TOTEM AI** 是面向下一代企业数字化协同演进的**本地全自主智能体工作台**。它不仅是问答助手，更是具备深度任务拆解、本地工具调度、环境自省、文件读写与持续演化的数字化生产力专家。

* **对外统称**: `TOTEM AI` 或 `Totem Agent`
* **产品身份**: 企业数字化工作 AI（专为跨工程协同、知识生产与自主自动化打造）
* **核心基调**: 严肃高效、结果导向、原子化交付、高安全性

### 1.2 对比传统 Copilot 的本质演进

| 维度 | 传统侧边栏 Copilot | TOTEM AI 企业数字化工作台 |
| :--- | :--- | :--- |
| **交互形态** | 附着于单一编辑器的对话小窗口 | 独立全功能桌面工作台，多项目/多空间并发 |
| **执行能力** | 仅生成文本/代码片段，需人工复制粘贴 | **全自主执行循环**：自主读写文件、运行命令、排错自愈 |
| **任务跨度** | 单轮/多轮短会话 | **长程目标 (Goal-Driven)**：支持数小时至跨天级复合任务 |
| **环境感知** | 仅感知当前激活的单文件 | 全局上下文、Git 状态、终端环境、系统网络与多仓联动 |
| **资产交付** | Markdown 纯文本输出 | 交互式 Web 小部件、多媒体素材、结构化报告、编译制品 |

### 1.3 核心技术栈与架构分层

```mermaid
flowchart TB
    subgraph UI_Layer["💻 TOTEM AI 客户端展示层 (Electron + React + Tailwind)"]
        Sidebar["一体化左侧导航栏 (WorkBuddy Unified Rail)"]
        CentralDesk["中央会话工作台 (Omnibox + Stream Canvas)"]
        RightInspector["多维资产交付面板 (Artifacts / Diff Viewer)"]
    end

    subgraph Agent_Core["🧠 核心智能体调度引擎 (Totem Agent Core)"]
        StateEngine["任务状态机与长程记忆 (State Management)"]
        ToolRegistry["企业工具与技能库 (Skill / Tool Registry)"]
        ExecLoop["感知-决策-执行循环 (Perception-Action Loop)"]
    end

    subgraph System_Boundary["🛡️ 企业安全沙箱与本地系统层 (Local Sandboxed OS)"]
        FS_Guard["原子化文件保护与 Git 快照 (Rollback Safe)"]
        ModelProxy["企业加密模型网关 (Multi-LLM Proxy)"]
        CronManager["定时作业后台调度器 (Background Cron Engine)"]
    end

    UI_Layer <--> Agent_Core
    Agent_Core <--> System_Boundary
```

---

## 第二章：工作台界面总览与交互规范

### 2.1 全局视窗与布局体系

TOTEM AI 采用沉浸式三栏现代化布局，兼具美学质感与极致效能：
* **窗口基准**: 推荐分辨率 `1440 × 900` 及以上（最小适配 `1024 × 640`）。
* **左侧一体化导航 (Unified Sidebar)**: 宽度固定 `260px`，集成品牌状态、全局操作、业务菜单、任务树与项目空间。
* **中央主工作台 (Central Workspace)**: 动态弹性延伸，支持空态欢迎看板与高保真流式对话视窗平滑切换。
* **右侧产物侧栏 (Right Inspector)**: 可按需展开/折叠，用于实时审查代码 Diff、运行 WebGL 交互预览或查看渲染报告。

### 2.2 一体化侧边栏 (Unified Sidebar) 深度解析

侧边栏自上而下包含以下 5 大核心功能区块：

```text
┌──────────────────────────────────────┐
│  TOTEM AI  v1.0.0                    │  <- 顶部品牌与版本
├──────────────────────────────────────┤
│  [  (+) 新建任务  ]                  │  <- 全宽主行动按钮
├──────────────────────────────────────┤
│  🤖 助理                             │  <- / (核心多模态对话)
│  🧩 发现应用                         │  <- /capabilities (技能扩展)
│  ⏰ 定时任务                         │  <- /cron (自动化调度)
│  📚 资料库                           │  <- /artifacts (资产归档)
│  🗂️ 更多                             │  <- /command-center (命令中心)
├──────────────────────────────────────┤
│  任务 (Tasks)                     🔍 │  <- 历史会话分组 (刚刚/今天/更早)
│  ├─ 优化企业财务报表自动化导出        │
│  └─ 重构前端组件样式层                │
├──────────────────────────────────────┤
│  空间 (Spaces)                    ➕ │  <- 项目与工作区隔离绑定
│  ├─ Hermes                           │
│  └─ Marketing-Portal                 │
├──────────────────────────────────────┤
│  🟢 TOTEM AI    🔔   🧭   🔄   ⚙️     │  <- 底部系统操作栏
└──────────────────────────────────────┘
```

1. **顶部品牌区**:
   - 展示企业专属品牌标 `TOTEM AI` 及版本号 `1.0.0`。
2. **「(+) 新建任务」专属操作块**:
   - 醒目高亮设计，一键开启干净、无污染的独立任务沙箱。
3. **核心功能菜单导航**:
   - **🤖 助理 (`/`)**: 日常多模态智能对话与工作流执行主阵地。
   - **🧩 发现应用 (`/capabilities`)**: 浏览、配置与激活可用工具、内置 Skill、浏览器自动化插件等。
   - **⏰ 定时任务 (`/cron`)**: 创建与编排无需人工值守的后台周期性运行任务。
   - **📚 资料库 (`/artifacts`)**: 统一检索由智能体沉淀的代码文件、分析图表、SVG 图标与调研报告。
   - **🗂️ 更多 (`/command-center`)**: 进阶开发者命令中心与高级过滤视图。
4. **任务 (Tasks) 树形列表**:
   - 智能时间分群：会话根据活跃度自动归入「刚刚」、「今天」、「昨天」、「更早」。
   - 支持快捷搜索关键词实时过滤历史任务。
   - 右键/悬浮操作：支持会话重命名、置顶关注与安全归档。
5. **空间 (Spaces) 项目隔离区**:
   - 支持添加多个本地工程目录，在空间之间切换即可实现上下文环境、Git 关联仓库的完全隔离。
6. **底部系统工具栏**:
   - **状态指示点**: 实时反馈 Agent 后台执行与心跳状态（绿色表示在线健康）。
   - **🔔 消息中心**: 聚合后台任务完成提醒与异常告警。
   - **🧭 帮助与使用指南 (Compass)**: **点击直接拉起系统默认浏览器，跳转飞书在线最新使用文档**。
   - **🔄 经典极客模式切换**: 快速在现代化工作台与官方极客面板之间无损切换。
   - **⚙️ 偏好设置 (`/settings`)**: 模型配置、网关鉴权、界面主题与个性化设定。

### 2.3 中央工作台与全能输入框 (Omnibox)

* **富上下文输入**: 支持键盘直接输入、多行代码粘贴、图片直接拖入、本地文件/文件夹拖拽挂载。
* **流式执行动效**: 在智能体思考与调用系统工具时，呈现高保真流式呼吸动效与实时耗时计时器（如 `执行耗时: 8.3s`）。
* **过程透明化**: 每一项系统底层调用（文件读取、脚本执行、测试验证）均以结构化折叠卡片呈现，支持点击审查原始 I/O，保障安全合规。

---

## 第三章：企业高频业务场景实战操作

### 3.1 复杂任务拆解与全自主闭环执行

当面对跨目录、多文件的复杂研发或业务编排需求时，TOTEM AI 具备标准的工程执行链路：

```mermaid
sequenceDiagram
    autonumber
    actor User as 企业用户
    participant Agent as TOTEM AI 调度中枢
    participant FS as 本地文件沙箱
    participant Test as 测试与编译系统

    User->>Agent: 提交复杂需求 (如: "重构登录鉴权模块并增加短信验证")
    Agent->>Agent: 任务理解与意图拆解 (生成分步规划 Plan)
    Agent->>FS: 检索项目结构与现有鉴权源码 (Read Context)
    Agent->>FS: 原子化新增/修改独立功能模块 (Write/Edit Files)
    Agent->>Test: 自动执行语法检查与单元测试 (Run Verification)
    alt 测试通过
        Agent-->>User: 汇总变动文件清单，展示验证结果与交付物
    else 测试报错
        Agent->>Agent: 启动自省纠错模式 (Systematic Debugging)
        Agent->>FS: 调整代码消除 Bug 并重新验证
    end
```

### 3.2 项目空间 (Spaces) 与本地代码库隔离

为保障企业内部不同项目的安全性与上下文纯净性，建议采用「空间隔离机制」：
1. 点击侧边栏「空间」右侧的 `+` 图标，选择本地目标项目根目录。
2. 切换至对应空间后，TOTEM AI 会将该目录锁定为命令与文件操作的根边界，严禁跨边界非法读写。
3. **Git Worktree 分支隔离**：对于大型工程，可在任务中开启独立分支工作树，实现并行特性开发互不干扰。

### 3.3 定时任务 (Cron) 与企业自动化调度

TOTEM AI 内置强大的后台调度引擎，支持执行周期性自动化工作：
1. 点击左侧导航栏 **「⏰ 定时任务」** 进入配置面板。
2. 点击「新建定时任务」，设定任务名称与执行周期（支持标准 5 段式 Cron 表达式，如 `0 9 * * 1-5` 代表工作日早 9 点执行）。
3. 配置任务指令（例如：*“抓取竞品官网最新发布动态，整理成 Markdown 晨报保存至资料库”*）。
4. 系统将在后台静默调度，执行完毕后在底部通知铃铛推送消息通知。

### 3.4 资料库 (Artifacts) 与数字化资产交付

当智能体生成长文档、架构图、SVG 矢量设计图或单页面应用时，系统会自动将其归集至 **「📚 资料库」**：
* **结构化归档**: 资产按会话与生成时间自动分类。
* **一键复制/导出**: 支持一键导出为本地 HTML、Markdown、PDF 或 PNG。
* **飞书文档一键同步**: 资料库中的 Markdown 文档支持一键复制到剪贴板，无缝粘贴至飞书多维表格或飞书知识库。

---

## 第四章：企业级后台命令体系 (Command System)

在 TOTEM AI 输入框中，输入 `/` 即可快速唤起交互式斜杠指令菜单：

### 4.1 核心斜杠指令清单

| 命令 | 名称 | 适用场景说明 |
| :--- | :--- | :--- |
| `/goal` | **长程目标模式** | 适用于数小时或跨夜执行的高复杂度任务，智能体将竭尽全力直至完全达成目标 |
| `/plan` | **分步规划模式** | 在正式动工修改前，强制智能体先生成详尽步骤计划，待人工审查确认后再行执行 |
| `/compact`| **上下文紧凑压缩** | 当当前任务对话极长、Token 消耗过大时，无损压缩历史上下文，释放窗口容量 |
| `/browser`| **网页与浏览器自动化**| 调度无头浏览器进行外网调研、页面截图、表单填报与多源信息检索 |
| `/schedule`| **快捷设定计划任务** | 一键将当前指令挂载为单次定时提醒或周期性后台任务 |
| `/boost` | **超强思考模式** | 针对疑难系统 Bug 或关键算法架构，启用多维度头脑风暴与严密推导 |
| `/learn` | **经验知识沉淀** | 将本轮对话中排查出的系统环境特性或修正规则沉淀至知识库，供后续复用 |

### 4.2 TOTEM AI 后台系统指令

若企业管理员需通过命令行或自动化脚本管理工作台，统称为 **TOTEM AI 后台系统指令**（切勿以底层旧名称混淆）：
* **环境健康诊断**:  
  可在工作台中直接指示智能体：*“执行系统环境自检与依赖诊断”*，智能体将自动检测 Node.js、Python、Git 及编译链路。
* **极速构建与热更新维护**:  
  位于工程根目录下的自动化脚本支持秒级维护客户端：
  - `.\scripts\quick_update_totem.ps1`：极速构建前端并热更新至客户端。
  - `.\scripts\update_totem_client.ps1`：标准解包更新与完整打包重启。

---

## 第五章：系统配置与企业级环境部署

### 5.1 多模型接入体系 (LLM Providers)

点击左下角 **⚙️ 偏好设置** -> **模型配置**，TOTEM AI 全面兼容主流大模型协议：

```text
┌────────────────────────────────────────────────────────┐
│  模型提供商 (Provider)  [ OpenAI 兼容接口 (Custom) ∨ ]   │
│  API 基础地址 (Base URL) [ https://api.your-company.com/v1 ]│
│  访问密钥 (API Key)    [ sk-•••••••••••••••••••••••• ] │
│  主推模型名称 (Model)   [ qwen-2.5-72b / claude-3-5   ] │
└────────────────────────────────────────────────────────┘
```

1. **企业私有化/内网模型 (vLLM / Ollama / LocalAI)**:
   - 基础地址配置为内网代理或本地服务（如 `http://127.0.0.1:11434/v1`）。
   - 彻底实现数据不出企业内网。
2. **主流公有云商用 API**:
   - 原生支持 OpenAI、Anthropic Claude、Google Gemini 等 API 接口协议。

### 5.2 API 密钥与安全认证管理

* **端侧加密存储**: 所有配置的 API Key 均使用当前操作系统安全凭据管理器（Windows DPAPI / macOS Keychain）在本地加密存储，绝不回传任何第三方服务器。
* **按空间覆盖**: 支持为特定项目空间配置独立的 API Key，实现项目间的账单与权限隔离。

### 5.3 桌面客户端更新与热补丁运维

当团队有定制化 UI 变动或品牌资产更新时，无需全员重新安装几百兆的安装包，使用内置的热更新脚本即可在 5 秒内完成部署：

```powershell
# 在 Windows PowerShell (管理员模式) 中执行
cd d:\Hermes
.\scripts\quick_update_totem.ps1
```

> **该脚本执行逻辑**：
> 1. 优雅停止运行中的 TOTEM AI 进程；
> 2. Vite 增量编译前端资源；
> 3. 同步最新 dist 文件至 `app.asar` 镜像目录；
> 4. 秒级重构 `app.asar` 并自动拉起 TOTEM AI 客户端。

---

## 第六章：企业安全合规与数据保护准则

为保障企业级应用的高可用性与代码安全性，TOTEM AI 严格恪守以下三大铁律：

### 6.1 绝对禁止修改框架核心源码 (Never Modify Framework Core)
* 所有定制化开发、UI 套壳重构、品牌视觉叠加均采用**非侵入式叠加层 (Branding Overlay)** 与独立挂载扩展实现。
* 保证系统底层与上游官方源码保持 100% 干净合并与 Git Rebase 能力，杜绝上游升级冲突。

### 6.2 零风险与秒级安全回滚机制 (Zero-Risk & Instant Rollback)
* 所有代码修改均具备原子化特征。在进行任何关键调整前，系统必须确认工作区处于已保存或已快照状态。
* 一旦运行出现任何逻辑偏离或编译异常，保证可在 1 秒内无损回滚至上一稳定基线版本。

### 6.3 严格中文注释与文档完整性 (Mandatory Chinese Documentation)
* 所有内部扩展代码均包含详尽的结构化中文注释与 JSDoc 说明，确保团队内部任何成员均可无障碍接管与二次维护。

---

## 第七章：常见问题排查与运维指南 (FAQ)

### Q1：点击左下角🧭指南针图标，会发生什么？
> **解答**：现在左下角指南针已全面升级为**客户端内置原生帮助中心**！点击将直接在 TOTEM AI 内部弹出全功能沉浸式使用手册模态弹窗（包含快速上手、任务闭环、斜杠指令一键复制、空间隔离、Cron 定时任务编排与配置指引等），无需打断当前任务或跳出外部浏览器，支持全局搜索与键盘 `Esc` 秒级关闭。若需要访问飞书云端协作版，也可在弹窗右上角一键直达。

### Q2：使用过程中出现“网络连接异常 / API 超时”怎么办？
> **解答**：
> 1. 检查左下角设置中的 API Key 与 Base URL 是否正确，末尾是否多出了 `/` 或协议头错误；
> 2. 检查当前网络环境是否开启了代理。若使用了企业代理，可在设置中配置 HTTP/HTTPS 代理端口；
> 3. 检查模型服务商或企业内网网关的 QPS 限制是否触发限流。

### Q3：如何将本手册完整导入到飞书文档？
> **解答**：
> 1. 打开飞书，进入您所在的知识库或个人空间；
> 2. 点击 **「新建」->「导入」->「Markdown」**，选中本文件（`TOTEM_AI_USER_MANUAL.md`）；
> 3. 或者直接在本地编辑器中 `Ctrl+A` 全选本文件内容并复制，在飞书空白文档中 `Ctrl+V` 粘贴；
> 4. 飞书将 100% 完美解析文中的所有标题层级、表格、Mermaid 流程图、代码块与强调引用卡片；
> 5. 点击右上角 **「分享」**，将阅读权限设为“互联网上获得链接的人可阅读”或“组织内全员可阅读”，复制该分享链接即可。

---

> 💡 **小贴士**：本说明文档由 TOTEM AI 数字化办公中枢持续维护。若在日常使用中有任何新功能建议或优化反馈，欢迎通过飞书文档评论区即时协同！