@jspg-ai/coding-bb 0.0.1

package/README.md

@@ -0,0 +1,41 @@
+# @jspg-ai/coding-bb
+
+整合业界热门且高价值的工具、框架与技能，为 AI CODING AGENT 提供统一的行为准则与工作流，辅助开发者将需求高效落地为符合规范的代码。
+
+---
+
+## 功能特性
+
+- **编码规范**：提供 API、模型、代码风格、错误处理、日志等核心规范
+- **数据库规范**：MySQL 表设计、索引、SQL、事务等规范
+- **ES 规范**：Elasticsearch 索引设计、查询优化等规范
+- **架构规范**：分层架构、模块组织、中间件选型等规范
+- **OpenSpec 工作流**：完整的需求→设计→实现→验证→归档工作流
+- **Worktree 管理**：多仓库联动开发环境，支持 git worktree 隔离
+
+---
+
+## 快速安装
+
+```bash
+# 全局安装（公开包，无需登录）
+npm install -g @jspg-ai/coding-bb
+
+# 新建目录，初始化业务空间（唯一主命令，首次运行自动安装用户级组件）
+cbb setup
+```
+
+---
+
+## 文档导航
+
+| 文档 | 说明 |
+|------|------|
+| [快速开始](docs/快速开始.md) | 安装、初始化、更新、卸载完整指南 |
+| [CLI 参考](docs/CLI参考.md) | CLI 命令一览（人用 / Agent 用 / 自动） |
+| [Skills 参考](docs/Skills参考.md) | 编码规范与 OpenSpec 工作流命令一览 |
+| [开发工作流](docs/开发工作流.md) | OpenSpec 工作流完整说明 |
+| [项目结构](docs/项目结构.md) | 源码目录结构速览（维护者） |
+| [AGENTS.md](AGENTS.md) | 项目架构与仓库内容分层说明 |
+| [NPM 发布指南](docs/NPM发布指南.md) | 版本发布流程（维护者） |
+| [版本历史](docs/版本历史.md) | 版本变更记录 |

package/cbb/dev-standards/rules/cbb-ai-behavior.md

