Caotang

Caotang

Caotang 是一款用于创作小说及其他长篇小说作品的写作工作室。你的手稿保存在自己的设备上，AI Agent 也可以参与创作。计划和草稿会等待你批准，小幅修改会立即应用；在“设置”中设定的检查点限制范围内，你可以撤销最近的每一轮操作。

Caotang 具备 Scrivener 作者熟悉的结构：包含章节和场景的活页夹、软木板、检查器、用于管理角色和地点的资料库，以及可将内容导出为 Word、EPUB、Markdown 或纯文本的编译步骤。此外，它还提供剧本场景（Fountain）、分支对话（Ink）和带有视频提示词包的故事板编辑器，编译步骤也支持导出这些格式。它的不同之处在于 Agent。你可以使用自己的服务商密钥，让 Agent 通过应用内置的命令工作。它会提出计划，由你批准或修改；每轮会更改项目的操作都会留下一个检查点，你可以在“设置”中设定的限制范围内将其恢复。

前往 caotang.app 体验，或直接在 caotang.app/app 打开应用。

Caotang 免费且采用 MIT 许可证。没有账户、订阅、用量计量，也没有 Caotang 服务。如果你使用模型服务商，则直接向该服务商付费。

当前可用功能

• 项目。 在浏览器中创建、打开、重命名和删除项目。设置标题、作者、语言、ISBN 和封面。将项目导出为 .caotang 包并重新导入。在 Chrome 或 Edge 中，打开项目文件夹或保存到文件夹。如果文件夹中存放的是本浏览器已保留的项目，且包含同一本书，打开该文件夹时会将其作为该项目打开；如果文件夹属于另一个标签页已打开的项目，则会拒绝打开。Caotang 会在覆盖未由它所做的更改之前询问你，也会在写回被其他程序删除的 caotang.json 之前询问你。打开文件夹时，其中的写作会话会导入到此浏览器。
• 活页夹。 包含章节和场景的手稿，以及永不编译的研究部分。可拖动以重新排序、重命名、设置状态或标签、删除和撤销。提供筛选栏（文本、状态、标签、字数、关键词和最近日期）及已保存的筛选条件；页脚显示字数目标、冲刺计时器、写作历史，以及已停止的标签页保留的字数。
• 软木板。 将章节中的场景或手稿中的章节显示为三种尺寸的卡片。拖动即可重新排序。
• 检查器。 显示所选项目的梗概、笔记、关键词、状态和标签、设定集链接与场景声明，以及对话的容器设置。
• 编辑器。 场景采用 Markdown 格式，并会随着输入自动保存。显示字数统计、每日目标和专注模式。Agent 起草的内容会先出现在场景中，并显示在预览栏里。
• 剧本。 场景采用 Fountain 格式，提供剧本视图、源码视图和页面视图；页面视图会定位到源码视图中的对应行。将 .fountain 或 .fdx 剧本导入为分区和场景。Final Draft 文件尚未在 Final Draft 本身中进行过检查。
• 对话。 容器是 Ink 故事，包含大纲、分支图、调查结果和行 ID。导入 .ink 故事时，每组彼此跳转的节点会成为一个容器；也可以将 Twee 3 故事（.twee）导入为一个容器，导入前会显示逻辑剥离报告。
• 故事板。 镜头卡片可添加图片（选择、拖放或粘贴），显示动画总时长和剧本覆盖情况；每种目标视频模型都有对应的提示词，并可将提示词包导出为 JSON、Markdown 或 CSV。
• 设定集。 包含角色、地点、物品、背景设定、支线剧情和其他条目，并提供别名、包含策略、排除短语，以及每个名称出现过的文档列表。
• Agent 指令和记忆。 常驻指令保存在项目根目录的 CAOTANG.md 中，并会随每个请求发送，但上限为 1,500 个 token，此上限会明确显示。Agent 保存的笔记是 memory 文件夹中的普通文件，你可以查看、编辑和删除。Agent 只会将内容写入你批准的卡片之后。
• 技能。 可重复使用的 Agent 写作指令（例如“用贴近人物的第三人称写作”），以标准 Agent Skills 文件夹形式保存在项目中，其他工具也能读取。告知 Agent 使用某项技能之前，你需要先阅读并批准；技能发生更改时，也需要再次批准。技能会指导 Agent，但不会改变任何需要你批准的事项。
• 宏。 将已批准的计划保存为宏，并留出几个待填写的值，然后从设置中再次运行。运行时会像任何计划一样显示卡片，一次撤销即可还原，并且仍遵循你的规则和权限模式。只有你可以运行宏；Agent 无法运行。
• 钩子。 编写 Agent 必须遵守的检查，例如禁止使用某个词、禁止触碰某个状态、必须遵守某个篇幅或必须通过连续性检查；这些检查会在 Agent 每次调用前后运行。钩子可以发出警告、停止步骤并在变灰的“批准”按钮旁说明原因，也可以给 Agent 留下笔记。钩子绝不会批准任何内容；最终仍由你的规则和权限模式决定，而且只有你可以添加或移除钩子（在设置中提供专用面板之前，需手动编辑项目文件）。请参阅钩子。
• 调查结果。 快速扫描手稿，并与设定集及场景声明进行比对；也可运行模型审查，但必须先批准其计划。调查结果按严重程度分组，并引用相关段落。你可以说明理由后忽略某项、标记为已修复，或通过 让 Agent 修复 将其交给 Agent。运行历史会保留每次运行的记录。
• Agent。 Agent 面板中提供计划、单步卡片和草稿预览；也可以在设置中选择让 Agent 将新文本直接保留在场景中，并仅标记发生更改的词语，供你接受或拒绝。还提供检查点和恢复功能，以及 追踪 选项卡，显示每轮发送和收到的内容（仅保留在当前打开的标签页中，可按需导出）。你可以停止正在运行的轮次、用笔记引导它，或在它工作时排队发送下一条消息。模式 控件用于设置由谁处理其卡片：仅计划、询问（默认）、接受编辑或自动；还可设置在遇到问题时停止轮次的限制。需要调用模型五次或更多次的计划可在后台运行，让你继续写作；应用任何内容前，你都可以先审阅草稿。处理长篇阅读任务时，它可以交给辅助 Agent 阅读并提出建议；只有在你批准的计划中包含建议时，才会提出建议。它可以使用主流提供商的预设（Anthropic、OpenAI、Google、xAI、Mistral、DeepSeek、OpenRouter 等），也可以使用你添加的任何 OpenAI 兼容端点，或使用无需密钥的内置演示提供商。模型支持时，它会使用原生工具调用；也可以将模型审查作为计划步骤运行，并调用你连接并启用的 MCP 服务中的工具（见下文）。
• 导出。 可将整份手稿或其中一部分导出为 Markdown、纯文本、Word（.docx）和 EPUB。对于剧本、对话和故事板，可导出为 Fountain、Final Draft（.fdx，尚未在 Final Draft 本身中进行过检查）、分页剧本 PDF、Ink 故事、对话表、镜头列表和故事板联系表（PDF；也可导出为空白编号画格，以便绘制，再将拍好的画作照片拖放回对应镜头）。还可导出一致性报告。配方会保存你的导出设置。
• 设置。 提供提供商配置、Agent 上下文预算、每日目标和自动保存延迟、一致性检查、浅色和深色主题、检查点数量限制、MCP 和工具以及数据设置。
• MCP 和工具。 设置中可以通过 Streamable HTTP 连接外部 Model Context Protocol 服务。每个服务的工具列表都必须经过审查才能使用，并且可以关闭单个工具。只有当服务已获准读取且工具为只读时，Agent 才会立即调用启用的工具。其他调用都需要等待你的批准。
• 将 Caotang 用作 MCP 服务。 其他 AI 工具可以读取项目文件夹，将其中的文档、笔记和设定集作为资源附加，并运行携带 Caotang 为场景收集的上下文的提示词。允许写入后，它们也可以修改内容；每项需要确认的更改都会在宿主中得到确认。请参阅将 Caotang 用作 MCP 服务。 此版本尚未包含：桌面封装。docs/USER-GUIDE.md 列出了它以及其他尚未包含的内容，docs/ROADMAP.md 说明了实现顺序。

