forge-onboarding

Forge 入门

通过一次连贯的流程，引导首次构建者从零开始，构建并部署、安装 Rovo Agent——Forge Guru。从一段介绍开始，通过一次设置关卡，完成一次构建。保持 Agent 简洁；自助阅读者一开始就能获得热情欢迎，工作坊参与者则能体验适合演示文稿的流程。

按阶段加载指南

只阅读当前阶段的参考资料。不要预先加载整个流程、README、资源或评估案例。在状态和转换中使用以下固定阶段名称。

阶段	阅读时机	参考资料	推进依据
welcome	开始新的引导会话时	使用下方的欢迎脚本	用户表示准备开始
setup	开始新流程时（或工具／登录失败时）	设置	已验证工具和登录；已收集开发空间、测试站点和应用目录；已获得捆绑授权
build	执行端到端构建时	构建	已在获授权的目标上成功完成脚手架搭建、自定义、部署和安装
celebrate	报告成功时	庆祝	用户知道在哪里找到 Guru，并获得了可尝试的示例提示词
next-steps	结束教程时	后续步骤	已分享迭代循环和同类技能的使用路径
恢复	需要调查已发现的故障时	恢复	故障已解决或已报告具体阻碍
平台检查	某阶段需要获取当前 CLI、架构或端点信息时	平台约定	已验证相关信息并记录证据

默认转换：welcome → setup → build → celebrate → next-steps。 恢复后返回被中断的阶段。退出会立即停止工作流。

保留精简的会话记录

在对话上下文中保留以下值，并在完成重要操作后更新：

状态	记录内容
进度位置	阶段、上一个已完成的操作、下一个操作
本地环境	OS／Shell、Node 和 CLI 版本、身份验证结果、已接受的警告
本地目标	绝对父目录和应用路径；目标位置在创建前是否已存在
Atlassian 目标	账户、Developer Space 名称／ID、确切站点、产品、环境
身份信息	已注册的 app.id、运行时、实际 Agent 键名／名称、处理程序和操作名称
进度	已创建脚手架；已应用 Guru 资源；已安装依赖项；lint 结果；已确认部署和安装
实时证据	Guru 已回答真实的 Forge 问题；站点上 Agent 的链接
授权	单项捆绑授权：确切的已批准操作、目标和影响

不要存储凭据。除非用户提出要求，否则不要创建进度文件。

跳过、退出和恢复

• 尊重“跳过介绍”“少讲解一点”和“退出”等要求。
• 默认流程中，welcome 和 setup 是仅有的面向用户的暂停点。 不要在只读检查之间或 build 步骤之间添加其他“准备好了吗？”提示。
• 恢复时，沿用已知结果。仅运行下一条命令所需的未完成检查。 版本警告不代表可执行文件运行失败：解释一次，并尊重用户的选择。
• 在 setup 阶段收集目标。由于 build 会安装 Guru，因此必须提供测试站点。 如果用户没有站点，请遵循设置中的开通流程。
• 跳过教学并不代表已提供凭据、已选择明确的目标、已接受条款，或已授权部署或安装。
• 退出时，停止调用工具和提问。根据已记录的证据，简要说明已发生的更改和剩余事项。 不要继续推荐教程的下一步。
• 恢复时，沿用上下文并检查应用。视情况检查身份信息和安装状态。 绝不要在现有应用上重新运行脚手架搭建，也不要无故重放已完成的编辑、安装、授权或教学内容。

保留执行边界

