# 提交文件与本地文件 / Committed files and local files

仓库保存重现源码、公共 API、测试和示例所需的文件。构建结果、下载的依赖和本地资料
保留在工作区，由 `.gitignore` 排除；不需要为了提交而删除它们。

The repository keeps the files needed to reproduce the source, public API, tests and examples. Build outputs, downloaded dependencies and local reference material stay in the workspace and are excluded by `.gitignore`; they do not need to be deleted before committing.

| 文件或目录<br>File or directory | 是否提交<br>Commit? | 原因<br>Reason |
| --- | --- | --- |
| `moon.mod`、各包的 `moon.pkg`<br>`moon.mod` and each package's `moon.pkg` | 是<br>Yes | 模块元数据、固定版本的依赖与构建配置<br>Module metadata, pinned dependencies and build configuration |
| `core/`、`route/`、`transport/` 的 `.mbt`、C shim<br>`.mbt` files and C shim in these SDK packages | 是<br>Yes | SDK 实现与原生 socket 边界<br>SDK implementation and native socket boundary |
| `state/` 的 `.mbt`<br>`.mbt` files in `state/` | 是<br>Yes | Snapshot、严格配置 schema、显式意图、Diff 和 Plan 的纯状态实现<br>Pure Snapshot, strict configuration schema, explicit intent, Diff and Plan implementation |
| `reconcile/` 的 `.mbt`<br>`.mbt` files in `reconcile/` | 是<br>Yes | 顺序执行、部分失败报告、尽力补偿和最终状态验证<br>Ordered execution, partial-failure reports, best-effort compensation and final-state verification |
| `*_test.mbt`、`*_wbtest.mbt` | 是<br>Yes | 纯协议、失败路径和 Linux 回归测试；fixtures 内嵌于测试源码<br>Pure protocol, failure-path and Linux regression tests; fixtures are embedded in test sources |
| `pkg.generated.mbti` | 是<br>Yes | `moon info --target native` 生成的公共 API 审查记录，不能手工修改<br>Public API review record generated by `moon info --target native`; never edit manually |
| `cmd/moonnet/`、`examples/` | 是<br>Yes | 查询、JSONL 监听及隔离修改示例，以及直接调用公共 API 的 `examples/network_config_app` 应用样例<br>Queries, JSONL monitoring and isolated mutation examples, plus the `examples/network_config_app` application sample that calls the public API directly |
| `.ci/*.sh`、`.ci/*.py` | 是<br>Yes | 可复现的隔离 namespace 验证与 `ip -j` 差分脚本<br>Reproducible namespace validation and `ip -j` differential scripts |
| `README.md`、`docs/`、`LICENSE` | 是<br>Yes | 使用方式、公开实现进度、协议和安全约定、许可证<br>Usage, public implementation status, protocol/safety contracts and license |
| `demo/` | 是<br>Yes | 固定 desired 配置、隔离演示入口、带断言的公共 CLI 演示，以及 `demo/compare/` 的对照契约、样例、独立契约校验器、脚本基线和用例运行器<br>Fixed desired configurations, isolated entry points, asserted public CLI demonstrations and the `demo/compare/` comparison contract, samples, independent contract checker, script baseline and case runner |
| `.gitignore`、`.gitattributes` | 是<br>Yes | 提交边界与跨平台 LF 换行规则<br>Commit boundaries and cross-platform LF line endings |
| `_build/`、`target/` | 否<br>No | 可重新生成的构建、测试和文档产物<br>Rebuildable build, test and documentation outputs |
| `.mooncakes/` | 否<br>No | 通过 `moon update` 下载的依赖；版本由 `moon.mod` 记录<br>Dependencies downloaded by `moon update`; versions are recorded in `moon.mod` |
| `TODO.md` | 否<br>No | 本地工程指导和任务记录；不暂存、不提交、不推送，更新留在工作区<br>Local engineering guidance and task records; never stage, commit or push |
| `docs/project-proposal.md` | 否<br>No | 本地项目申报书；不暂存、不提交、不推送，更新留在工作区<br>Local project proposal; never stage, commit or push |
| 编译链接产物、Python 缓存、日志、临时文件<br>Compiler/linker output, Python caches, logs and temporary files | 否<br>No | 本地运行结果，不属于源码<br>Local runtime output, not source |
| `.env*`（示例除外）、`.aws/`、`.codex/`、`.agents/`<br>These paths, excluding example environment files | 否<br>No | 本地凭据或运行状态<br>Local credentials and runtime state |
| `MoonBit 黑客松大赛章程/` | 否<br>No | 本地参考资料，不是项目实现或项目发布内容<br>Local contest references, not implementation or release content |
| `.git/` | 否<br>No | Git 自己维护的历史与本地配置，不作为源码文件提交<br>Git history and local configuration managed by Git, not source files |

`.ci/` 中的脚本目前需要手动运行；它们不是已配置的 GitHub Actions 工作流。
当前已支持 Snapshot/DesiredState/Diff/Plan、保护 API、dry-run 和确认后的 Apply CLI。
后续集成验收与发布任务继续推进。公开能力与限制以 README 和相关 API 文档为准。

Scripts in `.ci/` currently run manually; they are not configured GitHub Actions workflows. Snapshot/DesiredState/Diff/Plan, protection APIs, dry-run and confirmed Apply CLI are supported. Further integration acceptance and release tasks remain in progress. README and public API documentation define the supported behavior and limitations.

每个小任务完成并验收后独立提交，实现、测试、公开文档和生成接口一同交付。
任务勾选与内部指导仅更新本地 `TODO.md`，不能把该文件加入任务 commit。

Commit each small task independently after completing its acceptance checks, including implementation, tests, public documentation and generated interfaces. Update task checkboxes and internal guidance only in local `TODO.md`; never include that file in a task commit.

提交前检查：

Checks before committing:

```sh
moon check --target native --warn-list +73
moon test --target native
moon fmt --check
moon info --target native
git status --short
git status --ignored --short
git diff --check
git diff --cached --check
git diff --cached --stat
```

Linux 隔离验收：

Isolated Linux acceptance checks:

```sh
bash .ci/validate-queries.sh
bash .ci/validate-link-state.sh
bash .ci/validate-mutations.sh
bash .ci/validate-plan.sh
bash .ci/validate-apply.sh
bash .ci/validate-idempotence.sh
bash .ci/validate-failures.sh
bash .ci/validate-robustness.sh
```

新增源码应明确加入暂存区，再检查暂存清单。不要用 `git add -f` 将被忽略的本地文件
混入提交。推送前读取远程分支状态；已有远程提交应保留，不使用强制推送。

Stage new source files explicitly, then review the staged list. Do not use `git add -f` to include ignored local files. Read the remote branch state before pushing, preserve existing remote commits and do not force-push.