paperclip-admin

Paperclip 管理

通过最精简且安全的工作流处理零散的 Paperclip 管理员请求。

适用于不主要涉及澄清、策略记录、递归规划、AFK 就绪情况分类或执行监控的临时 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

如果缺少这些项目文档，请先运行 paperclip-setup，根据随附模板生成文档。

请求路由

• 对跨 Agent、问题、审批、活动、成本或阻塞工作的全面只读健康报告，请使用 paperclip-monitor。
• 当操作员期望的结果不明确、需要先梳理清楚再更改控制平面记录时，请使用 paperclip-clarify。
• 当操作员想要创建新的目标、项目、父问题或 plan 文档时，请使用 paperclip-record-strategy。
• 将策略文档或父问题拆解为子问题时，请使用 paperclip-plan-work。
• 判断问题是否已准备好进行 AFK 执行时，请使用 paperclip-triage。
• 创建或聘用新的 Paperclip Agent 时，请使用 paperclip-create-agent。
• 请求涉及创建、更新、重命名、归档、删除、发布、同步或以其他方式修改 Paperclip llm-wiki 内容时，请使用 paperclip-wiki-manage。
• 对于范围较小的读取、轻微编辑、现有 Agent 管理、公司技能库操作、已准备好的任务交接、审查关卡微调、预算／状态检查和一次性维护，请继续使用 paperclip-admin。

操作流程

1. 确定当前公司和配置文件。
2. 在进行任何更改之前，检查当前 Paperclip 状态。
3. 判断请求是只读还是会产生更改。
4. 对于只读请求，直接根据相关记录和不确定性作答。
5. 对于会产生更改的请求，提出确切的拟议更改并等待批准。
6. 仅应用已批准的更改。
7. 重新读取已更改的记录，并核实预期字段。
8. 报告更改内容、记录 ID 以及仍需处理的事项。

常见读取操作

如果 paperclipai 支持读取，优先使用它并采用 JSON 输出。如果命令行输出不足或不可用，则使用 MCP 读取：

paperclipai context show --json
paperclipai company list --json
paperclipai agent list -C <company-id> --json
paperclipai skills list -C <company-id> --json
paperclipai issue list -C <company-id> --json
paperclipai approval list -C <company-id> --json
paperclipai activity list -C <company-id> --json

Agent 管理

创建新的 Paperclip Agent 应使用 paperclip-create-agent。只有在检查现有 Agent 或对已创建的 Agent 进行经批准的小幅更新时，才使用此技能。

提出对现有 Agent 的变更前：

1. 列出现有 Agent 和公司技能。
2. 确认受影响 Agent 当前的角色、经理、适配器／运行时、预算、心跳策略和已附加的技能。
3. 检查所请求的变更是否应改为新建职位。
4. 确认提及的技能存在于公司技能库中；若不存在，先提议安装。
5. 提交拟议的更新以供批准。

获得批准后，使用最合适的途径：

• 如果 paperclipai 提供所需的 Agent 命令并能验证原生字段，则使用它。
• 如果提供了创建／更新 Agent 的 MCP 工具，或需要通过 MCP 读取上下文，则使用 MCP。
• 如果 CLI 和专用 MCP 工具无法访问所需的原生字段，则使用 paperclipApiRequest。
• 如果 CLI 和 MCP 不可用或无法正常工作，则使用直接 REST API。
• 如果没有可安全创建或更新 Agent 的可调用途径，则将 Paperclip UI 作为最后的备用方案。

更新后，重新读取 Agent，并验证名称、角色、经理、适配器、技能、预算和心跳策略。

对于托管指令包的读取／写入，请检查 paperclipai agent --help；如果存在以下原生命令，优先使用它们：instructions-bundle、instructions-bundle:update、instructions-file:get、instructions-file:put 和 instructions-file:delete。当前没有专用的 MCP 指令包工具。只有在已安装的 CLI 缺少所需命令时，才使用 paperclipApiRequest 或直接 REST：

• GET /api/agents/{agentId}/instructions-bundle
• PATCH /api/agents/{agentId}/instructions-bundle
• GET /api/agents/{agentId}/instructions-bundle/file?path=AGENTS.md
• PUT /api/agents/{agentId}/instructions-bundle/file
• DELETE /api/agents/{agentId}/instructions-bundle/file?path=...

写入指令前，先读取当前文件，提交准确的差异或无操作验证计划，并取得批准。写入后，重新读取并验证准确内容、字节大小、包模式、入口文件和涉及的文件路径。除非经批准的变更明确要求，否则不要添加或删除末尾换行符。

小幅变更

对于以下小幅且已获批准的变更，请使用此技能：

• 编辑 issue 的标题、描述、优先级、标签、受指派人或生命周期状态
• 通过 executionPolicy.stages[].participants 设置或清除 issue 的审核关卡
• 在 issue 上发表评论
• 为 Agent 附加或移除公司技能
• 在明确获批后读取或更新托管的 Agent 指令包
• 调整 Agent 预算或暂停／恢复设置
• 修正检查时发现的 Paperclip 记录中的小型不匹配
• 在操作人员已明确所需 issue 内容时创建单个简单 issue

