Agent-almanac install-putior

install

source · Clone the upstream repo

git clone https://github.com/pjt222/agent-almanac

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/pjt222/agent-almanac "$T" && mkdir -p ~/.claude/skills && cp -r "$T/i18n/zh-CN/skills/install-putior" ~/.claude/skills/pjt222-agent-almanac-install-putior-7f1e6b && rm -rf "$T"

manifest: i18n/zh-CN/skills/install-putior/SKILL.md

source content

安装 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()
```
设置一个。