ClaudeR

ClaudeR 可将通过 MCP 配置的大模型 Agent（例如 Claude Code 或 Codex）连接到你正在使用的 R 会话。Agent 会在实际存放清理后数据和拟合模型的会话中运行代码，查看绘制的图表，读取环境中的对象，还能编辑你在编辑器中打开的文件。配套的 Python 包也能为正在运行的 Python 会话提供相同功能，而且两者都适用于 RStudio 和 Positron。

多个 Agent 可以共享同一个会话并分工协作；你也可以并行运行多个独立会话，让每个 Agent 使用自己的数据集而不影响其他会话。

它涵盖了许多付费研究 AI 工具所具备的功能，所有工作都在你自己的会话中进行，并且会记录 Agent 运行的每一行代码。

快速入门

# Install
if (!require("devtools")) install.packages("devtools")
devtools::install_github("IMNMV/ClaudeR")

# Set up your AI tool
library(ClaudeR)
install_clauder()          # For Claude Desktop / Cursor
install_cli(tools = "claude")  # For Claude Code CLI

# Start the server in RStudio
claudeAddin()

**AI Agent：**自动安装说明请参阅 llms-install.md。

演示

通过 Claude Desktop App 使用单个 Agent	多 Agent：通过 CLI 使用 Codex + Claude Code	GPT 5.4 Codex：数据分析 + Quarto 报告

近期更新（点击展开）

• 长任务期间减少状态检查，不遗漏长输出内容，让 Agents 面板更清爽（R 0.16.2 / clauder-mcp 0.16.2）。get_async_result 现在会等待任务完成并在完成时立即返回（最长等待 wait_s 秒，默认为 300 秒），因此，拟合一个耗时 20 分钟的模型只需调用几次，而不是大约 120 次。输出过长、无法完整发送时，系统会将完整内容保存到文件，并告知 Agent 文件位置，这样它就能读取被截断的部分，而不必重新运行代码。插件的 Agents 面板现在会隐藏一天内未出现的 Agent，与 cr_roster() 的行为一致，因此新打开的会话不再列出数周前的 Agent。

• 修复了加载项的控制台日志记录（R 0.14.2）。 在 0.14.1 中，勾选加载项里的“同时记录我自己的控制台命令”不会启动任何功能，而在控制台中调用 start_console_logging() 则可以正常工作。原因是 globalCallingHandlers()（用于观察警告和消息）只能在处理器堆栈为空时调用；在处理复选框的 Shiny 观察器中调用它会报错，导致函数在注册控制台回调之前就中止。现在会先无条件注册回调；只有从控制台启动日志记录时才安装处理器，否则每条命令执行后都会从 last.warning 读取警告。从加载项启动时，唯一无法捕获的是 message() 的输出，加载项也会对此进行提示。

• 控制 Agent 接收的内容，不再发送无人查看的绘图（R 0.15.0 / clauder-mcp 0.15.0）。 根据两位用户的请求新增。加载项中的“AGENT CONTEXT”面板提供两项功能。“自动向 Agent 发送绘图”可以关闭：Agent 会收到已绘制绘图的通知，并通过 execute_r_with_plot 请求查看；如果你主要需要文本，每张图大约可节省 4,500 个 token。无论如何，你的 Plots 窗格都不受影响。“Agent 可用的工具”可以隐藏你不使用的整个工具组（编辑器、会话、协调、后台作业、手稿审查）；每次请求中，全部 41 个工具的架构约占 8,600 个 token，而仅用于编程的会话只需要其中约 1,200 个 token。这两项设置均按会话生效，无需重启；不过，有些 MCP 客户端只有在重新连接后才会发现工具列表发生了变化。另有一项错误修复：p <- ggplot(...) 会将完整图像返回给 Agent，尽管赋值操作不会显示图像，因此 Agent 收到了从未出现在你的 Plots 窗格中的绘图。现在只有实际显示的绘图才会被捕获。

• 日志记录修复（R 0.14.1）。 根据一位用户的反馈修复了两个问题。Agent 的输出从未写入日志，日志里只有代码，因为日志条目是在代码运行前写入的；现在日志会记录每次调用打印的内容。0.14.0 中新增的输出捕获功能也可能导致控制台日志记录完全停止：它在注册控制台回调之前先打开自己的输出 sink，如果无法打开该 sink，就不会记录任何内容。现在打开 sink 是可选的；如果打开失败，则会回退为记录命令及其值；如果其他执行过程恢复了 sink，也会将其恢复；Agent 运行也不会再弹出并非由它打开的 sink。日志输出行会添加标记，以便重放、历史记录和笔记本导出跳过这些行。

• 控制台日志现在会捕获输出，而不仅仅是结果（R 0.14.0）。 根据对日志记录请求的后续反馈，日志记录了命令返回的值，因此副作用产生的打印内容都会遗漏：cat()、进度输出，以及函数内部调用的 print()。运行 f() 时，日志中有调用本身，却没有 f() 打印的内容；而当你把自己遇到的错误交给 Agent 时，这些内容正是它需要的上下文。现在标准输出会同时写入日志，并归入产生它的命令之下，且会与此前已捕获的警告、消息和错误并列显示。控制台仍会照常显示所有内容。

• 修复了 Windows 会话存活状态检查（R 0.13.2）。 检查已记录的 R 会话是否仍在运行时，会使用 tools::pskill(pid, signal = 0)。这是 Unix 上的标准用法，但在 Windows 上，pskill 无论 signal 是什么都会调用 TerminateProcess。因此，检查会杀死它正在查询的会话，随后却将其报告为仍在运行，并留下过期的发现文件。因此，启动服务可能会终止另一个 RStudio 会话，并导致 Agent 被路由到已失效的端口。现在会在不发送信号的情况下检查会话是否存活。另外，如果要注册的会话名称已被另一个仍在运行的会话占用，现在会发出警告，而不是静默覆盖其发现文件；此前这会导致 Agent 持有错误的端口和令牌。

• 统一控制台日志记录（R 0.13.0）。 会话日志会记录 Agent 执行的内容，却不会记录你执行的内容，因此如果你想让 Agent 解释你在控制台遇到的错误，就必须让它重新执行一遍工作。在 Logging 下勾选“Also log my own console commands”，你的控制台操作就会写入同一个文件，并标明是谁执行了什么：命令、输出结果，以及任何警告、消息或错误。现在，向 Agent 询问“读取日志的最后 100 行”就足以让它看到会话双方的操作。此功能默认关闭；可在 addin 中切换，或调用 start_console_logging() / stop_console_logging()。

• 修复编辑器工具，并新增应用前审批编辑功能（R 0.12.5 / clauder-mcp 0.14.4）。 此次修复源自两位用户的反馈。modify_code_section 和 insert_text 现在默认保存到磁盘，并报告 saved_to_disk，因此 Agent 不会再误以为文件已写入，而更改实际上仍未保存到缓冲区。限定范围的替换可以改变行数（已取消旧的行数相等约束）。这两个工具都接受用于指定目标文件的 path，会打开并聚焦该文件；如果目标是其他文档，则会拒绝编辑，而不是静默失败。get_active_document 现在会报告路径、文档 ID，以及缓冲区是否与磁盘内容不同，从而避免混淆缓冲区状态和文件状态。新增 suggest_edit 工具：Agent 提出更改后等待用户批准；如果已安装的 rstudioapi 提供 rstudioapi::showEditSuggestion()，则使用该函数，否则会先暂存未保存的编辑，用户可通过保存来接受，或通过撤销来拒绝。

