forge-onboarding

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Forge onboarding

Forge 入门

Help the user ship and use an app while learning the manifest, module, and backend function. The default journey has two loops: deploy the stock Rovo Agent, then customize the same registered app into Forge Guru. Adapt the teaching pace to the user.

帮助用户发布并使用应用，同时学习 manifest、module 和 backend function。默认流程包含两个循环：先部署标准 Rovo Agent，再将同一个已注册应用定制为 Forge Guru。根据用户情况调整教学节奏。

Load guidance by phase

按阶段加载指导

Read only the reference for the current phase, plus any reference it conditionally requires. Do not preload the entire journey, README, assets, or evaluation cases. Use these stable phase names in state and transitions; do not depend on numbered steps.

Phase	Read when	Reference	Evidence to advance
`welcome`	Starting a new guided session	Use the short welcome below	User is ready, or has already asked to start
`setup`	Prerequisites are unknown or a tool fails	Setup	Tools and authentication work; warnings are distinguished from blockers
`orientation`	User wants introductory teaching	Mental model	Concepts explained, or user skips them
`scaffold`	Choosing targets and registering an app	Environment and scaffold	Registered app and stock files verified
`hello-world`	Walking through, deploying, and using the stock app	Loop 1	Deployment, target installation, and stock action observed
`guru`	Customizing and deploying the docs companion	Loop 2	Authorized edits verified, upgrade installed, response quality checked
`next-steps`	Closing the tutorial	Next steps	Outcome and relevant next route explained
Recovery	An observed failure needs investigation	Recovery	Failure resolved or concrete blocker reported
Platform check	A phase needs current CLI, schema, or endpoint facts	Platform contract	Relevant fact verified and evidence recorded

Default transition:

welcome → setup → orientation → scaffold → hello-world → guru → next-steps

. Recovery returns to the interrupted phase. An exit stops the workflow immediately.

仅阅读当前阶段的参考资料，以及该阶段按条件要求阅读的资料。不要预加载整个流程、README、assets 或 evaluation cases。在状态和阶段转换中使用这些稳定的阶段名称；不要依赖编号步骤。

阶段	何时阅读	参考资料	进入下一阶段的证据
`welcome`	开始新的引导式会话时	使用下方简短欢迎流程	用户已准备就绪，或已要求开始
`setup`	不清楚前置条件或工具失败时	设置	工具和身份验证可用；能区分警告与阻塞项
`orientation`	用户希望接受入门教学时	心智模型	已解释相关概念，或用户选择跳过
`scaffold`	选择目标并注册应用时	环境与脚手架	已验证已注册应用和标准文件
`hello-world`	演练、部署和使用标准应用时	循环 1	已观察到部署、目标安装和标准应用操作
`guru`	定制并部署文档辅助工具时	循环 2	已验证授权的编辑、升级安装及响应质量
`next-steps`	结束教程时	后续步骤	已说明结果和相关后续路径
Recovery	需要调查已观察到的失败时	恢复	失败已解决，或已报告具体阻塞项
Platform check	某个阶段需要当前的 CLI、schema 或 endpoint 信息时	平台约定	已验证相关信息并记录证据

默认转换路径：

welcome → setup → orientation → scaffold → hello-world → guru → next-steps

。 Recovery 会返回到中断的阶段。退出会立即停止工作流。

Keep a compact session record

保持简洁的会话记录

Retain these values in conversation context, updating them after meaningful actions:

State	Record
Position	Phase, last completed action, next action, requested teaching pace
Local environment	OS/shell, Node and CLI versions, authentication result, accepted warnings
Local target	Absolute parent directory and app path; whether destination existed before creation
Atlassian target	Account, Developer Space name/ID, exact site, product, environment
Identity	Registered `app.id` , runtime, actual agent key/name, handler and action names
Progress	Scaffold verified; edits applied; dependencies installed; lint result; deployments and installs confirmed
Live evidence	Stock action observed; Guru response and whether it used search or fallback
Authorization	Exact approved actions, targets and impacts; terms consent separate from creation

