开发工作流¶
Status: Current
Last verified: 2026-07-01
Code anchors:CONTRIBUTING.md,.github/workflows/,scripts/
这篇文档回答什么:如何以最小摩擦向 DiPECS 提交代码、通过 CI、并把文档同步更新。
适合谁读:第一次给 DiPECS 贡献代码或文档的开发者。
TL;DR¶
- 从
main切出feat//fix//docs/分支。 - 写代码 + 测试 + 文档;本地跑
cargo fmt、cargo clippy、cargo test。 - 提交符合 Conventional Commits 的 commit message。
- 开 PR,描述清楚问题、改动、验证方式。
- CI 全绿 + 至少一位模块维护者 review 后,squash merge。
分支命名¶
| 类型 | 前缀 | 示例 |
|---|---|---|
| 新功能 | feat/ | feat/cloud-llm-provider |
| Bug 修复 | fix/ | fix/proc-reader-diff |
| 文档 | docs/ | docs/decision-routing |
不要在同一分支里混功能改动和大量格式整理;格式整理单独一个 PR。
Commit message¶
使用 Conventional Commits:
常用 type:
feat— 新功能fix— 修复docs— 文档test— 测试refactor— 重构perf— 性能ci— CI 配置chore— 杂项
示例:
feat(spec): add collector envelope for app transition
fix(core): reject over-capability actions in local evaluator
docs(readme): clarify authorized action boundary
test(action): add android bridge envelope coverage
仓库配置了 scripts/dev/commit-msg.sh hook,提交时会校验格式。如需绕过可用 git commit --no-verify,但不推荐。
本地检查清单¶
每次提交前建议运行:
cargo fmt --all -- --check
cargo clippy --workspace --all-targets -- -D warnings
cargo test --workspace
如果需要完整验证(含 Android 交叉编译):
scripts/dev/check-all.sh 会跑:
cargo fmt --all -- --checkcargo clippy --workspace --all-targets -- -D warningscargo test --workspacecargo check --workspace --target aarch64-linux-android --all-targets
运行项目¶
Daemon¶
带 Android JSONL:
RUST_LOG=info cargo run -p aios-daemon --bin dipecsd -- \
--no-daemon \
--android-trace-jsonl apps/android-collector/actions.jsonl \
--trace-output data/evaluation/runtime.ndjson
CLI replay¶
cargo run -p aios-cli -- replay data/traces/sample_replay.jsonl \
--stages policy \
--audit data/evaluation/audit.ndjson
Android collector¶
文档更新¶
新增或修改 docs/src/ 页面后:
- 在
docs/mkdocs.yml的nav:里加入入口。 - 本地构建:
- 确保没有 broken internal link 警告。
- 如果新增了 cross-reference,更新相关文档的“相关文档”列表。
提交 PR¶
使用 .github/pull_request_template.md,包含:
- 改动类型(feat/fix/docs/...)
- 问题背景
- 具体改动
- 验证方式(运行了哪些命令)
- 关联的 RFC / Issue(架构或协议变更必须关联)
要求:
- 改动聚焦,不要把功能改动和格式整理混在一起。
- 至少一位相关模块维护者 review。
- 跨模块协议变更需要更严格 review。
- CI 红了不能合并。
CI 检查说明¶
| Workflow | 触发条件 | 检查内容 |
|---|---|---|
lint.yml | Rust/Cargo 改动 | cargo fmt、cargo clippy、cargo machete |
test.yml | Rust/Cargo 改动 | cargo nextest、cargo test --doc、replay fixture |
build.yml | Rust/Cargo 改动 | Linux/Android release build、ELF audit |
audit.yml | 定时/手动 | cargo-deny、依赖拓扑检查、CVE 扫描 |
docs.yml | docs/ 改动 | mkdocs build、cargo doc、LaTeX 报告 |
android-collector.yml | app/ 改动 | Android 单元测试、assembleDebug |
mirror_sync.yml | 每次 push | 镜像到 OSH-2026/DiPECS.git |
合并方式¶
使用 Squash and merge:
- PR 分支会被删除。
- 合并前把
Co-authored-by:行手动复制到 squash message。 - 合并后本地运行:
常见失误¶
| 问题 | 避免方法 |
|---|---|
| CI 上 clippy 失败 | 本地先跑 cargo clippy --workspace --all-targets -- -D warnings |
| 文档页面没出现在导航 | 记得改 docs/mkdocs.yml |
| commit message 被 hook 拒绝 | 按 type(scope): subject 格式写,长度 ≥ 10 |
| 合并后本地分支落后 | git pull 或 git reset --hard origin/main |