flows-external-app-submit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Flows External App Submit

Flows外部应用提交

This is step 4 (final) of the Flows app certification flow:

flows-app-brief  →  build  →  flows-code-review  →  flows-design-review  →  flows-external-app-submit (this skill)

This skill does not rerun any review. It verifies the artifacts from the prior three steps and only then invokes the CLI submit command.

这是Flows应用认证流程的第4步（最终步骤）：

flows-app-brief  →  build  →  flows-code-review  →  flows-design-review  →  flows-external-app-submit（本技能）

本技能不会重新执行任何评审。它只会验证前三个步骤生成的成果，只有验证通过后才会调用CLI提交命令。

Preconditions (show these to the user first)

前置条件（先展示给用户）

Before doing anything, print this checklist so the user knows exactly what is being verified:

```
App-Brief.md
```
exists at repo root and all required frontmatter fields are populated.

The latest

reviews/code-review/feedback-round-<N>/code-review-report.md

is committed to git and reports Must Fix open: 0
.

The latest

reviews/design-review/feedback-round-<N>/design-review-report.md

is committed to git and reports Average score: X.X
with X.X ≥ 3.8.

Certification artifacts are committed —
```
apps submit
```
uses
```
git archive HEAD
```
and silently excludes uncommitted files.
A deploy bundle exists in
```
.cognite-bundles/
```
and is not older than HEAD.

在执行任何操作前，先打印以下检查清单，让用户清楚了解需要验证的内容：

```
App-Brief.md
```
存在于代码仓库根目录，且所有必填的前置元数据字段已填写完整。

Step 0 — Air-hatch preflight (offer stubs if reviews are missing)

步骤0 — 应急预检查（若缺少评审报告则提供占位文件选项）

App-Brief.md

is non-negotiable — it captures the value case the certification reviewer reads first. The code and design reviews, however, can be air-hatched with a clear "SKIPPED" status that the reviewer will see and act on. Use this when the user wants to submit without spending the 20+ minutes each review takes.

Probe for each review artifact via

git ls-files

bash

git ls-files 'reviews/code-review/'   | grep -q 'code-review-report.md'   && echo code_present   || echo code_missing
git ls-files 'reviews/design-review/' | grep -q 'design-review-report.md' && echo design_present || echo design_missing

Both reports present → skip Step 0, continue at Step 1.
```
App-Brief.md
```
missing → continue to Step 1, which fails with the standard "Run
```
flows-app-brief
```
first" message. The air-hatch does not cover App-Brief.
Either review missing → offer the air-hatch via
```
AskQuestion
```
:

"Review artifacts missing: <list which>. Choose:
Run real reviews — exit here; user runs
flows-code-review
/
flows-design-review
first (~20 min each). Recommended for first-time submissions.
Quick submit (stubs) — write SKIPPED stub reports for the missing reviews. The Cognite certification reviewer will see the SKIPPED status and request real reviews before approval, but you can submit now.

Cancel — stop without doing anything."

On Run real reviews: print the next-step command (

flows-code-review

and/or

flows-design-review

) and exit.

On Cancel: exit.

On Quick submit: for each missing review, write the stub using the templates in "Stub templates" at the end of this skill:

reviews/code-review/feedback-round-0/code-review-report.md

reviews/design-review/feedback-round-0/design-review-report.md

Round 0 is intentional — real review skills start at

feedback-round-1

. When the user later runs a real review,

sort -V | tail -1

picks the higher round number, so the stub is automatically superseded without manual cleanup.

After writing the stubs, tell the user:

"Stub reports written. Commit them along with
App-Brief.md
, then re-run this skill:
git add App-Brief.md reviews/
git commit -m 'chore: certification artifacts (reviews skipped)'"

Exit. The user re-runs the skill after committing.

App-Brief.md

是必不可少的 — 它记录了认证评审员首先会查看的价值案例。不过，代码和设计评审可以通过生成明确标记为“SKIPPED（已跳过）”的占位报告来应急提交，评审员会看到该状态并采取相应措施。当用户希望跳过每次评审所需的20多分钟直接提交时，可以使用此选项。

通过

git ls-files

检查是否存在各评审报告：

bash

git ls-files 'reviews/code-review/'   | grep -q 'code-review-report.md'   && echo code_present   || echo code_missing
git ls-files 'reviews/design-review/' | grep -q 'design-review-report.md' && echo design_present || echo design_missing

两个报告均存在 → 跳过步骤0，继续执行步骤1。
```
App-Brief.md
```
缺失 → 继续执行步骤1，此时会触发标准错误提示：“请先执行
```
flows-app-brief
```
”。应急选项不覆盖App-Brief的缺失情况。
任一评审报告缺失 → 通过
```
AskQuestion
```
提供应急选项：

