# 第十二章：工程参考与扩展阅读
前十一章从产品和设计角度解释 bot-forge。本章把仓库中更精确、面向维护者或机器的资料组织成索引。手册负责建立上下文，这些参考负责给出字段、Schema、源码位置和质量门禁。
把本章当作入口索引，而不是新的设计说明：先从目标表找到章节，再以 Schema、源码和测试
作为事实来源。
## 12.1 配置与机器 Schema
| [第四章](04-configuration.md) | 推荐短格式、分层、安装级别与类型化安装后端 |
| [机器 JSON Schema](../../schema/config.json) | 编辑器、校验器和工具集成使用的输入契约 |
| [组织覆盖层示例](../../examples/site-overlay.toml) | 内部源、APT mirror、环境修改的分层示例 |
这些内容由以下命令生成或校验：
```bash
cargo run --bin generate-config-artifacts
cargo run --bin generate-config-artifacts -- --check
```
生成器维护配置 Schema、由 Rust 托管注册表类型生成的状态 Schema，以及配方目录 checksum。修改输入或持久状态类型时，应重新生成；默认安装级别的人类可读摘要由 README 校验区块提供。
## 12.2 CLI、输出与状态契约
- [第三章：从预览到日常维护](03-commands.md)：场景化命令说明；
- [第八章](08-output-and-interaction.md)：退出码、人类可读输出/JSON 与 JSONL 边界；
- `bot-forge generate json|jsonl`：命令元数据协议样例；
- `bot-forge generate schema`：配置 Schema；
- `bot-forge generate completion|man`：命令元数据生成物；
- `schema/registry.json`：托管注册表机器契约。
机器调用应依赖 Schema、严格字段和语义约束，不依赖人类可读中文文案。协议变化需要同步测试、生成产物、输出章节和架构手册。
## 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) | 人类可读输出/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/ 命令操作与状态流程
├── config/ Schema、目录、加载、合并与规范展开
├── planning/ 解析器与不可变执行计划
├── execution/ 调度器、命令宿主与编排
├── backends/ 类型化平台与包管理器适配器
├── artifact.rs 已验证的不可变工件生命周期
├── skills.rs 技能发现与智能体目标
├── events.rs 生命周期路由、脱敏与 JSONL
├── state/ 注册表、事务日志与缓存
├── reporting/ 最终报告持久化
├── diagnostics/ 环境与代理检查
└── ui/ 输入、渲染器和原始输出边界
```
`artifact.rs`、`events.rs` 和 `skills.rs` 是 crate-private 的中立能力；它们出现在根目录，
是因为多个应用模块共享其生命周期语义，而不是因为它们构成新的用户命令或公共库 API。
集成测试位于 `tests/`，发布、架构、性能和压力脚本位于 `scripts/`，内置配方目录位于 `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 承担全部职责。
---