paperclip-setup

Paperclip 设置

为 Paperclip 技能套件准备本地操作员环境。

参考资料

先阅读以下内容：

• 打包的共享文档：
  • references/CONTEXT.md
  • references/docs/paperclip-operator/control-plane.md
  • references/docs/paperclip-operator/workflow.md
  • references/docs/paperclip-operator/cli-contract.md
  • references/docs/paperclip-operator/integration-matrix.md
• 缺少项目文档时使用的内置模板：
  • references/project-docs/AGENTS.md
  • references/project-docs/CLAUDE.md
  • references/project-docs/CONTEXT.md
  • references/project-docs/docs/paperclip-operator/control-plane.md
  • references/project-docs/docs/paperclip-operator/workflow.md
  • references/project-docs/docs/paperclip-operator/afk-readiness.md
  • references/project-docs/docs/paperclip-operator/cli-contract.md
  • references/project-docs/docs/paperclip-operator/integration-matrix.md
  • references/project-docs/docs/paperclip-operator/paperclip-docs-index.md
  • references/project-docs/docs/growth-operator/workflow.md
  • references/project-docs/docs/growth-operator/control-plane.md
  • references/project-docs/docs/growth-operator/afk-readiness.md

工作流

1. 检查本地 Paperclip CLI。

   command -v paperclipai
   paperclipai --version
   paperclipai context show --json
   

2. 如果缺少 paperclipai，引导用户全新安装。

   先检查环境是否可以安装 npm 包：

   command -v node
   node --version
   command -v npm
   npm --version
   

   如果已安装 Node.js 和 npm，告知操作员全局安装 CLI。 paperclipai 是 Paperclip 官方第一方 CLI；供应链扫描器会像扫描任何软件包安装一样对这项全局安装发出警告：

   npm install -g paperclipai
   

   然后验证二进制文件是否位于 PATH 中：

   command -v paperclipai
   paperclipai --version
   

   如果安装成功，但 command -v paperclipai 仍然失败，请检查 npm 的全局二进制目录，并告知操作员将其添加到 PATH：

   npm bin -g
   

   未经操作员批准，不要执行全局安装。如果缺少 Node.js 或 npm，请先让操作员为其平台安装 Node.js，然后重新运行设置。

3. 如果已安装 CLI，请继续设置，不要因为第一条 Paperclip 命令失败就停止。

   将设置视为一个阶梯：

   • 已安装 CLI，且位于 PATH 中
   • CLI 可以读取其上下文
   • API 基础地址可访问
   • 已配置身份验证
   • 已选择公司上下文
   • 已安装 Paperclip MCP 配置，或有意跳过
   • 存在共享操作员文档

   某一层级失败时，应给出所需的下一条具体命令或决策，而不是提供笼统的阻塞报告。

4. 在尝试读取公司信息之前，先验证已配置的 API 基础地址。

   检查当前活动上下文：

   paperclipai context show --json
   

   如果 API 基础地址缺失、为空或只是无法访问的默认地址，请先询问操作员 Paperclip 环境 URL，再尝试身份验证或公司命令。可以将其表述为设置所需的信息，例如：

   What Paperclip environment URL should this CLI use? For example: https://paperclip.example.com or http://localhost:3100.
   

   操作员提供 URL 后，先验证再写入上下文：

   curl -fsS <api-base>/api/health
   

   如果该 URL 可访问，展示拟进行的上下文变更并征求批准。执行任何 context set 之前，先读取当前上下文，以便保留现有值：

   paperclipai context show --json
   

   paperclipai context set --api-base <api-base> --use
   

   如果操作员需要隔离配置文件或命名配置文件，请在 --use 前添加 --profile <name>。将 context set 视为替换该配置文件已配置的值，而不是与未知的现有字段合并：如果已知 API 基础地址和公司 ID，请在一条命令中同时设置。

   如果 API 基础地址是 http://localhost:3100，请验证本地 Paperclip API 是否实际正在运行：

   curl -fsS http://localhost:3100/api/health
   

   如果 API 健康检查失败，请说明安装已完成，但 Paperclip API 服务无法访问。询问操作员是要启动本地 Paperclip API，还是提供其他 Paperclip 环境 URL。在 API 可访问之前，不要将此问题视为身份验证失败。

5. 如果 API 可访问，但缺少身份验证或上下文，请引导用户登录并选择上下文。

   paperclipai auth login --api-base <api-base>
   paperclipai company list --json
   paperclipai context show --json
   

   如果登录后未选择公司，请询问操作人员要使用哪家公司。不要跨公司猜测。

6. 如果已配置 Paperclip 身份验证，检查可用公司。

   paperclipai company list --json
   

