yshop 是基于当前流行技术组合的前后端分离 B2C（单商户）/ B2B2C（多商户）商城系统，采用 SpringBoot2 + MyBatis-Plus + SpringSecurity + JWT + Redis + Vue + UniApp 技术栈，包含商品、多规格、运费模板、素材库、拼团、快递、秒杀、优惠券、积分、分销、会员、充值等功能，适合企业或个人二次开发。
🤖 本项目同时是一套 NPC（数字员工）协作模式的实践样本——用 4 个 AI 角色 + 真人验收拍板的方式完成"需求 → 设计 → 拆解 → 编码 → 评审"的完整研发闭环。详见下方 NPC 协作矩阵。
本项目是 CNB NPC 协作模式的实践样本：NPC 自驱推进流程，真人负责验收和拍板。所有研发流程通过 issue / PR 上的标签 + 评论协作完成；NPC 之间不形成自治循环，每个关键决策节点都回到真人。
| 角色 | 类型 | 一句话职责 | 核心产出物 | 加载的 Skills |
|---|---|---|---|---|
| 📋 产品经理 | 协作型 | 把模糊需求细化为 PRD | issue 评论中的 PRD | prd-workflow |
| 🏗️ 研发 Leader | 协作型 | 出技术方案、拆原子任务、编排子任务依赖 | 技术方案 + 子 issue + 自动调度 | arch-design / task-breakdown / dependency-orchestration |
| ⚒️ 开发工程师 | 执行型 | 按子 issue 自包含上下文实现代码 | 代码 + PR | dev-workflow / preview / frontend-design |
| 👀 代码评审 | 协作型 | 按检查矩阵给出分级 review 意见 | PR 评论中的 Review | code-review |
所有 NPC 共同加载三件套底座：project-context（项目背景）+ label-protocol（标签协议）+ issue-collaboration（协作 SOP）。
图例：
- 🟨 PM / 🟪 Leader / 🟦 开发 / 🟩 评审 / 🟧 真人决策 / 🟥 阻塞与自动调度
- 🏷 = 当前 issue 上挂的标签
- 菱形 = 真人决策卡点（NPC 在此停下等 LGTM / 反馈 / 合并）
- 虚线 = 由事件触发的自动调度（流水线 → Leader 扫描）
| 原则 | 说明 |
|---|---|
| 真人验收拍板 | 每个 *-in-review / ready-to-merge 必须等真人 LGTM，NPC 严禁擅自跨过；NPC 自驱推进非卡点状态 |
| 标签即协议 | 任何状态变更 = 标签推进 + 评论说明，禁止只评论不改标签或反之 |
| 克制 @ | 只在 4 种合法场景 @ 对方：正向流转 / 请求评审 / review-fix 反馈 / 应答反馈达成一致；其他一律 @ 真人 |
| 应答反馈 @ 反馈方 | 处理完反馈后必须 @ 当初给反馈的那个人（不是流程下一棒），由 ta 确认达成一致后再推进 |
| 3 轮安全边界 | 同一争议反复应答超过 3 轮 → 当前状态责任 NPC 强制加 blocked-by-conflict，明确说明争议焦点、双方立场、轮次记录、当前搁置方案，并 @ 真人决策；不再 @ 对方 NPC 继续讨论 |
命名对齐 Atlassian Jira Status Category + GitHub label conventions（kebab-case），让真人工程师和 AI 共用一套词汇。详见 .agents/skills/label-protocol/SKILL.md。
| 类别 | 标签 | 备注 |
|---|---|---|
| 🟡 To Do（未开始） | needs-triage、ready | |
| 🔵 In Progress（进行中） | requirement-in-progress / requirement-in-review / requirement-changes-requesteddesign-in-progress / design-in-review / design-changes-requestedbreakdown-in-progress / development-in-progressin-progress / in-review / changes-requested / ready-to-merge | 父需求阶段带前缀；子任务无前缀 |
| 🟢 Done | close 表达 | 不设独立标签 |
| 📌 工作类型 | feature / bug / task | |
| ⛔ 阻塞标志（可叠加） | blocked-by-upstream / blocked-by-deps / blocked-by-conflict / on-hold | Blocked 用 flag 而非独立状态（Atlassian 推荐做法） |
研发 Leader 能在没有真人介入的情况下，按依赖图自动调度子任务：
- 拆任务时按依赖图客观判定子 issue 初始标签：无前置依赖 → 直接
ready+ @ 开发；有未满足依赖 →ready+blocked-by-deps（不 @） - 任意 PR 合入到 master → CNB 流水线触发研发 Leader → 关闭对应子 issue → 扫描所有
blocked-by-deps子任务，对依赖已满足者自动移除阻塞标志 + @ 开发 - 父需求所有子任务 close → 在父 issue 汇报 + @ 真人决策是否关闭（NPC 不擅自关闭父需求）
详见 .agents/skills/dependency-orchestration/SKILL.md。
新增/调整 NPC 角色必须遵守 .agents/skills/npc-design/SKILL.md 中的 §5 标准流程 + §6 自检清单 + §7 反模式，避免引入 owner:* 标签或破坏"真人验收拍板"的卡点设计。
研发 Leader 拆任务时不再以人天为单位（AI 没有人天概念），而是基于 AI 上下文规模做客观判定（参考 Anthropic SAM Pipeline / arXiv Chain of Agents / ACON 长视野 agent 上下文压缩研究）：
- 单任务涉及文件数 ≤ 8
- 单任务跨越分层 ≤ 2
- 内联到 issue body 的方案章节 ≤ 3 个
- 决策点 ≤ 1 个
- 子 issue body 完全自包含（PRD/方案关键内容已内联，AI 无需跨文档跳转）
详见 .agents/skills/task-breakdown/SKILL.md。
┌──────────────────────────────────────────────────────────────────┐
│ Docker Compose (中间件) │
│ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ MySQL 8 (预初始化)│ │ Redis 7 │ │
│ │ yshop_mall_boot │ │ │ │
│ │ :3306 │ │ :6379 │ │
│ └────────┬─────────┘ └────────┬─────────┘ │
│ │ │ │
│ │ 端口映射到宿主机 │ │
└───────────┼──────────────────────┼───────────────────────────────┘
│ │
▼ ▼
┌──────────────────────────────────────────────────────────────────┐
│ env 容器 (手动启动服务) │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ yshop-admin │ │ yshop-app │ │ Vue 前端 │ │
│ │ :8001 │ │ :8008 │ │ :8686 (dev) │ │
│ └──────────────┘ └──────────────┘ └──────────────────┘ │
│ │
│ Maven 腾讯云源 → .mvn/settings.xml │
│ npm 腾讯云源 → yshop-mall-vue/.npmrc │
│ 连接 localhost:3306 (MySQL) / localhost:6379 (Redis) │
└──────────────────────────────────────────────────────────────────┘
项目提供了 start-services.sh 一键启动脚本，自动完成中间件检查、后端启动、前端启动和服务验证，并输出每个环节的耗时统计。
# 1. 启动中间件（MySQL + Redis）
docker compose up -d
# 2. 构建 + 启动所有服务（首次使用或代码变更后）
bash start-services.sh build
# 3. 直接启动所有服务（已构建过，无需重新编译）
bash start-services.sh
# 4. 查看服务状态
bash start-services.sh status
# 5. 停止所有业务服务
bash start-services.sh stop
docker compose up -d
等待 MySQL 和 Redis 健康检查通过：
# 查看中间件状态，确认 mysql 和 redis 均为 healthy
docker compose ps
项目已配置腾讯云加速源（
.mvn/settings.xml+pom.xml），依赖下载会自动走腾讯云镜像。 Maven 本地仓库缓存于/root/.m2，首次构建约 72s，缓存后约 10s。
cd /workspace/yshop-mall-boot
# 构建项目（跳过测试，启用并行编译）
mvn clean package -DskipTests -s .mvn/settings.xml -T 1C
构建成功后会在以下路径生成 jar 包：
yshop-admin/target/yshop-admin-1.9.0.jaryshop-app/target/yshop-app-1.9.0.jar
cd /workspace/yshop-mall-boot
# 创建文件上传目录
mkdir -p /home/yshop/file /home/yshop/avatar
# 启动管理后台 API（端口 8001）
java -Xms1g -Xmx1g -jar yshop-admin/target/yshop-admin-1.9.0.jar --spring.profiles.active=dev &
# 启动移动端 API（端口 8008）
java -Xms1g -Xmx1g -jar yshop-app/target/yshop-app-1.9.0.jar --spring.profiles.active=dev &
使用
devprofile，连接localhost的 MySQL 和 Redis（由 Docker Compose 端口映射提供）。 日志直接输出到终端，如需后台运行可自行追加nohup ... > xxx.out 2>&1 &。
等待服务就绪后，检查端口是否监听：
ss -tlnp | grep -E '8001|8008'
已配置
.npmrc使用腾讯云 npm 加速源，npm install自动走腾讯云镜像。
cd /workspace/yshop-mall-vue
npm install
npm run dev
| 服务 | 地址 |
|---|---|
| 管理后台前端 | http://localhost:8686 |
| 管理后台 API | http://localhost:8001 |
| 移动端 API | http://localhost:8008 |
| Swagger (Admin) | http://localhost:8001/swagger-ui.html |
| Swagger (App) | http://localhost:8008/swagger-ui.html |
初始化账号密码： admin / 123456
# 启动中间件
docker compose up -d
# 停止中间件
docker compose down
# 查看中间件状态
docker compose ps
# 查看中间件日志
docker compose logs -f mysql
docker compose logs -f redis
# 停止后端服务
pkill -f yshop-admin
pkill -f yshop-app
# 重新构建（代码变更后）
cd /workspace/yshop-mall-boot && mvn clean package -DskipTests -s .mvn/settings.xml -T 1C
以下路径建议声明为缓存，避免每次环境重建重复下载：
| 路径 | 大小 | 说明 |
|---|---|---|
/root/.m2 | ~169M | Maven 依赖缓存（首次构建 72s → 缓存后 10s） |
/root/.npm | ~220M | npm 下载缓存（加速 npm install） |
/workspace/yshop-mall-vue/node_modules | ~447M | 前端依赖（省去 npm install 约 30s） |
注：完整 JDK 8 已包含在 env 镜像中（
/usr/local/openjdk-8），无需额外缓存。
| 镜像 | 说明 |
|---|---|
docker.cnb.cool/xh-test/npc-showcase/show/mysql-yshop | MySQL 8.0（预初始化 yshop_mall_boot 数据库，含 83 张表） |
docker.cnb.cool/xh-test/npc-showcase/show/redis:7-alpine | Redis 7 |
docker.cnb.cool/xh-test/npc-showcase/show/env | 应用运行环境（JDK 8 + Maven 3.8.8 + Node.js 16.20.2） |
# 在项目根目录构建包含 JDK + Maven + Node.js 的环境镜像
docker build -f Dockerfile.env -t docker.cnb.cool/xh-test/npc-showcase/show/env:latest .
docker push docker.cnb.cool/xh-test/npc-showcase/show/env:latest
| 子工程 | 说明 |
|---|---|
yshop-mall-boot | Java 后端工程（Spring Boot 2.7 + MyBatis-Plus） |
yshop-mall-vue | 管理后台前端（Vue 2 + Element UI） |
yshop-mall-uniapp | 移动端（UniApp，支持小程序 / H5） |
本项目基于 yshop 意象商城 开源版本，感谢原作者的贡献。
- 原项目地址：https://www.yixiang.co
- eladmin：https://github.com/elunez/eladmin
- MyBatis-Plus：https://github.com/baomidou/mybatis-plus
- Hutool：https://github.com/dromara/hutool
- WxJava：https://github.com/Wechat-Group/WxJava
- Vue：https://github.com/vuejs/vue
- Element：https://github.com/ElemeFE/element
