pinable - 多后端 AI 代码任务执行器

总览

pinable 是一个多后端 AI 代码任务执行器，支持 Codex、Claude、Claude、Gemini 四个后端。提供文件引用（@ 语法）、并行任务执行、后端选择等功能。适用于代码生成、重构、调试、文档生成等场景。

支持的后端

后端	说明	最佳场景
codex	OpenAI Codex（默认）	代码分析、复杂开发、大规模重构
claude	Anthropic Claude	简单任务、文档生成、快速修复
gemini	Google Gemini	UI/UX 原型、设计系统实现
opencode	OpenCode	代码补全、代码生成

核心能力

• 代码生成 - 根据描述生成代码
• 代码重构 - 优化和改进现有代码结构
• 代码调试 - 定位和修复 bug
• 文档生成 - 生成代码文档和 README

使用方式

单任务执行

# HEREDOC 语法（推荐）
pinable --backend codex - <<'EOF'
<task content here>
EOF

# 指定工作目录
pinable --backend codex - /path/to/dir <<'EOF'
<task content here>
EOF

# 简单任务
pinable --backend codex "simple task" [working_dir]

并行任务执行

pinable --parallel <<'EOF'
---TASK---
id: task1
backend: codex
workdir: /path/to/dir
---CONTENT---
task content
---TASK---
id: task2
backend: claude
dependencies: task1
---CONTENT---
dependent task
EOF

恢复会话

pinable --backend codex resume <session_id> - <<'EOF'
<follow-up task>
EOF

后端选择指南

任务类型	推荐后端	原因
深度代码分析	codex	深度代码理解，复杂逻辑实现
大规模重构	codex	精确依赖跟踪
算法优化	codex	性能调优能力强
快速修复	claude	速度快，轻量级
技术文档	claude	文档生成质量高
UI 组件原型	gemini	UI/UX 专长
设计系统	gemini	样式一致性保证

文件引用语法

使用 @ 符号引用文件：

pinable --backend codex - <<'EOF'
Analyze the call graph of @src/core and refactor the module dependency structure
EOF

环境变量

变量	说明	默认值
CODEX_TIMEOUT	超时时间（毫秒）	7200000（2小时）
PINABLE_SKIP_PERMISSIONS	跳过权限检查	disabled
PINABLE_MAX_PARALLEL_WORKERS	并行任务数限制	无限制

输出模式

• Summary（默认） - 结构化报告，包含变更、输出、验证和审查摘要
• Full (--full-output) - 完整任务消息，仅用于调试

关键规则

不要终止 pinable 进程。长时间运行任务（2-10分钟）是正常现象。终止会浪费 API 成本并丢失进度。

查看任务状态：

# 实时输出
tail -f /tmp/claude/<workdir>/tasks/<task_id>.output

# 检查任务是否在运行
cat /tmp/claude/<workdir>/tasks/<task_id>.output | tail -50

返回格式

Agent response text here...

---
SESSION_ID: 019a7247-ac9d-71f3-89e2-a823dbd8fd14

安全最佳实践

• Claude 后端：权限检查默认启用
  • 跳过检查：设置 PINABLE_SKIP_PERMISSIONS=true
• 并发限制：生产环境建议设置 PINABLE_MAX_PARALLEL_WORKERS
• 自动化场景：专为 AI 驱动自动化设计，避免权限提示阻塞执行