• Reviewer Zero 现在会进行推理，而不只是核对（R 0.12.4）。 在基础审计协议中新增了必需的第 5 轮（内容推理）。确定性工具（reconcile_values、verify_references、check_cross_references、probe_scripts）可以发现数值、引用、交叉引用和代码缺陷，但无法理解含义；稿件即使通过所有这些检查，仍可能有误。第 5 轮是有门槛且权重相等的一轮，包含八项工具无法完成的检查：仪器和来源归属、每项报告的检验是否能根据现有数据计算、引用的每张图或表是否确实包含所声称的证据、对量级的措辞、不同研究之间的一致性、因果关系与普遍性的表述、描述性声明是否有数据支撑，以及补充材料和附录的整合情况（每份补充材料都已引用，且正文中的论断不依赖未引用的补充材料）。在一项针对已知缺陷集的合成稿件开展的受控基准测试中，检测能力从低于原生工具基线的 16.8 / 24 提升到明显高于基线的 21.3 / 24，准确找回了旧的工具主导协议所遗漏的推理缺陷，同时没有增加误报。

• 共享连接身份、协调可见性和过期会话防护（R 0.12.2 / clauder-mcp 0.14.2）。 来自一次由三种角色参与的实地会话的三项修复。（1）共享一个 MCP 连接的角色会互相更改名称，因为 set_agent_name 会更改整个连接的身份。send_message、check_messages 和 wait_for_message 新增了 as_agent 参数，可在单次调用中充当具名角色，并为每个名称设置独立的读取游标。桥接程序现在会强制执行这一模式：除非使用强制选项，否则会拒绝使用不同名称再次调用 set_agent_name；每条发送确认都会回显消息发出时使用的名称；Agent 简介会说明当前身份的来源。（2）协调消息按设计绕过 R，因此 Agent 交流时，控制台和 Agents 面板上什么也看不到。现在，插件会将每个新的协调事件完整回显到控制台（不截断），追加到会话日志，并显示包含最近活动时间的实时协调成员列表。（3）指向已失效 R 会话的桥接程序过去会在写入没有在线 Agent 读取的协调日志时，仍报告“成功”。现在，如果不存在在线会话，协调调用会明确报错；如果连接重新绑定到另一个在线会话，也会发出通知。此外，来自试点 2 的改进：check_cross_references 现在支持以 S 开头的补充材料编号；审计协议也记录了如何对 htest 字段使用 unname()，以及如何按作者和年份匹配引文。

• Agent 身份与跨重启历史记录（R 0.11.0 / clauder-mcp 0.13.0）。 根据一次为期多天、由三个 Agent 参与的会话实地报告构建。新增 set_agent_name 工具：Agent 可设置一次工作名称（例如“Claude-Stasis”），执行历史、消息归属、在线状态和读取游标都会携带该名称。这解决了多个 Agent 或角色共享一个 MCP 连接时被合并为单个随机 ID 的问题。get_session_history 新增 include_past：它会解析磁盘上的先前会话日志文件，因此，对谁运行了什么的审计现在可跨 R 重启保留。协调协议现在将身份验证设为报到的第一步。

• 研究人员工作流版本（R 0.10.0 / clauder-mcp 0.12.0）。 三种收费工具提供的工作流，基于 ClaudeR 已有的机制构建。（1）系统综述筛选：来自不同模型系列的两个独立 AI 筛选员根据你的标准评判每一篇摘要；新增的 screening_report 工具会计算一致率、Cohen's kappa、PRISMA 流程计数和冲突集，让人类只需阅读意见不一致的部分。（2）Grant Panel Mode：grant_panel_prompt(rubric = "nih") 会召集模拟研究评审组，为每项标准安排一名评审员，列出有依据的弱点，并按优先级给出能够提高评分的修改建议。（3）审稿意见回复：reviewer_response_prompt() 会将决定信解析为逐点登记表，重新运行分析，使回复包含实际计算出的数值；在所有意见均得到回复前禁止完成，并通过 export_response_letter() 导出回复信，同时在稿件中添加 Word 批注。

• 协调 v2 + 共识门槛（R 0.9.0 / clauder-mcp 0.11.0）。 多 Agent 看板现在是磁盘上的类型化追加式事件日志，设计依据是实际多小时多 Agent 会话的现场反馈：使用类型化信号而非通过搜索文字来筛选；为每个 Agent 设置独立读取游标（从结构上杜绝共享数据框竞争）；支持回复串接、基于租约的任务认领、用于共享状态的事实存储、自动盖章的在线状态，以及 wait_for_message 工具，该工具会阻塞等待伙伴的事件到达，而不会触碰忙碌的 R 会话。新增共识门槛：调用 propose_plan() 后，每个执行响应都会显示一致同意提示，直到所有 Agent 都逐字运行带有所需句子的 confirm_agreement()。只有这时计划才会标记为已批准。此外还有 referee_prompt(stance = "reviewer2")：一位严苛但公正的 Reviewer 2，会先给出未经预先提示的三句话评读（核心主张是什么，以及强势期刊会不会接收？），再将发现分为致命、必须修复和次要，并标注每项发现涉及的研究。

• Referee Mode v2：可配置的审稿人（R 0.8.0）。 referee_prompt() 现在接受 lenses（运行任意子集）、reviewers_per_lens（2 = 对抗性检察官 + 核验者组合，3 则增加一位逆向阅读者）、model（所有子 Agent 使用的模型档位，例如快速审查用的 "haiku" 或投稿级审查用的 "opus"，也可以指定按 lens 区分的命名向量），以及 cross_vendor = TRUE，通过 codex/agy/qwen 单次调用将逻辑／方法审稿人分派到其他模型供应商。协议现在强制要求遵循防止评审趋同的规则：每个 lens 和立场的审稿提示词都必须从头撰写，一致性 lens 要从后往前阅读，每项发现都必须附带独立审稿人之间的佐证数量。

• Referee Mode（R 0.7.0 / clauder-mcp 0.10.0）。 付费服务每轮收费约 $50 的实质性论文审查，现在可以用你已有的订阅免费运行，并以最合适的形式交付：作为 Word 批注写入论文。reviewer_zero_prompt(referee = TRUE)（或独立的 referee_prompt()）会运行五个仅审查内容的评审 lens（论证逻辑、方法、内部一致性、证据呈现、框定），在 CLI 支持时将其作为并行子 Agent 运行。每项发现都必须以逐字引文为依据，并在通过独立核验后才能写入文档；严重程度必须如实标注；对于质量过硬的论文，给出没有问题的报告也是有效结果。与此同时，新增的 check_cross_references 工具可确定性地捕捉悬空引用（例如“见表 4”，但表 4 已不存在），以及正文从未提及的表格或图表。

