PinableAgents 系统概述与核心理念

PinableAgents 是一个模块化的多智能体编排平台，旨在将复杂的软件开发任务分解为可管理的阶段，由不同的专业智能体协作完成。与传统的单一 AI 助手不同，PinableAgents 通过工作流（Workflow）定义任务的执行路径，每个工作流包含多个阶段，每个阶段由具有特定职责的智能体负责。

核心理念可以概括为三个关键词：Workflows（工作流定义流程）、Orchestration（编排协调智能体）、Execution（执行产出结果）。系统采用"约定优于配置"的设计哲学，默认提供合理的工作流配置，同时允许用户根据项目需要进行深度定制。

PinableAgents 的桌面端应用（pinable-desktop）提供了图形化的模块管理、工作流配置和实时执行监控界面，降低了使用门槛。底层通过统一的 CLI 接口对接多种 AI 后端（Codex、Claude、Gemini），使用户可以根据任务特点选择最合适的模型。

PinableAgents 不是一个"万能 AI 工具"，而是一个让多个 AI 智能体按照软件工程最佳实践协作的框架。它的价值在于流程的可靠性和可重复性。

macOS 安装步骤

PinableAgents 在 macOS 上以 DMG 安装包的形式分发。请确保你的系统满足最低要求：macOS 12 Monterey 或更高版本，至少 8 GB 内存。

步骤一：下载安装包

从 PinableAgents 官方网站下载最新版本的 PinableAgents-mac.dmg 安装文件。文件大小约为 120 MB。你也可以在项目首页点击"下载 macOS 版"按钮直接获取。

步骤二：挂载并安装

双击下载的 DMG 文件，系统将自动挂载磁盘映像。在弹出的窗口中，将 PinableAgents 图标拖拽到 Applications 文件夹中完成安装。

# 如果需要通过命令行安装
hdiutil attach PinableAgents-mac.dmg
cp -R "/Volumes/PinableAgents/PinableAgents.app" /Applications/
hdiutil detach "/Volumes/PinableAgents"

步骤三：处理安全提示

首次打开时，macOS 可能会弹出"无法打开，因为无法验证开发者"的提示。你需要进入系统设置 > 隐私与安全性，在页面底部找到关于 PinableAgents 的提示，点击"仍要打开"。或者使用以下命令移除隔离标记：

xattr -cr /Applications/PinableAgents.app

步骤四：配置工作目录

PinableAgents 默认将配置和模块存储在 ~/.pinable-agents/ 目录下。你可以在首次启动的配置向导中更改此路径。建议使用 SSD 存储以获得更好的性能。

Windows 安装步骤

Windows 版本以 EXE 安装程序的形式分发，支持 Windows 10 版本 1903 及以上系统。

步骤一：下载安装程序

从官方网站下载 PinableAgents-win.exe 安装文件。文件大小约为 95 MB。

步骤二：运行安装程序

双击 EXE 文件启动安装向导。Windows Defender SmartScreen 可能会弹出警告，选择"更多信息"然后点击"仍要运行"。安装向导将引导你选择安装路径（默认为 C:\Program Files\PinableAgents）。

步骤三：配置 PATH 环境变量

安装程序会自动将 PinableAgents CLI 添加到系统 PATH。如果你发现命令行工具不可用，需要手动添加。打开"系统属性 > 高级 > 环境变量"，在系统变量的 Path 中添加安装路径下的 bin 目录。

步骤四：验证安装

打开 PowerShell 或命令提示符，运行以下命令确认安装成功：

pinable-agents --version
# 预期输出：PinableAgents v1.x.x (build xxxxx)

首次启动与配置向导

安装完成后首次启动 PinableAgents，系统会自动进入配置向导，帮助你完成必要的初始化设置。配置向导包含以下四个步骤：

  1. 选择工作目录：指定模块和配置文件的存储位置。建议选择有足够磁盘空间（至少 2 GB）的目录。
  2. 配置 AI 后端：选择你要使用的 AI 后端（Codex、Claude 或 Gemini），并输入对应的 API 密钥。你可以同时配置多个后端。
  3. 安装基础模块：向导会推荐安装 do 和 essentials 模块作为基础配置。
  4. 运行诊断检查：自动检测依赖工具（Go、Node.js、Git）是否已安装并可用。

配置向导的所有设置都会写入 ~/.pinable-agents/config.json 文件，你可以在之后随时修改。

验证安装是否成功

完成安装后，建议通过以下几种方式验证安装是否正确：

命令行验证

# 检查 CLI 版本
pinable-agents --version

# 检查已安装的模块
pinable-agents modules list

# 检查后端连接状态
pinable-agents backend status

# 运行完整的健康检查
pinable-agents doctor

桌面端验证

打开 PinableAgents 桌面端，检查以下几项：

  • Modules 页面应显示已安装的模块列表，且状态为"已启用"
  • Workflows 页面应能正常加载工作流选择器
  • Config 页面应显示当前的 config.json 内容
  • 底部状态栏应显示"已连接"和所选后端名称

快速功能测试

运行一个最简单的测试任务来确认端到端流程可以正常工作：

# 在一个测试项目目录中运行
mkdir ~/test-pinable && cd ~/test-pinable
git init
echo "# Test Project" > README.md
git add . && git commit -m "init"

# 运行一个简单的 do 工作流
pinable-agents run do --task "在 README 中添加项目描述段落"

