pjt222/agent-almanac/install-putior

安装 putior

安装 putior R 包及其可选依赖项，使注释到图表流水线准备就绪。

适用场景

• 首次在项目或环境中安装 putior
• 为工作流可视化任务准备机器
• 下游技能（analyze-codebase-workflow、generate-workflow-diagram）需要 putior 已安装
• 在 R 版本升级或 renv 清空后恢复环境

输入

• 必需：可用的 R 安装（>= 4.1.0）
• 可选：是否从 CRAN 安装（默认）还是 GitHub 开发版
• 可选：要安装的可选依赖组：MCP（mcptools、ellmer）、交互式（shiny、shinyAce）、日志（logger）、ACP（plumber2）

步骤

第 1 步：验证 R 安装

确认 R 可用且满足最低版本要求。

R.Version()$version.string
# Must be >= 4.1.0

# From WSL with Windows R
"/mnt/c/Program Files/R/R-4.5.2/bin/Rscript.exe" -e "cat(R.version.string)"

预期结果： 打印 R 版本字符串，>= 4.1.0。

失败处理： 安装或升级 R。Windows 上从 https://cran.r-project.org/bin/windows/base/ 下载。Linux 上使用 sudo apt install r-base。

第 2 步：安装 putior

从 CRAN（稳定版）或 GitHub（开发版）安装。

# CRAN (recommended)
install.packages("putior")
 
# GitHub dev version (if latest features needed)
remotes::install_github("pjt222/putior")

预期结果： 包安装无错误。library(putior) 静默加载。

失败处理： 如果 CRAN 安装失败并提示"此版本 R 不可用"，使用 GitHub 版本。如果 GitHub 安装失败，检查 remotes 是否已安装：install.packages("remotes")。

第 3 步：安装可选依赖项

根据所需功能安装可选包。

# MCP server integration (for AI assistant access)
remotes::install_github("posit-dev/mcptools")
install.packages("ellmer")
 
# Interactive sandbox
install.packages("shiny")
install.packages("shinyAce")
 
# Structured logging
install.packages("logger")
 
# ACP server (agent-to-agent communication)
install.packages("plumber2")

预期结果： 每个包安装无错误。

失败处理： 对于 mcptools，确保先安装了 remotes。对于 Linux 上的系统依赖错误，安装所需库（如 sudo apt install libcurl4-openssl-dev 用于 httr2 依赖）。

第 4 步：验证安装

运行基础流水线确认一切正常。

library(putior)
 
# Check package version
packageVersion("putior")
 
# Verify core functions are available
stopifnot(
  is.function(put),
  is.function(put_auto),
  is.function(put_diagram),
  is.function(put_generate),
  is.function(put_merge),
  is.function(put_theme)
)
 
# Test basic pipeline with a temp file
tmp <- tempfile(fileext = ".R")
writeLines("# put id:'test', label:'Hello putior'", tmp)
cat(put_diagram(put(tmp)))

预期结果： 打印到控制台的 Mermaid 流程图代码，包含 test 和 Hello putior。

失败处理： 如果找不到 put，说明包未正确安装。使用 install.packages("putior", dependencies = TRUE) 重新安装。如果图表为空，验证临时文件是否已创建，且注释语法中在双引号内使用单引号。

重要：自定义调色板不能通过 MCP 使用。 put_diagram 的 palette 参数接受由 put_theme() 创建的 putior_theme R 对象。由于 MCP 通过 JSON 通信，无法跨 MCP 边界序列化 putior_theme 等 R 对象。通过 MCP 调用 put_diagram 时，请改用基于字符串的 theme 参数（例如 theme = "viridis"）。对于自定义调色板，请直接在 R 会话中调用 put_theme() 和 put_diagram(palette = ...)。

关键默认值：所有扫描函数（put()、put_auto()、put_generate()、put_merge()）默认 recursive = TRUE，自动扫描子目录。这是相较于 0.2.0 之前版本（默认为 FALSE）的破坏性变更。所有扫描函数还接受 exclude 参数用于基于正则表达式的文件过滤（例如 put("./src/", exclude = "test_")）。

如果安装了可选的 shiny 包，请尝试交互式沙箱：

putior::run_sandbox()

这将启动一个基于浏览器的编辑器，您可以在其中试验 PUT 注释语法并实时查看渲染的图表。

验证清单

• [ ] library(putior) 加载无错误
• [ ] packageVersion("putior") 返回有效版本
• [ ] 包含有效 PUT 注释的文件调用 put() 返回单行数据框
• [ ] put_diagram() 生成以 flowchart 开头的 Mermaid 代码
• [ ] 所有请求的可选依赖项加载无错误

常见问题

• 错误的引号嵌套：PUT 注释在注释内使用单引号：id:'name'，而非 id:"name"（在某些上下文中与注释字符串分隔符冲突）。
• vignette 缺少 Pandoc：如果计划在本地构建 putior 的 vignette，确保在 .Renviron 中设置了 RSTUDIO_PANDOC。
• renv 隔离：如果项目使用 renv，必须在 renv 库中安装 putior。使用 renv::install("putior") 而非 install.packages("putior")。
• GitHub 速率限制：从 GitHub 安装 mcptools 时，没有 GITHUB_PAT 可能失败。通过 usethis::create_github_token() 设置一个。

相关技能

• analyze-codebase-workflow — 安装后对代码库进行调查的下一步
• configure-putior-mcp — 安装可选依赖后设置 MCP 服务器
• manage-renv-dependencies — 在 renv 环境中管理 putior
• configure-mcp-server — 通用 MCP 服务器配置