• 价值优先审计（R 0.6.0 / clauder-mcp 0.9.0）。 基于完整审计论文及其补充材料后的现场反馈构建。read_file 现在会透明地提取 .docx/.pdf（之前会返回原始字节），提取器还会保留结构：标记标题，并按行输出表格单元格，单元格之间用分隔符隔开（之前会被全部丢弃）。新增 reconcile_values 工具：枚举论文中的每个数字，并逐一与代码生成的数据集核对，同时考虑显示精度（5038.5 与 5038.46 匹配）、逗号、百分比、科学记数法和 < .001 阈值。按值建立的 values_registry 将数值完整性变成构建流程的一部分，而非寄望于审慎检查。Reviewer Zero 现在会设置适合审计的打印选项（不再出现 tibble 三位有效数字引发的误报）、以数值全面核查作为门槛，并通过 probe_scripts(capture_output = TRUE) 从干净环境的运行结果中得出最终结论。CrossRef 查询现在会采用退避重试，不再因 429 错误而静默截断参考文献核查。

• 研究者工具包发布（R 0.5.0 / clauder-mcp 0.8.0）。 新增五项功能，助力论文顺利发表。（1）Reviewer Zero 写回：reviewer_zero_prompt(writeback = TRUE) 会通过新的 annotate_manuscript()，将每项被标记的主张作为原生 Word 评论写入论文副本。（2）引用升级：verify_references 现在会通过 Crossref 更新通知标记撤稿或更正的论文，解析 arXiv ID（并检查是否引用了已发表版本），还会对没有 DOI 的参考文献进行书目匹配。新增的 search_citations（OpenAlex）和 get_bibtex（doi.org）工具，让 Agent 可以查找引用，而非凭空编造。（3）generate_notebook：将会话日志转换为带有叙述说明的 Quarto 实验记录，渲染时会重新运行分析。（4）generate_codebook：一次调用即可生成变量级代码本，以及 OSF 和期刊要求的包、脚本和输出清单。（5）所有功能均已接入 CI。

• 会话检查点（R 0.4.0 / clauder-mcp 0.7.0）。 新增三种 MCP 工具：checkpoint_session 将 R 全局环境快照保存到磁盘，restore_session 将其回滚（会先保存当前状态，因此可以撤销恢复操作），list_checkpoints 则显示可用的检查点。系统会提示 Agent 在执行高风险操作前创建检查点。用户始终可以通过控制台运行 ClaudeR::restore_session() 来恢复。

• Reviewer Zero：预注册审计与稳健性检验。 reviewer_zero_prompt(prereg_path = ...) 会追加 Pass 5，将已执行的分析与预注册计划进行审计，并生成完整的偏差报告。reviewer_zero_prompt(robustness = TRUE) 会追加 Pass 6，对主要主张运行规格曲线分析：合理的替代规格会通过后台作业展开计算，最终生成敏感性表和规格曲线。

• 深度审计版本（R 0.3.1 / clauder-mcp 0.6.2）。 修复了加载项、桥接程序和 Lab Mode 中的 20 多个错误：重新打开的加载项 UI 现在会与运行中的服务共享实时状态（关闭并重新打开 UI 后，设置开关仍能正常使用）；绘图捕获现在会识别图形设备（png(); plot(); dev.off() 不会再重复发送过期的屏幕图像）；modify_code_section 不会再破坏包含反斜杠的替换内容；异步作业结果具有幂等性，即使桥接程序超时也能保留；错误响应会包含出错前打印的所有内容；一个 Agent 的长时间计算不会再让其他 Agent 误以为加载项已关闭；Lab Mode 的第 2 轮及后续重新验证门禁现在会正常触发。会话令牌现在通过操作系统熵生成。日志记录默认开启。CI（GitHub Actions）现在会在每次推送时执行检查：R 功能检查，以及针对已构建桥接程序的真实 MCP stdio 握手。

• 将 mcp SDK 固定为 1.x。 MCP 2026-07-28 规范版本发布时，将 mcp 2.0.0 发布到了 PyPI，而该版本移除了桥接程序所依赖的服务端 API。clauder-mcp >= 0.6.1 会固定使用 mcp<2。如果桥接程序无法运行，请执行 uvx --refresh clauder-mcp。计划进行 SDK 2.0 迁移（并支持新的异步工具 Tasks 扩展）。

• AI 驱动的数据标注。 新增两种 MCP 工具（load_annotation_data、annotate），让 Agent 无须编写代码即可逐行标注 CSV 数据集。在 _schema 列中定义标注字段，调用 data_annotation_prompt() 获取标注协议，之后由 Agent 完成其余工作。原始文件不会被修改；如果任务中断，会话会自动恢复。

• 多 Agent 协作协议。 内置协议，支持多个 Agent 共用一个 RStudio 会话。Agent 通过 R 环境中的共享消息板协商，达成任务计划，开始工作前认领任务，并交叉检查彼此的输出。使用 multi_agent_prompt() 加载。

• verify_references 工具。 从论文参考文献中提取 DOI，逐一查询 CrossRef API，并返回元数据（标题、作者、年份、期刊），以便与论文中的主张进行比对。无法解析的 DOI、元数据不匹配以及没有 DOI 的参考文献都会被标记。既可独立使用（“检查我的参考文献”），也可作为 Reviewer Zero 的 Pass 4。

• R 最佳实践协议。 内置统计分析协议，涵盖探索性数据分析、假设检验、模型构建、诊断、多重校正和报告。使用 r_best_practices_prompt() 加载，或让 Agent 阅读该协议。

• Reviewer Zero：自动化学术审计。 现已成为用于 AI 驱动论文核验的四阶段协议。Agent 会提取每项统计和方法学主张，核实提取结果，根据作者的 R 代码重新计算数值，并通过 CrossRef 检查参考文献。方法学主张（例如“零方差导致无法进行检验”）会直接接受检验，而不会被轻信。运行 reviewer_zero_prompt() 获取完整协议。

• clean_error_log 工具。 将会话日志交给 Agent，它会解析每个代码块、查找错误、检查错误后是否进行了修复，然后删除错误代码块以及它们前面重复的代码。结果是只包含可运行代码的干净日志。可选传入 output_path，将结果写入单独文件，而不覆盖原文件。

• UI 重启后服务仍会运行。 关闭 Shiny 加载项（通过控制台停止或点击 Done 按钮）不再会终止 MCP 服务。再次运行 claudeAddin() 会使用正确的端口、会话名称和执行次数，重新连接到仍在运行的服务。只有在 UI 中点击“Stop Server”才会真正停止服务。

• 描述性日志文件名。 日志文件现在包含会话名称、端口和时间戳：clauder_default_8787_20260301_143022.R。每次点击 Start Server 都会创建新的日志文件，此后所有代码执行内容都会追加到该文件。

• Viewer 内容捕获与 insert_text 工具。 新增两种工具：get_viewer_content 可分页读取交互式组件（plotly、DT、leaflet）的 HTML，让 Agent 无须让上下文溢出即可检查 htmlwidget 输出；insert_text 可在光标位置或活动文档的指定行列插入文本。Agent 执行期间，htmlwidget 会在浏览器中打开，而不会占用 Shiny 加载项的 Viewer 面板。

• 多会话路由修复。 存在多个活动会话时，Agent 现在会优先选择名为“default”的会话，避免因发现顺序不确定而路由错误。绑定会话后，Agent 会持续使用该会话。非默认 Agent 应调用 connect_session 来指定目标会话。

