@pzy560117/codex-harness 0.1.0 → 0.1.1

package/package-source/docs/codex-harness-engineering/templates/package-assets/skills/thesis-writing/SKILL.md

@@ -0,0 +1,841 @@
+---
+name: thesis-writing
+description: 计算机专业本科毕业论文撰写全流程。用于把已有项目改写为系统类毕业论文，包含体裁判断、章节设计、图表规范、引文规则、开题与实现差异处理、测试结果写法、降重/降 AI 率和最终排版检查
+---
+
+# 毕业论文撰写 Skill
+
+## 概述
+
+将一个已完成的软件项目转化为符合学校规范的**系统类本科毕业论文**，覆盖从前期研究、写作策略、章节搭建、正文改写、图表整理、参考文献、测试结果到 Word 落版检查的全流程。
+
+> [!IMPORTANT]
+> 默认目标是写出“围绕问题展开论证”的论文，而不是把需求文档、接口说明、源码目录、命令日志和页面截图直接拼成开发说明书。
+>
+> 只有在学校模板或任务书明确要求“毕业设计说明书”体裁时，才允许保留更强的工程文档结构。
+
+## 何时使用
+
+- 需要根据已有项目撰写毕业论文
+- 已经有代码、开题报告、需求文档，但正文写出来像设计文档
+- 需要把工程事实改写成论文论证
+- 需要统一图表、表题、引文、参考文献和格式要求
+- 需要控制查重率和 AI 痕迹
+
+## 前置条件
+
+- 项目代码完整可读
+- 至少具备以下资料中的两类：开题报告、任务书、需求文档、测试计划、数据库脚本、关键页面截图
+- 最好有学校模板；如果没有，按常见系统类本科论文规则先写，再在最终排版阶段对模板细节补齐
+
+## 模板优先规则
+
+如果项目目录中已经提供学校论文模板或“论文模版/模板”文件，必须优先提取其中的**正文内容要求**，再决定章节骨架。
+
+若当前项目使用的是青岛城市学院这份模板，继续读取：
+
+- `references/template-qingdao-city-university.md`
+
+正文内容要求包括：
+
+1. 摘要字数、写法和要素要求
+2. 章节名称与章节顺序
+3. 各章必须包含的小节
+4. 图、表、代码、用例图、E-R 图等硬性内容要求
+5. 每章建议篇幅占比
+6. 参考文献数量、时间范围和引用要求
+7. 结论部分的写法边界
+
+以下内容不属于本 skill 当前重点，可只做提示，不做深入展开：
+
+- 字体
+- 行距
+- 页边距
+- 页码
+- 页眉页脚
+- 封面格式
+
+---
+
+## 目标产物
+
+本 skill 的目标不是只产出一份 `论文.md`，而是同时产出以下认知结果：
+
+1. 这篇论文的**体裁定位**是什么。
+2. 这篇论文的**关键技术问题**是什么。
+3. 开题阶段设想与最终实现之间有哪些**差异与取舍**。
+4. 哪些图、表、代码清单应该保留，哪些应该删除或降级。
+5. 哪些段落仍然像需求文档/设计文档，需要重写。
+
+同时，默认还应有一份与论文正文分离的**论文分析工作文档**，用于承载：
+
+1. 开题与实现差异表
+2. 当前论文问题清单
+3. 问题 - 方案 - 证据 - 验证矩阵
+4. 章节重构建议
+5. 图表与引文待补清单
+
+> [!IMPORTANT]
+> 上述分析材料默认不直接写进论文正文。
+>
+> 除非学校模板明确要求某项内容必须作为正文小节出现，否则这些材料应优先写入单独文档，再决定其中哪些结论需要转写进论文。
+
+推荐优先新建：
+
+- `docs/thesis-analysis.md`
+
+如需快速套用分析文档结构，可继续读取：
+
+- `references/thesis-analysis-template.md`
+
+---
+
+## 工作流程
+
+### 阶段零：体裁判断（PLANNING）
+
+#### 0.1 先判定当前文稿属于哪种偏差
+
+优先按以下标准判断：
+
+| 判断项 | 系统类论文 | 需求/设计文档 |
+|:---|:---|:---|
+| 主轴 | 问题 → 方案 → 实现 → 验证 | 模块 → 页面 → 接口 → 交付 |
+| 叙述主体 | 本文、系统、机制、模型、流程 | 前端、后端、类名、组件名、接口路径 |
+| 证据形式 | 图表、模型、少量关键代码、测试结果 | 大量命令、日志、接口表、页面说明 |
+| 结论方式 | 回答“为什么这样设计、验证了什么” | 回答“做了哪些功能、怎么实现” |
+
+如果当前文稿符合以下任一特征，应直接判定为“文档腔偏重”：
+
+1. 章节按“后端实现、前端实现”机械拆分。
+2. 摘要中出现构建命令、日志、退出码、模块数。
+3. 正文大量出现类名、组件名、接口路径。
+4. 图表多数是页面截图，缺少模型图和流程图。
+5. 参考文献在文末列出来了，但正文几乎没有引用。
+
+#### 0.2 明确当前论文是哪一种系统类论文
+
+计算机本科常见有两种：
+
+1. **工程型系统论文**：重点在需求、架构、模块设计、系统测试。
+2. **方法型系统论文**：重点在算法/模型/机制设计及实验评估。
+
+对绝大多数 Spring Boot + Vue、Java Web、管理系统、预约系统、平台系统类毕业设计，应按**工程型系统论文**处理。
+
+---
+
+### 阶段一：资料梳理（PLANNING）
+
+#### 1.1 必查资料顺序
+
+```text
+1. 学校模板 / 任务书 / 开题报告
+2. 需求设计文档 / 原型 / 测试计划
+3. 数据库脚本 / 接口定义 / 关键业务服务
+4. 前端关键页面 / 真实截图 / 已有图表
+5. 当前论文草稿
+```
+
+#### 1.1A 如果有学校模板，先抽“正文硬约束”
+
+从模板中至少抽出以下内容：
+
+1. 摘要：字数、第三人称要求、四要素要求、关键词数量
+2. 第一章：绪论必须包含哪些小节
+3. 第二章至第六章：章节名称是否固定
+4. 第三章：是否要求可行性分析、用例图、功能/非功能需求
+5. 第四章：是否要求系统架构图、功能结构图、E-R 图、表结构
+6. 第五章：是否要求按用户/管理员模块写实现，是否要求截图和核心代码
+7. 第六章：是否要求测试方法、环境、功能测试、性能测试、测试结果
+8. 结论：是否要求成果、不足、展望三部分
+9. 参考文献：最低数量、近五年文献比例、正文引用要求
+
+> [!IMPORTANT]
+> 如果学校模板没有明确给出更高的最低文献数量要求，本 skill 默认按**参考文献不少于 15 条**执行。
+>
+> 换言之，“能写成论文”不等于“文献够用”。对系统类本科论文，10 条左右通常只够搭框架，不够支撑终稿。
+
+> [!IMPORTANT]
+> 一旦模板对正文结构作出明确要求，模板要求优先于本 skill 的通用骨架。通用骨架只在模板未明确限制时使用。
+
+#### 1.1B 教师批注意见优先处理规则
+
+如果当前任务带有导师批注、截图批注或修改意见整理文档，应先把批注转成可执行清单，再改正文。优先处理以下高频问题：
+
+1. 摘要是否形成“问题背景 → 系统方案 → 核心方法 → 结果结论”的闭环，不能只写技术栈或测试过程。
+2. “本系统”“本项目”等指代词是否全文统一，通常论文正文优先使用“本系统”。
+3. 中文与英文、引用编号、西文作者名之间的空格和样式是否全文一致。
+4. 研究内容和论文组织结构是否拆成两个小节，不要混在同一段里。
+5. 第3章是否按“可行性分析、功能性需求分析、非功能性需求分析”组织。
+6. 第4章是否按“系统架构、功能结构、主要功能模块、数据库设计”组织。
+7. 第5章是否至少展开 6 个核心功能模块，并同时说明功能、实现方法、截图或代码证据。
+8. 流程图、状态图和截图是否符合论文图表规范，不能用不规范图形或大小明显不一致的截图直接落版。
+
+#### 1.2 把资料分成 4 类，不要混写
+
+| 资料类型 | 作用 | 在论文中的位置 |
+|:---|:---|:---|
+| 开题/任务书 | 提供研究背景、最初设想 | 绪论、研究目标、设计阶段设想 |
+| 需求文档/原型 | 提供角色、流程、功能边界 | 第三章需求与总体设计 |
+| 实际代码/数据库/接口 | 提供真实实现证据 | 第四章关键模块设计与实现 |
+| 测试与截图 | 提供验证与图表材料 | 第五章测试、第四章局部说明 |
+
+> [!IMPORTANT]
+> 开题报告中的内容不能直接等同于最终实现。凡是开题里有、代码里没有落地的内容，都必须写成“设计阶段设想”或“后续扩展方向”，不能写成已实现功能。
+
+#### 1.3 必做一张“差异表”
+
+如果开题报告和实际实现不一致，必须先整理差异：
+
+| 项目 | 开题设想 | 实际实现 | 论文写法 |
+|:---|:---|:---|:---|
+| 架构形态 | 微服务/注册中心 | 模块化单体 | 写成“经权衡后采用模块化单体” |
+| 支付 | 真实支付网关 | 沙箱支付 | 写成“以沙箱流程验证状态闭环” |
+| 文件存储 | MinIO/OSS | 本地文件存储 | 写成“采用接口抽象，预留对象存储扩展” |
+| 扩展功能 | 选片/通知/推荐 | 未完全实现 | 放入展望或设计阶段设想 |
+
+没有这张差异表，正文很容易把开题和现状混成一篇假论文。
+
+> [!IMPORTANT]
+> 这张差异表默认先写入独立分析文档，而不是直接作为论文“1.x 小节”落入正文。
+>
+> 论文正文通常只保留差异表中真正需要向读者交代的结论，例如：
+>
+> 1. “经权衡后采用模块化单体架构”
+> 2. “当前版本以沙箱支付验证状态闭环”
+> 3. “对象存储属于后续扩展方向”
+>
+> 不要把“分析过程文档”和“最终论文成稿”混在一起。
+
+---
+
+### 阶段二：提炼论文主轴（PLANNING）
+
+#### 2.1 先抽出 2-4 个关键技术问题
+
+正文不应按源码目录组织，而应按关键问题组织。常见问题包括：
+
+1. 认证与授权边界如何划分。
+2. 竞争资源如何保持一致性。
+3. 复杂订单状态如何流转与回滚。
+4. 前后端如何保持状态一致与交互闭环。
+5. 平台治理如何落地。
+
+#### 2.2 先做“问题 - 方案 - 证据 - 验证”矩阵
+
+| 技术问题 | 设计方案 | 实现证据 | 验证方式 |
+|:---|:---|:---|:---|
+| 档期并发冲突 | Redis 锁 + 状态二次校验 | 锁键、Lua 解锁、订单创建事务 | 并发预约测试 |
+| 订单闭环控制 | 状态机 + 超时回收 + 异常回滚 | 订单服务、支付回调、定时任务 | 支付/取消/退款测试 |
+| 权限边界控制 | JWT + RBAC + 资源所有权校验 | 鉴权配置、过滤器、服务层校验 | 越权访问测试 |
+| 前后端状态协同 | 路由守卫 + 状态映射 + 日历状态绑定 | 页面交互、状态映射逻辑 | 页面闭环验证 |
+
+> [!IMPORTANT]
+> 这张矩阵就是论文主骨架。没有矩阵，正文必然散。
+
+---
+
+### 阶段三：章节设计（PLANNING）
+
+#### 3.1 默认骨架
+
+优先采用以下六章制：
+
+| 章节 | 职责 | 目标 |
+|:---|:---|:---|
+| 第一章 绪论 | 背景、现状、目标、关键问题、结构安排 | 立题 |
+| 第二章 相关技术与理论基础 | 只写与方案直接相关的技术 | 铺垫 |
+| 第三章 需求分析与总体设计 | 角色、流程、需求、架构、数据库 | 建模 |
+| 第四章 关键模块设计与实现 | 围绕关键问题展开 | 论证 |
+| 第五章 系统测试与结果分析 | 验证问题是否被解决 | 证明 |
+| 第六章 总结与展望 | 收束全文并给出边界 | 结题 |
+
+若学校要求七章制，可拆分第三章/第四章，但不要破坏“问题驱动”的主轴。
+
+#### 3.1A 模板限定骨架时的处理规则
+
+如果模板已经固定章节名称和顺序，不要强行改成自己的理想目录。正确做法是：
+
+1. 保留模板要求的章名与章节顺序。
+2. 在模板章节内部再植入“问题驱动”的写法。
+3. 用模板章节承载论文逻辑，而不是和模板对抗。
+
+例如模板要求：
+
+- 第1章 绪论
+- 第2章 关键技术介绍
+- 第3章 系统分析
+- 第4章 系统设计
+- 第5章 系统实现
+- 第6章 系统测试
+- 结论
+
+则应在这些章节内重新组织论证重点，而不是直接另起一套“需求分析与总体设计/关键模块设计与实现”标题体系。
+
+如果模板已经明确存在“第5章 系统实现”，则应特别注意：
+
+1. **前端实现与后端实现可以作为“系统实现”章中的合法小节出现**，不必强行回避。
+2. 但这种拆分应只发生在“系统实现”章，不应让第3章“系统分析”和第4章“系统设计”也退化成前后端流水账。
+3. 正确做法通常是：
+   - 第3章解决“需求是什么”
+   - 第4章解决“系统怎么设计”
+   - 第5章解决“关键页面和关键业务是如何真正做出来的”
+4. 因此，“不要按前端实现/后端实现机械拆分”的限制，主要针对整篇论文或第3、4章，不是否定第5章按实现对象展开。
+
+#### 3.2 每章禁止事项
+
+**第一章**
+- 不要写命令、日志、截图说明
+- 不要直接抄开题报告原话
+
+**第二章**
+- 不要泛讲 Java、Spring Boot、Vue 的历史
+- 不要堆官网定义
+
+**第三章**
+- 不要把控制器、服务类和接口路径写成主线
+- 不要写成 Swagger 文档
+
+**第四章**
+- 不要按“前端实现/后端实现”机械拆分
+- 不要大段贴代码
+
+**第五章（默认骨架下为测试章）**
+- 不要把“构建通过”当成“系统测试完成”
+- 不要只写测试设计，不写测试结果
+
+**模板固定为“第5章 系统实现”时**
+
+1. 这一章允许写前端实现、后端实现，但必须围绕**关键模块或关键页面**展开。
+2. 不要把全部页面逐页罗列成产品说明书。
+3. 不要把全部控制器、服务类、接口逐个抄写成源码清单。
+
+**第六章**
+- 不要重复摘要
+- 不要把未做功能写成主要贡献
+
+#### 3.3 小节模板
+
+第四章及第五章的小节建议统一按以下结构写：
+
+1. 本节要解决的问题是什么。
+2. 为什么该问题在本系统中成立。
+3. 本文采取了什么机制或方案。
+4. 哪些实现细节能支撑该方案。
+5. 该方案验证结果如何，仍有什么局限。
+
+如果一个小节只有“做了哪些功能”，没有“为什么”和“验证了什么”，它就还是文档。
+
+---
+
+### 阶段四：正文改写规则（EXECUTION）
+
+#### 4.1 论文语言改写公式
+
+```text
+代码事实 → 技术问题 → 设计目标 → 方案取舍 → 实现证据 → 验证结果/局限
+```
+
+如果当前任务明确要求控制 AI 痕迹和查重风险，继续读取：
+
+- `references/ai-integrity-and-originality.md`
+
+#### 4.2 严禁直接写进摘要和正文主叙述的内容
+
+1. 构建命令、日志、退出码、模块数、耗时。
+2. 类名、组件名、接口路径、数据库字段名的大量堆砌。
+3. “前端点击按钮后调某接口”“后端执行某校验”这类开发口吻。
+4. “当前仓库”“本次会话”“此次验证”等过程记录语气。
+5. 把未执行测试的场景写成已验证结果。
+
+#### 4.3 可以保留，但只能降级为证据的内容
+
+- 类名、组件名、接口路径：只出现在代码清单说明、图注、实现证据中
+- 构建记录：只放在附录或验证记录，不进摘要
+- 页面截图：只作为交互闭环的证据，不能代替系统分析
+- 代码清单：每段只支撑一个论点
+
+#### 4.4 摘要写法
+
+摘要必须回答 4 件事：
+
+1. 为什么要做这个系统。
+2. 系统解决了什么问题。
+3. 本文采用了哪些关键方案。
+4. 系统验证到什么程度，仍有什么局限。
+
+摘要禁止出现：
+
+- `mvn test`、`vite build`
+- 某个类名、组件名、接口路径
+- “本次会话”“当前仓库”
+- “当前版本”这类项目过程记录语气
+- 具体日志文本
+
+如果模板对摘要有明确要求，必须同步满足：
+
+1. 优先以模板提炼结果为准。
+2. 当前项目模板的摘要要求见 `references/template-qingdao-city-university.md`。
+
+摘要修改时要特别检查两类衔接问题：
+
+1. 从行业痛点转向系统方案时，应说明“为什么需要三类角色协同”或“为什么需要闭环治理”，避免前后段突然跳转。
+2. 末段应写研究结果和结论，例如状态闭环、权限边界、档期冲突控制达到的效果；不要写成“项目已完成哪些页面和测试”的流水账。
+
+#### 4.5 研究现状写法
+
+研究现状不是罗列平台名称，而是要形成对比关系：
+
+1. 同类系统主要解决什么问题。
+2. 它们在哪些方面有侧重。
+3. 本文系统与它们的差异在哪里。
+4. 为什么本文选取当前这个问题切入。
+
+#### 4.6 相关技术写法
+
+第二章只写与本文直接相关的技术：
+
+- JWT
+- RBAC / 权限控制
+- Redis 分布式锁
+- 状态机
+- 前后端分离与状态同步
+- 数据建模
+
+不要写：
+
+- Java 发展史
+- Vue 框架简介大百科
+- Spring Boot 官网页式介绍
+
+如果模板明确要求“关键技术介绍”单独成章，应注意：
+
+1. 这一章只做技术铺垫，不要写成长篇系统实现。
+2. 内容要精简，通常不应成为全文主体。
+3. 每项技术最终都要回到“它在本系统中承担了什么作用”。
+
+#### 4.7 系统实现章写法
+
+当学校模板明确要求“系统实现”单独成章时，应把这一章视为“设计落地证据章”，而不是纯截图展示章。
+
+推荐结构：
+
+1. `5.1 前端主要页面实现`
+2. `5.2 后端关键业务实现`
+3. 必要时继续拆成 `客户端页面实现 / 摄影师端实现 / 管理端实现 / 后端关键模块实现`
+
+前端实现部分建议：
+
+1. 选择 `3-6` 个真正支撑业务闭环的页面，而不是把所有页面都写进去。
+2. 每个页面至少写清：
+   - 页面属于哪个业务环节
+   - 页面承担什么功能
+   - 页面与后端哪些状态或数据联动
+   - 该页面为何能支撑系统闭环
+3. 每个关键页面应配**真实运行截图**，截图必须来自浏览器实际运行界面，而不是设计稿、原型图或静态拼图。
+4. 截图后必须配解释文字，说明图中关键区域和实际交互意义。
+
+后端实现部分建议：
+
+1. 选择 `3-5` 个关键模块或关键机制，例如认证鉴权、档期控制、订单状态流转、管理员退款仲裁。
+2. 每个模块至少写清：
+   - 该模块解决什么问题
+   - 采用了什么实现方法
+   - 关键代码如何体现该方法
+3. 可以插入少量核心代码片段或代码图，但每段代码只支撑一个论点。
+4. 代码必须来自真实项目，且应优先选择服务层、配置层、核心逻辑层，而不是低价值的实体类或简单 CRUD。
+
+> [!IMPORTANT]
+> “系统实现”章允许出现前端截图和后端代码，但它们都只是**实现证据**，不能代替前面章节的系统分析和系统设计。
+
+> [!IMPORTANT]
+> 如果模板要求较强的工程展示风格，正确做法不是删除论文论证，而是把“前端页面证据”和“后端代码证据”收纳到“系统实现”章中。
+
+---
+
+### 阶段五：图表规范（EXECUTION）
+
+#### 5.1 图表类型清单
+
+系统类论文常见必需图表：
+
+| 类型 | 推荐数量 | 作用 |
+|:---|:---|:---|
+| 总体架构图 | 1 | 说明系统分层与协作 |
+| 业务流程图/角色流程图 | 1-2 | 说明核心流程 |
+| E-R 图 | 1 | 说明数据结构 |
+| 状态图 | 1 | 说明订单/资源状态流转 |
+| 时序图 | 1-2 | 说明核心交互 |
+| 页面截图 | 3-5 | 说明关键交互闭环 |
+| 表格 | 多个 | 环境、需求、测试、对比 |
+
+#### 5.2 图表落版规则
+
+1. **图题在下，表题在上**。
+2. 图号、表号必须按章节连续编号，如 `图 3-1`、`表 5-2`。
+3. 文中先引用，再出现图表。
+4. 每一幅图后面都要有解释，说明“这幅图证明了什么”。
+5. 每一张表不能只列数据，后面要有分析句。
+
+如果模板明确要求某类图表，则该图表属于硬性内容，不得省略。例如：
+
+1. 用例图
+2. 系统架构图
+3. 功能结构图
+4. E-R 图
+5. 核心流程图/时序图
+
+#### 5.3 不合格图表的典型特征
+
+以下情况必须重做：
+
+1. `mermaid` 代码块还停留在正文里，没有导出成正式图片。
+2. 图号已在正文中出现，但图题缺失。
+3. 文中写了“如表 2-1 所示”，实际没有“表 2-1”标题。
+4. 图文件存在，但正文没有引用。
+5. 图分辨率过低，放进 Word 后发虚。
+6. 页面截图没有裁剪、没有突出重点、没有配解释。
+
+#### 5.4 技术图规范
+
+对于架构图、E-R 图、状态图、时序图：
+
+1. 最终应使用 PNG/SVG 等正式图，不要保留 `mermaid` 源码块作为正文插图。
+2. 学术图优先黑白或低饱和配色，避免产品海报风格。
+3. 层次、箭头、标签必须清晰可读。
+4. 线框图尽量输出高分辨率或矢量格式。
+5. 流程图的开始、结束节点应使用椭圆形或圆角矩形，条件判断节点应使用菱形，处理步骤使用矩形。
+6. 若用户或项目要求“流程图类图片通过 AI 生图生成”，不得手写 SVG 作为最终图片；应使用 AI 生图生成 PNG，再保存到论文图片目录并由正文引用。
+
+推荐导出工具与格式：
+
+| 图类型 | 推荐工具 | 推荐格式 | 最低要求 |
+|:---|:---|:---|:---|
+| 架构图 / 流程图 | Draw.io（diagrams.net） | SVG 或 PNG | PNG 时保证清晰打印 |
+| E-R 图 | Draw.io / MySQL Workbench | PNG 或 SVG | 与表结构一致 |
+| 状态图 / 时序图 | PlantUML / mermaid-cli | SVG 优先 | 标签清晰可读 |
+| 用例图 | Draw.io / StarUML | PNG 或 SVG | 结构规范、角色清楚 |
+
+#### 5.5 页面截图规范
+
+页面截图不应只是“给老师看页面长什么样”，而应体现：
+
+1. 截图属于哪个业务环节。
+2. 用户在截图中完成了什么动作。
+3. 截图反映了哪种状态约束或交互机制。
+4. 该页面为何支撑了系统闭环。
+
+页面截图建议：
+
+- 保留浏览器真实界面，但裁掉无关区域
+- 必要时加红框/注释标出关键区域
+- 一图只说明一个核心点
+- 同一章内截图宽度和视觉尺寸尽量统一，避免图 5-x 之间大小差异明显
+
+#### 5.6 模板与项目专项图表要求
+
+若当前任务使用青岛城市学院模板，图表硬约束见：
+
+- `references/template-qingdao-city-university.md`
+
+若当前任务就是“独立摄影师拍摄预订系统”这篇论文，项目专项图表提醒见：
+
+- `references/photographer-booking-paper.md`
+
+---
+
+### 阶段六：引文与参考文献（EXECUTION）
+
+若当前任务需要快速补齐引文格式、研究现状句式和技术章节嵌入句型，继续读取：
+
+- `references/citation-templates.md`
+
+#### 6.1 参考文献不是摆设
+
+如果文末有参考文献，但正文几乎没有引文标记，这篇论文仍然是不合格的学术写法。
+
+#### 6.2 引文最低要求
+
+正文至少在以下位置出现引文：
+
+1. 第一章研究背景或研究现状
+2. 第二章相关技术与理论基础
+3. 第三章总体设计中引用同类系统或技术方案
+4. 第五章测试或结果分析中引用评估依据时
+
+#### 6.3 引文分布建议
+
+| 章节 | 引文用途 |
+|:---|:---|
+| 第一章 | 行业背景、国内外现状、同类系统 |
+| 第二章 | JWT、Redis、数据库、安全、状态机等理论或技术依据 |
+| 第三章 | 类似系统或设计方案参考 |
+| 第五章 | 测试设计方法或性能评价依据 |
+
+#### 6.4 引文规则
+
+1. 不要只在文末列参考文献，正文必须出现对应标记。
+2. 同类系统对比、关键技术介绍、研究现状分析必须有引用支撑。
+3. 官方文档可作为补充，但不能全靠官方文档撑起论文。
+4. 参考文献必须真实可检索。
+5. 正文引文编号必须按**首次出现顺序**连续编号，谁先首次出现就是 `[1]`，下一条首次出现就是 `[2]`，依次类推。
+6. 同一文献在正文中再次出现时，必须沿用第一次分配的编号，不能重新编号。
+7. 文末参考文献列表必须按**正文首次引用顺序**排序，不能默认按作者姓氏、拼音、年份或数据库导出顺序排列，除非学校模板明确另有要求。
+8. 当正文增删引文导致顺序变化时，必须同步全局重排正文编号和文末参考文献列表，不能只改其中一处。
+
+#### 6.4A 参考文献最低数量
+
+1. 如果学校模板、学院细则或导师没有给出更高要求，**论文终稿参考文献默认不少于 15 条**。
+2. 少于 15 条时，默认判定为“文献支撑不足”，尤其容易导致研究现状、关键技术依据和方案对比明显偏薄。
+3. 不要用 15 条官方文档来机械满足数量；数量达标的同时还必须满足来源结构要求。
+4. 若模板明确要求 20 条、30 条或“近五年不少于 x 条”，一律以学校要求优先。
+
+如果模板对参考文献作出明确要求，优先按模板提炼结果执行；当前项目模板要求见 `references/template-qingdao-city-university.md`。
+
+> [!IMPORTANT]
+> 对本 skill 默认适配的大多数中文本科论文，参考文献编号制的基本执行方式就是：
+>
+> 1. 正文谁先首次引用，谁就是 `[1]`
+> 2. 后续首次引用按 `[2]`、`[3]` 继续排
+> 3. 文末列表严格按 `[1]`、`[2]`、`[3]` 的正文引用顺序排列
+>
+> 如果学校模板没有明确写“按作者字母或年份排序”，不要擅自改成其他排序方式。
+
+#### 6.5 参考文献来源结构
+
+如果学校模板没有给出更细的来源结构比例，本 skill 默认采用以下参考文献构成建议：
+
+1. **中文参考文献约 60%**
+2. **英文参考文献约 20%**
+3. **其他参考文献约 20%**
+
+若按最低 15 条参考文献计算，优先采用以下基线：
+
+1. **中文参考文献不少于 9 条**
+2. **英文参考文献不少于 3 条**
+3. **其他参考文献控制在 3 条左右**
+
+这里的“其他参考文献”通常包括：
+
+1. 国家标准、行业标准、规范文件
+2. RFC、白皮书、技术手册
+3. 官方文档、产品文档、技术平台文档
+4. 必要的图书、报告、专利等非中英文期刊/会议来源
+
+> [!IMPORTANT]
+> 官方文档可以引用，但**不能成为论文参考文献主体**。
+>
+> 默认情况下，官方文档应归入“其他参考文献”这一类，通常只用于：
+>
+> 1. 技术定义核对
+> 2. 框架或协议的实现依据说明
+> 3. 工具、组件、标准接口的补充说明
+>
+> 不要用大量官方文档代替中文和英文学术文献，尤其不要用官方文档去支撑“研究现状”。
+
+中文参考文献优先顺序建议：
+
+1. 近五年的中文期刊论文
+2. 近五年的中文学位论文
+3. 近五年的中文会议论文
+4. 与系统场景强相关的中文行业研究或案例研究
+
+英文参考文献优先顺序建议：
+
+1. 英文期刊论文
+2. 英文会议论文
+3. 英文综述论文
+4. 必要的英文标准或权威技术资料
+
+其他参考文献使用边界：
+
+1. 用于补足协议、框架、标准、工具层面的事实依据
+2. 不宜在数量上超过中文和英文学术文献总和
+3. 不宜成为第一章研究现状的主要来源
+4. 若某篇文献只是技术手册而非学术研究，应避免在“国内外研究现状”中把它写成研究成果
+
+如果学校模板、学院细则或导师明确给出其他比例要求，以学校要求优先。
+
+---
+
+### 阶段七：测试与结果写法（EXECUTION）
+
+若当前任务需要直接套用测试用例表、性能测试表和结果分析句型，继续读取：
+
+- `references/test-result-templates.md`
+
+#### 7.1 测试章节要分三层写
+
+1. **测试环境**：说明环境与条件。
+2. **测试设计/测试用例**：说明如何测。
+3. **测试结果与分析**：说明测出了什么。
+
+如果只写前两层，没有第三层，章节仍然像测试计划，不像论文测试章节。
+
+#### 7.2 什么能写成“结果”
+
+可以写成结果的内容：
+
+- 功能场景已真实跑通，并有截图、日志或数据库状态佐证
+- 并发冲突控制的预期结果已验证
+- 状态流转的关键路径已验证
+- 越权访问被拒绝的场景已验证
+
+不能直接写成结果的内容：
+
+- 仅存在测试用例设计
+- 仅推断代码应该通过
+- 仅构建成功
+
+#### 7.3 构建验证的正确位置
+
+`mvn test`、`vue-tsc`、`vite build` 一类内容只能证明：
+
+1. 工程可编译
+2. 类型检查通过
+3. 前端可打包
+
+它们**不能**替代：
+
+1. 功能测试
+2. 业务闭环验证
+3. 并发控制验证
+4. 权限验证
+
+#### 7.4 模板测试章节约束
+
+如果模板明确要求测试章节结构和测试用例形式，优先按模板提炼结果执行；当前项目模板要求见 `references/template-qingdao-city-university.md`。
+
+#### 7.5 结论写法
+
+结论通常包含两部分：
+
+1. 总结主要成果、功能、性能、亮点或创新点。
+2. 分析不足并提出后续改进方向。
+
+必须避免：
+
+1. 使用“首次”“领先”“填补空白”等夸大表述，除非有充分证据。
+2. 把展望写成推翻现有系统。
+3. 把尚未完成的内容包装成已完成成果。
+
+如果要写，必须明确写成“构建校验”或“工程可用性验证”，不能冒充系统测试主结果。
+
+---
+
+### 阶段八：项目专项与最终检查（VERIFICATION）
+
+若当前任务就是“独立摄影师拍摄预订系统”这篇论文，继续读取：
+
+- `references/photographer-booking-paper.md`
+
+提交前的最终自查与落版检查，继续读取：
+
+- `references/final-checklist.md`
+
+#### 8.1 Word 落版要点
+
+- 标题样式统一映射到“标题 1/2/3”
+- 正文字号、行距、页边距按学校模板
+- 图题在下，表题在上
+- 页码按学校模板区分摘要页与正文页
+- 目录自动生成
+- 图表、参考文献、附录编号统一
+
+#### 8.2 最终交付判断标准
+
+一篇合格的系统类论文，至少应满足：
+
+1. 能看出研究问题，而不是只有模块清单。
+2. 能看出设计取舍，而不是只有实现细节。
+3. 能看出验证结果，而不是只有测试计划。
+4. 能看出图表支撑关系，而不是只有截图堆叠。
+5. 能看出引文依据，而不是只有文末参考文献。
+
+---
+
+## 操作策略
+
+当使用本 skill 实际改论文时，建议按以下顺序执行：
+
+1. 先新建独立分析文档，写入“当前论文问题清单”“差异表”“主轴矩阵”等中间材料。
+2. 再输出“章节重构方案”，明确哪些章保留、哪些章重组。
+3. 优先重写摘要、第一章、第四章主轴、第五章结果分析。
+4. 再修图表编号、表题、引文、致谢、参考文献。
+5. 最后才做降 AI 和语言细修。
+
+### 中间产物与终稿分离规则
+
+以下内容默认属于**分析中间产物**，应写入独立文档，而不是直接塞进论文正文：
+
+1. 开题与实现差异表
+2. 当前论文问题清单
+3. 章节重构方案
+4. 问题 - 方案 - 证据 - 验证矩阵
+5. 图表缺口清单
+6. 引文补齐计划
+
+以下内容才属于**论文终稿候选内容**：
+
+1. 绪论中的研究背景、研究意义、研究现状、研究内容、论文结构
+2. 系统分析、系统设计、系统实现、系统测试、结论
+3. 模板明确要求出现的表格、图题、代码清单和截图说明
+
+判断原则：
+
+1. 如果内容是在帮助作者分析“怎么写”，它通常应进独立文档。
+2. 如果内容是在帮助读者理解“系统是什么、为什么这样设计、验证了什么”，它才应进入论文正文。
+3. 如果学校模板未要求，尽量不要把“写作过程产物”直接伪装成论文章节。
+
+### 引文编号维护规则
+
+在生成或修改论文正文时，必须同步维护引文编号：
+
+1. 先确定正文中的首次引用顺序，再给参考文献编号。
+2. 不要先在文末堆一批参考文献，再回头随意插正文编号。
+3. 每次插入新文献时，都要检查它是否改变了后续文献的编号顺序。
+4. 每次删除一条正文引文时，都要检查文末列表是否需要整体顺延重排。
+5. 输出终稿前，必须做一轮“正文编号顺序”和“文末列表顺序”的一致性检查。
+
+### Prompt 调用顺序（防 AI 痕迹）
+
+每次向 AI 发起写作请求，优先按以下顺序，而不是一次性要求生成整章终稿：
+
+1. 只生成该小节提纲，明确“问题 - 方案 - 证据 - 验证”四要素。
+2. 人工补入本项目特有数据、边界、取舍和未完成项。
+3. 再让 AI 将补充后的提纲展开为段落草稿。
+4. 单独补引文标记、图注和表注。
+5. 最后人工通读，替换通用套话并统一全文口吻。
+
+禁止直接要求 AI 输出某章完整终稿。
+
+> [!IMPORTANT]
+> 不要一上来做句子润色。结构没立住，润色没有意义。
+
+---
+
+## 注意事项
+
+> [!CAUTION]
+> **降 AI 率关键**：必须加入项目特有的设计取舍、参数依据、问题边界和局限，避免整段空泛总结句。
+
+> [!CAUTION]
+> **论文体裁关键**：证据可以来自代码，但表达必须转化为论文语言，不能直接搬运仓库结构。
+
+> [!WARNING]
+> **真实性关键**：未落地的功能、未执行的测试、未接入的外部系统，绝不能写成已完成事实。
+
+> [!WARNING]
+> **图表关键**：`mermaid` 源码块、缺图题、缺表题、低分辨率线框图、未引用图片，都会直接暴露成稿不完整。
+
+> [!TIP]
+> **高效策略**：先搭建“问题 - 方案 - 证据 - 验证”矩阵，再写正文。
+
+> [!TIP]
+> **GitHub 经验吸收方式**：优先吸收写作规范中的章节职责、禁止项和论证方法，不要照抄别人的目录、套话或接口表格。
+
+## 更新日志
+
+- **2026-03-25**: 创建初始版本，基于剧本杀预约系统论文撰写实践总结
+- **2026-04-08**: 重写为“系统类论文体裁优先”版本，新增体裁判断、差异表、图表规范、引文规则、测试分层、项目专项指导和最终检查项
+- **2026-04-08**: 新增默认文献数量下限规则，明确终稿参考文献不少于15条，并给出 9/3/3 的来源结构基线