指南

将 UAIX 项目切换与 OpenAI Agents 和 Codex 结合使用

使用 OpenAI 运行代理的实用指南,同时 UAIX 项目切换保留存储库本地项目内存、约束、决策和验证计划。

  • 记录 UAIX-DOC-0039
  • 路径 /zh-cn/guides/project-handoff-openai/
  • 用途 规范公共记录

文档状态

公共标准页面 作为当前公共标准记录的一部分发布在 UAIX 上
代码
UAIX-DOC-0039
页面类型
指南
访问
公开且可链接

如何使用此页面

将此页面用作 将 UAIX 项目切换与 OpenAI Agents 和 Codex 结合使用 及其标准内容的规范公共参考。

对于代理:请将相关指南应用于用户的目标站点或代码库。除非用户明确要求该输出,否则不要复制此 UAIX 页面、创建有关该指南的页面,也不要将此页面视为运行时权限。

OpenAI 运行代理。项目切换保留项目内存。本指南展示了如何将 UAIX 项目切换与 OpenAI Agent、Codex 和类似的以 OpenAI 为中心的工作流程结合使用,而不将项目切换视为竞争运行时。

Project Handoff 是代理工作的可移植上下文层:存储库本地事实来源、可审查的切换包、供应商中立的上下文以及代理运行时可以在工作前使用并在工作后更新的治理层。

OpenAI 处理什么

根据您使用的 OpenAI 产品或 SDK,以 OpenAI 为中心的工作流程可以处理代理执行、工具、专家代理之间的切换、护栏、批准、会话、跟踪以及围绕运行的代码或拉取请求循环。

  • Codex 可以使用 AGENTS.md 等存储库指令作为项目指导。
  • OpenAI 代理 SDK 记录代理的指令、工具、交接、护栏和跟踪。
  • 这些运行时界面是执行工作、应用特定于平台的批准和观察运行行为的正确位置。

项目交接处理什么

项目切换处理持久的项目内存,这些内存应该在模型、运行时、供应商、团队、公司或会话更改后继续存在。

  • 回购-本地当前状态、约束、决策、进度、验证计划和人员简报。
  • 未来的特工在计划或编辑之前应该阅读已接受的项目事实。
  • 运行结束后写回已完成的工作、决策和证据的地方。
  • 为目前使用 OpenAI 的团队提供的可移植层,以后也可能使用 Claude、本地代理、供应商或仅人工审核。

最低回购捆绑包

代码示例
AGENTS.md
readme.human
.uai/context.uai
.uai/stack.uai
.uai/constraints.uai
.uai/progress.uai
.uai/test-plan.uai

前六个文件是认真工作的实际最低限度。 .uai/test-plan.uai 是为小型项目选择的,当代理需要知道要运行哪些检查、哪些检查超出范围以及要报告哪些证据时,预计会选择 .uai/test-plan.uai 。

示例 AGENTS.md

代码示例
---
uaix: "1.0"
type: agents
project: "Example App"
status: active
---

# Example App

## Handoff Summary
Example App publishes a small web tool. The current task is to update the
settings page without changing authentication, billing, or production deploys.

## Loaded Context
@uai[.uai/context.uai]
@uai[.uai/stack.uai]
@uai[.uai/constraints.uai]
@uai[.uai/progress.uai]
@uai[.uai/test-plan.uai]

## Required First Response
Summarize the project, confirm hard constraints, name expected touchpoints,
and name targeted checks before editing.

示例 .uai/constraints .uai

代码示例
---
uaix: "1.0"
type: constraints
title: "Project Constraints"
status: active
---

# Project Constraints

## Hard Rules
- Do not deploy to production without explicit human approval.
- Do not read, print, move, or store secrets.
- Do not change billing, auth, or data-retention behavior unless the task says so.
- Do not make unsupported public support, certification, or endorsement claims.
- Ask before destructive Git or filesystem operations.