• 日志中的可复现性元数据。 启用日志记录后，每个新会话日志都会以标题开头，其中包含日期、工作目录和完整的 sessionInfo() 输出（R 版本、平台、已加载的包）。任何收到该日志的人都能准确了解代码运行所处的环境。

• 导出干净脚本。 在 Shiny 加载项中点击“Export Clean Script”，即可从会话日志中删除所有时间戳、Agent 标签和日志标题，生成仅含代码且可运行的 .R 文件。错误代码块会保留为注释。也可通过 export_log_as_script() 以编程方式使用。

• PyPI 包（clauder-mcp）。 Python MCP 桥接程序现已作为独立包发布到 PyPI。运行 uvx clauder-mcp 即可免配置启动，无须设置 Python 路径或安装 pip。安装器（install_cli() 和 install_clauder()）默认使用 uvx，同时提供 use_uvx = FALSE 选项以兼容旧版设置。

• read_file 工具。 Agent 现在可以从磁盘读取任意文本文件（.R、.qmd、.csv、.log 等），无须在 RStudio 中打开文件。此功能支持会话延续工作流：将之前的日志文件交给 Agent，并让它从上次会话中断处继续。

• 支持 Codex CLI。 install_cli(tools = "codex") 会生成 OpenAI Codex 的设置命令。Codex 与 Claude Code 和 Gemini 一同成为受支持的 CLI Agent。

• 多 Agent 编排。 多个 AI Agent 可在同一个 R 会话中运行，也可分布在不同的 RStudio 窗口中。每个 Agent 启动时都会获得唯一 ID。控制台输出、日志文件和执行历史均会按 Agent 标记，让你随时知道谁执行了什么。每个 Agent 在首次调用工具时都会收到上下文简报，其中包含其自身 ID、当前会话中的其他活动 Agent，以及日志文件路径，让它无需任何手动设置即可全面了解共享环境。Agent 可以调用 get_session_history 查看其他 Agent 的操作，也可以直接读取共享日志文件。Shiny Viewer 会实时显示已连接的 Agent。

• 会话发现。 每个 RStudio 会话启动时都会在 ~/.claude_r_sessions/ 中写入发现文件。AI Agent 无须硬编码端口即可自动查找会话。为会话命名（例如“analysis”“modeling”），并在不同端口上运行。存在多个会话时，Agent 会自动连接到名为“default”的会话。非默认 Agent 应调用 connect_session 绑定到目标会话。单会话设置完全无须配置。

• 重新设计的 Shiny Viewer。 UI 更简洁，并按会话、Agent、日志记录和高级设置分组显示面板。实时显示已连接的 Agent 和执行次数。点击 ? 按钮可查看内置指南，了解多会话设置和 Agent 身份。

• 非阻塞式异步执行。 execute_r_async 现在通过 callr 在独立的 R 进程中运行长时间代码，让主会话始终保持响应。作业运行期间，其他 Agent 可以继续工作。Agent 编写自包含代码（明确地使用 saveRDS 保存和加载数据），提交代码，然后使用 get_async_result 获取结果。此方式不会复制环境，也不会使内存占用翻倍；只会序列化作业所需的数据。

• 过期绘图检测。 修复了最后生成的绘图图像会持续保留，并在后续每次调用 execute_r 时重新出现（即使没有新绘图）的错误。

• 降低绘图的 token 用量。 绘图捕获现在使用更小的尺寸（600x400，dpi 100），以减小 base64 图像大小并避免 token 溢出错误。

• MCP 工具注解。 根据当前 MCP 规范，所有工具现在都包含 readOnlyHint、destructiveHint 和 idempotentHint 注解。

• 加强字符串转义。 escape_r_string 现在可以处理反引号、回车符、制表符和空字节。已将其应用于任务工具输入，以防止注入攻击。

• 修复 install_cli() 命令语法。 已更新为在当前 Claude Code CLI 中使用 --transport stdio 标志和 -- 分隔符。现在会在添加新的 MCP 注册项之前移除过期项，避免升级 R 版本时出现问题。

目录

• 快速入门
• 功能
• Python 会话和 Positron
• 工作原理
• Reviewer Zero
• R 最佳实践协议
• 多 Agent 协作协议
• AI 驱动的数据标注
• 系统综述筛选
• 资助评审模式
• 回复审稿人
• CLI 集成
• 安全模型
• 安装
• 用法
• 日志选项
• 交互示例
• 重要说明
• 故障排除
• 限制
• 许可证
• 贡献

功能

ClaudeR 为 AI 助手提供了一套工具，可与 R 环境交互：

• execute_r：执行 R 代码并返回输出。

• execute_r_with_plot：执行可生成模型能看到的图表的 R 代码。

• execute_r_async：异步执行长时间运行的 R 代码（>25 秒）。返回用于轮询的作业 ID。

• get_async_result：等待异步作业，并在其完成时立即返回结果（最长等待 wait_s 秒，默认值为 300）。wait_s = 0 仅检查状态。

• list_sessions：列出 Agent 可连接的所有活动 RStudio 会话。

• connect_session：按名称连接到特定的 RStudio 会话，以支持多会话工作流。

• get_session_history：查看按 Agent ID 筛选的执行历史记录。

• read_file：读取磁盘上的任意文件（.R、.qmd、.csv、.log 等），无需在 RStudio 中打开。文稿会自动处理：.docx 和 .pdf 会提取为结构化文本，并标注标题、分隔表格单元格。支持通过 start_line/end_line 对大型文件进行分页。

• check_cross_references：确定性地检查内部引用完整性：标记悬空提及（例如，出现“参见表 4”，但没有表 4），以及正文中从未引用的表格/图。

• annotate_manuscript（R 函数，由审计协议使用）：将审计结果写入 .docx 副本，作为原生锚定 Word 评论，作者可在 Word 中接受或驳回。

• reconcile_values：审计的核心工具。提取文稿中的每个数值，并逐一与代码实际生成的数字（日志、输出、表格）核对，同时考虑显示精度、逗号、百分比、科学计数法和 < .001 阈值。返回逐值登记表，确保不会悄然漏掉任何数值。

• get_active_document：读取当前聚焦的编辑器缓冲区。返回内容、文件路径，以及缓冲区是否有未保存的更改，从而避免混淆缓冲区状态和磁盘状态。

• get_r_info：获取有关 R 环境的信息。

• modify_code_section：在编辑器文档中使用正则表达式查找并替换。支持多行模式，允许替换内容更改行数，保留字面反斜杠，默认保存到磁盘，并接受用于指定目标文件的 path。

• insert_text：在光标处或指定的行/列插入文本。默认保存到磁盘；接受用于指定目标文件的 path。

• suggest_edit：提出编辑建议，供用户批准，而非直接应用。若可用，则使用 rstudioapi::showEditSuggestion()；否则，会在编辑器中暂存未保存的更改，用户可通过保存接受，或通过撤销拒绝。

• get_viewer_content：读取查看器窗格中的 HTML 内容（plotly、DT、leaflet 小部件），并支持分页。

• clean_error_log：清理会话日志，删除错误代码块及其重复的前置版本，仅保留可运行代码和随后进行的修复。

• search_project_code：在项目源文件（.R、.Rmd、.qmd）中搜索正则表达式模式。返回文件、行号和代码片段。

