软件工程第一次团队作业

26软工实践 棋理学伴 团队展示与选题报告

项	内容
作业所属课程	2026 秋软件工程实践（福州大学 202601SofwareEngineering）
作业要求	团队作业-第一次：团队展示 + 选题报告 + 需求分析
作业的目标	围绕一个真实领域，用领域知识把一个通用模型定制成"懂这一行"的智能体，并在它之上做出功能完整、能实际使用的软件。本次作业要交的是三件事：把团队立起来、把选题说清楚、把需求分析写实——不是先画大饼再回头补。
团队名称	棋理学伴团队
团队成员学号-名字	182400143 张宇天、102401418 王宇航、102401421 丁政伟、292400336 吴涵彬、112401430 王龙滨、112401341 吴佳辉、102401404 孟维涛、102402117 蔡以恒、102401414 许书凯

项目已上线：https://qili.jhw233.online（HTTPS + 项目口令）
源码版本：qili-study v0.2.10｜自动测试 172 项全通过｜20 个教学局面可解性校验通过

---

一、团队展示

1.1 队名

棋理学伴

一句话定位：面向象棋初学者的短局面战术学习助手——用户先独立落子，再依据规则证据与分级讲解，理解这一步为什么成立。

我们不提供"最优解"，我们提供"这一步为什么对/为什么错"。

1.2 团队首次合照

【待补：团队首次合照】

1.3 队员风采

九人九职，每人对应一个可交付的模块。

学号	姓名	团队角色	主责交付物	性格	擅长技术 / 兴趣
182400143	张宇天	队长 / PM	规划、分工、进度与答辩统筹	沉稳，善于统筹；棋龄较长	项目排期与需求拆解、Git 协作流；爱好：象棋、城市骑行
102401418	王宇航	需求分析	调研访谈、需求优先级与需求文档撰写	耐心细致，注重追因	问卷与访谈设计、飞书/Axure 文档；爱好：心理学读本、纪录片
102401421	丁政伟	领域知识	7 条棋理与 20 题教案整理	注重细节，擅长资料整理	象棋残局资料整理、Notion 知识库；爱好：打谱、读史
292400336	吴涵彬	规则与算法	合法判定、多解枚举与短将杀搜索	严谨，关注边界情况	JavaScript 搜索算法、node:test 单测；爱好：算法题、解谜游戏
112401430	王龙滨	前端交互	棋盘操作、解法回放与自由摆谱	响应快，擅长交互原型	原生 JS 与 Canvas、Figma 原型；爱好：摄影、前端动效
112401341	吴佳辉	后端与安全	接口、访问口令、限流与模型代理	谨慎，习惯先查日志	Node.js/Express、Linux 运维与安全加固；爱好：CTF、自建服务
102401404	孟维涛	AI 集成	提示编排、结构校验与对照评测	关注提示工程，常读技术文献	Prompt 设计、结构化输出校验、Python；爱好：读论文、模型评测
102402117	蔡以恒	测试与验收	172 项自动测试、冒烟与验收标准	注重复盘，习惯以用例验证	用例设计与自动化测试、接口联调；爱好：桌游、跑步
102401414	许书凯	视觉与文档	界面视觉、博客与讲稿录屏	具审美意识，擅长摄影与版式	Figma 视觉版式、剪辑与录屏；爱好：摄影、逛展

说明：性格与角色对应团队内部的实际分工；"擅长技术 / 兴趣"一栏用于补充成员画像，不影响"主责交付物"的归属。

1.4 团队分工说明

分工的核心原则是一个模块只有一个主责人，一件交付物只对应一个验收人：

• 产品侧（张宇天、王宇航、丁政伟）：范围与优先级、需求文档、领域知识（7 条棋理 + 20 题教案）
• 技术侧（吴涵彬、王龙滨、吴佳辉、孟维涛）：规则判定与搜索、前端交互、后端与安全、AI 集成与提示编排
• 验证侧（蔡以恒、许书凯）：自动测试与验收口径、界面视觉与对外材料