"缺失评审成果：<列出缺失的项>。请选择：
执行真实评审 — 退出当前流程；用户需先执行
flows-code-review
和/或
flows-design-review
（每项约20分钟）。首次提交推荐选择此选项。
快速提交（使用占位文件） — 为缺失的评审生成标记为SKIPPED的占位报告。Cognite认证评审员会看到SKIPPED状态，并在批准前要求提交真实评审报告，但你可以现在提交。

取消 — 终止操作，不执行任何内容。"

若选择执行真实评审：打印下一步命令（

flows-code-review

和/或

flows-design-review

）并退出。

若选择取消：直接退出。

若选择快速提交：为每个缺失的评审使用本技能末尾“占位文件模板”中的模板生成占位报告：

reviews/code-review/feedback-round-0/code-review-report.md

reviews/design-review/feedback-round-0/design-review-report.md

使用round 0是有意为之 — 真实评审技能从

feedback-round-1

开始。当用户后续执行真实评审时，

sort -V | tail -1

会选取编号更高的评审轮次，占位报告会自动被覆盖，无需手动清理。

生成占位报告后，告知用户：

"已生成占位报告。请将它们与
App-Brief.md
一起提交，然后重新执行本技能：
git add App-Brief.md reviews/
git commit -m 'chore: certification artifacts (reviews skipped)'"

退出流程。用户提交后需重新执行本技能。

Step 1 — Verify App-Brief.md

步骤1 — 验证App-Brief.md

bash

test -f App-Brief.md

If missing → fail with: "Run
flows-app-brief
first to create the App-Brief.md."

Parse the YAML frontmatter (the block between the first

---

and the next

---

at the top of the file). Required keys that must be present and non-empty:

```
appName
```
```
customer
```
```
tier
```
```
owner
```
```
userRole
```
```
currentProblem
```
```
oneSentenceStory
```
```
successCriteria
```
```
userEvidence
```

If any are missing or empty → fail with the list of missing fields and: "Re-run
flows-app-brief
to complete the brief."

Optional (not blocking):

userCount

businessValue

milestones

repoUrl

bash

test -f App-Brief.md

若文件缺失 → 触发错误："请先执行
flows-app-brief
生成App-Brief.md。"

解析文件顶部第一个

---

和下一个

---

之间的YAML前置元数据块。必须存在且非空的必填字段包括：

```
appName
```
```
customer
```
```
tier
```
```
owner
```
```
userRole
```
```
currentProblem
```
```
oneSentenceStory
```
```
successCriteria
```
```
userEvidence
```

若任何字段缺失或为空 → 触发错误，列出缺失字段并提示："请重新执行
flows-app-brief
完成该文档。"

可选字段（不影响验证）：

userCount

、

businessValue

、

milestones

、

repoUrl

。

Step 2 — Verify code review

步骤2 — 验证代码评审

Find the latest committed round report:

bash

git ls-files 'reviews/code-review/' | grep 'code-review-report.md' | sort -V | tail -1

If no result → fail with: "Run
flows-code-review
first, then commit the artifacts."

Parse the Summary block from that

code-review-report.md

If the Summary block contains a line matching

^- Status: SKIPPED$

→ mark this check as SKIPPED (not PASS, not FAIL) and skip the numeric check. The stub came from the Step 0 air-hatch; the reviewer will see the SKIPPED status.

Otherwise, it must contain a line matching this exact regex:

^- Must Fix open: (\d+)$

If the integer is

→ pass. Otherwise → fail with: "Open Must Fix items remain in the latest
code-review-report.md
. Re-run
flows-code-review
until
Must Fix open: 0
."

If neither the Status nor the Must Fix line is present → fail with: "Latest code review report is missing the Summary block. Re-run
flows-code-review
."

查找最新提交的评审轮次报告：

bash

git ls-files 'reviews/code-review/' | grep 'code-review-report.md' | sort -V | tail -1

若无结果 → 触发错误："请先执行
flows-code-review
，然后提交相关成果。"

解析该

code-review-report.md

中的摘要块。

若摘要块中包含匹配

^- Status: SKIPPED$

的行 → 将此检查标记为SKIPPED（已跳过），跳过数值检查。该占位报告来自步骤0的应急选项；评审员会看到SKIPPED状态。

否则，摘要块中必须包含匹配以下正则表达式的行：

^- Must Fix open: (\d+)$

若整数为