• probe_scripts：在干净的后台会话中加载 R 脚本，并报告创建的对象（名称、类、维度），且不影响主会话。

• verify_references：核验学术参考文献：通过 CrossRef 检查 DOI（并依据 Crossref 更新通知标记撤稿/更正），解析 arXiv ID 并检查是否存在已发表版本；对于没有 DOI 的条目，则进行书目匹配并提供候选 DOI。

• search_citations：在 OpenAlex 学术索引中搜索适用于某项主张的正确参考文献（标题、作者、年份、出版物、DOI、引用次数），而不是凭记忆引用。

• get_bibtex：通过 doi.org 内容协商获取 DOI 对应的规范 BibTeX 条目。

• generate_notebook：将会话日志转换为带有说明文字的 Quarto 实验室笔记本。渲染时会重新运行代码，以重新生成输出和图表。

• generate_codebook：扫描项目并生成 OSF 和期刊要求的代码簿：带版本信息的软件包列表、脚本清单、逐变量摘要（类、n、缺失情况）以及生成的输出。

• screening_report：汇总系统综述的筛选轮次。计算两名模型筛选员之间的一致率和 Cohen's kappa、PRISMA 流程计数，以及需要人工裁定的冲突项。

• send_message / check_messages / wait_for_message / coordination_roster：在仅追加的共享日志中进行类型化多 Agent 消息传递。wait_for_message 会阻塞，直至收到匹配事件（无需轮询即可会合）；即使 R 会话正忙于执行另一个 Agent 的代码，所有功能仍可正常使用。

• checkpoint_session：在执行高风险操作前，将 R 全局环境快照保存到磁盘。即使 R 重启，检查点仍会保留。

• restore_session：将环境回滚到某个检查点。会先保存当前状态，因此恢复操作本身也可以撤销。需要自行恢复 Agent 的错误时，也可在控制台中调用（ClaudeR::restore_session()）。

• list_checkpoints：列出当前会话的已保存检查点。

• create_task_list：根据提示词生成任务列表，避免长上下文任务遗漏事项。

• update_task_status：跟踪生成列表中每项任务的进度。 借助这些工具，你可以：

• 直接执行代码：AI 可以在你当前的 RStudio 会话中编写、执行代码并安装软件包。

• 反馈与协助：获取 R 脚本的说明，或请求修改特定行。

• 可视化：AI 可以生成、查看并优化图表和可视化内容。

• 数据分析：让 AI 分析你的数据集，并逐步提供见解。

• 多 Agent 工作流：同时在同一个 R 会话中运行 Claude Desktop、Claude Code 和 Gemini CLI。每个 Agent 都有唯一标识，并且可以通过共享历史记录和日志文件查看彼此的工作。

• 长时间运行的分析：异步执行可处理模型拟合、模拟和大型数据处理，不会超时。

• 代码记录：将 AI 执行的所有代码保存到日志文件中，以供日后参考。每条记录都会标注执行该代码的 Agent。

• 控制台打印：在执行前将 AI 的代码打印到控制台。

• 环境集成：AI 可以访问你 R 环境中的变量和函数。

• 动态摘要：摘要可以动态提取对象和数据框中的结果，以避免产生幻觉。

• Quarto 渲染：AI 可以创建并渲染 Quarto 演示文稿。为获得最佳效果，请要求生成 .qmd 文件，并在完成后将其渲染为 HTML。

• Reviewer Zero：用于自动化学术审查的内置协议。AI 会逐块阅读手稿，将每项统计结论提取到登记表中，核实提取结果，然后根据作者的 R 代码重新计算每项结论。运行 reviewer_zero_prompt() 查看完整协议。请参阅下文的 Reviewer Zero 部分。

Reviewer Zero：自动化学术审查

ClaudeR 内置了一套协议，用于对学术论文进行 AI 驱动的技术审查。AI 充当“Reviewer Zero”：系统地核验论文中的每个 p 值、系数和置信区间是否与生成它们的代码相符。

工作原理（核心协议）：

1. 提取：AI 使用分页的 read_file，逐块读取论文（提取 .docx 和 .pdf 时会保留结构，包括表格单元格），将所有定量和方法学主张提取到结构化登记表中（一个显示在 RStudio Environment 窗格中的 data.frame）。首先设置审计专用的打印选项，因此控制台输出绝不会截断正在核验的精度。
2. 核验：AI 重新读取每项主张对应的源代码行，确认没有误读数值。在所有主张都核验完毕之前，不会运行任何代码。
3. 对账与重新计算：核心是数值扫描：reconcile_values 会枚举论文和补充材料中的每一个数值，并按照文档显示的精度，将其与代码实际生成的数值全集逐一对账。每个未匹配的数值都必须重新计算或作出解释，审计才能继续：通过设计确保完整性，而非依赖认真程度。随后，针对具体主张的重新计算会基于干净环境中的脚本输出运行（probe_scripts 并捕获输出），因此会话中的过时对象绝不会造成检查结果虚假一致。方法学主张（例如“零方差使检验无法进行”）会直接接受检验，而不是照单全收。
4. 参考文献：verify_references 会通过 CrossRef 检查每个 DOI，并标记元数据不匹配、无法解析的 DOI，以及已撤稿或已更正的论文。arXiv 预印本会被解析，并与已发表版本进行匹配。没有 DOI 的参考文献会进行书目信息匹配。文内引文会与参考文献表交叉核对。

可选扩展，可通过参数组合使用（示例如下）：预注册偏离审计（prereg_path）、规格曲线稳健性检查（robustness）、将每项发现写回为 Word 批注（writeback），以及 Referee Mode（referee，或单独使用 referee_prompt()），对推理本身进行实质性审查：论证逻辑、方法、内部一致性、证据呈现和表述框架。审查由并行审稿子 Agent 执行，可配置模型层级、对抗立场和跨厂商调度，并通过确定性的 check_cross_references 检查流程完成核验，最终以锚定的 Word 批注交付。

开始使用：

# Print the full protocol prompt to give to your AI agent
reviewer_zero_prompt()

# Optional Pass 5: audit the analysis against your preregistration.
# Produces a deviation report (followed / disclosed deviation /
# undisclosed deviation / not executed) plus a list of exploratory
# analyses that are not labelled as such.
reviewer_zero_prompt(prereg_path = "prereg.docx")

# Optional Pass 6: specification-curve robustness check. The agent
# enumerates defensible alternative analysis choices for the primary
# claims, runs the grid in background jobs, and reports a sensitivity
# table plus a specification curve.
reviewer_zero_prompt(robustness = TRUE)

# Optional write-back: every flagged claim becomes a native Word comment
# in a copy of the manuscript, so you can accept/dismiss findings in Word.
reviewer_zero_prompt(writeback = TRUE)

# All extensions together
reviewer_zero_prompt(prereg_path = "prereg.docx", robustness = TRUE, writeback = TRUE)

# Referee Mode, configured. Quick-and-dirty pass on a fast model tier:
referee_prompt(model = "haiku")

# Submission-grade: strongest tier, adversarial reviewer pairs per lens
# (prosecutor + verifier), and lenses dispatched across model vendors
# (codex/agy/qwen) so same-model blind spots can't hide the same flaw twice:
referee_prompt(model = "opus", reviewers_per_lens = 2, cross_vendor = TRUE)

