# 简易 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` 检查文档格式。