不要擅自将广泛的工作转为 todo、分配广泛的 issue、为广泛的 issue 附加审核关卡、签出工作、手动触发心跳、批准看板关卡或修改 wiki 内容。如果某项变更会使工作变为可启动状态，或会更改 llm-wiki 内容，请指出这涉及分诊、委派或 wiki 管理，并明确征求许可。

审核关卡

当操作员要求为某个问题指定审核者时，请使用 Paperclip 原生的问题执行策略：

• 在 type: "review" 的阶段中写入 executionPolicy.stages[].participants
• 在审核阶段中设置 approvalsNeeded
• 当要求审核者发表评论时，设置 commentRequired: true
• 除非刚刚确认目标环境会将 reviewRequest 映射到 UI 审核者字段，否则不要写入 reviewRequest
• 普通执行策略中的审核者仅限 Agent
• 当需要人工最终验收时，应在交接中写明该要求，并要求 Agent 审核者创建幂等的 request_confirmation；不要将操作员添加为用户审批阶段的参与者

写入后，重新读取问题并确认审核者参与者已存在。如果所选审核者 Agent 的 status: "error"，请说明该指派正确，但运行时审核执行可能仍需先清除该 Agent 的错误状态。

预备分配协议

将任务分配视为会触发事件的派发操作，而非被动修改字段。

1. 在未分配时做好准备。 阅读问题、阻塞项、评论、活动记录、issue live-runs、issue active-run、近期的 issue runs、恢复操作、执行器配置、项目工作区和审查策略。除非操作员明确要求覆盖，否则保留执行器现有的默认环境。分配前补充或更新完整的交接内容，并配置 Agent 审查关卡。如果需要人工最终验收，明确决策标准，并要求审查者创建 request_confirmation；不要配置用户审批阶段。重新读取问题并核实任务说明、状态、阻塞项、未分配状态、工作区／环境设置以及 executionPolicy。完成标准：问题内容完整且已核实、未分配，并且没有正在运行或排队的任务，也没有未解决的恢复操作。
2. 仅派发一次。 获得明确批准后，通过分配执行器，并在必要时设置 status: todo，完成最终的可启动变更。如果可用界面支持，优先一次性更新。分配是唤醒触发器；不要再调用 heartbeat 或 resume，不要提及 Agent、签出或执行第二次分配变更。完成标准：活动记录显示已排队唤醒，或存在由预期执行器执行的任务。
3. 只读观察。 Paperclip 报告 wake queued、任务已排队／正在运行或 workspace ready 后，即视为已成功接手。只读取活动记录和任务状态。任务排队或运行期间，不要修改状态、受派人、评论、工作区、环境、执行策略或 Agent 配置。评论属于工作注入，可能产生单独排队的交互。
4. 由 Agent 原生处理审查流程。 执行器记录证据，并将问题状态转换为 done。Paperclip 会拦截此转换，将问题移至 in_review，更新 executionState，并分配／唤醒选定的 Agent 审查者。诊断审查路由时，核实 executionState.currentStageType 和 currentParticipant。除非 Paperclip 明确报告审查派发被跳过或失败，否则不要手动分配、提及或唤醒审查者，也不要调用 resume。
5. 通过交互请求人工验收。 如果交接要求人工最终验收，审查者会创建一条幂等的 request_confirmation，其中包含证据、剩余风险以及接受／拒绝的影响，然后等待。确认交互处于待处理状态且可见。接受或拒绝后，审查者会恢复工作、记录决定，并使用原生的批准／请求修改流程。不要将操作员添加为审查者／审批者，不要伪造正式审批，也不要代替操作员通过 CLI 完成最终处理。
6. 仅在静止状态下纠正。 对于已批准的重大纠正，先中断或取消一次，然后等待所有正在运行的任务、交互恢复尝试、进程恢复、评论重试和相关恢复操作全部结束。之后才能取消分配、修复问题／配置、核实修正后的状态，并重新分配一次。切勿中断后立即取消分配并重新分配。

硬性规则：Paperclip 报告 wake queued、任务已排队／正在运行或 workspace ready 后，切换为只读观察，除非 Paperclip 明确报告派发被跳过或失败。

变更规则

可自由读取。创建、更新、删除、分配、签出、批准、拒绝、安装或附加任何内容到 Paperclip 前，都必须先询问。分配本身已足以完成派发；不要手动调用 heartbeat 或 resume，也不要伪造另一次唤醒。唤醒已排队或任务正在运行后，必须保持只读，直到任务完成，或已明确批准的纠正操作进入静止状态。

破坏性变更必须获得特别明确的批准：删除、取消、削减预算、更改凭据／运行时、拒绝审批，以及停用／终止 Agent。