# 第十二章：工程参考与扩展阅读
前十一章从产品和设计角度解释 bot-forge。本章把仓库中更精确、面向维护者或机器的资料组织成索引。手册负责建立上下文，这些参考负责给出字段、schema、源码位置和质量门禁。
把本章当作入口索引，而不是新的设计说明：先从目标表找到章节，再以 schema、源码和测试
作为事实来源。
## 12.1 配置与机器 Schema
| [第四章](04-configuration.md) | 推荐短格式、分层、profile 与类型化安装后端 |
| [机器 JSON Schema](../../schema/config.json) | 编辑器、校验器和工具集成使用的输入契约 |
| [组织 overlay 示例](../../examples/site-overlay.toml) | 内部源、APT mirror、环境修改的分层示例 |
这些内容由以下命令生成或校验：
```bash
cargo run --bin generate-config-artifacts
cargo run --bin generate-config-artifacts -- --check
```
生成器维护配置 Schema、由 Rust 托管注册表类型生成的状态 Schema，以及 catalog checksum。修改输入或持久状态类型时，应重新生成；默认 profile 的人类可读摘要由 README 校验区块提供。
## 12.2 CLI、输出与状态契约
- [第三章：从预览到日常维护](03-commands.md)：场景化命令说明；
- [第八章](08-output-and-interaction.md)：退出码、Human/JSON 与 JSONL 边界；
- `bot-forge generate json|jsonl`：命令元数据协议样例；
- `bot-forge generate schema`：配置 schema；
- `bot-forge generate completion|man`：命令元数据生成物；
- `schema/registry.json`：托管注册表机器契约。
机器调用应依赖 schema、严格字段和语义约束，不依赖 Human 中文文案。协议变化需要同步 tests、generated artifacts、输出章节和架构手册。
## 12.3 架构事实源
架构约束直接维护在当前资料中：
| [第十章](10-architecture.md) | 模块边界、依赖方向、扩展流程和确定性 |
| [第五章](05-planning-and-dag.md) | 计划、依赖闭包、DAG 和稳定身份 |
| [第六章](06-efficiency-and-concurrency.md) | 资源预算、动态 jobs、锁、缓存和效率 |
| [第七章](07-artifacts-and-recovery.md) | 托管工件、事务日志、托管注册表与恢复 |
| [第八章](08-output-and-interaction.md) | Human/JSON、event、键盘与取消边界 |
| [第十章](10-architecture.md) | 模块归属、依赖方向、公开边界与架构门禁 |
当前仍处于首次正式发布前，不单独维护开发期决策历史。手册解释“为什么和怎样设计”，
源码、schema 与测试提供可执行事实；三者不一致时，应在同一变更中一起修正。
## 12.4 安全资料
| [安全报告流程](../../SECURITY.md) | 私下报告漏洞和敏感信息处理 |
| [第九章](09-security.md) | 从使用和设计角度解释各信任边界 |
公开 issue、日志和示例不得包含 credential、内部 mirror URL 或生产配置。
## 12.5 发布资料
- [第十一章](11-quality-and-release.md)：本地 gate、发布验证、分发边界与 asset smoke；
- 外部发布配置：构建目标、SBOM 与附件打包流程（仓库不附带 workflow）；
- 外部发布校验：版本、installer tag 与附件清单一致性门禁（由发布环境执行）。
首次正式发布前不维护候选版本历史，也不保留实验配置格式的版本字段和迁移路径。发布时根据实际 tag、附件和验证证据一次性编写正式说明。
配置应以当前参考为准，并在发布前运行 `config validate/effective/explain`。
## 12.6 源码导航
```text
src/
├── cli/ command actions and state workflows
├── config/ schema, catalog, load/merge/canonical expansion
├── planning/ resolver and immutable execution plan
├── execution/ scheduler, command host and orchestration
├── backends/ typed platform and package-manager adapters
├── artifact.rs verified immutable artifact lifecycle
├── skills.rs skill discovery and agent destinations
├── events.rs lifecycle routing, redaction and JSONL
├── state/ registry, journal and cache
├── reporting/ final report persistence
├── diagnostics/ environment and proxy checks
└── ui/ input, renderer and raw output boundary
```
`artifact.rs`、`events.rs` 和 `skills.rs` 是 crate-private 的中立能力；它们出现在根目录，
是因为多个应用模块共享其生命周期语义，而不是因为它们构成新的用户命令或公共库 API。
Integration tests 位于 `tests/`，发布/架构/性能/压力脚本位于 `scripts/`，内置 catalog 位于 `catalogs/`。
## 12.7 常用维护命令
```bash
# Rust 质量门禁
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets --all-features
# 生成物与文档事实
cargo run --quiet --bin generate-config-artifacts -- --check
python3 scripts/validate-readme-config.py
python3 scripts/validate-docs.py
# 架构、性能与 Cargo 压力
python3 scripts/architecture_audit.py
bash scripts/test-performance-gates.sh
python3 scripts/test-cargo-stress.py
# 发布附件清单
git diff --check
```
运行结果只证明执行环境内取得的证据。平台和发布结论按第十一章的证据层级报告。
## 12.8 本章小结
README 是产品入口，手册解释完整使用和设计，机器 schema 提供精确输入字段，源码和测试验证运行事实。维护者应在这些层之间保持链接和事实一致，而不是让一份超长 README 承担全部职责。
---