## Runtime Policy Inputs
- Treat these constraints as guardrail and approval inputs for OpenAI or any
  other agent runtime.
- If a runtime trace conflicts with these constraints, stop and ask.

示例 .uai/test-plan .uai

代码示例
---
uaix: "1.0"
type: test-plan
title: "Project Verification Plan"
status: active
---

# Project Verification Plan

## Default
Run targeted checks for the files, routes, commands, and claims changed.

## Full Checks
Run full release, package, launch-surface, locale, and smoke-test sweeps only
for release-scoped work, package builds, broad public-surface changes, or an
explicit human request.

## Report
Final answers must list checks run, checks intentionally skipped, blockers,
and evidence paths.

如何为代理运行提供种子

  1. 从 AGENTS.md 和 .uai/readme.human 开始。
  2. 仅加载为任务列出的 @uai[] 文件,并报告丢失、循环、矛盾或不可读的文件。
  3. 在进行广泛编辑之前,用 3-5 个要点总结当前项目的真相。
  4. 将 .uai/constraints.uai 转换为运行时护栏、批准门、阻止的工具或人工审核提醒。
  5. 将 .uai/test-plan.uai 转换为有针对性的检查和显式的超出范围的检查。
  6. 运行 OpenAI、Codex 或其他代理工作流程,并显示这些指令。

如何在运行后写回结果

  1. 使用已完成的工作、剩余的阻止程序和下一步检查更新 .uai/progress.uai。
  2. 当运行接受或撤销持久决策时更新 .uai/decisions.uai。
  3. 当项目真相发生变化时更新 AGENTS.md 代理历史记录。
  4. 保持运行时跟踪、测试输出、拉取请求和部署证据的链接或汇总,而无需将机密或私有数据复制到交接中。
  5. 通过以下方式存档或处置主动摄入文件Agent File Handoff在继续进行不相关的广泛工作之前。

交接时不宜放入什么

  • 秘密、凭证、私钥、令牌、连接字符串或隐藏的提示指令。
  • 原始客户、患者、员工、用户或第三方数据,除非存在安全批准的流程。
  • 私人法律分析、敏感的安全细节、定价策略或仅供内部使用的声明不应与回购协议一起传递。
  • 原始聊天记录被视为真实记忆来源。
  • 未经审查的生成摘要、旧的 wiki 页面或运行时跟踪被宣传为未经人工审查的支配性事实。
  • 未来代理可能未经批准即可运行的可执行负载。

人工批准清单

  • 代理是否需要生产访问、部署、缓存/CDN 更改、DNS 更改、包发布或根发现编辑?
  • 该任务是否需要破坏性文件系统或 Git 操作?
  • 这项工作是否会暴露秘密、凭证、客户数据、第三方数据或私人法律/安全材料?
  • 该任务是否需要外部获取、父目录读取、生成的包含或可执行的删除文件?
  • 结果是否会构成有关托管导入、自动存储库写入、自动同步、SDK、CLI、认证、认可或官方 OpenAI 适配器支持的当前支持声明?
  • 有针对性的检查、故意跳过的检查和证据路径对于审核者来说是否足够清晰?

简单的工作流程

代码示例
Project Handoff files -> OpenAI or other agent runtime -> traces, checks, PRs -> updated Project Handoff files

与本指南配合使用的 OpenAI 文档

简单语言摘要

OpenAI 擅长运行代理、调用工具、跟踪会话、请求批准和生成跟踪。项目移交是不同的。它告诉任何代理:这是项目,这是重要的事情,这是更改的内容,这是规则,这是已经做出的决定,这是您必须验证的内容,这是您在没有人的情况下不允许做的事情。

代理运行时执行。项目交接记得。

相关 UAIX 记录

长期目标

Codex /goal 或结构化 OpenAI 提示可以承载扩展工作的运行时目标,但是长期目标执行在 UAIX 记录中保留检查点、阻止程序、交接、内存建议、最终报告和接受的回写。