# Mix tiers per lens: deep model where the reasoning is hard, fast elsewhere
referee_prompt(model = c(logic = "opus", methods = "opus", consistency = "haiku"))

此协议适用于 .docx、.pdf、.qmd、.Rmd、.tex 或纯文本论文，并支持包含多个脚本的 R 项目。

R 最佳实践协议

ClaudeR 内置了一套统计分析协议，其灵感来自我在统计课程中学到的建模工作流，以及我在实际统计工作中使用 AI Agent 时从失误中总结出的经验。其目标是通过自然语言引导模型开展可复现、由理论驱动的分析，涵盖 EDA、假设检查、模型构建、诊断、多重校正和报告撰写。

# Print the full protocol to give to your AI agent
r_best_practices_prompt()

你也可以直接让 Agent 运行 ClaudeR::r_best_practices_prompt()，它就会自行读取该协议。

多 Agent 协调协议

当两个或更多 Agent 共用同一个 RStudio 会话时，需要一种划分工作的方式，以免互相干扰。协调 v2 基于磁盘上的类型化、仅追加事件日志运行，由 R 会话和每个 Agent 的桥接程序共享：使用类型化信号，而非约定俗成的文字；每个 Agent 都有自己的读取游标（因此没有 Agent 能覆盖其他 Agent 的状态）；通过 to: 定向发送消息并串联回复；基于租约认领任务；使用最新值优先的事实存储共享状态；每次写入都会更新在线状态；还提供 wait_for_message，让 Agent 等待合作方的信号，而不是反复轮询。R 重启后，日志仍会保留。

核心功能是共识门控：当 Agent 使用 propose_plan() 提出计划后，会话中的每个代码执行响应都会显示横幅，要求明确达成一致，直到每个 Agent 都使用规定的原文句子运行 confirm_agreement()。Agent 无法各说各话、各自开展冲突的工作：只有在所有参与方都确认已阅读彼此的立场并达成一致后，计划才会标记为已批准。

# Print the full protocol to give to your AI agents
multi_agent_prompt()

你也可以直接让 Agent 运行 ClaudeR::multi_agent_prompt()，它们便会自行阅读协议。

AI 驱动的数据标注

ClaudeR 提供专用标注工作流，可使用 AI Agent 为 CSV 数据集添加标签。Agent 使用两个专用 MCP 工具逐行处理数据集，无需编写代码。

**CSV 格式：**在文件中添加 _schema 列，并在第一行使用简单的类型语法定义标注字段：

text,label,confidence,_schema
"Some text","","","label:choice[positive,negative,neutral];confidence:float[0,1]"
"More text","","",""

支持的类型：choice[a,b,c]、float[min,max]、int[min,max]、bool、text

运行标注会话：

# Print the full protocol to give to your agent
data_annotation_prompt()

或者让 Agent 运行 ClaudeR::data_annotation_prompt()，它便会自行阅读协议。随后，Agent 调用 load_annotation_data 开始标注，再调用 annotate 为每一行添加标签。原始文件不会被修改；如果会话中断，还可以自动恢复。

系统综述筛选

标题和摘要筛选是系统综述中最耗时的环节。通常需要两位人工阅读每条记录。ClaudeR 通过两位独立的 AI 筛选员替代大部分阅读工作，只将有分歧的记录留给人工处理。

工作流：将去重后的数据库检索结果导出为 CSV，在 _schema 列中添加纳入和排除标准，并使用两个不同的模型系列（例如 Claude 和免费的本地 ollama 模型）分别运行两次 run_annotation_job。然后：

# Agreement, Cohen's kappa, PRISMA counts, and the conflict set
screening_report("pass_claude_annotating.csv", "pass_qwen_annotating.csv")

报告会提供一致率、两位筛选员之间的 Cohen's kappa、PRISMA 流程图数据，以及一个 screening_conflicts 数据框，其中只包含两个模型意见不一致的记录。你可以对这些记录作出裁定，通常只占总数的一小部分。每项决定都会附带理由，因此只需使用一个筛选条件，审计记录就能回答“为什么排除这条记录”。使用 screening_prompt() 打印完整协议。

资助评审小组模式

在真正的评审小组召开会议前，先为你的资助申请模拟一次评审。每项标准由一位评审子 Agent 负责，给出客观评分，并为每项弱点附上申请书中的原文引述。

grant_panel_prompt(rubric = "nih")   # Significance, Investigators, Innovation,
                                     # Approach, Environment, scored 1 to 9
grant_panel_prompt(rubric = "nsf")   # Intellectual Merit and Broader Impacts

主席的综合意见最后会给出最关键的内容：一份按优先级排序的具体修改清单，说明哪些修改能提高分数，并将每项修改表述为你本周就能完成的任务。评审结果还可以写入申请书副本，作为 Word 批注。

给审稿人的回复

将修订并重新提交的工作流压缩到极致。将决定信和稿件交给 Agent，然后运行 reviewer_response_prompt()。Agent 会将信件解析为各条审稿意见，在稿件中定位每条意见，并起草逐条回复。若审稿人询问数据，Agent 会在当前会话中重新运行分析，因此回复中包含实际计算出的数字，而非凭记忆给出的数字。只有在每条意见都已起草回复后，流程才会允许完成。

交付内容：通过 export_response_letter() 生成格式化的回复信（Markdown；安装了 pandoc 时还会生成 .docx），以及在稿件中需要修改的位置添加 Word 注释，并标记所回应的审稿意见。

Python 会话和 Positron

ClaudeR 还可以将 Agent 连接到实时的 Python 会话，并且这两部分在 Positron 和 RStudio 中都能使用。

import clauder
clauder.start()

随后，Agent 会在该会话中执行代码，其中已加载你的数据框和拟合模型，并能看到它生成的图表。可在 Positron、Jupyter、VS Code 或纯 REPL 中运行。会话的声明方式与 R 会话相同，因此 list_sessions 会同时显示两者，Agent 可按名称连接任一会话：

Active sessions (2):
  analysis [python] — port 8790, pid 8088, started 2026-09-09T10:50:09
  modelling [r] — port 8787, pid 84615, started 2026-09-09T09:12:44

每个会话启动一次即可，与在 R 中运行 claudeAddin() 相同。如果端口正忙，它会改用下一个空闲端口，并告知你使用了哪个端口。

如果不想每次都输入，可以通过 IPython 启动文件运行：

# ~/.ipython/profile_default/startup/50-clauder.py
import clauder
clauder.start(quiet=True)

这样，每次启动 Python 会话时都会打开一个服务，包括你并不打算向 Agent 开放的会话。因此该功能默认关闭，启用前值得仔细考虑。

各环境中的功能

Python 会话可以访问实时环境，但无法访问编辑器或审计工具，因为这些功能通过 rstudioapi 驱动 IDE，而 Python 没有对应接口。

	R	Python
在实时会话中执行代码	是	是
将图表返回给 Agent 并显示在绘图窗格中	是	是
记录每行已执行代码的 Agent 日志	是	是
多 Agent 协作和共识门控	是	是
读取和编辑已打开的编辑器缓冲区	是	否
应用前先批准编辑（suggest_edit）	是	否
检查点和回滚环境	是	否
Reviewer Zero 和审计工具	是	否

