linux_format_docs_check/plan.md

# 简易 DOCX 规范分析 Web 应用开发计划

## 1. 目标与范围

开发一个部署在离线内网环境的简易 Web 应用，用户上传 `.docx` 文档后，系统读取 `GJB438C-2021_prd_skills/` 下的技能规范集合，判断文档是否符合相关规范，并生成可下载的分析报告。应用默认使用 `configs/api_config.yaml` 中 `intranet` 配置的内网模型 `qwen3-coder`。

本计划聚焦最小可用版本：上传 DOCX、抽取文本与章节结构、选择或自动匹配技能、调用内网模型分析、生成报告并下载。

## 2. 当前仓库基础

- `GJB438C-2021_prd_skills/`：核心规范知识库，目前包含 39 个 `SKILL.md`。
- `GJB438C-2021_prd_skills/index.md`：技能索引，包含技能名称、用途和分类导航。
- `configs/api_config.yaml`：模型供应商配置，默认 `default_provider: intranet`，内网接口为 `http://10.30.10.1:8000/v1`。
- `test/`：可存放人工验证用的 DOCX 样例。
- `AGENTS.md`：说明该仓库是文档与技能包工作区，无现有构建系统。

## 3. 推荐总体架构

建议采用 Python Web 后端为主的单体应用：

```text
浏览器
  -> 上传 DOCX
  -> Python Web 服务
     -> DOCX 解析
     -> 技能索引加载
     -> 技能相关性匹配
     -> 内网模型分析
     -> 报告生成
  -> 下载分析报告
```

推荐目录结构：

```text
app/
  main.py                 # Web 入口
  config.py               # 读取 configs/api_config.yaml
  docx_parser.py          # DOCX 文本、标题、表格抽取
  skill_loader.py         # 加载 index.md 与 SKILL.md
  analyzer.py             # 规则匹配与模型调用
  report_generator.py     # 生成 Markdown/DOCX 报告
  templates/
  static/
outputs/                  # 临时分析结果，需加入 .gitignore
uploads/                  # 临时上传文件，需加入 .gitignore
```

## 4. 核心处理流程

1. 用户在页面上传 `.docx` 文件。
2. 后端校验文件类型、大小和文件名，保存到 `uploads/` 临时目录。
3. 使用 DOCX 解析库抽取正文、标题层级、表格文本、页眉页脚和可识别编号。
4. 加载 `GJB438C-2021_prd_skills/index.md`，获得技能清单、描述和适用场景。
5. 根据文档标题、关键词和用户可选文档类型，筛选候选技能。
6. 读取候选技能的 `SKILL.md`，构造分析提示词。
7. 调用 `configs/api_config.yaml` 中 `intranet` 的 OpenAI 兼容接口。
8. 输出结构化分析结果：符合项、不符合项、缺失章节、风险等级、修改建议、引用技能。
9. 生成可下载报告，优先支持 `.docx`，同时保留 `.md` 便于审计。
10. 清理过期上传文件和分析结果。

## 5. 技能使用策略

技能集不应一次性全部塞入模型上下文。建议分两阶段使用：

- 预筛选阶段：读取 `index.md` 中的 Skill、Description、Use When，按关键词匹配文档类型，例如 SRS、接口设计、测试计划、配置管理、交付准备等。
- 深度分析阶段：只加载命中的 3 到 8 个 `SKILL.md`，逐项检查文档是否包含技能要求的章节、要素、约束和输出。

如果用户明确选择文档类型，应优先使用对应技能；如果未选择，则自动匹配并在报告中说明匹配依据。

## 6. 报告内容设计

报告建议包含以下章节：

- 基本信息：文件名、分析时间、使用模型、命中技能。
- 总体结论：通过、部分通过、不通过或需人工复核。
- 技能符合性矩阵：技能名称、检查项、符合状态、证据位置、问题说明。
- 缺失与风险：缺少的章节、不可验证需求、追溯性不足、接口描述不完整等。
- 修改建议：按优先级给出可执行改进项。
- 附录：解析到的文档目录、模型提示摘要、版本信息。

## 7. Python 技术路线分析

候选技术：