要求

• Node.js。 package.json 的 engines 字段允许使用 22 系列的 Node 22.12 或更高版本、24.x，以及 26 或更高版本。持续集成会测试最低版本 Node 22.12.0 和 Node 24；虽然允许使用 Node 26，但不会对其进行测试。
• pnpm 12.9.1，由 packageManager 固定。使用 Node 22.12.0 时，先用 npm install --global [email protected] 更新 Corepack；捆绑的 Corepack 0.29.4 无法验证 pnpm 当前的签名密钥。然后运行 corepack enable。
• 浏览器。 此应用面向当前浏览器开发。每个拉取请求都会在 Chromium、Firefox 和 WebKit 中运行端到端测试；Firefox 和 WebKit 测试套件也会每晚运行，并支持按需运行。打开和保存项目文件夹需要使用 Chrome、Edge 或其他基于 Chromium 的浏览器。构建产物可在任何浏览器中运行。
• 至少 960 px 宽的窗口，以使用桌面布局。宽度低于 1100 px 时，工具栏会换到第二行，侧边面板也会变窄。宽度低于 960 px（手机或竖屏平板）时，Caotang 会采用窄屏布局：资料夹会变成抽屉，检查器会变成面板；软木板、故事板、对话分支图、剧本的 Pages 视图、MCP 和工具，以及 Markdown 和纯文本以外的编译格式都会显示“请在桌面上打开”。此布局在模拟的 Chromium 环境中测试，不会在真实手机上测试；并且没有同步功能，因此请导出备份。

