Agent 接入：让 Codex、Claude Code 操作你的项目

KloseDoc 提供 MCP（Model Context Protocol）适配器 @klosedoc/mcp。配置后，本地运行的 Codex、Claude Code 或其他支持 MCP 的 Agent 可以列出、读取、创建和更新你的文档项目，以及上传和发布网页演示。Agent 不需要 KloseDoc 源码，只需要 Node.js 24 或更高版本。

入口：项目首页左下角账户菜单 → Agent 接入。对话框分三步。

第一步：创建令牌

• 令牌名称：最多 80 个字符，例如“我的本地 Agent”。
• 有效期：7 天、30 天（默认）或 90 天。
• 权限 分三类：
  • 文档项目：无（默认）/ 只读 / 读写。
  • 网页演示：仅上传草稿（默认）/ 上传、发布、回滚和下线。上传草稿始终允许。
  • GitHub 同步：无（默认）/ 推送和拉取已关联仓库。只作用于你拥有且已关联 GitHub 仓库的文档项目，配合文档读写权限使用。

令牌明文只显示一次，关闭后无法再查看，请立即复制。每位用户最多 20 个有效令牌。

管理令牌 列出所有令牌的前缀、最后使用时间、到期时间和权限标签。修改权限 可以就地调整权限（扩大权限时会提示所有已配置该令牌的 Agent 会立即获得新权限）；名称和有效期不能改。撤销 立即让令牌失效。

第二步：配置客户端

选择 Agent 客户端：Codex（TOML）、Claude Code（JSON）或 其他客户端（JSON）。页面生成的配置通过 npx -y @klosedoc/mcp@<固定版本> 启动适配器，并包含服务地址和你刚创建的令牌。

• 配置只能在创建令牌后立即生成，已有令牌无法再次显示。
• 按 macOS / Windows / Linux / WSL 标签页的说明，打开对应配置文件（Codex 为 ~/.codex/config.toml，Claude Code 为 ~/.claude.json），粘贴并保存，然后重启客户端连接。Claude Code 用户可以用 /mcp 命令确认。
• 包含令牌的配置文件不要提交到 Git。
• 服务地址必须是 HTTPS，只有 localhost 允许明文 HTTP。

如果页面提示“安装包尚未发布，暂不可复制安装配置”，说明管理员尚未在服务器上启用公开安装，请联系管理员。

第三步：开始使用

页面提供可以直接复制到 Agent 的提示词，按 操作 选择：

• 文档项目：从本地目录新建文档项目、更新现有文档项目、只读检查文档项目，可选填 项目 ID。更新现有项目的提示词只有一句 klosedoc sync <项目 ID>，见下文“一句话同步”。
• 网页演示：上传并发布、仅上传草稿。
• 测试连接：一条只读提示，让 Agent 列出你的项目以确认配置有效。

一句话同步：klosedoc sync

在本地项目目录里对 Agent 说 klosedoc sync，它会把这个目录的内容更新到 KloseDoc：

• 项目已关联 GitHub：先把 KloseDoc 的内容推送到仓库，再在本地拉取、合并、推送，最后拉取回 KloseDoc（见下文“已关联 GitHub 的项目”）。
• 未关联 GitHub：读取项目状态后以合并模式上传，保留主文件，不删除文件。

目录里有 klosedoc.json 时不用带项目 ID；否则写成 klosedoc sync <项目 ID>。中文说“KloseDoc 同步”也可以。这个词的含义由 MCP 适配器定义，Codex、Claude Code 等客户端行为一致。

想用斜杠命令的话，在客户端保存一个只有一行 klosedoc sync 的文件：Claude Code 是 ~/.claude/commands/sync.md，Codex 是 ~/.codex/prompts/sync.md，之后输入 /sync 即可。Claude Code 还会把适配器自带的 prompt 列为 /mcp__klosedoc__sync，不需要建文件。

从项目内发起

• 文档项目编辑器的“更多操作”菜单中有 用 Agent 更新，显示项目 ID、可复制的 klosedoc.json 和提示词。查看者看不到此入口。
• 网页演示发布页的 更新演示 → 用 Agent 更新 提供同样的信息，见网页演示。

把 klosedoc.json 放进本地项目目录后，Agent 就能知道要更新哪个项目、输出目录在哪。它不包含令牌。

Agent 可以做什么

文档项目（Markdown / LaTeX / Typst）

只读权限：

