📓系统架构

系统架构设计文档

GJB438C-DocSkill 架构设计说明

1. 概述

1.1 系统定位

GJB438C-DocSkill 是一个 Claude Code 插件，通过 JSON 驱动的严格模式引擎，自动生成符合 GJB 438C 标准的军用软件文档。当前支持 [10] 软件需求规格说明书 (SRS) 和 [11] 软件设计说明书 (SDD)。

1.2 设计原则

原则 描述
严格模式 锚点未匹配直接报错，不做静默降级
JSON 驱动 所有内容来自 JSON 配置，引擎零硬编码业务逻辑
内容与结构分离 只允许修改 content 和 rows，结构字段不可变
模板可复用 strict_word_filler/ 引擎可被不同 Skill 复用
不可变数据模型 所有 Rule 和 BuildPlan 均为 frozen=True dataclass

2. 系统架构

2.1 架构总览

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
┌───────────────────────────────────────────────────────────────┐
│                    Claude Code Plugin Layer                    │
│            (.claude-plugin/plugin.json)                        │
├───────────────────────────────────────────────────────────────┤
│                                                                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │   Skill 层    │  │   配置层      │  │   引擎层      │        │
│  │              │  │              │  │              │        │
│  │ SKILL.md     │  │ config.json  │  │ models.py    │        │
│  │ (触发/约束)   │  │ project.json │  │ loader.py    │        │
│  │              │  │              │  │ docx_ops.py  │        │
│  │              │  │              │  │ pipeline.py  │        │
│  └──────────────┘  └──────────────┘  └──────────────┘        │
│                                                                │
├───────────────────────────────────────────────────────────────┤
│                    模板层                                       │
│  ┌────────────────────────┐  ┌────────────────────────┐      │
│  │ template_rules.py      │  │ documents/*.docx       │      │
│  │ (锚点常量/插入规则)     │  │ (Word 模板文件)         │      │
│  └────────────────────────┘  └────────────────────────┘      │
└───────────────────────────────────────────────────────────────┘

2.2 层次说明

Skill 层

由 SKILL.md 定义，负责：

  • 定义触发关键词和约束条件
  • 描述交互工作流程（封面 → 章节内容 → 生成）
  • 指定 JSON 规则（哪些字段可修改）

配置层

文件 用途
config.json 封面信息：project（名称/版本/单位）、document（标识/标题/密级/阶段/日期）、content（背景概述）
project.json 章节内容：template_info + structure（每个章节含 placeholders、tables、cscis）

引擎层（strict_word_filler/）

模块 职责
models.py 不可变数据模型：BuildPlan、各 Rule 类型
loader.py JSON 解析 → BuildPlan 构建，含完整字段校验
docx_ops.py Word 文档操作：替换、动态章节、表格填充、CSCI、图表编号、TOC 标记
template_rules.py 模板专属常量：锚点文本、动态章节插入规则、CSCI 规则
errors.py StrictTemplateError、StrictDataError
pipeline.py CLI 参数解析与执行入口

模板层

  • template_rules.py：定义模板特有的锚点常量（IDENTITY_LINE_ANCHORS）、动态章节规则（INSERTION_PARENT_RULES）、CSCI 规则（CSCI_SECTION_RULE）
  • documents/*.docx：GJB 438C 标准 Word 模板

3. 核心处理流程

3.1 BuildPlan 模式

1
2
3
config.json ──┐
              ├──► loader.build_plan() ──► BuildPlan ──► docx_ops.apply_plan() ──► .docx
project.json ──┘

引擎采用两阶段设计：

  1. 构建阶段（loader.py）：解析 JSON → 构建不可变的 BuildPlan
  2. 应用阶段（docx_ops.py）：按顺序执行 BuildPlan 中的规则

3.2 apply_plan 执行顺序

1
2
3
4
5
6
7
8
9
10
11
12
13
def apply_plan(doc, plan):
    for rule in plan.exact_replacements:    # 1. 精确替换（封面）
        apply_exact_replacement(...)
    for rule in plan.dynamic_sections:      # 2. 动态章节
        apply_dynamic_section(...)
    for rule in plan.paragraph_replacements: # 3. 段落替换
        apply_paragraph_replacement(...)
    for rule in plan.csci_sections:         # 4. CSCI 章节（仅 [11]）
        apply_csci_sections(...)
    for rule in plan.tables:                # 5. 表格填充
        apply_table_fill(...)
    apply_caption_numbering(doc)            # 6. 图表编号
    mark_toc_for_update(doc)                # 7. TOC 标记

3.3 四种替换策略

策略 Rule 类型 说明
精确替换 ExactReplaceRule paragraph.text == old_text，验证命中数量
段落替换 ParagraphReplaceRule anchor_text in paragraph.text，支持多行文本展开
动态章节 DynamicSectionRule 克隆标题/正文原型段落，生成可变数量子章节
CSCI 章节 CSCISectionRule [11] 专属，克隆整个 CSCI 原型块（概述/部件/执行/接口）

3.4 表格填充

TableFillRule 通过 locator_rows（表格头部行文本）定位目标表格，然后按 rows 数据填充：

  1. 通过 locator_rows 精确匹配唯一表格
  2. 若数据行不足，克隆最后一行数据行原型
  3. 逐行逐格写入内容
  4. [11] 版本额外清除多余数据行并处理合并单元格

4. 数据模型

4.1 [10] BuildPlan

1
2
3
4
5
BuildPlan
├── exact_replacements: tuple[ExactReplaceRule, ...]
├── paragraph_replacements: tuple[ParagraphReplaceRule, ...]
├── dynamic_sections: tuple[DynamicSectionRule, ...]
└── tables: tuple[TableFillRule, ...]

4.2 [11] BuildPlan（扩展）

1
2
3
4
5
6
BuildPlan
├── exact_replacements: tuple[ExactReplaceRule, ...]
├── paragraph_replacements: tuple[ParagraphReplaceRule, ...]
├── dynamic_sections: tuple[DynamicSectionRule, ...]
├── csci_sections: tuple[CSCISectionRule, ...]       # [11] 新增
└── tables: tuple[TableFillRule, ...]

4.3 关键差异

维度 [10] SRS [11] SDD
动态章节 3.1/3.2/3.3/3.4 可变子节 无（INSERTION_PARENT_RULES = {}）
CSCI 无 第 4 章使用 cscis 数组
表格处理 标准填充 _actual_row_cells() 处理合并单元格，清除多余行
模板编码 gbk utf-8

5. 错误处理

异常类型 触发场景
StrictTemplateError 锚点未命中、命中数量不符、表格列数不匹配、段落顺序非法
StrictDataError JSON 缺少必填字段、字段为空、字段类型非法

所有错误均终止执行并输出详细信息，不做静默降级。

6. 扩展设计

6.1 添加新 Skill

  1. 从 GJB438C全套模版/ 选取目标模板
  2. 创建 skills/word-fillter-438c-XX/ 目录
  3. 复用 strict_word_filler/ 引擎
  4. 编写 template_rules.py 定义锚点常量
  5. 编写 SKILL.md 定义触发规则

6.2 添加新的替换类型

  1. 在 models.py 中添加新的 Rule dataclass
  2. 在 loader.py 中添加解析逻辑
  3. 在 docx_ops.py 中添加应用函数
  4. 在 apply_plan() 中插入执行步骤