7. 确认当前公司范围。

   如果未选择公司，请询问操作人员要使用哪家公司。不要跨公司猜测。

   操作人员选择公司后，保留 API 基础地址并写入公司 ID：

   paperclipai context set --api-base <api-base> --company-id <company-id> --use
   paperclipai context show --json
   

   验证生成的配置文件同时包含 apiBase 和 companyId。如果没有，请同时设置这两个值进行修复，然后再次读取上下文。

8. 验证 Paperclip MCP 配置。

   Paperclip MCP 在 CLI 之后使用 @bbengamin/paperclip-mcp-server 作为后备接口。加载技能不要求 MCP；只有 Paperclip 操作需要 MCP 后备接口时，才需要 MCP。

   对于 Codex，默认使用当前受信任项目的项目级 Codex 配置：

   .codex/config.toml
   

   对于 Claude Code，默认使用当前受信任项目的项目级 Claude MCP 配置：

   .mcp.json
   

   仅当操作人员明确提出要求时，才使用全局或用户级配置：

   ~/.codex/config.toml
   

   提出更改前，先检查预期目标：

   test -f .codex/config.toml && sed -n '1,220p' .codex/config.toml
   test -f ~/.codex/config.toml && sed -n '1,220p' ~/.codex/config.toml
   test -f .mcp.json && sed -n '1,220p' .mcp.json
   

   建议的 Codex 项目级 TOML：

   [mcp_servers.paperclip]
   command = "npx"
   args = ["-y", "@bbengamin/paperclip-mcp-server"]
   

   建议的 Claude Code 项目级命令：

   claude mcp add paperclip -s project -- npx -y @bbengamin/paperclip-mcp-server
   

   这会写入等效的 .mcp.json 条目：

   {
     "mcpServers": {
       "paperclip": {
         "command": "npx",
         "args": ["-y", "@bbengamin/paperclip-mcp-server"]
       }
     }
   }
   

   如果操作人员需要明确的主机本地覆盖项，只包含其要求的环境变量值：

   [mcp_servers.paperclip.env]
   PAPERCLIP_API_URL = "<api-base>"
   PAPERCLIP_COMPANY_ID = "<company-id>"
   

   优先使用不含令牌的配置，使其回退到当前的 paperclipai 配置文件和看板身份验证。不要将 PAPERCLIP_API_KEY 写入项目级配置。如果需要 Bearer 令牌，请让操作人员使用本地环境变量或用户级配置。

   写入 MCP 配置前，展示以下信息：

   • 目标范围：项目级或全局
   • 目标路径
   • 完整的 TOML 表、Claude 命令或 JSON 条目
   • paperclip MCP 条目将被创建、替换还是保持不变

   编辑配置文件前，请先征得明确批准。写入后，验证：

   sed -n '1,220p' <target-config-path>
   claude mcp get paperclip
   npm view @bbengamin/paperclip-mcp-server version
   

   然后告知操作人员，在预期 Paperclip MCP 工具出现前，需要重启 Codex 或 Claude Code，或开启新的对话/会话。除非重启后的会话仍无法加载工具，否则不要将同一运行中的对话里缺少 MCP 工具视为安装失败。

9. 验证共享文档是否存在。

   必需文件：

   • AGENTS.md
   • CLAUDE.md
   • CONTEXT.md
   • docs/paperclip-operator/control-plane.md
   • docs/paperclip-operator/workflow.md
   • docs/paperclip-operator/afk-readiness.md
   • docs/paperclip-operator/cli-contract.md
   • docs/paperclip-operator/integration-matrix.md
   • docs/paperclip-operator/paperclip-docs-index.md
   • docs/growth-operator/workflow.md
   • docs/growth-operator/control-plane.md
   • docs/growth-operator/afk-readiness.md

10. 如果缺少文档，请提议创建文档框架。

展示将要创建或更新的确切文件。写入前请征得批准。

使用 references/project-docs/ 中附带的模板。根据需要创建缺失的目录。

如果目标文件已存在，不要在未告知的情况下覆盖。概述冲突，并询问是跳过、手动合并还是替换。

11. 报告设置状态。

包括：

• 是否找到 paperclipai，或是否提供了安装指南
• CLI 路径和版本
• 当前配置文件
• API 基础地址
• API 是否可访问，以及下一步是启动本地 API 还是更改 API 基础地址
• 公司 ID（如果已配置）
• 身份验证状态或所需的下一条身份验证命令
• MCP 安装范围、目标路径，以及是否需要重启/开启新对话
• 已创建、已跳过或仍缺失的文档
• 尚未解决的设置问题

变更规则

此技能可以自由读取。更改 CLI 上下文、创建 Paperclip 记录、安装或更改 Paperclip MCP 配置、安装 Paperclip 公司技能或编辑共享文档前，必须先征求许可。只有在获得操作员批准后，才允许根据随附模板创建缺失的共享文档。