因此，“加载此文件、拟合模型、绘制残差图”在 Python 中可行。“查看我打开的文件并修复该函数”则仅适用于 R。Agent 仍可使用自己的文件工具读写这些文件，只是无法通过你的编辑器缓冲区操作。

Positron 说明

在 Positron 中使用 R 无需特别设置。Positron 自带 rstudioapi 兼容层，因此编辑器工具可在其中使用，但有一点不同：suggest_edit 会暂存未保存的更改，而不是调用 Positron 尚未实现的 showEditSuggestion()。保存即可接受，撤销即可拒绝。

工作原理

ClaudeR 使用 模型上下文协议（MCP），在 AI 助手与 RStudio 环境之间建立双向连接。MCP 是 Anthropic 推出的开放协议，可让 AI 安全地与本地工具和数据交互。

工作流如下：

1. Python MCP 服务充当桥梁。
2. AI 向 MCP 服务发送代码执行请求。
3. 服务将请求转发给运行在 RStudio 中的 R 插件。
4. 代码在你的 R 会话中执行，结果随后返回给 AI。

这种架构确保 AI 只能通过定义明确的接口执行经批准的操作，让你始终完全掌控自己的 R 环境。

CLI 集成

ClaudeR 支持命令行界面（CLI）Agent：Claude Code CLI、OpenAI Codex CLI、Qwen Code CLI 和 Google Antigravity CLI（agy）。Google Gemini CLI 已于 2026 年 6 月 18 日停止服务；agy 已取而代之，而 install_cli(tools = "gemini") 仍然保留，供使用旧版固定版本的用户使用。对于偏好基于终端的工作流的开发者来说，这种方式非常理想：既可以直接从命令行与 AI 助手交互，又能与 RStudio 会话保持实时连接。

安全模型

ClaudeR 是一种受监督的强大工具。Agent 会在你正在使用的 RStudio 会话中执行 R 代码，你的数据和变量也都位于同一会话中。你应当检查它所做的操作，就像运行同事的代码之前会先进行检查一样。

服务端身份验证

绑定到 127.0.0.1 并不构成安全边界。你机器上的任何其他进程都能向该端口发送代码；你访问的任何网页也能通过浏览器无需 CORS 预检即可发送的跨域 POST 请求做到这一点。两者都能在你的 R 会话中执行任意代码。ClaudeR 有两种防护措施：

• 来源拦截（始终启用）。 任何带有 Origin 标头的请求都会被拒绝，并返回 403。只有浏览器会设置 Origin，而 MCP 桥接程序不会，因此无需配置，也不会影响兼容性，就能阻止恶意网页发起的攻击。
• 会话令牌（选择启用）。 点击 Start Server 时，ClaudeR 会生成一个随机令牌，并将其写入发现文件（模式为 0600，只有你能读取）。桥接程序会读取该令牌，并通过 X-Clauder-Token 将其回传。在 Advanced 下勾选 Require auth token，即可拒绝所有缺少该令牌的请求。这样也能阻止本地进程发起的攻击。

令牌默认关闭，因为启用后会拒绝所有版本低于 clauder-mcp 0.6.0 的桥接程序，这会导致现有安装升级后无法工作。要启用它：

uvx --refresh clauder-mcp    # get a bridge that sends the token

然后在插件的 Advanced 面板中勾选 Require auth token，并重启服务端。在此之前，每当无令牌的桥接程序连接时，插件都会在控制台打印一次性提示。

防护措施（并非沙箱）

validate_code_security() 会拒绝明显危险的操作：system()、system2()、shell()、rstudioapi::terminal，以及递归删除或通配符删除。请把这当作安全带，而不是沙箱。它只是一个正则表达式阻止列表，设计上很容易绕过（例如 get("system")(...)、do.call、eval(parse(...)) 等）。它的作用是捕获粗心生成的代码，而非阻止蓄意为之的 Agent。Agent 的任务就是运行任意 R 代码，因此不可能有一种万无一失的防护方式。

ClaudeR 不会限制的操作

Agent 可以读取你有权读取的任何文件、安装软件包、覆盖环境中的对象、发起网络请求，以及消耗计算资源。这些都是让它发挥作用所必需的。因此：

• 使用日志记录（默认启用），完整记录执行的每一行代码以及运行代码的 Agent。
• 在项目目录中工作，以限制 Agent 默认可见的内容。
• 信任前先检查：尤其是在 Reviewer Zero 审核中，应将输出视为需要你核验的草稿。

提示词注入：审查他人手稿前请先阅读

ClaudeR 特意结合了三项功能：能够执行任意 R 代码的 Agent、会引入不可信第三方内容的工具（read_file、get_viewer_content、verify_references、load_annotation_data），以及能够写入文件并访问网络的 R 会话。

这意味着，他人编写的手稿、CSV 或 HTML 小组件都是可能导致代码执行的不可信输入。Reviewer Zero 的整个前提（让 Agent 查看一篇并非由你撰写的论文）正是具有风险的情形。包含针对模型而非读者的文本的文档，可能会改变 Agent 的行为。

没有任何过滤器能解决这个问题，因为运行代码本身就是该功能。缓解风险的方法是：对待处理第三方文档的 Agent 会话，就像对待运行陌生人的脚本一样：在项目目录中操作，保持日志记录开启，阅读日志，并且不要把凭据留在工作目录或环境中。

限制仅适用于 AI 执行的代码。你手动执行的 R 代码不受影响。

安装

第 1 步：从 GitHub 安装 ClaudeR

在 RStudio 控制台中运行此命令：

if (!require("devtools")) install.packages("devtools")
devtools::install_github("IMNMV/ClaudeR")

第 2 步：运行正确的安装程序

选择与你的工作流相匹配的选项。

选项 A：适用于桌面应用（Claude Desktop / Cursor）

此函数会自动为桌面应用配置 MCP 配置文件。默认情况下，它使用 uvx 运行 clauder-mcp PyPI 包，并自动处理所有 Python 依赖项。

# Load the package
library(ClaudeR)

# Run the installer for Claude Desktop
install_clauder()

# Optional: For Cursor users
# install_clauder(for_cursor = TRUE)

无法使用 uvx 的用户（例如，受限环境中的用户）可改用旧版 Python 路径方法：

library(ClaudeR)
install_clauder(use_uvx = FALSE, python_path = "/path/to/your/python")

选项 B：适用于 CLI 工具（Claude Code / Codex / Gemini）

此非交互式函数会生成 CLI 工具所需的准确命令或 JSON 配置。

library(ClaudeR)

# For Claude Code CLI
install_cli(tools = "claude")

# For OpenAI Codex CLI
install_cli(tools = "codex")

# For Qwen Code CLI
install_cli(tools = "qwen")

# For Google Antigravity CLI (agy, Gemini CLI's replacement)
install_cli(tools = "agy")

# For Google Gemini CLI (legacy, shuts down June 18, 2026)
install_cli(tools = "gemini")

无法使用 uvx 的用户可改用旧版 Python 路径方法：

install_cli(tools = "claude", use_uvx = FALSE, python_path = "/path/to/my/python")

运行该函数后，你必须手动应用配置：