PinableAgents 采用模块化设计，不同的模块提供不同的能力。对于初次使用者，我们推荐以下组合：

模块名称 功能说明 推荐场景
do 核心交付工作流，包含需求分析到代码实现的完整流程 日常功能开发
essentials 基础智能体集合，包含代码探索、架构设计、代码审查等能力 所有场景
omo 信号驱动路由工作流，适合复杂和不确定性高的任务 Bug 调查、重构
bmad 企业级敏捷工作流，模拟完整的 Scrum 团队 大型项目、团队协作

对于新手用户，建议先从 do + essentials 开始。这个组合提供了最基础也最实用的功能，学习曲线平缓。当你熟悉了基本流程后，再逐步引入 omo 或 bmad 以应对更复杂的场景。

# 安装推荐的初始模块组合
pinable-agents modules install do essentials

# 验证模块已安装
pinable-agents modules list
# 输出：
# - do        v1.2.0  [已启用]
# - essentials v1.1.0  [已启用]

环境变量配置说明

PinableAgents 通过环境变量控制核心行为。以下是所有支持的环境变量及其说明：

环境变量 说明 默认值
CODEAGENT_BACKEND 指定默认的 AI 后端，可选值为 codex、claude、gemini codex
CODEAGENT_MODEL 指定使用的具体模型版本 由后端决定
OPENAI_API_KEY OpenAI API 密钥，使用 Codex 后端时必需 -
ANTHROPIC_API_KEY Anthropic API 密钥，使用 Claude 后端时必需 -
GEMINI_API_KEY Google API 密钥，使用 Gemini 后端时必需 -
PINABLE_WORK_DIR 工作目录路径 ~/.pinable-agents
PINABLE_LOG_LEVEL 日志级别：debug、info、warn、error info

建议将这些环境变量添加到你的 shell 配置文件中以持久化设置：

# macOS / Linux：添加到 ~/.zshrc 或 ~/.bashrc
export CODEAGENT_BACKEND=claude
export CODEAGENT_MODEL=claude-opus-4-6
export ANTHROPIC_API_KEY=sk-ant-xxxxx
export PINABLE_LOG_LEVEL=info

# 重新加载配置
source ~/.zshrc
# Windows PowerShell：添加到 $PROFILE
$env:CODEAGENT_BACKEND = "codex"
$env:CODEAGENT_MODEL = "o3"
$env:OPENAI_API_KEY = "sk-xxxxx"

# 或永久设置系统环境变量
[System.Environment]::SetEnvironmentVariable("CODEAGENT_BACKEND", "codex", "User")

依赖工具安装

PinableAgents 依赖以下工具来执行各项任务。请在安装 PinableAgents 之前确保这些工具已正确安装。

Go 1.21+

PinableAgents 的核心编排引擎使用 Go 编写。你需要安装 Go 1.21 或更高版本。

# macOS (通过 Homebrew)
brew install go

# Windows (通过 winget)
winget install GoLang.Go

# 验证安装
go version
# 预期输出：go version go1.21.x darwin/arm64

Node.js 18+

部分模块和桌面端应用依赖 Node.js 运行时环境。

# macOS (通过 Homebrew)
brew install node@18

# Windows (通过 nvm-windows)
nvm install 18
nvm use 18

# 验证安装
node --version && npm --version

Git

PinableAgents 的工作流依赖 Git 进行版本控制和 worktree 隔离。

# macOS（通常预装，如需更新）
brew install git

# Windows
winget install Git.Git

# 验证安装
git --version

AI 后端 CLI 工具

根据你选择的 AI 后端，安装对应的 CLI 工具：

# Codex CLI
npm install -g @openai/codex

# Claude CLI (Claude Code)
npm install -g @anthropic-ai/claude-code

# Gemini CLI
npm install -g @anthropic-ai/gemini-cli

常见安装问题与解决方案

问题：macOS 提示"应用已损坏"

这通常是由于 macOS 的 Gatekeeper 安全机制导致的。运行以下命令解除限制：

sudo xattr -rd com.apple.quarantine /Applications/PinableAgents.app

问题：CLI 命令找不到

确认安装路径已添加到系统 PATH 中。你可以运行 which pinable-agents（macOS）或 where pinable-agents（Windows）来检查。如果命令不存在，手动添加路径或重新安装。

问题：模块安装失败

检查工作目录是否有写入权限，以及网络连接是否正常。如果使用代理，确保代理设置正确。你可以尝试以下步骤：

# 清除模块缓存
pinable-agents modules clean

# 重新安装
pinable-agents modules install do essentials --force

问题：AI 后端连接超时

首先检查 API 密钥是否正确配置。然后确认网络可以访问对应的 API 端点。对于中国大陆用户，可能需要配置代理或使用镜像端点：

# 配置 HTTP 代理
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890

# 或在 config.json 中配置
{
  "proxy": {
    "http": "http://127.0.0.1:7890",
    "https": "http://127.0.0.1:7890"
  }
}

问题：Go 版本过低

PinableAgents 需要 Go 1.21 及以上版本。使用 go version 检查当前版本，如果低于 1.21，请升级 Go。Homebrew 用户可以运行 brew upgrade go。

问题：Windows 上权限不足

以管理员身份运行安装程序，或者选择安装到不需要管理员权限的目录（如用户目录下）。对于 PowerShell 执行策略问题，运行：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser