系统设置与初始配置

完成首次启动配置，了解主界面结构，并为使用私有知识库和共享空间做好准备。

1.1 首次启动

启动流程

首次启动 MeshWork 时，应用会引导你完成以下步骤：

1. 选择或创建私有知识库：选择现有目录作为私有知识库，或创建一个新的私有知识库目录。私有知识库建议存放你自己的长期笔记、草稿、资料和未公开想法。
2. 进入主工作台：默认会先打开私有知识库，因为它是最稳定的个人入口。你可以在侧边栏上半部分看到私有知识库的文档树。
3. 后续添加共享空间：需要团队协作时，再通过侧边栏下方的 + 按钮创建或导入共享空间。共享空间可以稍后再配置 Git。

主界面结构

进入主工作台后，你会看到以下界面结构：

• 侧边栏：左侧分为上下两部分。上半部分是私有知识库，下半部分是共享空间列表。共享空间区域下方有 + 按钮，用于添加新的共享空间。
• 主内容区：中间区域显示当前选中的文档内容或讨论区内容。
• 右侧边栏：编辑文档时，右侧边栏可以打开 AI 助手，提供智能辅助。

1.2 工作台管理

理解工作台结构

工作台主界面的左侧侧边栏会显示所有已添加的内容。侧边栏分为两个区域：

• 上半部分：固定显示私有知识库及其文档树。
• 下半部分：显示所有已添加的共享空间列表。

工作台管理页面用于添加物理目录（私有知识库或共享空间）。添加完成后，这些内容会直接在主界面的左侧侧边栏中显示，无需额外的切换操作。

添加共享空间

通过侧边栏下方的 + 按钮添加共享空间：

1. 点击侧边栏下方的 + 按钮。
2. 选择"创建共享空间"或"导入共享空间"。
3. 创建时需要指定目录位置和名称，可选择使用模板。
4. 导入时需要指定已存在的共享空间目录。
5. 添加完成后，共享空间会立即出现在侧边栏的共享空间列表中。

移除共享空间

要移除侧边栏中的共享空间：

1. 在侧边栏中右键点击要移除的共享空间。
2. 选择"从工作台移除"选项。
3. 确认移除后，该共享空间将不再显示在工作台侧边栏中。

移除共享空间不会删除磁盘上的数据，只是从工作台视图中隐藏。你可以随时重新添加该共享空间。

侧边栏排序与布局

工作台会保存你的侧边栏排序和展开状态：

• 私有知识库始终固定在侧边栏上半部分。
• 共享空间在侧边栏下半部分，可以通过拖拽调整顺序。
• 每个共享空间下可以展开显示公共知识库和讨论区。
• 展开和折叠状态会被记住。

1.3 应用设置

MeshWork 的应用设置可以通过菜单栏或系统设置入口打开。当前设置窗口包含外观、AI、文档、讨论、Git、网络代理、许可证和关于等页面。

1.3.1 外观设置

在"设置 → 外观"中自定义界面显示：

• 主题：选择跟随系统、浅色或深色主题。跟随系统主题会根据 macOS 的外观设置自动切换。
• 语言：选择界面语言（简体中文或英文）。AI 智能体会根据当前应用语言自动调整回复语言。
• 界面密度：调整界面的紧凑程度，影响间距、工具栏和控件尺寸。
• 界面字号：调整界面文字大小。文档编辑器字号和预览缩放也可以在编辑器视图中单独调整。

1.3.2 文档设置

在"设置 → 文档"中配置文档助手的行为。这些配置是应用全局的，会影响私有知识库和公共知识库中的所有文档编辑页面：

• 提示词自定义：可以覆盖默认的文档助手提示词，让 AI 按照你的偏好提供帮助。
• 工具调用次数：限制文档助手单次回复最多可以调用多少次工具。
• 自定义命令：添加你常用的快捷命令，如 /summarize（总结当前文档）、/action（提取待办事项）等。输入 / 时会显示可用的命令列表。

1.3.3 讨论设置

在"设置 → 讨论"中配置讨论区话题的默认行为：

• 自动会话时长：设置讨论区话题默认使用的自动会话窗口时长，默认为 2 分钟，范围为 2-10 分钟。在这段时间内，你继续发送的消息会自动发送给上次回复的智能体，无需重复 @。
• 提示词：设置新话题的默认提示词，定义智能体在讨论中的角色和行为方式。
• 分支总结提示词：自定义话题分支的自动总结提示词，用于生成分支的简要描述。
• 自定义命令：添加全局讨论命令。共享空间和单个话题还可以继续配置自己的命令；同名时优先使用话题命令，其次是共享空间命令，最后是全局命令。
• 单次工具调用次数限制：设置智能体单次回复中最多可以调用工具的次数，防止意外消耗过多资源。

