0. Calibrate first, then write configuration
Before writing/modifying package, manifest, build, or executing build/deploy/release,you must first read and execute references/spec-sync.md: record the target lzcos and CLI versions, obtain the official source text, check the local snapshot, and declare conflicts. HTTP errors, empty documents, and HTML error pages do not count as success; when offline, you may only explicitly declare that a snapshot is being used, and must not claim real-time calibration.
The baseline is lzcos >=1.5.0、lzc-cli >=2.0.0; each new capability also requires an independent verification threshold. The current skill is not a guarantee of being "always up to date".
1. Analyze the application
Sort out ports/protocols, CPU architecture, image entrypoint and UID, internal data/user files, dependencies, business authentication, and required permissions. Do not treat Compose as-is as the manifest, and do not request root/privileged/all permissions by default.
2. Write the four types of configuration separately
| File/Requirement | Action instruction |
|---|---|
| package.yml: static identity, version, permissions | Read references/package-spec.md |
| lzc-manifest.yml: services, routes, inject, entries, runtime identity | Read references/manifest-spec.md |
| lzc-build.yml: formal build | Read references/build-spec.md |
| lzc-build.dev.yml: development differences | Same as above, do not copy the entire release configuration |
| Resource export/import | Read references/resource-export.md |
| Permissions, initialization, probes, persistence failures | Read references/troubleshooting.md |
| Publishing and review | Read references/store-publish.md |
The V2 manifest does not contain static fields such as package/version/name/locales/permissions/import_resources. The content of a full package is optional; image-only does not need to fake a contentdir; icons follow the official PNG/store requirements, and size limits must not be fabricated.
3. Build and verify
lzc-cli --version
lzc-cli project build -o release.lpk
Check the Build config actually used, the package.yml/manifest.yml in the final tar package, necessary resources, and the image lock.buildscript Do not call project build. Raw files with #@build or Go template must first be preprocessed/rendered according to the real stage, then subjected to strict YAML validation; duplicate keys must not be ignored, and template errors must not be treated as valid files.
Installation/deployment changes device state, so execute only when the user authorizes it:
lzc-cli app install ./release.lpk
# 本地开发场景；优先 dev 配置
lzc-cli project deploy
Test first install, upgrade, restart persistence, least privilege, passwordless login, and API authentication; local static validation alone must not claim "deployment successful". Use the lzc-cli docker prefix to check deployed applications; when a MicroServer name is needed, proactively execute lzc-cli box default。
4. Boundaries that cannot be omitted
- Internal configuration/database: var; cache: cache; user files: those with document.private
/lzcapp/documents/$uid. Do not stuff all persistence into var, and do not default to legacy home compatibility mounts. - run_as (>=1.6.0) is chosen based on image compatibility; do not mix it with user/setup_script for the same service.
- routes strip the prefix by default; use upstreams to preserve the prefix; use ingress for non-HTTP, and it must not be used to bypass user authentication or arbitrarily take over ports 80/443.
- localhost on a development machine requires ctx.net.via.client(ctx.dev.id), not the container's default network.
- Intra-service internal communication and application mutual access on behalf of users are different mechanisms; the latter followsInter-application accessCalibrate permissions and tickets.
- public_path is not business authorization; operations such as remote publishing, privilege escalation, and Token creation and destruction must have an explicit scope and authorization.
Delivery includes: calibration source/original text summary, target version and threshold, configuration/package location, actual verification results, unverified items, and next steps requiring authorization.