用途:定义 Capsem 中 Justfile 的职责边界。Justfile 被视为产品接口而非脚本抽屉,其公开命令面由 config/public-surface.toml 白名单唯一决定,契约测试会比对实际 recipe 列表,新增、删除、改名或数量漂移都会失败;新增公开 recipe 需用户或产品明确批准并同步更新白名单。
主要能力与命令:公开命令包括 just dev(选择开发界面,不支持透传参数)、just build、just build-all、just build-docs、just shell、just exec、just run-service、just logs、just doctor、just fast-test、just focus-test、just install、just test、just release-binaries、just release-profile,以及 slow 权限参数。just --summary 必须只输出 [just].approved 中的名字。
使用方式与分工:focus-test、release-binaries、release-profile 通过一个精确的 argv 边界进入 capsem-gate;命令形状与计划图在 src/capsem/gate/<domain>.py,共享工作用可组合 fragment,顺序用 after= 显式边,子进程与文件操作用 actions.py、fileactions.py,路径与环境名在 config/gate.toml,证据与计时由 gate 运行日志负责。recipe 只能是分发或单条命令,禁止 shell 主体、最多五行可执行行、禁止 if/for/while/case/until/trap。
限制:plan action 不得再调用 just 或另一个 capsem-gate 命令,因为机器锁不可重入;本地完整测试独占一个进程、锁、工作区、计划与日志,发布命令不消费它。fast-test 只覆盖不完整的 test-fast 模块,focus-test 只是别名,两者都不具发布权威。不得新增通用或合并的发布 recipe、依赖更新、夹具更新、审计、覆盖率、清理、会话 SQL 或额外安装便利 recipe,也不得新增 UI 别名、内核/rootfs/Docker/架构/打包的公开构建原语或公开续跑 recipe。私有下划线 recipe 仅可作为已批准命令的依赖或狭窄 CI 原语。本地验证不得导入、解锁或使用 Apple Developer 证书。公开接口门禁运行两条命令:uv run --project build_system --frozen python build_system/scripts/audit/check_public_surface.py 与 uv run --project build_system --frozen python -m pytest -c build_system/pyproject.toml --rootdir . tests/test_public_surface_contract.py。修改 Python 编排前阅读 /dev-gate,修改发布计划前阅读 /release-process。