• 列出你拥有或可编辑的项目，可按标题和类型筛选。
• 查看项目状态：类型、主文件、文件列表、当前修订、正在编辑的人、最新版本和 GitHub 连接状态。
• 读取单个文本文件（最大 1 MB；更大或二进制文件只返回元数据）。
• 把整个项目下载并解压到本地目录，默认不覆盖已有文件。

读写权限还可以：

• 用默认模板创建一个空项目。
• 从本地目录导入为新项目，自动识别类型和主文件。
• 更新现有项目：合并模式（默认）新增和覆盖文件、保留其他文件；替换模式删除本地目录里没有的文件。可以同时切换主文件，但不能删除当前主文件。
• 直接写入或删除单个文件。

Agent 写入的规则：

• 修改直接进入实时文档，协作者立即看到。
• 写入前会先把你自己的最新编辑保存为一个检查点，Agent 的修改再记录为一条来源为“agent”的版本，可以在版本历史中恢复。
• 有人正在编辑时，Agent 必须带上它读取到的修订号；修订过期会被拒绝，避免覆盖他人的改动。
• Agent 不能触发编译，不能发布；推送和拉取 GitHub 需要令牌单独授予 GitHub 同步权限。
• 打包本地目录时会跳过隐藏文件、.git、node_modules、klosedoc.json、LaTeX / Typst 的构建产物，以及 PDF（除非明确要求包含）。

已关联 GitHub 的项目：让 Agent 走 git

直接上传会用本地文件覆盖项目里的同名文件，本地和项目两边都改过时，后上传的一方会丢掉另一方的改动。项目已经关联 GitHub 仓库（见GitHub 同步）时，推荐让 Agent 通过仓库更新，由 git 负责合并。令牌同时具有 文档读写 和 GitHub 同步 权限时，整个流程 Agent 可以自己完成：

1. Agent 调用 推送，把项目当前内容提交到仓库分支。
2. Agent 在本地克隆里 git pull 该分支、合并自己的改动，再 git push。
3. Agent 调用 拉取，项目更新为合并后的结果，并记录一条“已拉取 GitHub 修改”版本，协作者立即看到。

Agent 可用的 GitHub 操作有：读取同步状态、刷新状态（向 GitHub 查询分支最新提交）、推送、拉取。它们只对项目所有者有效，其他成员的令牌会被拒绝。推送时如果两端都有改动，会像网页里一样生成 klosedoc/<时间戳>-<随机串> 冲突分支，Agent 可以在本地把冲突分支合并进主分支再推送、拉取，不需要你去 GitHub 处理。

令牌没有 GitHub 同步权限时，第 1 步和第 3 步由你在 更多操作 → GitHub 集成 里手动 推送 和 拉取，第 2 步仍交给 Agent。

为此 KloseDoc 做了三件事：

• 编辑器里的 用 Agent 更新 检测到项目已关联 GitHub 时，会显示仓库、分支和当前同步状态；提示词仍是一句 klosedoc sync，Agent 会按已关联的方式通过仓库更新，而不是直接上传。
• Agent 读取项目状态时会看到 GitHub 关联信息和同样的建议；MCP 工具说明也要求只有在你明确要求时才直接写入已关联的项目。
• GitHub 上有尚未拉取的更改时，Agent 的直接写入会被拒绝，提示先拉取，避免覆盖仓库里更新的内容。

没有关联 GitHub、或本地目录就是唯一的编辑来源时，直接上传仍然是最省事的方式。

网页演示

• 创建演示项目（不会发布）。
• 查询演示列表或某个演示的状态和版本 ID。
• 把本地输出目录（默认 dist）或 HTML / ZIP 打包上传为草稿。
• 有发布权限时：发布、回滚（恢复历史版本为草稿）、下线。发布保留已设置的访问范围和到期时间，Agent 不能修改它们。
• 删除版本、修改发布设置和下载演示只能在网页上操作。

发布类操作要求 Agent 带上当前线上版本和草稿版本的 ID，避免覆盖其他人的更改；创建和上传的重试使用幂等键，不会产生重复项目。

配额

安全提示

• 令牌等同于你的账号权限，只配置在自己的机器上。
• 不要在演示输出目录或项目目录里放私密文件。适配器的过滤只识别文件类型和路径，不能识别文件内容中的敏感数据。
• 发布仍需你在 Agent 中明确要求，且令牌必须具有发布权限。