- Web 框架：FastAPI 或 Flask。
- DOCX 解析：`python-docx`。
- 配置读取：`PyYAML`。
- 模型调用：`requests` 或 OpenAI 兼容 SDK。
- 报告生成：`python-docx` 生成 DOCX，或 `markdown` 先生成 Markdown。

优点：

- 后端可直接读取本仓库的 `SKILL.md` 和 `api_config.yaml`。
- DOCX 解析和 DOCX 报告生成库成熟。
- 更适合调用内网模型接口，避免浏览器跨域和接口暴露问题。
- 离线部署清晰，可用虚拟环境、wheelhouse 或 PyInstaller 打包。

缺点：

- 需要在内网服务器安装 Python 运行环境和依赖。
- 前端交互能力较弱时，需要额外编写模板或少量静态资源。

## 8. HTML + CSS + JavaScript 技术路线分析

候选技术：

- 纯前端页面：HTML、CSS、JavaScript。
- DOCX 读取：浏览器端可用 Mammoth.js 提取文本。
- 报告生成：前端生成 Markdown、HTML 或借助 docx.js 生成 DOCX。

优点：

- 部署简单，静态文件可直接由 Nginx 或文件服务器提供。
- 用户界面响应快，适合做上传进度、结果预览、筛选技能等交互。
- 若只做本地规则检查，可减少服务端复杂度。

缺点：

- 纯前端无法安全读取服务器上的 `GJB438C-2021_prd_skills/` 全量文件，除非预先打包为 JSON。
- 调用内网模型会暴露接口地址和凭据，并可能遇到 CORS 限制。
- DOCX 结构、表格、页眉页脚和复杂格式解析能力通常弱于 Python。
- 大文件分析、报告生成和审计留痕不如后端集中处理可靠。

## 9. 推荐方案

建议采用 Python FastAPI + 简洁 HTML/CSS/JavaScript 前端的混合方案。

FastAPI 负责文件上传、DOCX 解析、技能加载、模型调用和报告生成；前端只负责上传、展示进度、显示结果摘要和下载报告。该方案在离线内网环境中更稳健，也能最大化复用当前仓库中的 Markdown 技能文件和 YAML 配置。

## 10. 离线部署方案

1. 在联网环境准备依赖：
   - `fastapi`
   - `uvicorn`
   - `python-docx`
   - `pyyaml`
   - `requests`
   - `jinja2`
   - `python-multipart`
2. 整个项目使用python的库管理器uv，然后使用 `pip download -d wheelhouse -r requirements.txt` 准备离线依赖包。
3. 将代码、`wheelhouse/`、`GJB438C-2021_prd_skills/`、`configs/` 一并拷贝到内网服务器。
4. 在内网执行 `pip install --no-index --find-links wheelhouse -r requirements.txt`。
5. 启动服务：`uvicorn app.main:app --host 0.0.0.0 --port 8000`。
6. 确认服务器可访问 `http://10.30.10.1:8000/v1` 模型接口。

## 11. 安全与配置要求

- 上传文件和生成报告默认保存在临时目录，定期清理。
- 限制上传类型为 `.docx`，限制单文件大小。
- 不在前端暴露模型 API 配置。
- `configs/api_config.yaml` 中的真实密钥和内网地址不应进入公开仓库。
- 报告中应标注“模型分析结果需人工复核”，避免将自动分析当作正式审查结论。

## 12. 开发里程碑

### 阶段一：原型

- 搭建 FastAPI 上传页面。
- 实现 DOCX 文本与标题提取。
- 加载技能索引并支持手动选择技能。
- 生成 Markdown 分析报告。

### 阶段二：可用版本

- 实现自动技能匹配。
- 接入内网 `qwen3-coder` 模型。
- 生成 DOCX 下载报告。
- 增加错误处理、文件大小限制和日志。

### 阶段三：增强版本

- 增加符合性矩阵和证据定位。
- 支持批量文档分析。
- 增加任务状态页面和历史记录。
- 增加离线安装脚本和部署说明。

## 13. 验证方式

- 使用 `test/` 下样例 DOCX 进行上传验证。
- 用不同文档类型验证技能匹配准确性。
- 断开公网，仅保留内网模型接口，验证离线可运行。
- 检查生成报告是否包含命中技能、问题列表、证据摘要和修改建议。
- 使用 `git diff --check` 检查文档格式。