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

26软工实践 棋理学伴 团队展示 · 选题报告 · 需求分析

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

文档版本：需求评审稿 v1.0｜本次提交覆盖：团队展示 · 选题报告 · 需求分析

---

一、团队展示

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	蔡以恒	测试与验收	自动化测试、冒烟与验收标准	注重复盘，习惯以用例验证	用例设计与自动化测试、接口联调；爱好：桌游、跑步
102401414	许书凯	视觉与文档	界面视觉、博客与讲稿录屏	具审美意识，擅长摄影与版式	Figma 视觉版式、剪辑与录屏；爱好：摄影、逛展

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

1.4 团队分工说明

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

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

1.5 团队愿景

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

1.6 协作机制

机制	具体做法
需求可验收	需求先转成可检查的验收条目，再进入开发，避免"做完了才发现不是要的"
一人主责 + 一人复核	每个模块由作者以外的成员承担交叉复核，减少"自己测自己"的盲区
每周一次例会	只讲三件事：进展、阻塞、能不能当场跑一遍
固定回归口径	以自动测试与 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 项目标志：矢量源文件（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 题、分类/主题筛选、翻转、重试	棋子显示正确；筛选结果与"下一题"一致	P0
F02	走法与目标判定	合法性、三态判定、多解接受	非法被拒；合法未达标有区别提示；多解全通过	P0
F03	受阻时的辅助	三级提示、E1–E4 证据、本地解法回放	提示逐级递进；证据取自实际走法	P0
F04	错误记录与复练	错题本、重练、导入导出	刷新不丢；多标签页不互相覆盖	P1
F05	棋力参考	手动调用 Pikafish	返回合法推荐；区分绝杀与困毙	P1
F06	着法解释	DeepSeek 逐步讲解	调用状态可见；结构错误明确失败，不假装成功	P0
F07	定制效果评估	基础组 / 定制组同条件对照	保存原始输出，可人工逐条点评	P2
F08	多步残局	2–3 步连续将杀	黑方自动应将；最终绝杀才计通关	P1

优先级口径：P0 为训练闭环必需，P1 为闭环之外的增强，P2 为评估配套；本期全部列入范围，按 P0 → P1 → P2 排开发顺序。

3.8 非功能需求

N01 安全与成本

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

N02 交付方式

• 计划交付：HTTPS 站点 + 项目口令访问；随包提交源码、启动说明与复现步骤
• 交付前需完成：真实用户试用、模型讲解抽样评审、公网安全检查

3.9 定制效果的检查方式（计划）

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

层次	怎么查	何时验证
软件正确性	自动测试覆盖判定、提示、回放与错题记录；另做 20 题可解性校验	开发阶段、每次交付前
规则与判定	逐题核对目标、多解、多步将杀	开发阶段
定位 / 引用一致性	结构校验失败即报错；引用不一致时保留原文并附加提示	开发阶段
教学效果	基础组 vs 定制组同条件对照 + 人工点评	上线后、真实用户试用

3.10 迭代记录（需求稿）

下表记录的是需求稿的评审与修订，不是软件版本；软件迭代在开发阶段再维护。

版本	时间	主要变更	触发原因	影响范围	评审方式
v0.1 初稿	10-21	团队分工、领域选择、用户假设 H1–H4 与 20 题结构初稿	作业要求下达、组内分工	1.3、2.1、2.2	组内通读，逐条标注疑问
v0.2 调研稿	10-22	依据 42 份问卷与 6 位访谈补写 2.2–2.3；H4（付费意愿）不成立，去掉本期付费设想	调研结论与初稿假设不一致	2.2、2.3、3.7	对照问卷与访谈原始记录交叉核对
v0.3 范围稿	10-23	明确本期不做（自由对弈、在线匹配、长将长捉、账号云同步）；补验收标准、智能体约束与三条信任边界	组内评审发现范围过大、验收不可判定	2.3、3.2、3.3、3.7、3.8	按"一个模块一个主责人"逐项认领并复核
v1.0 评审稿	10-25	补全标志、思维导图、模块依赖图并定稿；全文收敛为团队展示 / 选题报告 / 需求分析三部分	评审意见与作业提交要求	全文	对照作业要求逐条检查，组内终审

---

团队：棋理学伴团队｜文档：需求评审稿 v1.0｜2026 秋软工实践 · 团队作业第一次