• 对于 Claude / Codex / Qwen：复制 R 控制台中打印的命令，并在终端中运行。
• 对于 Antigravity（agy）：将生成的 JSON 复制到 ~/.gemini/config/mcp_config.json（全局）或 .agents/mcp_config.json（每个工作区）。
• 对于 Gemini（旧版）：复制生成的 JSON，并手动将其添加到 ~/.gemini/settings.json 文件中。

完成设置后，退出并重启所有正在运行的桌面应用或终端会话，以加载新设置。

注意：如果升级了 R 版本，请重新运行 install_cli() 或 install_clauder()，以更新 MCP 服务路径。CLI 安装程序会在添加新注册项前自动移除过时的注册项。

使用方法

第 1 部分：在 RStudio 中

对于所有工作流，你都必须先从 RStudio 启动 ClaudeR 服务。

library(ClaudeR)
claudeAddin()

ClaudeR 插件会显示在 RStudio 的 Viewer 窗格中。点击**“Start Server”**。使用你选择的工具期间，请保持此窗口处于活动状态。

第 2 部分：在 AI 工具中

• 对于桌面应用：打开 Claude Desktop App 或 Cursor，然后开始会话。
• 对于 CLI 工具：打开终端并使用 claude 或 gemini 命令，开始与 AI 助手交互。

注意：点击 RStudio 控制台中的停止按钮，即可重新获得对控制台／当前文档的控制权。这会关闭 Shiny UI，但 MCP 服务会继续在后台运行，AI Agent 仍保持连接。重新运行 claudeAddin()，即可在 Viewer 窗格中恢复界面，并保留相同的服务状态（端口、会话名称、执行次数）。若要完全停止服务，请先在界面中点击**“Stop Server”**，再关闭界面。

日志选项

• 在控制台中打印代码：在代码运行前，在 R 控制台中查看 AI 的代码。代码前会显示以下标题：### LLM [agent-id] executing the following code ###。
• 将代码记录到文件：将所有执行过的代码保存到日志文件中。每条记录都会标记执行代码的 Agent ID，方便你追踪每个 AI Agent 执行了哪些代码。
• 自定义日志路径：指定日志文件的自定义位置。
• 描述性文件名：日志文件的命名格式为 clauder_<session>_<port>_<timestamp>.R（例如，clauder_default_8787_20260301_143022.R），方便你一眼看出每条日志由哪个会话生成。
• 可复现性标头：每条日志都以一个标头开头，其中包含日期、工作目录和完整的 sessionInfo() 输出（R 版本、平台、已附加／加载的软件包）。这使日志能够自我记录信息，便于复现。
• 导出干净脚本：点击日志面板中的“Export Clean Script”，生成一个可运行的 .R 文件，其中会移除所有时间戳和日志标头。错误块会保留为注释，方便你查看出错原因。也可以在控制台中调用 export_log_as_script()。

每次点击 Start Server 都会创建一个新的日志文件。Agent 执行的所有代码都会追加到该文件中，直到你再次停止并启动服务。

交互示例

• “我的环境中有一个名为 data 的数据集。请对它进行探索性数据分析。”
• “加载 mtcars 数据集，并创建一张以 mpg 为纵轴、hp 为横轴且带有趋势线的散点图。”
• “根据 wt 和 hp 拟合一个用于预测 mpg 的线性模型。”
• “为 iris 数据集生成相关矩阵并进行可视化。”
• “我当前打开了一个 qmd 文件。请制作一份精美的 Quarto 梯度下降演示文稿。受众是技术人员，请确保效果流畅。将演示文稿保存到 /Users/nyk/QuartoDocs/”

如果 R 能做到，你的 AI 助手也能做到。

重要说明

• 会话持久性：AI 创建的变量、数据和函数会保留在你的 R 会话中。
• 代码可见性：默认情况下，AI 的代码会打印到控制台。
• 端口配置：默认端口为 8787，但你可以按需更改。在 RStudio Server 上，8787 是 IDE 自己使用的端口，因此请选择其他端口（例如 8788）。
• 软件包安装：AI 可以安装软件包。请使用清晰的提示词来引导其行为。

故障排除

• 连接问题：
  • 确保 AI 工具配置正确。
  • 检查 config 或 CLI 命令中的 Python 路径。
  • 确保插件中正在运行服务器。
  • 如果端口已被占用，请重启 RStudio。
• Python 依赖问题：
  • could not find function install_clauder：重启 R 会话（Session -> Restart R），然后重试。
  • MCP 服务启动失败：如果使用 uvx，请确保已安装 uv（curl -LsSf https://astral.sh/uv/install.sh | sh）。如果使用旧版方法，通常表示检测到了错误的 Python 环境。请使用正确的 python_path 重新运行安装程序，或切换为 use_uvx = TRUE。
• AI 无法查看结果：
  • 确保插件窗口已打开且服务器正在运行。
• 图表未显示：
  • 指示 AI 使用 print() 包裹绘图对象（例如 print(my_plot)）。
  • 告诉 AI 使用 execute_r_with_plot 函数。
• 长时间运行的代码超时：
  • 对于运行时间超过 25 秒的代码，请让 AI 使用 execute_r_async。
  • AI 使用 get_async_result 获取结果，该函数会等待任务完成。
  • 异步任务通过 callr 在单独的 R 进程中运行，无法访问主会话的环境。AI 必须编写自包含代码，使用 saveRDS() 传入数据并写出结果，然后在任务完成后将结果加载回主会话。
• 服务器重启问题：
  • 如果重启服务器后看到“address already in use”错误，这是一个 UI 错误。服务器仍在运行。如果遇到连接问题，请在 Viewer Pane 中更改端口号或重启 RStudio。
  • 如果 AI 仍然无法连接，请点击 Advanced 部分下的 “Force Release Port”。此操作会强制终止占用该端口的进程，以便重新启动。
• 升级 R 后 MCP 路径过时：
  • 如果升级 R 后工具停止工作，请重新运行 install_cli() 或 install_clauder() 以更新脚本路径。

限制

• 每个 R 会话一次只能连接一个 Claude Desktop/Cursor 应用。不过，多个 CLI Agent（Claude Code、Codex、Qwen、agy）可以与一个桌面应用共享同一会话。若要隔离 Agent，请使用不同的会话名称和端口运行多个 RStudio 窗口。
• 你可以关闭 Shiny UI（在控制台中点击 Stop 按钮），同时使用 AI。服务器会在后台继续运行，Agent 仍保持连接。重新运行 claudeAddin() 可重新打开 UI，或点击 UI 中的 Stop Server 以完全停止服务器。
• R 是单线程的，但异步任务通过 callr 在单独的进程中运行，因此主会话仍能保持响应。后台进程不与主会话共享环境，因此异步代码必须是自包含的。

引用

如果 ClaudeR 对已发表的研究有所贡献，欢迎引用：

citation("ClaudeR")

Vitali, N. (2026). ClaudeR: Connect live RStudio and Python sessions to AI
agents over MCP. R package version 0.15.0.
https://github.com/IMNMV/ClaudeR

GitHub 侧边栏中的“Cite this repository”按钮会根据 CITATION.cff 生成相同内容。

许可证

本项目采用 MIT License 授权。详情请参阅 LICENSE 文件。

贡献

欢迎贡献！请随时提交 Pull Request。