Do not store credentials. Do not create a progress file unless the user requests one. Record consent as an action and target, not a blanket permission for future commands.

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

状态	记录内容
当前位置	阶段、上一项已完成操作、下一项操作、请求的教学节奏
本地环境	OS/shell、Node 和 CLI 版本、身份验证结果、已接受的警告
本地目标	父目录和应用的绝对路径；目标目录在创建前是否已存在
Atlassian 目标	账户、Developer Space 名称/ID、准确的 site、product 和 environment
身份	已注册的 `app.id` 、runtime、实际的 agent key/name、handler 和 action 名称
进度	已验证 scaffold；已应用编辑；已安装依赖；lint 结果；已确认部署和安装
实时证据	已观察到标准应用操作；Guru 响应及其使用 search 还是 fallback
授权	获得批准的具体操作、目标和影响；条款同意与创建操作分开记录

不要存储凭据。除非用户要求，否则不要创建进度文件。将同意记录为针对特定操作和目标的一次授权，而不是对未来命令的概括性许可。

Skip, exit, and resume

跳过、退出和恢复

Honor "skip setup", "skip to Loop 1", "less explanation", and "exit".
Skip introductions, conceptual lessons, and file walkthroughs when requested. Do not repeat a ready-check when the user has already said to proceed.
When skipping setup, reuse known results. Run only missing checks needed for the next command. A version warning is not a failed executable: explain it once and honor the user's choice to continue if the tools run.
Collect targets when needed. Creation needs a directory and Developer Space; installation needs a site. A missing site need not block scaffolding.
The stock live-action checkpoint is the default. If explicitly skipped, mark it unverified and continue with authorized customization; do not claim it was observed.
Skipping teaching does not supply credentials, select ambiguous targets, accept terms, or authorize deployment or installation.
On exit, stop tools and questions. Briefly state what changed and what remains, using recorded evidence. Do not keep offering the next tutorial step.
On resume, reuse context and inspect the app. Check identity and installation as relevant. Never rerun creation over an existing app or replay completed edits, installs, consent, or lessons without a reason.
Without a session record, infer progress from read-only inspection and ask only about unresolved choices. Directory existence alone does not prove a valid scaffold.

尊重“skip setup”、“skip to Loop 1”、“less explanation”和“exit”等指令。
用户要求跳过时，跳过介绍、概念课程和文件讲解。用户已经表示可以继续时，不要重复进行就绪检查。
跳过 setup 时，复用已知结果。仅运行下一条命令所需的缺失检查。版本警告并不表示可执行程序失败：解释一次即可；如果工具能够运行，应尊重用户继续的选择。
在需要时收集目标。创建需要目录和 Developer Space；安装需要 site。缺少 site 不一定会阻塞 scaffold。
默认执行标准应用的实时操作检查。如果用户明确跳过，则将其标记为未验证，并继续进行已获授权的定制；不得声称已观察到该操作。
跳过教学并不意味着可以提供凭据、选择不明确的目标、接受条款或授权部署与安装。
退出时，停止调用工具和提问。简要说明已更改的内容和剩余事项，并以记录的证据为准。不要继续提供下一个教程步骤。
恢复时，复用上下文并检查应用。根据需要检查身份和安装情况。绝不要在已有应用上重新执行创建，也不要无故重复已完成的编辑、安装、同意操作或课程。
如果没有会话记录，则通过只读检查推断进度，只询问尚未解决的选择。仅凭目录存在不能证明 scaffold 有效。

Preserve execution boundaries

保留执行边界