1.5 团队愿景

我们想做的不只是一个"能答题的象棋软件"，而是一个愿意把理由讲清楚的陪练：初学者走完一步，能看见规则层面的证据、看见对手的反击、也看见自己错在哪里；练过的错误会被记住，下次以另一种方式回到他面前。让"走对一步"和"理解为什么"被连接起来，这是我们希望达到的目标。

1.6 协作机制

机制	具体做法
需求可验收	需求先转成可检查的验收条目，再进入开发，避免"做完了才发现不是要的"
一人主责 + 一人复核	每个模块由作者以外的成员承担交叉复核，减少"自己测自己"的盲区
每周一次例会	只讲三件事：进展、阻塞、能不能当场跑一遍
固定回归口径	每次交付前统一执行 node --test tests/*.test.js 与 20 题可解性检查

---

二、选题报告

2.1 领域与选题

领域：中国象棋的基础规则与短局面战术（残局、短将杀）。

为什么选这个领域：它是一个规则完全可判定、但解释极其依赖经验的领域。走法合不合法、有没有将军、是否绝杀，程序可以算得比人准；但"为什么这步好、为什么不那样走"，需要把规则、局面和思路串起来讲明白。这恰好是"程序负责判定、模型负责解释"的理想分工点——也是我们把智能体放进软件里最站得住脚的位置。

2.2 调研情况

调研目标只有一个：验证"初学者缺的是理由，不是答案"这个假设是否成立。

• 问卷 42 份（线上 31、线下 11）
• 深度访谈 6 人，每人 20–30 分钟，逐字稿匿名化保存
• 78% 表示愿意使用讲解类功能

访谈原话（摘录）

"知道该走车，但说不清为什么不能先走马。"
—— 大二 · 学棋 4 个月

"视频里讲得很顺，轮到我自己摆，还是不知道错在哪一步。"
—— 大三 · 学棋半年

"走完之后要是能告诉我这步哪里不对，我愿意用。"
—— 研一 · 自学 1 年

四条假设的验证结果

假设	结论	依据
H1 需要理由而非答案	支持	6 人中 5 人主动提到"想知道为什么"
H2 规则混淆是主要卡点	支持	问卷 68% 勾选"马腿、炮架分不清"
H3 分级提示不破坏思考	部分支持	2 人承认会直接照做第三级示例
H4 愿为讲解单独付费	不支持	仅 21% 愿付费，更接受课程内置

关于样本量，我们如实说明：42 份问卷、6 个访谈只能界定首期范围，不足以外推到全部初学者。H4 不支持这条我们保留了——它直接影响了产品的商业化设想（本期不做付费）。

2.3 目标用户与使用场景

典型用户画像

小林，大二，自学象棋三个月
掌握基本走子与简单杀法；面对残局时常能判断优劣，但说不清依据；习惯用搜索了解单步理由；不愿为一次疑问专门请教练。

使用场景：课间十分钟打开手机，选一个两到三步的残局，自己走一步，发现被拒或者提示"合法但未达目标"，然后点开三级提示，或者看 AI 逐步讲解这一段为什么不行。

本期不做：完整自由对弈、在线匹配、长将长捉裁定、账号体系与云同步。

2.4 现有替代方案的不足

方案	能做到	缺什么
棋谱书 / 视频课	体系完整	与当前局面不同步，没有针对性反馈
象棋引擎	给出最优解	是评分和主变化，不是教学解释，初学者读不懂
真人教练	效果明确	单次复盘的时间与费用成本高

机会点：在同一局面上，同时给出规则事实与可读解释——判定由程序完成，解释由模型依据证据组织。

2.5 核心任务链：一次完整的学习闭环

步骤	用户动作	系统行为
1 选题	按"基础入门 / 残局专题"和车马炮兵主题筛选	展开题库，显示完成标记
2 独立落子	点击棋子、点击目标格	非法走法被拒；合法但未达目标给出区别提示
3 拿到判定	—	三态清晰：通过 / 未达标 / 非法
4 获取帮助	三级提示 → 本地解法 → AI 讲解	提示递进；证据取自实际走法；AI 调用显示真实状态
5 错题重练	在错题本点"再练一次"	区分"提示后完成"与"独立完成"，不把看答案算成学会

图 2-1 一次完整的学习闭环：五个步骤走完回到错题重练；第 5 步不删除记录，只标记状态

闭环的关键设计：第 5 步不删除记录，只标记状态。否则"错题本"会变成"已删列表"，看不出进步。

---

三、需求分析

3.1 领域知识与资料来源

领域性体现于可核验的规则条目，而不是模型的自由生成。

7 条棋理（每条附出处与示例）

1. 车的直线与阻挡
2. 炮架与隔子吃
3. 马腿被别
4. 象眼被塞
5. 兵的方向与过河
6. 应将的定义
7. 绝杀与困毙的区别

单个题目的教学结构

目标（吃子 / 应将 / 将杀）
  → 三级提示（观察方向 → 路径 → 具体着法）
  → 参考着法与 E1–E4 规则证据
  → 常见错误

20 题组成：8 道基础题 + 12 道残局，其中 8 道为两至三步连续将杀。

资料分层与许可

层	内容	来源与许可
规则	走法合法性、将军、将杀判定	上游开源规则与记谱（MIT），固定版本提交
教学	20 个局面、目标、提示、教案	团队自编，未标注任何教材摘录
棋力	参考分析与候选评分	Pikafish（GPLv3）+ 权重独立许可
讲解	逐步解释与整体总结	DeepSeek 官方接口，用户主动调用

边界（已写入文档，避免过度承诺）：长将、长捉与循环局面裁定不在本期；引擎评分不换算成胜率；一条引擎胜线不等于证明全部防守失败。

3.2 智能体定制思路

六步流程

图 3-1 六步定制流程：判定与事实由程序提供，模型只负责组织语言

步骤	谁做	做什么
规则判定	程序	合法性、是否将军、目标是否完成
知识检索	程序	按题目标签取对应规则条目与教学案例
引擎参考	Pikafish	给候选着法与评分，供解释引用
提示编排	程序	按"目的—应对—结果—其他选择"组织素材
讲解与校验	模型 + 程序	模型组织语言，程序校验结构与引用一致性

四项定制措施

1. 知识整理：7 条棋理 + 20 题教案，每条带出处
2. 标签检索：按题目主题检索条目（未使用向量库，标签足够精确）
3. 工具调用：规则证据与引擎候选都可复核
4. 提示编排：固定"目的—应对—结果—其他选择"的四段式

三条硬约束

• 判定不交由模型：合法性、绝杀与目标完成状态由本地规则程序计算
• 着法来源固定：棋盘与回放只采用本地核验过的线路，不执行解释文本里临时提出的着法
• 输出需经校验：结构损坏或步骤缺失明确报错；引用不一致时保留原文并附加提示

我们没做的，也写清楚：未进行模型微调，未使用向量检索。一致性提示能识别明显错配，但不保证解释完全正确。

3.3 系统架构与信任边界

图 3-2 系统架构：浏览器只负责操作与呈现，服务端重新核验并调度引擎与模型，三条信任边界见下表

三条信任边界

边界	做法
前端不可信	不接受前端上传的判定结果，服务端重新计算局面与历史
后端不存密钥	API Key 只存在页面内存，经服务端转发，不落盘、不入日志
引擎可降级	引擎不可用时保留规则核验与证据，明确标注讲解降级

复用与新增

• 复用：上游象棋规则与记谱模块（MIT）· Pikafish 引擎（GPLv3）与独立许可权重
• 新增：20 题教学题库、目标判定与多解枚举、三级提示与证据链、逐步讲解与摆谱、对照评测

主项目 MIT 不覆盖引擎与权重；公网访问用口令收敛范围，权重授权仍需与上游确认。

3.4 项目标志

主标志以棋盘九宫格为骨架，把"棋子"抽象成网格上的判断节点：米色圆环是规则边界，中央朱红点是当前这一着，其余交叉点代表可比较的候选。配色直接取自界面（深绿 #234b40、米色 #d8c597、朱红 #b54c3d），不使用棋类 App 常见的木纹写实风；报告中的其余图表沿用同一套配色，与产品视觉保持一致。

图 3-3 项目标志：矢量源文件为 public/logo.svg，此处为 1200 px 位图版本

3.5 思维导图

图 3-4 思维导图：团队 → 选题 → 需求 → 智能体；每条主线都对应报告或实现里可检查的部分

3.6 类图 / 模块依赖图

如实说明：本项目的源代码以模块和函数组织，没有同名的面向对象类。因此这里给出的是模块依赖关系图，而不是强行画一张 UML 类图去对应不存在的类。

图 3-5 模块依赖关系图：public/* 依赖规则库与后端 HTTP，src/* 依赖规则库与 engine.js，server.js 为唯一对外入口

依赖方向：public/* 只依赖 vendor/xiangqi.js（规则）与后端 HTTP 接口；src/* 依赖 vendor/xiangqi.js 与 engine.js；server.js 是唯一对外入口。

3.7 功能需求与验收标准

每项需求都能由外部人员复现验收，不使用"体验流畅""效果良好"这类无法验证的表述。

编号	需求	对应功能	验收标准（可复现）	状态
F01	选题与操作	20 题、分类/主题筛选、翻转、重试	棋子显示正确；筛选结果与"下一题"一致	已实现
F02	走法与目标判定	合法性、三态判定、多解接受	非法被拒；合法未达标有区别提示；多解全通过	已实现
F03	受阻时的辅助	三级提示、E1–E4 证据、本地解法回放	提示逐级递进；证据取自实际走法	已实现
F04	错误记录与复练	错题本、重练、导入导出	刷新不丢；多标签页不互相覆盖	已实现
F05	棋力参考	手动调用 Pikafish	返回合法推荐；区分绝杀与困毙	已实现
F06	着法解释	DeepSeek 逐步讲解	调用状态可见；结构错误明确失败，不假装成功	已实现
F07	定制效果评估	基础组 / 定制组同条件对照	保存原始输出，可人工逐条点评	机制已实现，真实对照待补
F08	多步残局	2–3 步连续将杀	黑方自动应将；最终绝杀才计通关	已实现

3.8 非功能需求

N01 安全与成本

• 线上访问需项目口令（timingSafeEqual 比较）；本机默认只监听 127.0.0.1
• 校验 Origin 与 Host；请求体大小与频率受限（12 次/分/客户端）
• CSP 严格；全站不使用 innerHTML
• API Key 只存在页面内存；模型调用由用户主动触发，失败不自动重试，避免重复计费
• 每次引擎分析独立进程、单线程、64 MiB 哈希，避免长期占用 CPU

N02 交付方式

• 已上线：https://qili.jhw233.online（HTTPS + 项目口令）
• 尚未完成：真实用户评测、模型质量大样本评测、公网渗透测试

3.9 定制效果的检查方式

评审口径要先分清两件事：软件正确性（可自动化验证）和模型教学效果（需真实用户验证）是两类验证，前者不能证明后者。

层次	怎么查	现在能不能查
软件正确性	172 项自动测试 + 20 题可解性校验	能，见第四节复现步骤
规则与判定	逐题核对目标、多解、多步将杀	能
定位/引用一致性	结构校验失败即报错；引用不一致加提示	能
教学效果	基础组 vs 定制组同条件对照 + 人工点评	机制已实现，真实结果待补

3.10 迭代记录

本表只记录有据可查的改动：每条都能在 docs/ 对应说明与自动测试数量上对上，未记录的不补写。

迭代	时间	主要变更	触发原因	影响范围	验证方式
v0.2.7	10-22	离开页面即中断在途模型请求并释放占用；残局、识图、参考分析与讲解草稿写入 sessionStorage，刷新后恢复但不自动重试	刷新后后台仍占用模型、草稿丢失	app.js、api-settings.js、learning-store.js	154 项自动测试 + 浏览器刷新复现
v0.2.8	10-22	讲解一致性由"拦截整份讲解 / 要求补写"改为"先显示原文 + 页面黄色提醒"（advisory 模式）	模型可能出现着法、证据或胜负措辞不一致	coach.js、coach-validation.js、app.js	162 项自动测试；advisory 模式检查
v0.2.9	10-22	"参考着法"统一为"查看本地解法"，新增独立回放棋盘（选步 / 上下步 / 走前走后 / 从所示局面摆谱）；调用状态区分成功、带提醒成功与失败	回放入口与调用状态不统一；失败时会自动展示本地答案	walkthrough-view.js、coach.js、app.js	166 项自动测试 + 浏览器回放检查
v0.2.10	10-22	摆谱与回放核验同步：顶部、全局反馈与设置区状态一致；回放切换按实际 FEN 更新行棋方、合法走法数与判定；换题 / 重试清理旧提示	连续将杀的中间将军被误判为绝杀；旧结果串到新棋盘	walkthrough.js、walkthrough-view.js、app.js	172 项自动测试 + 20 题可解性 + 手动回放

---

四、当前进展与验证方式

4.1 已验证的结果

项目	结果
自动测试	172 项：172 通过 / 0 失败 / 0 跳过
教学局面	20 个自编局面全部可解（含多解与多步防守分支）
线上服务	https://qili.jhw233.online 返回 200，HTTPS + 口令
源码文件完整性	109 项文件清单校验通过（SOURCE-MANIFEST.json）

4.2 如何自行复现（重要）

拿到源码包后，按顺序执行下面五步，否则会遇到两个看起来像 bug、实际是准备步骤的问题：

# 1) 安装开发依赖（jsdom / pngjs 是 devDependencies，源码包不含 node_modules）
npm install

# 2) 合并 NNUE 权重（权重以 4 个分片分发，需先拼成 engine/pikafish.nnue）
node scripts/prepare-engine.js

# 3) 自动测试：期望 172 通过、0 失败、0 跳过
node --test tests/*.test.js

# 4) 20 题可解性校验：期望 "Verified 20 authored teaching positions"
npm run verify

# 5) 启动
npm start        # 默认 http://127.0.0.1:3000

说明：若跳过第 2 步，会有 2 项依赖真实引擎的测试被跳过（而不是失败）。这两项在权重就绪后会正常执行。

4.3 已知问题

问题	状态
启动脚本路径在部分目录下不正确	待修（计划 10/26–11/01）
限流判断顺序可被绕过	待修
识图报错提示顺序不直观	待修
公网端口 80 因备案限制返回 403	请始终使用 https:// 访问

---

五、范围控制与下一步

5.1 风险与应对

风险	影响	应对
模型讲解不稳	教学价值不足	一致性提醒 + 人工核对 + 对照评测
图片识别误差	错误局面进入分析	必须人工校正后才能分析；已记录真实误差
单机限流与费用	多人访问受限	口令 + 配额；服务化前先评估成本
进度紧张	交付不完整	优先保证训练闭环与测试，再补调研

5.2 下一步

时间	事项
10/24	课上答辩：10 分钟主讲 + 6 分钟问答
10/25	博客提交
10/26–11/01	修复 3 个已知问题；继续开展访谈
11 月	线上反馈收集、真实对照样本与人工点评

5.3 一句总结

训练闭环已完成并上线，尚缺真实用户反馈与对照数据。

我们把这句话写在最后，是因为它就是我们现在的真实位置：软件是被验证过的，教学效果还没有。这两件事不混为一谈，是这次作业里我们最想守住的底线。

---

团队：棋理学伴团队｜线上：https://qili.jhw233.online｜源码版本 v0.2.10｜测试 172 项全通过