附录 A 建模规范WSaiOS UML Modeling Specification WSaiOS UML 2026年07月24日 东塬一老翁 《WSaiOS 人工认知智能理论与工程体系》、工程附录 AWSaiOS UML Modeling SpecificationWSaiOS UML 建模规范A.1 建模目标UML不是为了画图。而是用统一的方法描述WSaiOS工程结构。每张图必须满足可以对应代码可以验证实现可以指导开发可以长期维护如果一张图不能对应工程对象就不建议放入正式文档。A.2 UML使用原则整个WSaiOS统一采用UML类型 用途 是否必须Use Case 功能分析 √Package 工程目录 √Component 模块关系 √Class 类设计 √Sequence 调用过程 √Activity 工作流程 √State Machine 生命周期 √Deployment 部署模型 √Object 调试示例 可选统一使用九种图。不再增加。A.3 图编号规范建议第55章Figure 55-1Figure 55-2Figure 55-3例如Figure 55-1Cognitive Execution Class Diagram这样以后引用十分方便。A.4 Package颜色规范建议整个WSaiOS保持一致。例如蓝色Core绿色Service黄色Capability橙色Workflow紫色Plugin灰色Application整本书统一。A.5 Class命名规范统一类PascalCase。例如KernelRuntimeWorkflowEngineKnowledgeServiceDecisionEngine接口建议IKnowledgeIWorkflowIRuntime抽象类建议AbstractServiceA.6 属性规范统一public#protected-private例如Kernel-----------------id-runtime-status----------------start()stop()restart()整本书一致。A.7 Sequence规范统一从左到右Application↓Capability↓Workflow↓Service↓Kernel不要交叉。不要回跳。这样容易阅读。A.8 Activity规范开始统一Start结束统一End条件统一Decision Node。例如Start↓Knowledge↓DecisionYes↓Execution↓EndA.9 State规范状态统一Created↓Initialized↓Running↓Stopping↓Stopped不要每章自己创造状态。A.10 Component规范统一矩形。例如KernelRuntimeSchedulerWorkflowExecution箭头表示依赖。不是调用。A.11 Deployment规范统一Client↓Server↓Database不要把Class画到Deployment。A.12 Package规范目录完全对应Git。例如kernel/runtime/workflow/service/plugin/Package不是模块图。A.13 PlantUML规范统一所有源码例如startumlskinparam shadowing falseskinparam classAttributeIconSize 0enduml统一Style。以后图片全部一致。A.14 文件规范建议docs/uml/chapter55/chapter56/……chapter90/每章单独目录。例如chapter55/class.pumlsequence.pumlstate.puml以后Git管理。A.15 自动生成建议CI自动PlantUML↓SVG↓PNG↓PDF避免人工导图。A.16 与代码同步例如workflow.py对应workflow_class.puml修改代码。修改UML。一起提交。这样文档不会长期落后于实现。A.17 UML与章节对应关系建议建立统一映射表章节 推荐 UML 图Kernel Class、State、SequenceRuntime Component、SequenceService Class、SequenceCapability Component、ClassWorkflow Activity、Sequence、StateScheduler State、SequenceKnowledge Class、SequenceReasoning Activity、SequenceDecision Activity、SequenceExecution Activity、SequencePlugin Package、ClassAPI SequenceSDK Package、ClassSecurity Sequence、StateDeployment DeploymentVersion Activity、State这样每一章的 UML 类型固定避免重复和遗漏。A.18 UML文档模板建议每一章统一采用以下结构XX章理论说明↓工程实现↓Class Diagram↓Sequence Diagram↓State / Activity Diagram↓PlantUML源码↓工程验证(MVP)这样每章既有理论也有设计又有实现验证。A.19 UML工程目录建议整个仓库结构如下WSaiOS/├── docs/│ ├── chapters/│ ├── uml/│ │ ├── chapter01/│ │ ├── chapter02/│ │ ├── ...│ │ └── chapter90/│ └── images/├── src/├── tests/└── examples/其中 docs/uml 保存 PlantUML 源码docs/images 保存导出的 SVG 或 PNG方便出版和网页展示。A.20 本附录总结本附录建立了《WSaiOS》的统一 UML 建模标准包括UML 图类型规范类、接口、状态命名规范Package 与目录映射PlantUML 编码规范图编号规范文档组织规范UML 与代码同步原则。