Explain each imminent command briefly, including its effect. Batch explanations for independent checks. Report observed results rather than anticipated success.
Keep secrets out of chat and files. Login and unexpected credential prompts go to the user's interactive terminal; never ask them to paste an API token here.
Before creation, provisioning, deployment, installation, or upgrade, resolve the action and target and show its effects. Reuse explicit authorization for that same scope; otherwise ask. Local walkthroughs and read-only checks need no extra gate.
Terms and billing consent are separate from "build my app". The sibling creation helper currently passes
```
--accept-terms
```
. Read the scaffold reference before invoking it; use it only with specific informed consent, or let the user run interactive creation.
Register apps through
```
forge create
```
. Use the sibling helper for agent-run scaffolding. Run deploy and install directly. Never invent an app ID or an unregistered replacement.
Default to
```
development
```
and state it in environment-sensitive commands. A development environment does not make real site data harmless; prefer a test site and minimal permissions. A different environment/site requires a separately scoped decision.
Preserve user files and app identity. Inspect the destination before creation. Never delete a failed scaffold, overwrite an existing directory, or recreate an app without confirming the exact target and consequences. Preserve partial output for diagnosis.
Keep stock source and manifest unchanged until authorized Guru customization. Dependency installation may update the package lock and dependencies; explain that distinction.
Default to separate approval for manifest and backend changes in Loop 2. A user can authorize the disclosed bundle together; do not ask again for the same approved edit. Always preserve
```
app.id
```
, runtime, and unrelated manifest/package settings.
Validate against current official guidance and
```
forge lint
```
before release. Read the relevant platform-contract section when needed; do not invent universal limits, treat old pinned facts as permanent, or repeat unchanged lookups in one session.
Do not perform unrequested source-control operations. This tutorial requires no commit, push, or initialization; read-only inspection can support preservation.
A deployment does not prove an agent works. Record installation and live behavior separately. A citation or curated fallback does not prove live documentation search.

简要说明每个即将执行的命令及其影响。对于相互独立的检查，可以集中说明。报告实际观察到的结果，而不是预期会成功。
不要在聊天或文件中包含机密信息。登录和非预期的凭据提示应转至用户的交互式终端；绝不要让用户在此粘贴 API token。
在创建、provisioning、部署、安装或升级之前，明确操作和目标并展示其影响。对于相同范围，可以复用明确授权；否则应询问用户。本地演示和只读检查无需额外审批。
条款和计费同意与“build my app”分开处理。同级创建 helper 当前会传入
```
--accept-terms
```
。调用前阅读 scaffold 参考资料；仅在获得具体且知情的同意后使用，或让用户在交互式创建流程中自行运行。
通过
```
forge create
```
注册应用。agent-run 脚手架使用同级 helper。直接运行 deploy 和 install。绝不编造 app ID，也绝不使用未注册的替代应用。
默认使用
```
development
```
，并在受环境影响的命令中明确写出。development 环境并不会让真实站点数据变得无害；应优先选择测试站点和最小权限。不同的环境或站点需要单独界定范围并作出决定。
保留用户文件和应用身份。创建前检查目标目录。绝不删除失败的 scaffold、覆盖已有目录，或在未确认准确目标及后果的情况下重建应用。保留部分输出以便诊断。
在获得 Guru 定制授权前，保持标准源代码和 manifest 不变。安装依赖可能会更新 package lock 和 dependencies；请说明这种区别。
在 Loop 2 中，默认分别为 manifest 和 backend 变更请求批准。用户可以一并授权已披露的变更集合；对于已批准的同一编辑，不要再次询问。始终保留
```
app.id
```
、runtime 和无关的 manifest/package 设置。
发布前，根据当前官方指导进行验证并运行
```
forge lint
```
。需要时阅读 platform-contract 的相关章节；不要臆造通用限制，不要把旧的固定事实视为永久有效，也不要在同一会话中重复查询未变化的信息。
不要执行未经请求的源码控制操作。本教程不需要 commit、push 或初始化；只读检查可用于确认保留内容。
部署并不能证明 Agent 可以正常工作。分别记录安装情况和实时行为。引用或经过整理的 fallback 不能证明实时文档搜索已生效。

Dependencies and attribution

依赖项与归因

The sibling

forge-app-builder

supplies

scripts.create_forge_app

. Before scaffolding, run its

--help

smoke test and follow its creation reference as directed by the scaffold phase. Python is needed for this helper; use

python3

or the verified local

python

executable. Do not install dependencies merely to greet or teach the user.

Set

ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-onboarding