→ 验证通过。否则 → 触发错误："最新的
code-review-report.md
中仍存在未解决的Must Fix项。请重新执行
flows-code-review
直至
Must Fix open: 0
。"

若摘要块中既无Status行也无Must Fix行 → 触发错误："最新的代码评审报告缺失摘要块。请重新执行
flows-code-review
。"

Step 3 — Verify design review

步骤3 — 验证设计评审

Find the latest committed round report:

bash

git ls-files 'reviews/design-review/' | grep 'design-review-report.md' | sort -V | tail -1

If no result → fail with: "Run
flows-design-review
first, then commit the artifacts."

Parse the Summary block from that

design-review-report.md

If the Summary block contains a line matching

^- Status: SKIPPED$

→ mark this check as SKIPPED (not PASS, not FAIL) and skip the numeric check. The stub came from the Step 0 air-hatch; the reviewer will see the SKIPPED status.

Otherwise, it must contain a line matching:

^- Average score: (\d+(?:\.\d+)?)$

If the number is ≥ 3.8 → pass. Otherwise → fail with: "Design review average is below the launch threshold (3.8). Address the Must Fix and Should Fix items in the latest design-review-report.md and re-run
flows-design-review
in a new feedback round."

查找最新提交的评审轮次报告：

bash

git ls-files 'reviews/design-review/' | grep 'design-review-report.md' | sort -V | tail -1

若无结果 → 触发错误："请先执行
flows-design-review
，然后提交相关成果。"

解析该

design-review-report.md

中的摘要块。

若摘要块中包含匹配

^- Status: SKIPPED$

的行 → 将此检查标记为SKIPPED（已跳过），跳过数值检查。该占位报告来自步骤0的应急选项；评审员会看到SKIPPED状态。

否则，摘要块中必须包含匹配以下正则表达式的行：

^- Average score: (\d+(?:\.\d+)?)$

若数值**≥ 3.8** → 验证通过。否则 → 触发错误："设计评审平均分低于上线阈值（3.8）。请处理最新design-review-report.md中的Must Fix和Should Fix项，并在新的反馈轮次中重新执行
flows-design-review
。"

Step 4 — Verify certification artifacts are committed

步骤4 — 验证认证成果已提交

apps submit

uses

git archive HEAD

— uncommitted files are silently excluded from the source archive. Check that the three certification artifacts are tracked:

bash

git ls-files --error-unmatch App-Brief.md 2>/dev/null
git ls-files --error-unmatch "<latest-code-review-report-path>" 2>/dev/null
git ls-files --error-unmatch "<latest-design-review-report-path>" 2>/dev/null

If any of these files is not committed → BLOCK with:

"The following certification files are not committed to git.
apps submit
uses
git archive HEAD
and will silently omit them from the source archive — the reviewer will not see them.\n\nPlease run:\n git add <missing files>\n git commit -m 'chore: add certification artifacts'\n\nThen re-run this skill."

If all certification artifacts are committed but there are other uncommitted changes in the working tree → WARN (do not block):

"You have uncommitted changes outside the certification artifacts.
apps submit
uses
git archive HEAD
— those changes will not appear in the submitted source archive. If they should be part of certification, commit them first."

apps submit

命令使用

git archive HEAD

— 未提交的文件会被自动排除在源码压缩包之外。检查三个认证成果是否已被git追踪：

bash

git ls-files --error-unmatch App-Brief.md 2>/dev/null
git ls-files --error-unmatch "<latest-code-review-report-path>" 2>/dev/null
git ls-files --error-unmatch "<latest-design-review-report-path>" 2>/dev/null

若任一文件未提交 → 阻止执行并提示：

"以下认证文件未提交至git。
apps submit
使用
git archive HEAD
，会自动将它们排除在源码压缩包之外 — 评审员将无法看到这些文件。\n\n请执行：\n git add <缺失的文件>\n git commit -m 'chore: add certification artifacts'\n\n然后重新执行本技能。"

若所有认证成果已提交，但工作区中存在其他未提交的变更 → 发出警告（不阻止执行）：

"你有未提交的非认证相关变更。
apps submit
使用
git archive HEAD
— 这些变更不会出现在提交的源码压缩包中。如果它们需要纳入认证范围，请先提交。"

Step 5 — Verify deploy bundle

步骤5 — 验证部署包

bash