1. 执行每个步骤时，简要说明当前操作。build 期间每条命令用一行说明；对于相互独立的检查，可合并说明。报告实际观察到的结果，而非预期的成功。
2. 不要在聊天或文件中泄露机密信息。登录和意外出现的凭据提示应交由用户的交互式终端处理；绝不要要求用户在这里粘贴 API 令牌。
3. 一次性打包授权。 在 setup 结束时，完整说明操作范围——在准确指定的目录中搭建脚手架、应用 Guru 资源、部署到 development，并安装到准确指定的站点——然后一次性征求批准。获得批准后，在 build 中执行全部四项操作，不要再次征求批准。本地引导和只读检查无需额外审批。
4. 条款与账单同意和“构建我的应用”是两回事。同级创建辅助工具目前会传入 --accept-terms。将此项作为打包授权的一部分予以披露；不要将脚手架搭建的同意与条款同意视为彼此独立。
5. 通过 forge create（经由同级辅助工具）注册应用。绝不要编造应用 ID 或使用未注册的替代项。
6. 默认使用 development，并在与环境相关的命令中明确写出。development 环境并不意味着真实站点数据无害；优先使用测试站点并限制权限。使用其他环境或站点需要单独明确授权范围。
7. 保留用户文件和应用身份。在搭建脚手架之前检查目标位置。绝不要删除失败的脚手架、覆盖现有目录，或在未确认准确目标及后果的情况下重新创建应用。保留部分输出以便诊断。
8. 在部署前依据当前官方指南和 forge lint 进行验证。必要时阅读相关的平台契约部分；不要臆造适用于所有情况的限制、将过时的固定事实视为永久有效，或在同一会话中重复进行没有变化的查询。
9. 不要执行用户未要求的源代码管理操作。本教程无需提交、推送或初始化；只读检查可用于协助保护现有内容。
10. 部署和安装不能证明 Guru 可正常工作。在 celebrate 中记录 Guru 对实时查询的回答，作为与安装成功相互独立的证据。

依赖项和署名

同级的 forge-app-builder 提供 scripts.create_forge_app。搭建脚手架之前，先运行其 --help 冒烟测试，并按照 setup 阶段的指示遵循其创建参考文档。 此辅助工具需要 Python；请使用 python3 或已验证可用的本地 python 可执行文件。不要仅为向用户问候而安装依赖项。

对于由 Agent 直接运行的 Forge 命令，请设置 ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-onboarding。支持时使用环境映射；否则按照用户的 shell 语法操作，参见 Setup。持久 shell 可设置一次导出变量；每个新 shell 都必须重新设置。排除用户自行运行的登录命令。 同级辅助工具目前会将其调用标记为 forge-app-builder；不要声称调用方的标记会通过该辅助工具保留下来，也不要将修改其他技能的行为作为教程运行的一部分。

欢迎脚本

使用这段开场白开启新的引导会话（约 150 个词——简洁有力，让没有演示文稿的读者也能自行了解）。自然调整措辞；按顺序保留各个要点。

欢迎参加 Forge 入门引导。 Forge 是 Atlassian 的平台，可用于构建扩展 Jira、Confluence、Bitbucket 等产品的应用——你无需管理服务器。Forge 提供多种模块类型，用于实现不同类型的扩展；今天我们将聚焦 Rovo Agent 模块，它能让你构建运行在 Atlassian 产品内的对话式 Agent。

你将构建 Forge Guru——一个运行在你的开发者站点上、能回答你提出的任何 Forge 问题的 Rovo Agent。构建首个真正的 Forge 应用时，它就像你的专属 Forge 指南。

整个流程如下：我会检查你的环境，收集你的开发空间和测试站点，然后从头到尾完成 Guru 的脚手架搭建、自定义、部署和安装——大约需要 10 分钟。你在设置阶段批准计划后，我就会一气呵成地完成构建。所有操作都在测试站点上进行，不会涉及真实数据或计费。

准备好开始了吗？

只在此处询问一次是否准备就绪。之后不要重复询问。

简明讲解

欢迎结束后，讲解要简洁。每条命令前用一句话说明。build 期间用简短状态提示（“正在搭建脚手架……”“正在部署……”）。流程中不要穿插概念讲解；如果用户询问“X 是什么”或“刚才做了什么”，请简短回答，然后回到流程。提出问题时，明确提示用户如何回复；不要每次更新都附带问题。

完成与交接

默认的成功标准是：Forge Guru 已部署并安装到用户的测试站点，能回答一个真实的 Forge 问题并提供可用的官方链接。如跳过了实时检查，请明确说明。Guru 的可用时间取决于站点的生命周期和应用安装状态，并非“永久可用”。

后续功能开发使用 forge-app-builder，持续诊断使用 forge-debugger，发布审核使用 forge-app-review，连接器相关工作使用 forge-connector。结束或讨论这些后续方向时，请阅读 后续步骤。