1.3.4 网络代理设置

在"设置 → 网络代理"中配置代理服务。这对于需要通过代理访问 AI 服务或搜索服务的用户非常有用：

• 添加代理配置：点击"添加"按钮，输入代理名称和地址（如 127.0.0.1:7890）。
• 代理类型：支持 HTTP、HTTPS 和 SOCKS5 代理。
• 认证：如代理需要认证，可输入用户名和密码。
• 应用代理：在 AI Provider 或网络搜索服务配置中，可以选择使用哪个代理配置。

1.3.5 Git 设置

理解 MeshWork 的 Git 模型

在配置 Git 之前，需要理解 MeshWork 与 Git 的关系：

• 工作台本身不是 Git 仓库，Git 只绑定到真实的数据边界。
• 私有知识库可以选择启用或禁用 Git，即使启用也只管理私有知识库自己的内容。
• 每个共享空间可以有自己的 Git 配置，Git 只作用于当前共享空间。
• 同类资源可以共用同一个远端仓库，通过不同分支来区分不同的知识库。

添加远端仓库条目

在"设置 → Git"中维护可复用的远端仓库条目，然后在私有知识库或共享空间设置中绑定对应仓库。

1. 点击"添加"创建仓库条目。
2. 选择服务类型：GitHub、Gitee、GitLab 或自定义。
3. 填写仓库名称、远端 URL 和默认分支。
4. 选择认证方式：SSH Key、HTTPS Token 或不使用认证。
5. 如需代理访问，在仓库条目中选择已配置的网络代理。

MeshWork 当前通过内置 libgit2 后端执行 Git 操作，不依赖系统 /usr/bin/git。SSH 方式不使用 SSH Agent；请选择私钥文件，或粘贴 OpenSSH 私钥内容。私钥口令、HTTPS Token 和粘贴的私钥内容会保存到系统钥匙串。

准备 SSH 密钥

SSH 密钥用于与 GitHub、Gitee、GitLab 或自建 Git 服务进行认证。如果你计划使用 SSH 方式访问远程仓库，需要先在对应托管平台添加公钥。

检查现有 SSH 密钥

首先检查你的设备上是否已有 SSH 密钥：

1. 打开终端（Terminal）。
2. 运行命令 ls -al ~/.ssh。
3. 检查目录列表中是否包含 id_ed25519 或 id_rsa 等文件名。

如果已有密钥文件，可以跳过生成步骤，直接把公钥添加到对应 Git 托管平台。

生成新的 SSH 密钥

如果没有现有密钥，生成一个新的 SSH 密钥：

1. 打开终端。
2. 运行命令 ssh-keygen -t ed25519 -C "[email protected]"，将邮箱替换为你用于 Git 托管平台的邮箱。
3. 当提示输入文件位置时，按 Enter 使用默认位置。
4. 当提示输入密码时，可以输入密码也可以直接按 Enter 跳过（跳过密码更方便，但安全性较低）。

在 Meshwork 中配置 SSH Key

Meshwork 的 SSH 仓库认证使用 SSH Key，不使用 SSH Agent。你可以在 Git 仓库设置中选择私钥文件，或粘贴 OpenSSH 私钥内容。

1. 私钥文件通常位于 ~/.ssh/id_ed25519。
2. 如果粘贴私钥内容，Meshwork 会将内容保存到系统钥匙串。

复制 SSH 公钥并添加到托管平台

复制公钥内容，准备添加到 GitHub、Gitee、GitLab 或自建 Git 服务：

1. 运行命令 cat ~/.ssh/id_ed25519.pub。
2. 复制输出的全部内容，以 ssh-ed25519 开头，以你的邮箱结尾。

GitHub 账号与仓库配置参考

GitHub 认证方式概述

GitHub 自 2021 年 8 月起已永久移除密码认证。目前支持两种 Git 操作认证方式：

• Personal Access Tokens (PATs)：用于 HTTPS 方式克隆和推送。作为密码的替代方案，需要手动创建和管理。
• SSH Keys：用于 SSH 方式克隆和推送。需要设置 SSH 密钥，配置后无需每次输入密码。

创建 GitHub 账号

如果你还没有 GitHub 账号：

1. 访问 https://github.com。
2. 点击"Sign up"按钮。
3. 填写邮箱地址、密码和用户名。
4. 完成邮箱验证。
5. 选择个人计划（免费即可满足基本需求）。

在 GitHub 上添加 SSH 密钥

将你之前生成的 SSH 公钥添加到 GitHub：

1. 访问 https://github.com/settings/keys。
2. 点击"New SSH key"按钮。
3. 在"Title"字段中输入一个描述性名称，如"MacBook Pro"。
4. 在"Key"字段中粘贴你之前复制的公钥内容。
5. 点击"Add SSH key"按钮。
6. 如果提示，输入 GitHub 密码进行确认。

