fcode-code-validation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Factorial Code — App validation

Factorial Code — 应用验证

A pre-flight for the platform's own release validation (its criteria are in

fcode-ama

references/journey.md §8), run locally before the release is requested, adding the review dimensions a human gatekeeper would: forms and lifecycle, i18n, logging hygiene, security, email abuse.

It serves two audiences with the same procedure: an app developer self-checking before requesting a release, and a platform reviewer gating one. Either way the input is a workspace ("team") slug and the output is

APP_VALIDATION_REPORT.md

in the cloned workspace plus a ✅/❌ verdict in chat.

This skill owns only the procedure, the check catalog, the severities, and the report format. Every rule it checks is owned by another skill and cited on the catalog row — read the owner when a finding needs context.

平台自身发布验证的预检流程（其标准见

fcode-ama

references/journey.md §8），在请求发布前于本地运行，并加入人工审核者会关注的审查维度：表单与生命周期、i18n、日志规范、安全性、邮件滥用。

它面向两类受众，并采用同一套流程：请求发布前进行自检的应用开发者，以及为发布把关的平台审核者。无论哪种情况，输入都是工作区（"team"）slug，输出都是克隆工作区中的

APP_VALIDATION_REPORT.md

，并在聊天中给出 ✅/❌ 结论。

本 skill 仅负责流程、检查清单、严重级别和报告格式。它检查的每一条规则均由其他 skill 负责，并在检查清单的对应条目中注明——当某项发现需要更多上下文时，应阅读负责该规则的 skill。

Gotchas

易错点

This review is read-only. The only permitted writes are the clone itself and
```
APP_VALIDATION_REPORT.md
```
. Never
```
fcode push
```
, never
```
--force
```
, never
```
settings:versions:create
```
/
```
settings:aliases:set
```
, never edit workspace files, never
```
fcode add
```
the report.
Never
fcode run
during the review. Processes may call real APIs with credentials inherited from parent workspaces (
```
fcode-core-concepts
```
). This is a static review of code and config.
The clone slug is an encoded
dev-…
token, not the app's UUID from the browser URL — copy it from the app's "How to build locally" guide on its Development tab (see
```
fcode-cli
```
). A UUID-shaped slug will not clone.
Any Blocker → ❌. Warnings and Suggestions never flip the verdict.
Ambiguity blocks the review. If the user names a development team with several apps, or it's unclear which workspace (
```
dev-
```
/
```
deploy-
```
/
```
prod-
```
) to review, list the candidates and ask before cloning.
```
dev-
```
is the normal review target.
********
placeholders in pulled variables are normal — a masked secret is never a finding, and the review never needs real secret values. Never ask for them.
A failing
fcode clone
usually means UUID confusion or missing access — point at the access flow in
```
fcode-ama
```
; don't retry blindly.
A mixed JS/Python workspace is fine — review each process with its own language's rules and note the mix in the report header.
Review only what the workspace owns. Inherited resources — modules, processes, and variables from
```
parentTeams
```
parents,
```
variables.inherited.env
```
,
```
i18n/<locale>.inherited.yaml
```
— were already validated when their owning workspace was published. Don't audit their content; findings may only concern how this workspace uses them.

本次审查为只读。 唯一允许的写入操作是创建克隆以及写入
```
APP_VALIDATION_REPORT.md
```
。绝不执行
```
fcode push
```
，绝不执行
```
--force
```
，绝不执行
```
settings:versions:create
```
/
```
settings:aliases:set
```
，绝不编辑工作区文件，也绝不对报告执行
```
fcode add
```
。
审查期间绝不执行
fcode run
。进程可能会使用从父工作区继承的凭据调用真实 API （
```
fcode-core-concepts
```
）。这是对代码和配置的静态审查。
克隆所用的 slug 是编码后的
dev-…
token，而不是浏览器 URL 中该应用的 UUID—— 应从应用 Development 选项卡中的 "How to build locally" 指南复制（见
```
fcode-cli
```
）。形似 UUID 的 slug 将无法完成克隆。
只要出现一个 Blocker，结论即为 ❌。 Warning 和 Suggestion 永远不会改变结论。
存在歧义会阻塞审查。 如果用户指定了一个包含多个应用的开发团队，或不清楚要审查哪个工作区（
```
dev-
```
/
```
deploy-
```
/
```
prod-
```
），应列出候选项并在克隆前询问。
```
dev-
```
是常规审查目标。
拉取到的变量中出现
********
占位符属于正常情况——被遮蔽的 secret 绝不应作为发现项，审查过程也永远不需要真实的 secret 值。绝不向用户索要这些值。
fcode clone
失败通常意味着混淆了 UUID 或缺少访问权限——应指向
```
fcode-ama
```
中的访问流程；不要盲目重试。
混合使用 JS/Python 的工作区没有问题——应依据每种语言各自的规则审查每个进程，并在报告标头中注明这种混合情况。
仅审查工作区自身拥有的内容。 继承的资源——来自
```
parentTeams
```
父级的模块、进程和变量，以及
```
variables.inherited.env
```
、
```
i18n/<locale>.inherited.yaml
```
——已在其所属工作区发布时完成验证。不要审计其内容；发现项只能涉及此工作区如何使用这些资源。