安装和运行

克隆项目后，在仓库根目录运行：

pnpm install
pnpm dev

pnpm dev 会在 http://127.0.0.1:5173 提供应用。

要进行生产构建，请运行 pnpm build，然后运行 pnpm --filter @caotang/desktop preview。构建产物位于 apps/desktop/dist/，旁边有一份 THIRD-PARTY-NOTICES.md。预览服务默认在 http://127.0.0.1:4173 提供构建产物。关于它，有两点需要了解：

• 构建产物适用于其源站根目录，因此请像预览服务那样从根目录提供；如果使用 CAOTANG_BASE 将其构建到子路径，则不受此限制（参见“自托管”）。
• 项目按源站保存，源站由地址和端口共同确定。在 http://127.0.0.1:5173 创建的项目不会出现在 http://127.0.0.1:4173。请导出构建包以迁移项目。

自托管

Caotang 是静态文件，因此任何静态托管服务都可以提供它：GitHub Pages、Netlify、Cloudflare Pages、S3 存储桶，或你自己机器上的 nginx。无需运行服务器端组件。

1. 构建：运行 pnpm install，然后运行 pnpm build。网站文件都在 apps/desktop/dist/ 中，THIRD-PARTY-NOTICES.md 与其同级。复制整个文件夹。
2. 通过 HTTPS 提供服务。 浏览器仅在安全源（https://，或你自己机器上的 http://localhost 和 http://127.0.0.1）上提供 Caotang 使用的 WebCrypto 密钥封装和文件夹访问功能。
3. 在源站根路径提供服务（https://writing.example.com/），或者使用 CAOTANG_BASE 构建到子路径：CAOTANG_BASE=/caotang/ pnpm build 会生成一个可在 https://example.com/caotang/ 使用的构建版本。默认情况下，构建版本的资源路径以 / 开头。
4. 保存到文件夹需要 Chromium 浏览器（Chrome、Edge、Brave、Arc 等），这些浏览器支持 File System Access API。在其他浏览器中，项目保存在浏览器内，并通过 .caotang 包迁移。

项目按源站分别保存：在一个主机上创建的项目不会显示在另一个主机上。导出一个包即可迁移项目。

构建版本的 index.html 已在 <meta> 标签中包含 Content-Security-Policy。能够发送响应头的托管服务可以通过响应头发送相同的策略，并添加 <meta> 标签无法设置的保护措施（frame-ancestors）：

Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data: blob:; font-src 'self' data:; connect-src *; worker-src 'self'; frame-src 'none'; object-src 'none'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'
X-Content-Type-Options: nosniff
Referrer-Policy: no-referrer

connect-src * 是有意这样设置的：Agent 会直接从你的浏览器连接到你配置的任意提供商和 MCP 服务。如果要收紧此设置，请列出你使用的提供商；如果使用本地模型预设（Ollama、LM Studio、llama.cpp），还要加入 http://127.0.0.1:*。

对于 Netlify 或 Cloudflare Pages，将响应头写入 apps/desktop/dist/ 中的 _headers 文件（或写入 apps/desktop/public/，这样每次构建都会复制该文件）：