创建 GitHub 仓库

为私有知识库或共享空间创建远程仓库：

1. 访问 https://github.com/new。
2. 在"Repository name"字段中输入仓库名称。建议使用有意义的名称，如 meshwork-private 或 team-docs。
3. 选择仓库可见性：
   • Private：只有你和你授权的人可以访问。适合私有知识库。
   • Public：任何人都可以访问。适合开源项目或公共文档。
4. 不要勾选"Add a README file"、".gitignore" 或 "Choose a license"选项。MeshWork 会初始化仓库内容。
5. 点击"Create repository"按钮。

获取仓库地址与邀请协作成员

创建仓库后，获取其克隆地址：

1. 在仓库页面，点击绿色的"Code"按钮。
2. 选择"SSH"标签页（推荐）或"HTTPS"标签页。
3. 复制显示的仓库地址，如 [email protected]:username/meshwork-private.git。

如果你创建的是团队共享空间用的仓库，需要邀请团队成员：

1. 访问仓库的"Settings"页面。
2. 在左侧菜单中点击"Collaborators"。
3. 点击"Add people"按钮。
4. 输入团队成员的 GitHub 用户名或邮箱地址。
5. 选择权限级别（建议选择"Write"权限）。
6. 点击"Add"发送邀请。

在 MeshWork 中绑定远程仓库

在 MeshWork 中将私有知识库或共享空间绑定到 GitHub 仓库：

1. 先在"设置 → Git"添加远端仓库条目。
2. 打开私有知识库或共享空间的设置页面。
3. 选择要绑定的远端仓库。
4. 如果需要，指定分支名称。留空时 MeshWork 会根据资源类型、名称和 ID 自动生成分支名。
5. 点击"确定"保存绑定。

使用 Personal Access Token（可选）

如果你选择使用 HTTPS 方式而不是 SSH，需要创建 Personal Access Token：

1. 访问 https://github.com/settings/tokens。
2. 点击"Generate new token" → "Generate new token (classic)"。
3. 输入描述，如"MeshWork"。
4. 选择有效期。建议选择较长期限，如 90 天或更长。
5. 勾选必要权限：
   • repo：完整仓库访问权限（推荐）
6. 点击"Generate token"按钮。
7. 立即复制生成的 Token。它只会显示一次，之后无法再次查看。
8. 在 MeshWork 中配置远程仓库时，使用 Token 作为密码。

1.3.6 AI 设置

在"设置 → AI"中配置 AI 智能体的行为。MeshWork 支持通过兼容协议接入多种 AI 服务和搜索服务，你可以根据需要添加和配置。

AI 服务协议与兼容提供商

MeshWork 当前内置两种 AI 接入协议：OpenAI Compatible 和 Anthropic Compatible。设置中的"OpenAI"和"Anthropic"表示请求格式与协议类型，不代表只能使用这两家公司。只要第三方服务商提供兼容接口，就可以通过 API Key、Base URL 和模型名称接入。

以下是常见的兼容服务商示例。不同服务商的模型名称、工具调用、流式输出、思维模式等能力可能不同，请以对应服务商文档为准：

配置选项：

• 提供商 / 协议：根据目标服务商的接口格式选择 OpenAI Compatible 或 Anthropic Compatible。
• API Key：输入从对应平台申请的 API 密钥。
• Base URL：填写服务商提供的兼容 API 根地址，通常不要包含 /chat/completions 或具体模型路径。
• 模型：填写或选择服务商文档中的模型名称。默认示例为 gpt-4o 和 claude-3-5-sonnet-20241022，接入第三方服务时应改为对应模型 ID。
• 上下文窗口大小：设置最大上下文窗口（单位 KB），默认为 200KB，范围为 32KB-2048KB。
• 代理设置：如需通过代理访问，可选择对应的代理配置。
• 设为默认：标记为默认提供商，AI 助手会优先使用。

网络搜索服务

MeshWork 支持以下网络搜索服务提供商。点击链接访问官网并申请 API Key：

配置选项：

• 提供商：选择 Brave、Serper 或 Tavily。
• API Key：输入从对应平台申请的 API 密钥。
• Base URL：默认使用官方 API 地址，如有需要可自定义。
• 代理设置：如需通过代理访问，可选择对应的代理配置。
• 设为默认：标记为默认搜索服务，网络搜索工具会优先使用。

其他功能

• 测试连接：添加提供商后，可以使用"测试连接"按钮验证 API Key 是否有效。
• 思维控制：对于支持思维模式的模型（如 Anthropic Claude），可以启用思维控制功能，让 AI 在生成回复前先进行内部推理。