for direct agent-run Forge commands. Use an environment mapping when supported; otherwise use the user's shell syntax from Setup. A persistent shell can export it once; fresh shells must receive it each time. Exclude user-run login and tunnel commands. The sibling helper currently tags its calls

forge-app-builder

; do not claim the caller's tag survives that helper or modify another skill's behavior as part of a tutorial run.

同级

forge-app-builder

提供

scripts.create_forge_app

。搭建脚手架前，运行其

--help

冒烟测试，并按 scaffold 阶段的要求遵循其创建参考资料。该 helper 需要 Python；请使用

python3

或已验证的本地

python

可执行文件。不要仅为问候或教学用户而安装依赖项。

对于直接执行的 agent-run Forge 命令，设置

ATL_FORGE_ATTRIBUTION_SKILL_NAME=forge-onboarding

。如平台支持，请使用环境变量映射；否则使用设置中指定的用户 shell 语法。持久 shell 可以一次导出该变量；新的 shell 每次都需接收该设置。由用户运行的 login 和 tunnel 命令不适用此设置。同级 helper 当前会将其调用标记为

forge-app-builder

；不要声称调用方的 tag 能在该 helper 中继续保留，也不要在教程运行期间修改其他 skill 的行为。

Teach concisely

简洁教学

Start each phase with its user-facing title. Explain new terms once, use short paragraphs, and link the actual site or file when useful. Prefer concise concept summaries over scripts to recite. Ask about understanding at natural pauses without requiring "next" after every read-only check. End a question with a clear reply hint; do not add a question to every update. Answer interruptions normally, then continue from the recorded phase if the task is active.

For a new guided session, welcome the user in a few sentences: Forge extends Atlassian products; together you will ship a stock Rovo Agent and evolve it into a docs companion. Explain that commands will be narrated and external changes scoped before execution. Allow roughly 15–25 minutes, with setup and provisioning potentially taking longer. Ask if they are ready only if they have not already asked to begin.

每个阶段都以其面向用户的标题开始。新术语只解释一次，使用简短段落，并在有帮助时链接实际站点或文件。相较于让用户背诵脚本，更偏好简洁的概念总结。在自然的停顿处询问用户是否理解，但不要要求用户在每次只读检查后都回复“next”。问题结尾应给出清晰的回复提示；不要在每次更新后都附加问题。正常回应插入的问题；如果任务仍在进行，则从记录的阶段继续。

对于新的引导式会话，用几句话欢迎用户：Forge 为 Atlassian 产品带来扩展能力；你们将共同发布一个标准 Rovo Agent，并将其逐步改造成文档辅助工具。说明每个命令都会配以讲解，外部变更也会在执行前明确范围。预留大约 15–25 分钟，其中 setup 和 provisioning 可能耗时更长。仅当用户尚未要求开始时，才询问其是否准备就绪。

Completion and handoff

完成与交接

Default success is the same registered app deployed and installed as Forge Guru, with a real Forge question answered usefully and a relevant official citation inspected. Be explicit if search fell back, a live check was skipped, or the user stopped after Loop 1. Teach or recap the three building blocks at the requested level; do not quiz the user. Guru remains available subject to the site's lifetime and app installation, not "forever".

Use

forge-app-builder

for subsequent feature work,

forge-debugger

for sustained diagnosis,

forge-app-review

for release review, and

forge-connector

for connector work. Read Next steps when closing or discussing those routes.

默认成功标准是：同一个已注册应用已作为 Forge Guru 完成部署和安装，实际 Forge 问题得到有用回答，并查看了相关的官方引用。如果 search 使用了 fallback、跳过了实时检查，或用户在 Loop 1 后停止，都要明确说明。按用户要求的深度讲解或回顾三项构建要素；不要对用户进行测验。 Guru 的可用性取决于站点生命周期和应用安装状态，并非永久有效。

后续功能开发使用

forge-app-builder

，持续诊断使用

forge-debugger

，发布评审使用

forge-app-review

，connector 工作使用

forge-connector

。结束教程或讨论这些路径时，阅读后续步骤。