ls .cognite-bundles/*.zip 2>/dev/null | head -1

If no bundle exists → WARN (do not block): "No deploy bundle found in
.cognite-bundles/
. Run
npx @cognite/cli apps deploy
first so the submitted source archive and deployed bundle come from the same code."

If a bundle exists, check whether it pre-dates HEAD:

bash

bundle=$(ls -1t .cognite-bundles/*.zip 2>/dev/null | head -1)
if [ -n "$bundle" ]; then
  bundle_mtime=$(stat -f %m "$bundle" 2>/dev/null || stat -c %Y "$bundle")
  head_time=$(git log -1 --format=%ct HEAD)
  if [ "$bundle_mtime" -lt "$head_time" ]; then
    echo "WARN"
  fi
fi

If the bundle is older than HEAD → WARN (do not block):

"The deploy bundle in
.cognite-bundles/
is older than the current HEAD commit. The certification reviewer compares the deployed bundle against the submitted source — if you committed changes after your last deploy, they won't match. Re-run
npx @cognite/cli apps deploy
before submitting. (
npm run build
alone does not refresh the bundle — only
apps deploy
does.)"

bash

ls .cognite-bundles/*.zip 2>/dev/null | head -1

若无部署包 → 发出警告（不阻止执行）："在
.cognite-bundles/
目录下未找到部署包。请先执行
npx @cognite/cli apps deploy
，确保提交的源码压缩包与部署包来自同一代码版本。"

若存在部署包，检查其生成时间是否早于HEAD提交：

bash

bundle=$(ls -1t .cognite-bundles/*.zip 2>/dev/null | head -1)
if [ -n "$bundle" ]; then
  bundle_mtime=$(stat -f %m "$bundle" 2>/dev/null || stat -c %Y "$bundle")
  head_time=$(git log -1 --format=%ct HEAD)
  if [ "$bundle_mtime" -lt "$head_time" ]; then
    echo "WARN"
  fi
fi

若部署包早于HEAD提交 → 发出警告（不阻止执行）：

".cognite-bundles/

目录下的部署包早于当前HEAD提交。认证评审员会将部署包与提交的源码进行比对 — 如果你在上次部署后提交了变更，两者将不匹配。请在提交前重新执行

npx @cognite/cli apps deploy

。（仅执行

npm run build

不会更新部署包 — 只有

apps deploy`会更新。）"

Step 6 — Print pass/fail table

步骤6 — 打印验证结果表

Print a table like:

Check                                  Result
-----                                  ------
App-Brief.md complete                  PASS / FAIL — reason
Code review Must Fix open: 0           PASS / FAIL / SKIPPED — reason
Design review average ≥ 3.8            PASS / FAIL / SKIPPED — reason
Certification artifacts committed      PASS / FAIL — reason
Deploy bundle present and current      PASS / WARN — reason

SKIPPED

only applies to the code and design review rows and only when Step 0's air-hatch wrote a stub. Render SKIPPED rows with the note

SKIPPED — user opted out via Step 0 air-hatch

If any check is FAIL: stop here. Do not run the CLI. Print the precise next-step skill the user should run. SKIPPED rows do not block — they pass through to Step 7, which adds an explicit confirmation.

打印如下格式的表格：

检查项                                  结果
-----                                  ------
App-Brief.md已完成                      PASS / FAIL — 原因
代码评审无Must Fix项                   PASS / FAIL / SKIPPED — 原因
设计评审平均分≥3.8                     PASS / FAIL / SKIPPED — 原因
认证成果已提交                          PASS / FAIL — 原因
部署包存在且为最新版本                  PASS / WARN — 原因

SKIPPED（已跳过）

仅适用于代码和设计评审行，且仅当步骤0的应急选项生成了占位报告时才会出现。已跳过的行需标注说明

SKIPPED — 用户通过步骤0应急选项选择跳过

。

若任一检查项结果为FAIL：终止流程。不执行CLI命令。打印用户应执行的具体下一步技能。SKIPPED行不会阻止流程 — 会进入步骤7，此时会添加明确的确认提示。

Step 7 — Confirm and submit

步骤7 — 确认并提交

If any check is

SKIPPED

, prepend an explicit warning to the confirm prompt:

"WARNING — the following reviews are SKIPPED: <list>. The Cognite certification reviewer will see the SKIPPED status in the submitted reports and will request a real review before approval. Proceed with submit anyway?"

Otherwise (all PASS, warnings OK), use the standard confirm prompt:

"All certification checks passed. Run
npx @cognite/cli apps submit
now? This will zip the repo and pre-populate the Zendesk submission form."

yes

bash

npx @cognite/cli@latest apps submit

Stream the output to the user.

若有检查项结果为

SKIPPED

，在确认提示前添加明确警告：

"警告 — 以下评审已被跳过：<列出跳过的项>。Cognite认证评审员会在提交的报告中看到SKIPPED状态，并在批准前要求提交真实评审报告。是否仍继续提交？"

若所有检查项均为PASS（警告不影响），使用标准确认提示：

"所有认证检查已通过。是否现在执行
npx @cognite/cli apps submit
？此命令将压缩代码仓库并预填充Zendesk提交表单。"

若用户选择

yes

：

bash

npx @cognite/cli@latest apps submit

将命令输出实时展示给用户。

Step 8 — Post-submit handoff

步骤8 — 提交后交接

When this skill invokes

apps submit

via

Bash

, the CLI runs non-interactively (

process.stdout.isTTY === false

) and skips its auto-open-browser / reveal-in-file-manager step. The CLI still prints the file list, screen-recording prompt, and Zendesk URL — but the user must act on them manually.

After the CLI finishes, print this to the user:

The CLI ran non-interactively so it didn't open the browser or file manager. To finish:
Open the Zendesk URL from the CLI output above. The URL requires a sign-in on
support.cognite.com
— create an account there if you don't have one, then revisit the link.
Open
dist/submit/
in your file manager and drop in a short screen recording of the certified user journey.
Attach every file in
dist/submit/
(source archive, deploy bundle, screen recording) to the Zendesk ticket.
Push your commits if the branch is ahead of origin.

Then run

git status --short --branch

and surface the ahead/behind count explicitly under step 4 if the branch is ahead of origin.

当本技能通过

Bash

调用

apps submit

时，CLI会以非交互模式运行（

process.stdout.isTTY === false

），并跳过自动打开浏览器/在文件管理器中显示的步骤。CLI仍会打印文件列表、屏幕录制提示和Zendesk链接 — 但用户需手动操作。

CLI执行完成后，向用户打印以下内容：

CLI以非交互模式运行，因此未打开浏览器或文件管理器。请完成以下步骤：
打开CLI输出中的Zendesk链接。该链接需要在
support.cognite.com
登录 — 若你没有账号，请先注册，然后再访问该链接。
在文件管理器中打开
dist/submit/
目录，添加一段简短的认证用户旅程屏幕录制视频。
将
dist/submit/
目录下的所有文件（源码压缩包、部署包、屏幕录制视频）附加到Zendesk工单中。
如果当前分支领先于远程分支，请推送你的提交。

然后执行

git status --short --branch

，若分支领先于远程分支，在步骤4下明确显示领先/落后的提交数量。

Stub templates (used by Step 0 air-hatch)

占位文件模板（步骤0应急选项使用）

When the user picks Quick submit (stubs) in Step 0, write the missing reports using these exact templates. Create the parent directory first if it does not exist.

当用户在步骤0中选择**快速提交（使用占位文件）**时，使用以下精确模板生成缺失的报告。若父目录不存在，需先创建。

Code review stub

代码评审占位报告

Path:

reviews/code-review/feedback-round-0/code-review-report.md

markdown

undefined

路径：

reviews/code-review/feedback-round-0/code-review-report.md

markdown

undefined

Code Review Report — Round 0

代码评审报告 — 第0轮

Status: SKIPPED — user opted out of

flows-code-review

at submit time.

The Cognite certification reviewer will see this SKIPPED status and request a real

flows-code-review

run before approval. Re-run

flows-code-review

to replace this stub with a real round.

状态：已跳过 — 用户在提交时选择跳过

flows-code-review

。

Cognite认证评审员会看到此SKIPPED状态，并在批准前要求执行真实的

flows-code-review

。重新执行

flows-code-review

即可用真实评审报告替换此占位文件。

Summary

摘要

Status: SKIPPED
Must Fix open: 0
Should Fix open: 0
Nit open: 0

undefined

状态：已跳过
Must Fix未解决项：0
Should Fix未解决项：0
建议项未解决：0

undefined

Design review stub

设计评审占位报告

Path:

reviews/design-review/feedback-round-0/design-review-report.md

markdown

undefined

路径：

reviews/design-review/feedback-round-0/design-review-report.md

markdown

undefined

Design Review Report — Round 0

设计评审报告 — 第0轮

Status: SKIPPED — user opted out of

flows-design-review

walkthrough at submit time.

The Cognite certification reviewer will see this SKIPPED status and request a real

flows-design-review

walkthrough before approval. Re-run

flows-design-review

to replace this stub with a real round.

状态：已跳过 — 用户在提交时选择跳过

flows-design-review

评审流程。

Cognite认证评审员会看到此SKIPPED状态，并在批准前要求执行真实的

flows-design-review

评审流程。重新执行

flows-design-review

即可用真实评审报告替换此占位文件。

Summary

摘要

Status: SKIPPED
Average score: N/A

undefined

状态：已跳过
平均分：不适用

undefined