/*
  Content-Security-Policy: default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data: blob:; font-src 'self' data:; connect-src *; worker-src 'self'; frame-src 'none'; object-src 'none'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'
  X-Content-Type-Options: nosniff
  Referrer-Policy: no-referrer

对于 nginx：

server {
    listen 443 ssl;
    server_name writing.example.com;
    root /var/www/caotang;   # the contents of apps/desktop/dist

    add_header Content-Security-Policy "default-src 'self'; script-src 'self'; style-src 'self'; img-src 'self' data: blob:; font-src 'self' data:; connect-src *; worker-src 'self'; frame-src 'none'; object-src 'none'; base-uri 'self'; form-action 'none'; frame-ancestors 'none'" always;
    add_header X-Content-Type-Options nosniff always;
    add_header Referrer-Policy no-referrer always;

    location / {
        try_files $uri /index.html;
    }
}

仓库的 Pages 工作流 会部署 caotang.app：根路径提供 site/ 中的落地页，以及 llms.txt、robots.txt 和站点地图；/app/ 路径提供使用 CAOTANG_BASE=/app/ 构建的同一应用。

测试

pnpm verify                             # lint, typecheck, and the unit tests in packages/ and test/
pnpm exec playwright install chromium   # once, for the browser the pull-request end-to-end tests use
pnpm test:e2e                           # the Chromium Playwright suite
pnpm exec playwright install firefox webkit  # once, for the optional cross-browser suite
CAOTANG_E2E_BROWSERS=all pnpm exec playwright test --project=webkit  # run a cross-browser project

Agent 的黄金写作任务会在 pnpm verify 中运行：每项任务都会通过模拟提供方重放已提交的录制内容，无需密钥或网络；如果提示词或工具描述会向模型发送与录制内容不同的内容，任务就会失败。这些录制内容是合成的（答案由人工编写），因此它们用于检查提示词和测试框架，不代表任何模型的表现。目前还不支持从真实模型录制内容，也没有模型基准测试。

pnpm verify 不会运行 e2e/unit 中桌面应用的纯模型测试，因为它们是 Playwright 测试。运行 pnpm test:e2e 即可执行这些测试，以及开发服务器测试套件和生产构建的冒烟测试（e2e/prod-smoke.spec.ts）；后者会通过 vite preview 使用独立端口。

端到端测试套件会启动自己的开发服务器；在 CI 之外且未设置 CAOTANG_E2E_PORT 时，会复用已在端口 5173 上运行的服务器。若要与另一个 Caotang 副本并行运行，请使用 CAOTANG_E2E_PORT 为每个检出副本指定不同端口，例如 CAOTANG_E2E_PORT=5183 pnpm test:e2e。在 PowerShell 中，先使用 $env:CAOTANG_E2E_PORT = 5183 设置端口。之后，生产预览会使用该端口加 1000 得到的端口；也可以设置 CAOTANG_E2E_PREVIEW_PORT 指定端口。

持续集成（.github/workflows/ci.yml）会在 Node 22.12.0 和 24 上运行 verify 矩阵。每个任务都会使用冻结且严格检查引擎的方式安装依赖，然后运行 pnpm verify、pnpm build、包体积检查、MCP 服务打包和 CLI 包构建。Node 22.12 CI 会先检查 pnpm 压缩包的 SHA-512 是否与 packageManager 锁定版本一致，再直接安装该压缩包；Node 24 使用 Corepack。Node 24 Chromium 端到端测试套件会作为独立任务并行运行，此外还有 office-interop（使用 openpyxl 和 LibreOffice 测试 .xlsx 语料库）和 pdf-validate（使用 pdf.js、qpdf、Poppler、Ghostscript 和 MuPDF）。另一个工作流会在 Firefox 和 WebKit 中检查拉取请求，也会按夜间计划和手动触发运行；它会将每种浏览器的测试拆分为两个任务，并把结果合并到一份 HTML 报告中；若某个分片失败，则会上传该报告。在本地设置 CAOTANG_E2E_BROWSERS=all 即可启用这些项目。文件夹访问测试在 Chromium 之外会跳过，而 e2e/non-chromium-storage.spec.ts 会检查这些浏览器使用的纯打包文件路径。

提供方预设的真实密钥检查 e2e/provider-smoke.spec.ts 仅在设置了 CAOTANG_SMOKE_<PRESET> 密钥时运行；你可以在自己的计算机上运行，也可以由维护者手动触发 provider-smoke 工作流（gh workflow run provider-smoke.yml -f presets="anthropic deepseek"）。它不会在拉取请求上运行。请参阅 providers-browser-cors.md。

脚本化演示位于 e2e/demo.spec.ts。它会构建一个包含三个章节的故事，让 Agent 起草一个场景并批准草稿，在软木板上重新排列故事，然后将其编译为 Word 文档。接着，它会解压文件并检查其结构。演示使用内置演示提供方运行，无需密钥。

你的密钥与隐私

• 使用你自己的密钥。 在 设置 › 提供商中添加提供商：选择一个预设（其地址和身份验证信息会自动填入），或填写你自己的通用端点，然后选择模型并粘贴密钥。保存后，Caotang 会列出该提供商的模型，以检查是否正常工作。
• 你的密钥会留在此浏览器中。 密钥使用页面无法导出的密钥进行封存，且绝不会写入项目文件。封存可以防止存储的密钥被读取，但无法防范 Caotang 开启期间在页面中运行的代码。
• 请求会发送到你选择的提供商。 Agent 只会向每项任务角色所解析到的配置文件端点发送请求。本地模型预设（Ollama、LM Studio、llama.cpp）只会通过本机回环地址上的普通 http 与你自己电脑上的服务通信，因此文本会留在本机；其他所有提供商都需要 https。内置演示提供商完全不会发出网络请求。
• Agent 工作时，你的文本会发送给该提供商。 Agent 需要的项目内容会随每次请求发送。Agent 面板会显示未发送的内容。你在「发现」选项卡中发起模型审查时，只有在你批准计划后，才会发送模型读取的文本。
• MCP 服务默认关闭，需由你启用。 设置 › MCP 与工具默认处于关闭状态，关闭时不会联系任何服务。启用并连接服务后，Caotang 会向该服务的地址（https，或你本机上的 http）发送请求，以列出其工具，并在 Agent 调用工具前检查工具。Agent 调用工具时，它为该次调用选择的参数会发送到该服务，结果则会返回给 Caotang。Caotang 不会联系你尚未连接的服务。
• 无需账户，无 Caotang 服务，也无分析追踪。 项目保存在你的浏览器中。导出一个捆绑包，即可留存一份可在任何地方打开的副本。

磁盘上的项目

项目是一个文件夹：

caotang.json          the manifest: the binder tree, the codex, the vocabulary, recipes, filters and goals
caotang.json.bak.1..3 the three previous manifests
coherence.json        the findings and check runs, beside the manifest
tasks.json            the recurring agent tasks, definitions only (when each last ran stays in the browser)
docs/                 one file per scene, note or dialogue container, named by id: .md, .fountain or .ink
codex/                one file per codex entry
assets/               images: storyboard pictures and the cover
exports/              compiled files
sessions.jsonl        writing sessions, appended to and read back when the folder opens
.caotang-mcp.lock     present while an MCP server is running on the folder

完整格式见 docs/architecture/project-format.md。捆绑包就是压缩后的同一文件夹。

将 Caotang 用作 MCP 服务

Caotang 可通过 Model Context Protocol 向外部 AI 工具提供项目文件夹。完整参考见 packages/mcp-server/README.md。

只需构建一次服务：

pnpm --filter @caotang/mcp-server build

这会生成 packages/mcp-server/dist/caotang-mcp.mjs，这是一个可通过 node（22 或更高版本）运行的单文件程序。若要创建主机可安装的 MCP 捆绑包，请运行：

pnpm --filter @caotang/mcp-server run pack

这会生成 packages/mcp-server/dist/caotang-mcp-0.1.0.mcpb。也可以从最新版本下载 caotang-mcp-<version>.mcpb，其 SHA-256 值记录在 SHA256SUMS 中。捆绑包包含服务、其清单、告知文件和许可证。清单由本软件包固定版本的 MCPB CLI 检查。主机会要求你选择项目文件夹并设置 允许更改，此选项默认关闭。该捆绑包未经签名，也未在真实的 MCPB 主机中运行过；它已通过检查，并在 stdio 模式下运行过。

仅在 127.0.0.1 上通过 HTTP 提供项目文件夹：

node packages/mcp-server/dist/caotang-mcp.mjs serve --project ~/Writing/my-novel

除非添加 --allow-writes 或设置 CAOTANG_MCP_ALLOW_WRITES=true，否则服务为只读模式。允许写入后，七个工具会立即应用更改（meta.set、notes.append、synopsis.set、filter.save、goal.save、coherence.setFindingStatus 和 shots.annotate）；另外九个工具会要求你在主机中确认每次调用后才会写入任何内容（binder.restructure、codex.write、codex.import、doc.import、export.compile、notes.replace、vocabulary.upsert、scene.apply 和 dialogue.apply）。添加 --create "New Book"，即可在尚无项目的文件夹中创建新项目。对于已包含文档或 codex 文件，或清单副本（caotang.json.*）的文件夹，系统会拒绝执行 --create，因此不会接管这些文件。 **令牌。**通过 HTTP 连接时，服务启动时会打印一次承载令牌。若要自行选择令牌，请在启动服务前将 CAOTANG_MCP_TOKEN 设为至少 16 个字符。每个请求都必须发送 Authorization: Bearer <token>。

**Stdio。**若要让主机自行启动服务，请添加 --stdio。主机的进程边界将取代端口和令牌：

node packages/mcp-server/dist/caotang-mcp.mjs serve --project ~/Writing/my-novel --stdio

**连接主机。**通过 HTTP 连接时，端点为 http://127.0.0.1:7433/mcp。除非传入 --port，否则端口为 7433。需要 mcpServers 条目的主机应使用：

{
  "mcpServers": {
    "caotang": {
      "type": "http",
      "url": "http://127.0.0.1:7433/mcp",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

除了工具，服务还会提供项目文本作为资源，供你按需附加（在 Claude Code 中使用 @caotang:caotang://doc/…；在 Cursor 中使用资源选择器），并提供五个提示词，将 Caotang 为任务构建的上下文交给主机的大模型：draft-scene、fill-synopsis、continuity-check、codex-from-doc 和 revise-with-codex。资源包含整份文档，超过 2 MiB 的资源会被拒绝，而不会截断。提示词由主机的大模型执行，因此其中携带的文本会发送给该模型，就像主机通过工具读取文档时一样；Caotang 不会调用任何模型，也不会持有密钥。请参阅服务的 README 中的 Resources 和 Prompts。

连接前请注意以下三点：

• 如果主机无法显示确认提示，需要确认的更改就会被拒绝，且不会写入任何内容。主机必须支持 MCP elicitation。
• 使用 2025 协议修订版的主机在通过 HTTP 确认更改时，必须声明支持 elicitation，并保留服务在会话启动时返回的 Mcp-Session-Id。服务最多维持 16 个此类连接；空闲 30 分钟的连接会被关闭，而 16 个连接全部占用时，新主机会收到 503。无法保持会话的主机可以通过 --stdio 连接，或安装通过 stdio 运行的 .mcpb 包。
• 服务以 --allow-writes 运行期间，只有在服务已停止或逐一确认每个保存提示后，才能通过 Caotang 应用保存其文件夹。应用会在覆盖服务的锁之前询问，但确认保存仍可能覆盖服务写入的内容（请参阅服务 README 中的 Known gaps）。

需要模型的工具——scene.draft、synopsis.fill、continuity.scan、coherence.review、shots.derive、prompt.draft、prompt.variant 和 dialogue.draft——无法通过 MCP 使用，因为服务不持有任何提供商密钥。对于场景和对话，由主机自己的模型来撰写：scene.brief 和 dialogue.brief 会将 Caotang 的 Agent 本会发送的内容交给它，而 scene.apply 和 dialogue.apply 会在你确认后将其文本写入项目。确认并不等于审阅，因此请先阅读模型写下的内容；撤销会恢复文档。使用主机的大模型撰写内容介绍了详情。将现有写作内容导入 Caotang介绍了可用的导入工具 doc.import 和 codex.import。允许写入时，export.compile 可以在主机确认后，按任意导出格式（包括 EPUB）编译手稿、单个条目或已保存的配方。

安装捆绑包

1. 使用上面的 pack 命令构建 caotang-mcp-0.1.0.mcpb，或从最新版本下载。
2. 将文件拖到 Claude Desktop 等 MCPB 宿主中，或使用宿主打开该文件。宿主会显示一个对话框，其中包含捆绑包的名称、描述和两个设置。
3. 在 项目文件夹 下，选择一个已有 Caotang 项目的文件夹。
4. 除非你希望助手修改项目，否则请保持 允许更改 关闭。关闭时，助手只能读取项目。开启后，某些更改仍需先在宿主中由你确认。
5. 宿主可能会警告该捆绑包未签名，并提供 仍然安装 选项。该警告表示宿主无法为此文件标明发布者，因为当前的签名工具生成的捆绑包会被宿主拒绝。代码是开源的，你可以使用 pack 命令从源代码构建相同的文件。仅在由你构建或从本项目的版本发布中获取时才安装。

该服务在你的计算机上通过 stdio 运行，不会开放网络端口。卸载捆绑包会移除服务，并保留项目文件夹原样。不同宿主和版本中的对话框措辞可能有所不同。

该捆绑包未签名，也尚未在真实宿主中测试过。packages/mcp-server/HOST-CHECKS.md 列出了检查项并记录结果；目前还没有检查结果。版本发布中会在 SHA256SUMS 中列出该文件的 SHA-256。

从命令行运行 Caotang

caotang agent 会在项目文件夹中运行一轮 Agent，然后退出，可用于终端、Makefile、cron 作业或 CI。除非另有指定，否则它为只读模式：不使用 --write 时，文件夹中的内容不会发生变化，而可能被修改的文件会以差异形式输出。使用 pnpm --filter @caotang/cli build 构建后，会生成 packages/cli/dist/caotang.mjs（单个文件；使用 node 运行，并将 fonts/ 文件夹放在它旁边）。

# The demo provider: no key, no network. Prints the reply, exits 0, writes nothing.
node dist/caotang.mjs agent -p "Check the manuscript for continuity problems." --mock --project ~/Writing/my-novel

# A review with your own key, read-only. The key comes from the environment, never from a flag.
CAOTANG_API_KEY=... node dist/caotang.mjs agent -p "Check the manuscript for continuity problems." \
  --provider openrouter --project ~/Writing/my-novel --output-format json

# Approve every card the plan shows, save the folder, and print what changed.
CAOTANG_API_KEY=... node dist/caotang.mjs agent -p "Fill in the synopses for Chapter 1." \
  --provider openrouter --project ~/Writing/my-novel --permission approve-all --write

标志	含义
-p <intent>	要询问的内容。-p - 表示从标准输入读取。
--project <dir>	项目文件夹（默认为工作目录）。
--mock 或 --provider <preset>	演示用服务提供方，或服务提供方预设（可通过 --base-url、--model 和 --thinking 进一步配置）。
--key-env <VAR>	保存密钥的环境变量（默认为 CAOTANG_API_KEY）。没有用于直接传入密钥的标志：密钥会显示在 ps 和 shell 历史记录中。
--permission <mode>	read-only（默认）：取消所有卡片。auto：执行无需卡片的更改，取消所有卡片。approve-all：按显示内容批准所有卡片，但绝不批准服务提供方中断生成的草稿。
--approve-tools <tool,...>	与 approve-all 搭配使用：只有卡片中的每个步骤都属于这些工具之一时才批准。卡片中只要有任何其他步骤，就会整张取消。
--write	在本轮结束后保存文件夹。需要使用 auto 或 approve-all。
--plan-file <plan.json>	执行你编写的计划 { "steps": [{ "tool", "params", "expect" }] }，不调用规划器。
--output-format	text（默认）、json（本轮结束时输出一个对象）或 stream-json（每个事件占一行；每张卡片输出一行 decision，然后输出结果）。
--max-model-calls <n>	一轮最多可进行的大模型调用次数（默认为 8）。

标准输出仅包含所选格式；进度和说明会输出到标准错误。当本轮完成时，退出码为 0；发生内部错误时为 1；命令行错误或文件夹不包含项目时为 2；其他写入程序（应用或 caotang-mcp serve）占用文件夹时为 3；本轮需要输入时为 4（权限模式取消了卡片、达到限制，或服务提供方调用失败）；发生冲突时为 5；验证失败时为 6；收到 SIGINT 和 SIGTERM 后分别为 130 和 143。使用 --write 运行时，命令会记入撤销历史的末尾，因此请将文件夹置于 git 管理之下。caotang mcp serve 使用与 caotang-mcp serve 相同的标志启动 MCP 服务。caotang scan 无需大模型即可运行连续性检查；参见 CI 中的连续性检查。

CI 中的连续性检查

caotang scan 会在项目文件夹中运行 Findings 标签页中的确定性检查，无需浏览器、大模型或密钥，因此可以每晚检查存放在 Git 仓库中的项目，也可以在每个涉及稿件的拉取请求中进行检查。

node dist/caotang.mjs scan --project ~/Writing/my-novel                          # a report in the terminal; exit 7 if an error is open
node dist/caotang.mjs scan --format github --fail-on warning --summary ../report.md  # annotations on the files, the Markdown report in a file outside the folder

Flag	含义
--project <dir>	项目文件夹（默认为工作目录）。
--scope <scope>	full（默认）或 changed。full 会读取每份文档；changed 只读取自上次保存的运行以来有编辑的文档。若不使用 --write，运行状态永远不会更新，因此 CI 使用 full。
--checks <id,...>	只运行这些检查，例如 presence.expected,timeline.overlap（默认为全部检查）。
--format	text（默认）、markdown（连贯性报告）、json 或 github（每条发现对应一条工作流命令，使其显示在对应文件和行上）。
--fail-on <level>	error（默认）、warning、info 或 never：达到此严重级别的未解决发现会导致运行失败。
--write	将本次运行结果保存到 coherence.json。不使用此选项时只会读取文件夹，之后其中每个文件的字节内容都保持不变。
--summary <file>	另外将 Markdown 报告写入此文件。只有当路径解析后与 $GITHUB_STEP_SUMMARY 相同时，才会追加内容，因此可以接续其他步骤；其他文件会被完整写入。不使用 --write 时，--summary 必须指定项目文件夹之外的文件。
--help, -h	打印用法并以 0 退出。

扫描无异常或设置了 --fail-on never 时，退出代码为 0；存在达到或超过 --fail-on 级别的未解决发现时为 7；没有达到该级别的未解决发现、--fail-on 不是 never，且某份文档或 codex 文件不是 UTF-8 文本、因此未被检查时为 8（输出会列出该文件，扫描结果为部分检查）；内部错误时为 1；命令行错误或文件夹中没有项目时为 2；另一个写入进程占用了文件夹时为 3（仅适用于会锁定文件夹的 --write）。在应用中忽略或标记为已修复，并提交到 coherence.json 的发现不会打印，也不会导致运行失败；如果无法读取 coherence.json，则不会修复该文件，而是重新计算发现，并在输出中说明已忽略的发现会丢失。扫描也会运行对话检查。它会读取项目存放该文档的文件，因此，剧本中的发现会定位到其 .fountain 文件，对话容器中的发现则会定位到其 .ink 文件。

工作流。 docs/ci/continuity-scan.yml 是一个 GitHub Actions 工作流，可复制到项目仓库中的 .github/workflows/。它会在每晚、手动触发，以及更改 docs/、codex/、caotang.json 或 coherence.json 的拉取请求中运行。项目文件夹必须是仓库根目录：扫描步骤不会传入 --project，路径过滤器也假定项目位于根目录；若项目位于子文件夹中，请在该步骤添加 --project <dir>，并将该文件夹加入过滤器。它只请求 contents: read，不持有任何密钥，也绝不会使用 pull_request_target。它不会运行 npx：而是从 Caotang 发行版下载 caotang.mjs，并根据文件中写明的 SHA-256 校验文件，该发行版会在 SHA256SUMS 中列出此校验值。模板固定使用发行版 v0.1.0，因此复制后即可运行；若要改用较新的发行版，请从该发行版的 SHA256SUMS 中同时更新版本和校验值（pnpm --filter @caotang/cli build 会在本地写入相同的文件）。

输出内容。 注释和作业日志会包含稿件中的简短引文，因为发现会引用相关段落。在公开仓库中，任何人都能读取这些内容。如果对此有所顾虑，请将仓库设为私有，或在输出不会被公开的步骤中使用 --format text 运行扫描。

CI 中不进行模型审查。 CI 只运行确定性检查。不提供模型审查：它需要将密钥存入仓库机密，而这是密钥离开你设备的唯一环节；此外还会按计划产生费用。如果将来添加此功能，它将遵循重复任务的机制，采用逐任务主动选择和调用次数上限，并使用单独授权范围的密钥和只读工具允许列表。

脚本化 Caotang

Agent 也可以通过 Node 脚本、CLI 或 CI 运行，针对项目文件夹操作，并以审批策略代替卡片。该软件包为 @caotang/sdk，其 README 提供了三个示例：演示提供方、使用你自己的密钥进行只读审查，以及批准所有操作并写入文件夹的运行方式。更改会一直保留在内存中，直到你保存；diff() 会先显示更改；密钥保存在内存中，且只会发送给你的提供方。

文档

• docs/USER-GUIDE.md：面向作者的指南。
• CHANGELOG.md：本次发布包含的内容及其已知限制。
• docs/ARCHITECTURE.md：模块图、数据模型和原则。
• docs/architecture/：每个模块各有一份规范。agent-harness.md介绍 Agent 的工具，extensibility.md介绍 MCP 客户端和服务。
• docs/ROADMAP.md：已构建的内容、正在构建的内容，以及后续计划。
• docs/decisions.md：当前决策，每项决策各占一行，并注明决策者。
• CONTRIBUTING.md 和 SECURITY.md：如何参与贡献，以及如何报告漏洞。

Caotang 的构建方式

Caotang 是在所有者指导下，借助 AI 编码 Agent 构建的。docs/decisions.md 中标记为 [owner] 的每项决策均由人作出。

许可证

Caotang 基于 MIT License 发布。请参阅 LICENSE。THIRD-PARTY-NOTICES.md 列出了构建中使用的第三方软件包及其许可证。运行 node tools/third-party-notices.mjs --write 可重新生成该文件。当提交的副本与锁文件不一致时，测试会失败。