bootstrap-existing-agent-with-prefactor-cli

使用 Prefactor CLI 引导 Agent

在更改应用程序代码之前，先使用 CLI 配置 Prefactor 凭据。

核心原则：先配置，再接入。

编码助手用法

当用户要求执行以下操作时，首先应用此技能：

• “为此 Agent 设置 Prefactor”
• “注册 Prefactor Agent 并获取环境变量”
• “使用 CLI 引导配置 Prefactor”
• “在接入前准备 ID 和环境变量”

此技能完成后：

1. 如果支持该提供方，请继续使用 skills/instrument-existing-agent-with-prefactor-sdk/SKILL.md。
2. 如果不支持该提供方，请继续使用 skills/create-provider-package-with-core/SKILL.md。
3. 移交设置环境变量值和所选软件包。

前提条件

• 已安装 Prefactor CLI（prefactor 位于 PATH 中，或通过 npx @prefactor/cli 使用）。
• 用户已在真实终端中运行 prefactor login。
• 当前工作目录为项目根目录（或应写入环境变量的目录）。

不要运行 prefactor login、prefactor profiles add，也不要编造 API 令牌。如果 CLI 因未登录而导致设置失败，请停止并让用户运行 prefactor login。

CLI 工作流

使用一条设置命令。优先使用 --json，以便可靠地解析字段。

现有 Agent：

prefactor setup <agent_id> --json

新建 Agent：

prefactor setup --create --name "<short-agent-name>" --description "<short description>" --json

prefactor setup 会在需要时创建部署、生成部署范围的运行时令牌、通过 ping 验证该令牌，并输出：

• api_url
• api_token
• agent_id
• agent_identifier

将设置输出视为 Prefactor 配置的唯一事实来源。在首次引导配置时，不要列出账户、创建环境、手动创建 API 令牌或注册 Agent 实例。

写入环境变量

按照项目现有的环境变量模式添加设置值（与其他密钥使用相同的文件类型、加载机制和命名约定）。如果存在多种模式，优先使用 API 密钥模式。

将 JSON 字段映射为：

PREFACTOR_API_URL=<api_url>
PREFACTOR_API_TOKEN=<api_token>
PREFACTOR_AGENT_ID=<agent_id>
PREFACTOR_AGENT_IDENTIFIER=<agent_identifier>

不要编造新的密钥布局。不要提交 prefactor.json（其中可能包含配置文件令牌）。

选择软件包

检查项目并选择匹配的 Prefactor 适配器：

• LangChain -> @prefactor/langchain
• AI SDK -> @prefactor/ai
• OpenClaw -> @prefactor/openclaw
• Claude SDK -> @prefactor/claude
• 自定义／不支持的提供方 -> 使用 skills/create-provider-package-with-core/SKILL.md

使用项目现有的软件包管理器安装所选软件包。移交给接入步骤时，请从同一个适配器软件包导入辅助函数。

验证

• 设置已成功退出。
• 环境变量值与设置输出一致。
• 软件包选择与提供方或设置建议相符。
• prefactor.json 未暂存以供提交。

常见错误

• 在运行 prefactor setup 之前接入代码。
• 在设置流程之外运行 prefactor login 或创建令牌。
• 忽略设置 JSON，自行编造环境变量键或软件包名称。
• 混用适配器的 init 与来自 @prefactor/core 的 withSpan／shutdown，除非显式传入 tracer。
• 提交 prefactor.json。