@@ -0,0 +1,104 @@
+---
+trigger: always_on
+---
+
+# AI 行为准则
+
+七条行为准则，减少 AI 编码常见错误。源自 [Andrej Karpathy 对 LLM 编码缺陷的观察](https://x.com/karpathy/status/2015883857489522876)。
+
+**权衡：** 这些准则倾向于谨慎而非速度。对于简单任务（如修 typo、改文案），按常识判断即可。
+
+## 1. 先想后写
+
+**不假设，不隐藏困惑，主动呈现权衡。**
+
+实现前：
+- 明确声明假设，不确定时主动询问
+- 若存在多种解释，呈现出来而非自己默默选一种
+- 若有更简单的方案，说出来，必要时 push back
+- 若有不明确的地方，停下来，说出困惑，请求澄清
+
+## 2. 简洁至上
+
+**用最少代码解决问题，不加推测性内容。**
+
+- 不实现用户未要求的功能
+- 不为单次使用的代码创建抽象
+- 不添加用户未要求的"灵活性"或"可配置性"
+- 不为不可能发生的场景写错误处理
+- 写了 200 行却发现 50 行就能搞定 → 重写
+
+自问："资深工程师会说过度设计吗？"如果会，简化。
+
+## 3. 外科手术式修改
+
+**只改必须改的，只清理自己造成的烂摊子。**
+
+编辑已有代码时：
+- 不顺手"改进"相邻代码、注释或格式
+- 不重构没坏的东西
+- 匹配现有风格，即使你更习惯另一种写法
+- 发现无关的死代码，口头提及即可，不要删除
+
+当你的改动产生孤儿代码时：
+- 删除因你的改动而不再使用的 import / 变量 / 函数
+- 不删除已有的死代码，除非用户要求
+
+**检验标准：** 每一行改动都应该能追溯到用户的需求。
+
+## 4. 目标驱动执行
+
+**定义成功标准，循环直到验证通过。**
+
+将命令式任务转换为可验证的目标：
+
+| 而非… | 转换为… |
+|--------|---------|
+| "加个校验" | "先写无效输入的测试，再让测试通过" |
+| "修这个 bug" | "先写能复现的测试，再修到测试通过" |
+| "重构 X" | "确保重构前后测试全部通过" |
+
+多步任务先给简短计划：
+```
+1. [步骤] → 验证: [检查项]
+2. [步骤] → 验证: [检查项]
+3. [步骤] → 验证: [检查项]
+```
+
+清晰的成功标准让 AI 可以独立循环验证，模糊的标准（"搞一下"）需要反复澄清。
+
+## 5. 失败要大声说出来
+
+**悄悄绕过失败比直接失败更糟糕。**
+
+- 有步骤被跳过，"完成"就是错的——说出来
+- 有测试被跳过，"测试通过"就是错的——说出来
+- 不确定就直接说不确定，不假装确认
+- 默认暴露不确定性，不掩盖
+
+**检验标准：** 任何跳过的步骤、不确定的结论、未验证的结果，都以标记形式呈现，不悄悄带过。
+
+## 6. 不认同也要说出来
+
+当项目现有约定明显有问题时：
+
+- 照样遵循，保持一致——不悄悄另起炉灶
+- 明确提出来——指出风险，给出替代方案
+- 让用户做决策，不要替用户做选择
+
+**检验标准：** 你的代码放进现有代码中，读不出"换了一个人写的"。发现的问题以建议形式呈现，而非悄悄用另一种方式实现。
+
+## 7. 先批准，后动工
+
+**任何实现动作前，先陈述方案并获得用户批准。**
+
+- 动手前说出打算怎么做（方案、涉及文件、验证方式），等用户确认
+- 仪式随任务缩放：小改动两三句话说清即可；大改动走 openspec 工作流（propose → specs → design）
+- "太简单不需要方案"是最危险的念头——简单意味着方案短，而不是没有方案
+- 中途发现复杂度超出预期：停下来重新说明，不要闷头扩大改动范围
+
+**检验标准：** 用户从未因"AI 直接改了代码没打招呼"而感到意外。
+
+---
+
+**这些准则生效的标志：** diff 中不必要的改动减少、不会因过度设计而重写、澄清问题在实现前而非出错后提出。

package/cbb/dev-standards/rules/cbb-coding-rule.md

@@ -0,0 +1,50 @@
+---
+trigger: always_on
+---
+# 编码规范
+
+## 一. 代码结构
+
+- 方法禁止超过 **100 行**，超过必须拆分为语义明确的子方法
+- 主方法只做步骤编排，涉及业务规则判断、状态变更或外部调用的循环/分支逻辑必须抽取为独立方法；仅做参数校验、数据组装、简单赋值等非业务逻辑可保留
+- 命名贴合业务含义，同一工程避免同名类，同一概念命名一致，禁止望文不知义的缩写（反例：`aeh` 表示"运费估算处理"）
+- 类注释必须包含：说明、作者、版本、引入版本、相关类
+- 公共方法（public、REST、RPC）注释必须包含：入参要求和取值范围、出参结果、异常场景；私有/内部方法只要求写核心功能说明
+- 数据模型必须使用对应后缀：`Request`（入参）、`Response`（出参）、`DTO`（服务间传输）、`PO`（持久化对象）、`Param`（查询/操作参数）
+
+## 二. 架构约束
+
+- Controller 和 Facade 层禁止编写业务逻辑，仅限处理参数校验、权限检查、异常捕获与封装、日志埋点、结果组装等通用横切关注点；所有业务规则判断、状态流转、数据编排必须下沉到实现层，如Service层
+- Service 层访问外部系统必须通过 Repo 层封装，禁止直接调用外部 API
+
+## 三. API 规范
+
+- REST 接口中 long/double 类型字段必须使用字符串输出，避免 JS 精度丢失
+- REST 和 API 接口禁止直接抛异常，统一拦截封装成错误码返回；捕获异常后必须处理，禁止空捕获
+
+## 四. 数据安全
+
+- 以下字段必须加密传输和存储，加密方式沿用当前项目已有方案，多种方案共存或无先例时需与用户确认：身份证号、手机号、银行卡号、邮箱、住址
+- 密码、密钥等敏感信息必须存储在 Lion 配置中心，禁止硬编码
+- 日志中禁止输出未脱敏的敏感信息
+- 后台敏感操作（删除/修改）必须记录审计日志：操作人、时间、操作内容，有请求上下文时记录来源 IP
+- 三方资源限制使用频率
+
+## 五. 数据库规范
+
+- MyBatis 禁止使用 `${}`，必须使用 `#{}`（防止 SQL 注入）
+- 默认读从库；写链路中强依赖的数据查询必须走主库
+- 分布式锁不能加在数据库事务内，正确顺序：**加锁 → 开启事务 → 执行业务 → 提交事务 → 释放锁**（具体使用方法见 ironman-lock skill）
+
+## 六. 兼容性规范
+
+- 对外契约和数据格式的变更必须保持向后兼容：仅允许新增可选字段，禁止删除、重命名、改类型或变更已有定义的语义
+- 适用范围：REST/API 接口（避免影响调用方）、数据库表结构与存储格式（避免影响已部署服务）、MQ 消息结构（生产者与消费者双向兼容）、Redis key 命名与 value 序列化格式（变更时版本化 key 或清空旧缓存，避免新老实例读写不一致）、ES 索引 mapping（字段类型或 analyzer 变更需新建索引 + reindex + 别名切换平滑迁移，避免查询与写入异常）
+
+## 七. 枚举规范
+
+- 枚举只能新增，禁止修改和删除已有枚举值
+
+## 八. 单元测试
+
+- 单元测试必须覆盖增量业务逻辑，目标 **100%** 增量业务逻辑行覆盖，且全部运行通过

package/cbb/dev-standards/rules/cbb-priority.md

@@ -0,0 +1,56 @@
+---
+trigger: always_on
+---
+# 规范优先级
+
+全局规范与项目现有约定冲突时，按以下优先级处理：
+
+| 优先级 | 来源 | 说明 |
+|--------|------|------|
+| 1（最高） | 项目现有约定 | 包括代码中实际观察到的风格，以及项目目录下的显式规范（lint 配置、CLAUDE.md 等）。两者冲突时以显式规范为准 |
+| 2（最低） | 本规范库 | 统一规范，作为默认兜底。已吸收语言/框架官方惯例（如 PEP 8、Effective Go 等）作为基线 |
+
+**豁免**：以下情况不属于"沿用"范围，发现问题必须指出：
+
+- 会导致运行时错误或数据损坏的明显 bug
+- 安全缺陷（如 SQL 注入、敏感信息明文存储、XSS 风险等）
+- 已废弃的 API
+- 会导致严重性能退化的模式（如 N+1 查询、全表扫描后内存过滤、大事务长连接等）
+- 违反合规/法律要求的处理方式（如数据保留、隐私保护等）
+- 会导致可维护性灾难的模式（如单体方法超 500 行、循环嵌套深度 > 4 层等）
+
+---
+
+## 执行原则
+
+### 首次进入项目
+
+生成或修改代码前必须：
+
+1. **探测现有风格** — 检查目标文件所在目录的代码风格
+2. **识别架构模式** — 确认项目使用的分包模式、命名约定、注解风格
+3. **保持一致性** — 新代码遵循项目风格，而非套用全局规范
+
+> 目录内风格不一致时，以目录内多数文件的风格为准；仍无法判断时，以项目显式规范为准。
+
+### 冲突处理
+
+| 场景 | 处理方式 |
+|------|----------|
+| 项目已有分层架构 | 沿用现有分层，不强制统一为某种架构 |
+| 项目已有命名风格 | 保持统一，不自创新风格 |
+| 项目已用某中间件 | 继续使用，不强行切换 |
+| 项目内存在多种风格混用 | 以当前文件风格为准，不引入第三种风格；当前文件无明确风格时以目录内多数文件风格为准 |
+| 项目无先例可循（如首次使用 Redis、首次写 MQ 消费者） | 使用本规范库作为默认起点 |
+| 全局规范更新 | 以项目实际安装的版本为准，不自动覆盖 |
+| 全新项目 | 使用本规范库作为起点 |
+| 已有项目中的新模块 | 沿用项目现有约定，不另起风格 |
+
+> **显式规范与代码风格冲突时的处理**：显式规范优先用于新代码；不要求对已有代码做大规模 reformat。判断标准：涉及命名约定、架构分层、中间件选型等**结构性决策**时以显式规范为准；仅涉及缩进、换行等**格式细节**时以当前文件风格为准。
+
+### 重构场景
+
+当本次需求涉及架构重构时：
+
+- 以重构目标为准，而非沿用旧模式
+- 重构范围必须明确界定，不在范围内的代码保持现有风格

package/cbb/dev-standards/skills/architecture-specs/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: architecture-specs
+description: "架构与中间件规范。方案设计、编码实现、Code Review 三个阶段均须参照——涵盖 OpenSpec propose/apply/verify、Superpowers 头脑风暴/writing-plans/executing-plans/requesting-code-review/receiving-code-review、编写技术方案或架构设计、直接编码、直接代码审查。内容包括模块划分与分包（app/api/service/web/spi）、分层架构设计（Controller→Service→Repo→DAO）、中间件选型与使用（RPC/MQ/Redis/Config/SQL）、Spring Boot + MyBatis 技术栈、依赖管理、服务注册与发现、灰度发布、限流降级。仅限后端架构设计与中间件选型场景，不适用于前端架构或纯业务逻辑实现。"
+---
+
+# 架构与中间件规范
+
+提供分层架构、模块组织、中间件选型等完整规范。
+
+## 使用场景
+
+当你需要：
+- 设计系统架构
+- 划分模块和分包
+- 选型中间件（MQ、Redis、配置中心）
+- 了解技术栈要求
+
+## 规范内容
+
+### 分层架构规范
+
+采用 Controller → Service → Repo → DAO 四层架构，各层职责和约束详见 `/coding-specs`。
+
+#### 模块组织
+
+标准模块结构：
+
+```
+xxx-api/       → RPC 接口定义（Facade、DTO）
+xxx-web/       → REST 控制器和应用启动
+xxx-service/   → 业务逻辑实现
+xxx-spi/       → 服务提供者接口（可选）
+```
+
+RPC 接口：Facade 接口和 DTO 放在 xxx-api，实现类放在 xxx-service。
+
+#### 工程分模块
+
+- 简单工程（业务模块 <= 3）：REST+RPC 实现可以在一个模块中
+- 多个应用/模块共用的部分必须独立成模块
+- 无意义的模块划分会导致依赖管理复杂
+
+#### 分包策略
+
+**API 模块第一层包：**
+- `exception` — 对外暴露的自定义异常
+- `util` — 对外提供的基础工具类
+- `[Business module]` — 按业务模块分包（facade / dto / request）
+
+### 中间件选型规范
+
+#### 数据存储
+
+| 场景 | 中间件 | 客户端 |
+|------|--------|--------|
+| 核心业务数据持久化 | MySQL（ES/Redis 不可独立作为数据存储） | ironman-sql |
+| 全文检索/复杂查询 | Elasticsearch | ebatis |
+| 分布式缓存 | Redis | ironman-redis |
+
+#### 消息队列
+
+| 场景 | 中间件 | 说明 |
+|------|--------|------|
+| 业务系统消息通信 | RocketMQ | 通过 ironman-mq |
+| 大数据处理场景 | Kafka | - |
+| 延迟处理 | Delay 服务 | 范围 1s~7d，消息体 < 4K，QPS < 1000 |
+
+核心链路不可以强依赖 Kafka，建议使用 RocketMQ 替代。
+
+#### Ironman 中间件
+
+| 能力 | 中间件 | 使用指导 |
+|------|--------|----------|
+| 配置中心 | IronMan Config（ironman-config） | 详见 `/mb-ironman-config` skill |
+| RPC 框架 | IronMan RPC（ironman-rpc） | 详见 `/mb-ironman-rpc` skill |
+| 数据库访问 | IronMan SQL（ironman-sql） | 详见 `/mb-ironman-sql` skill |
+| Redis 访问 | IronMan Redis（ironman-redis） | 详见 `/mb-ironman-redis` skill |
+| 分布式锁 | IronMan Lock（ironman-lock），支持 Redis(AP) 和 Zookeeper(CP) | 详见 `/ironman-lock` skill |
+| 多级缓存 | IronMan Cache（ironman-cache） | — |
+| 幂等控制 | IronMan Idempotent（ironman-idempotent） | — |
+
+#### 通用能力
+
+| 能力 | 中间件 |
+|------|--------|
+| 敏感信息加密 | Thaad |
+| 定时任务 | YmmJob |
+| 监控告警 | Hubble + Cat |
+| 流控降级 | Sentinel |
+| 网关 | Hango |
+| 全局唯一 ID | Number-Generating（建议使用 String 类型） |
+
+#### 三方框架
+
+| 类别 | 产品 |
+|------|------|
+| 基础框架 | SpringBoot |
+| ORM | MyBatis-Plus（必须通过 Ironman-SQL 封装使用，禁止裸用） |
+| 对象映射 | MapStruct |
+| 代码生成 | Lombok |
+| 本地缓存 | Caffeine |
+| 单元测试 | JUnit + Mockito |
+| JSON 处理 | Jackson |
+| 工具类 | Hutool、Apache Commons |
+| 日志 | SLF4J + Log4j2 |
+| Excel 处理 | Apache POI |
+| HTTP 客户端 | OkHttp |
+
+#### 技术栈要求
+
+**必须使用**：
+- IronMan 中间件体系（Config、RPC、SQL、Redis、Lock、Cache）
+- MySQL 作为核心数据持久化存储
+- MyBatis-Plus（通过 Ironman-SQL 封装）作为 ORM 框架
+
+**禁止**：
+- ES/Redis 独立作为数据存储
+- 裸用 MyBatis-Plus（绕过 Ironman-SQL 直接使用原生 MP 或原生 MyBatis）
+- 使用 `${}` 进行 SQL 参数绑定（SQL 注入风险）
+
+## 检查清单
+
+使用本技能时，会检查：
+- [ ] 是否遵循四层架构
+- [ ] 模块划分是否合理
+- [ ] 是否使用 IronMan 中间件体系
+- [ ] 是否使用 MySQL + Ironman-SQL（MyBatis-Plus）
+- [ ] 中间件选型是否合理
+