Severity model

严重级别模型

Severity	Meaning	Effect on verdict
Blocker	Breaks at runtime, mishandles credentials, exposes the platform's mail domain to abuse, or fails a criterion the platform release gate checks	Any one → ❌
Warning	Violates a documented rule; expect reviewer pushback or future breakage	Advisory
Suggestion	Improvement aligned with platform conventions	Advisory

严重级别	含义	对结论的影响
Blocker	导致运行时故障、不当处理凭据、造成平台邮件域名可被滥用，或未满足平台发布门禁检查的标准	任意一个 → ❌
Warning	违反已记录的规则；预计审核者会提出异议，或未来可能发生故障	仅供建议
Suggestion	与平台惯例一致的改进项	仅供建议

Procedure

流程

Resolve the workspace. Confirm the slug is the encoded token (see Gotchas) and which workspace kind it is; disambiguate with the user when needed. Record the kind in the report header.
Acquire. Missing CLI: ask the user, then
```
pnpm install -g @factorialco/fcode-cli
```
— the one permitted install. Fresh copy:
```
fcode clone <workspace-slug> --skipSkillsSetup
```
. Already cloned:
```
fcode pull
```
; on divergence never
```
--force
```
— ask whether to review the local state as-is and record the answer in the report header.
Inventory (read-only). Detect the language per process (
```
index.js
```
vs
```
main.py
```
). List processes, modules,
```
appRole
```
s, and webhook/form settings from each
```
processes/<slug>/metadata.json
```
; read
```
settings.json
```
, the three variables files,
```
variables.meta.json
```
, and
```
i18n/
```
. Run
```
fcode status
```
,
```
fcode variables:status
```
,
```
fcode settings:status
```
, and
```
fcode i18n:status
```
. Separate owned from inherited as you go — the catalog applies to owned resources only (see Gotchas).
Run the check catalog. Read
```
references/checks.md
```
and evaluate every check against the inventory, recording
```
file:line
```
evidence. Whether step 2 was a fresh clone or a pre-existing local workspace decides if the STRUCT layout checks run fully or are marked "N/A — fresh clone".
Classify. Apply each catalog row's severity; deviate only where the row allows it, and say why in the finding.

Write the report to

<workspace>/APP_VALIDATION_REPORT.md

following

references/report-template.md

, overwriting any previous run.

Print the verdict in chat: the ✅/❌ line, per-severity counts, and the Blocker titles.

确定工作区。 确认 slug 是编码后的 token（见 "易错点"），并确认工作区类型；如有需要，向用户澄清。将类型记录在报告标头中。
获取工作区。 缺少 CLI：先询问用户，然后
```
pnpm install -g @factorialco/fcode-cli
```
——这是唯一允许的安装操作。全新副本：
```
fcode clone <workspace-slug> --skipSkillsSetup
```
。已克隆：
```
fcode pull
```
；如出现分歧，绝不使用
```
--force
```
——应询问用户是否按当前本地状态进行审查，并将答复记录在报告标头中。
盘点（只读）。根据每个进程检测语言（
```
index.js
```
对比
```
main.py
```
）。从每个
```
processes/<slug>/metadata.json
```
列出进程、模块、
```
appRole
```
以及 webhook/form 设置；读取
```
settings.json
```
、三个变量文件、
```
variables.meta.json
```
和
```
i18n/
```
。运行
```
fcode status
```
、
```
fcode variables:status
```
、
```
fcode settings:status
```
和
```
fcode i18n:status
```
。在此过程中区分自有资源与继承资源——检查清单仅适用于自有资源（见"易错点"）。
运行检查清单。 读取
```
references/checks.md
```
，根据盘点结果评估每项检查，并记录
```
file:line
```
证据。第 2 步获取的是全新克隆还是预先存在的本地工作区，决定 STRUCT 布局检查是完整运行还是标记为 "N/A — fresh clone"。
分类。 应用每个检查清单条目指定的严重级别；仅在该条目明确允许时偏离，并在发现项中说明原因。
编写报告，写入
```
<workspace>/APP_VALIDATION_REPORT.md
```
，遵循
```
references/report-template.md
```
，覆盖上一次运行生成的报告。
在聊天中打印结论：✅/❌ 行、各严重级别的数量以及 Blocker 标题。

Check categories

检查类别

STRUCT

LANG

FORM

I18N

SEC

MAIL

REUSE

LOG

LIFE

REL

— the full catalog, with per-check severities and owner citations, is in

references/checks.md

STRUCT

LANG

FORM

I18N

SEC

MAIL

REUSE

LOG

LIFE

REL

——完整检查清单（包括每项检查的严重级别和负责方引用）见

references/checks.md

。