flows-external-app-submit

Flows 外部应用提交

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

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

此技能不会重新执行任何审核。它会验证前 3 步生成的产物，然后才调用 CLI 提交命令。

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

在进行任何操作之前，先打印此清单，让用户明确了解将要验证的内容：

1. 仓库根目录存在 App-Brief.md，且所有必填 frontmatter 字段均已填写。
2. 最新的 reviews/code-review/feedback-round-<N>/code-review-report.md 已提交到 git，并且报告显示 Must Fix open: 0。
3. 最新的 reviews/design-review/feedback-round-<N>/design-review-report.md 已提交到 git，并且报告显示 Average score: X.X，其中 X.X ≥ 3.8。
4. 认证产物已提交——apps submit 使用 git archive HEAD，未提交的文件会被静默排除。
5. .cognite-bundles/ 中存在部署包，且其时间不早于 HEAD。

第 0 步 — 快速预检（审核缺失时提供占位报告）

App-Brief.md 是必须的——它记录了认证审核人员首先会查看的价值说明。不过，如果缺少代码审核或设计审核，可以使用状态明确标为“SKIPPED”的占位报告快速通过预检，审核人员会看到并据此采取行动。用户希望提交而不花费每项审核所需的 20 多分钟时，可使用此选项。

使用 git ls-files 检查每份审核产物：

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 步，该步骤会显示标准错误消息“Run flows-app-brief first”。快速通道不适用于 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

第 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)'”

退出。用户提交后重新运行此技能。

第 1 步 — 验证 App-Brief.md

test -f App-Brief.md

如果文件缺失 → 失败并显示：“请先运行 flows-app-brief，以创建 App-Brief.md。”

解析 YAML frontmatter（文件顶部第一个 --- 与下一个 --- 之间的内容）。以下必填键必须存在且非空：

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

如果任何字段缺失或为空 → 显示缺失字段列表，并提示：“请重新运行 flows-app-brief，补全 brief。”

可选字段（不影响流程）：userCount、businessValue、milestones、repoUrl。

步骤 2 — 验证代码审查

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

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

如果没有结果 → 失败，并显示："请先运行 flows-code-review，然后提交这些产物。"

解析该 code-review-report.md 中的 Summary 区块。

如果 Summary 区块包含与 ^- Status: SKIPPED$ 匹配的行 → 将此检查标记为 SKIPPED（既不是 PASS，也不是 FAIL），并跳过数值检查。此存根来自步骤 0 的安全阀；审查者会看到 SKIPPED 状态。

否则，它必须包含与此精确正则表达式匹配的行：

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

如果整数为 0 → 通过。否则 → 失败，并显示："最新的 code-review-report.md 中仍有未解决的 Must Fix 项。请重新运行 flows-code-review，直到 Must Fix open: 0。"

如果既没有 Status 行，也没有 Must Fix 行 → 失败，并显示："最新的代码审查报告缺少 Summary 区块。请重新运行 flows-code-review。"

步骤 3 — 验证设计审查

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

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

如果没有结果 → 失败，并显示："请先运行 flows-design-review，然后提交这些产物。"

解析该 design-review-report.md 中的 Summary 区块。

如果 Summary 区块包含与 ^- Status: SKIPPED$ 匹配的行 → 将此检查标记为 SKIPPED（既不是 PASS，也不是 FAIL），并跳过数值检查。此存根来自步骤 0 的安全阀；审查者会看到 SKIPPED 状态。

否则，它必须包含与以下内容匹配的行：

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

如果分数 ≥ 3.8 → 通过。否则 → 失败，并显示："设计审查平均分低于上线门槛（3.8）。请处理最新 design-review-report.md 中的 Must Fix 和 Should Fix 项，并在新的反馈轮次中重新运行 flows-design-review。"

步骤 4 — 验证认证产物已提交

apps submit 使用 git archive HEAD——未提交的文件会被静默排除在源代码归档之外。检查以下三个认证产物是否已纳入版本控制：

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请运行： git add git commit -m 'chore: add certification artifacts'

然后重新运行此技能。"

如果所有认证产物都已提交，但工作树中还有其他未提交的更改 → 警告（不阻止）：

"你有认证产物以外的未提交更改。apps submit 使用 git archive HEAD——这些更改不会出现在提交的源代码归档中。如果它们应该属于认证内容，请先提交。"

步骤 5 — 验证部署包

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

如果不存在部署包 → 警告（不阻止）："在 .cognite-bundles/ 中未找到部署包。请先运行 npx @cognite/cli apps deploy，以确保提交的源代码归档和已部署的包来自同一份代码。"

如果存在部署包，检查其时间是否早于 HEAD：

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 才会。）"

步骤 6 — 输出通过/失败表格

输出如下表格：

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 仅适用于代码审查和设计审查行，且仅当步骤 0 的安全阀写入了存根时使用。对于 SKIPPED 行，显示注释 SKIPPED — user opted out via Step 0 air-hatch。

如果任何检查为 FAIL：在此处停止。不要运行 CLI。打印用户应运行的准确后续技能。SKIPPED 行不会阻止流程——继续执行步骤 7，并在其中添加明确确认。

步骤 7 — 确认并提交

如果有任何检查状态为 SKIPPED，请在确认提示前添加明确警告：

“警告 — 以下评审已跳过：。Cognite 认证审核人员会在提交的报告中看到 SKIPPED 状态，并会在批准前要求进行实际评审。仍要继续提交吗？”

否则（全部通过，警告可接受），使用标准确认提示：

“所有认证检查均已通过。现在运行 npx @cognite/cli apps submit 吗？这会将仓库打包成 zip，并预先填写 Zendesk 提交表单。”

用户回答 yes 时：

npx @cognite/cli@latest apps submit

将输出流式显示给用户。

步骤 8 — 提交后的交接

当此技能通过 Bash 调用 apps submit 时，CLI 会以非交互模式运行（process.stdout.isTTY === false），并跳过自动打开浏览器／在文件管理器中显示文件的步骤。CLI 仍会打印文件列表、屏幕录制提示和 Zendesk URL，但用户必须手动处理这些内容。

CLI 运行结束后，向用户打印以下内容：

CLI 以非交互模式运行，因此没有打开浏览器或文件管理器。请完成以下操作：

1. 打开上方 CLI 输出中的 Zendesk URL。此 URL 需要登录 support.cognite.com — 如果你还没有账号，请先在那里创建账号，然后重新打开链接。
2. 在文件管理器中打开 dist/submit/，并放入一段简短的认证用户流程屏幕录制。
3. 将 dist/submit/ 中的所有文件（源代码归档、部署包、屏幕录制）附加到 Zendesk 工单。
4. 如果当前分支领先于 origin，请推送你的提交。

然后运行 git status --short --branch，如果当前分支领先于 origin，请在第 4 步下明确显示领先／落后数量。

存根模板（步骤 0 的快速通道使用）

当用户在步骤 0 中选择 快速提交（存根） 时，请使用以下精确模板编写缺失的报告。若父目录不存在，请先创建。

代码评审存根

路径：reviews/code-review/feedback-round-0/code-review-report.md

# Code Review Report — Round 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.

## Summary

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

设计评审存根

路径：reviews/design-review/feedback-round-0/design-review-report.md

# Design Review Report — Round 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.

## Summary

- Status: SKIPPED
- Average score: N/A