pulumi-neo

Pulumi Neo Skill

先决条件

• Pulumi Cloud 账户，且可使用 Neo
• PULUMI_ACCESS_TOKEN 环境变量已设置为你的 Personal Access Token
• 组织：所有 Neo API 调用都需要组织

检测组织

# Get current Pulumi organization from CLI
pulumi org get-default

# If no default org or using self-managed backend, ask user for organization name

如果 pulumi org get-default 返回错误或显示非云后端，请提示用户输入其 Pulumi Cloud 组织名称。

快速开始

重要： 在 Claude Code 中始终使用 --no-poll，以防止阻塞。

首选：Python 脚本

python <skill-base-directory>/scripts/neo_task.py --org <org> --message "Your message" --no-poll

替代方式：直接调用 API

export PULUMI_ACCESS_TOKEN=<your-token>
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
curl -s -X POST "https://api.pulumi.com/api/preview/agents/<org>/tasks" \
  -H "Authorization: token $PULUMI_ACCESS_TOKEN" \
  -H "Accept: application/vnd.pulumi+8" \
  -H "Content-Type: application/json" \
  -d "{\"message\":{\"type\":\"user_message\",\"content\":\"How many stacks do I have?\",\"timestamp\":\"$TIMESTAMP\",\"entity_diff\":{\"add\":[],\"remove\":[]}}}"

获取事件：curl -s "https://api.pulumi.com/api/preview/agents/<org>/tasks/<task-id>/events" -H "Authorization: token $PULUMI_ACCESS_TOKEN" -H "Accept: application/vnd.pulumi+8" | jq '.events[-1].eventBody.content'

MCP 工具（如果已安装 Pulumi MCP 服务）：mcp__pulumi__neo-bridge、mcp__pulumi__neo-get-tasks、mcp__pulumi__neo-continue-task

使用 Python 脚本

该脚本负责 Neo 任务的创建、轮询和管理：

# Create a task and poll for updates (interactive/terminal use)
python scripts/neo_task.py --org <org-name> --message "Help me optimize my Pulumi stack"

# Create task without polling (CI/CD or programmatic use)
python scripts/neo_task.py --org <org-name> --message "Analyze this" --no-poll

# Create task with stack context
python scripts/neo_task.py --org <org-name> \
  --message "Analyze this stack" \
  --stack-name prod --stack-project my-infra --no-poll

# Create task with repository context
python scripts/neo_task.py --org <org-name> \
  --message "Review this infrastructure code" \
  --repo-name my-repo --repo-org my-github-org --no-poll

# List existing tasks
python scripts/neo_task.py --org <org-name> --list

# Fetch current events (single request, no polling)
python scripts/neo_task.py --org <org-name> --task-id <task-id> --get-events

# Poll an existing task for updates (interactive)
python scripts/neo_task.py --org <org-name> --task-id <task-id>

# Send approval for a pending request
python scripts/neo_task.py --org <org-name> --task-id <task-id> --approve

# Cancel a pending request
python scripts/neo_task.py --org <org-name> --task-id <task-id> --cancel

Neo 任务工作流

创建任务

创建任务时，需用自然语言消息描述你希望 Neo 执行的操作：

• 基础设施分析：“分析我的生产堆栈，查找安全问题”
• 维护操作：“帮我升级 Kubernetes 集群”
• 配置更改：“为我的 Lambda 函数添加监控”
• 多步骤工作流：“为此项目设置完整的 CI/CD 流水线”

实体上下文

附加实体以提供上下文：stack（名称 + 项目）、repository（名称 + 组织 + forge）、pull_request（编号 + 是否已合并 + 仓库）、policy_issue（ID）。

任务状态

状态	说明
running	Neo 正在主动处理任务
idle	任务正在等待输入或已完成处理

注意： 任务是否完成以及是否需要审批，应通过检查事件来确定，而不是查看任务状态。

审批流程

当 Neo 需要确认某项操作时（这是一个关键概念——Neo 从不会未经询问就进行破坏性更改）：

1. 任务状态仍为 running 或转为 idle
2. agentResponse 事件包含带有 approval_request 工具的 tool_calls——这是需要查找的特定事件结构
3. approval_request_id 位于工具调用参数中
4. 用户审核提议的更改
5. 使用 --approve 发送批准，或使用 --cancel 取消

检测审批请求： 检查事件中是否有包含 approval_request 条目的 eventBody.tool_calls，不要依赖任务状态。响应时需要使用工具调用参数中的 approval_request_id。

# Approve a pending request
python scripts/neo_task.py --org <org> --task-id <task-id> --approve

# Cancel/reject a pending request
python scripts/neo_task.py --org <org> --task-id <task-id> --cancel

常见工作流

分析基础设施

python scripts/neo_task.py --org myorg \
  --message "What security improvements can I make to my AWS infrastructure?" \
  --stack-name prod --stack-project aws-infra --no-poll

修复策略违规

python scripts/neo_task.py --org myorg \
  --message "Help me fix the policy violations in my production stack" --no-poll

生成 Pulumi 代码

python scripts/neo_task.py --org myorg \
  --message "Create a new Pulumi TypeScript project for a containerized web app on AWS ECS" --no-poll

审查拉取请求

python scripts/neo_task.py --org myorg \
  --message "Review the infrastructure changes in this PR" \
  --repo-name infra --repo-org myorg --repo-forge github --no-poll

故障排除

错误	原因	解决方案
401	令牌无效或缺失	使用 curl -s -H "Authorization: token $PULUMI_ACCESS_TOKEN" https://api.pulumi.com/api/user 验证
404	组织或端点错误	使用 pulumi org get-default 验证组织
409	任务正忙	等待当前操作完成
脚本挂起	缺少 --no-poll	使用 Ctrl+C 终止，并添加 --no-poll 标志
找不到令牌	未导出	运行 export PULUMI_ACCESS_TOKEN="$PULUMI_ACCESS_TOKEN"

API 参考

基础 URL：https://api.pulumi.com/api/preview/agents

端点	方法	说明
/{org}/tasks	POST	创建任务
/{org}/tasks	GET	列出任务
/{org}/tasks/{id}	GET	获取任务
/{org}/tasks/{id}/events	GET	获取事件
/{org}/tasks/{id}	POST	发送消息/审批

必需的请求头：

• Authorization: token $PULUMI_ACCESS_TOKEN
• Accept: application/vnd.pulumi+8
• Content-Type: application/json

完整详情请参阅 references/pulumi-neo-api.md。