@jspg-ai/coding-bb 0.0.1

package/cbb/dev-standards/skills/es-design-specs/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: es-design-specs
+description: "Elasticsearch 索引设计规范。方案设计、编码实现、Code Review 三个阶段均须参照——涵盖 OpenSpec propose/apply/verify、Superpowers 头脑风暴/writing-plans/executing-plans/requesting-code-review/receiving-code-review、编写技术方案或详细设计、直接编码、直接代码审查。内容包括索引结构设计、mapping 定义、字段类型选择、索引命名、分片与副本配置、dynamic mapping 控制、别名管理、索引生命周期管理。仅限 ES 索引结构设计场景，ES 查询编写与 bulk 操作参见 coding-specs。"
+---
+
+# Elasticsearch 索引设计规范
+
+提供 ES 索引结构设计、mapping 定义、分片策略等规范。
+
+## 使用场景
+
+当你需要：
+- 设计 ES 索引结构
+- 定义索引 mapping 和 setting
+- 规划分片和副本策略
+- 选择字段类型
+
+## 规范内容
+
+### 集群配置
+
+- 集群命名格式：`es7-应用名称`，使用中划线 `-`，禁止下划线和特殊字符
+- 集群节点数 >= 3
+- 核心链路必须使用 KnowSearch + EBatis 实现多集群互备
+
+### 索引设计
+
+- 索引名使用小写字母，禁止以 `_` 开头，禁止特殊字符
+- 必须明确指定 mapping 和 setting，禁止使用默认值
+- 禁用 dynamic mapping
+- 使用索引别名访问
+
+#### Mapping 模板
+
+```json
+{
+  "mappings": {
+    "dynamic": "strict",
+    "properties": {
+      "id": { "type": "long" },
+      "order_no": { "type": "keyword" },
+      "cargo_status": { "type": "integer" },
+      "company_name": {
+        "type": "text",
+        "analyzer": "ik_max_word",
+        "fields": {
+          "keyword": { "type": "keyword", "ignore_above": 256 }
+        }
+      },
+      "freight_amount": { "type": "long" },
+      "create_time": {
+        "type": "date",
+        "format": "yyyy-MM-dd HH:mm:ss||epoch_millis"
+      },
+      "update_time": {
+        "type": "date",
+        "format": "yyyy-MM-dd HH:mm:ss||epoch_millis"
+      }
+    }
+  },
+  "settings": {
+    "number_of_shards": 3,
+    "number_of_replicas": 1,
+    "refresh_interval": "1s"
+  }
+}
+```
+
+### 字段类型选择
+
+| 场景 | 推荐类型 |
+|------|---------|
+| 数值范围匹配 | numeric |
+| 仅 term 查询 | keyword（优先） |
+| 全文搜索 | text + keyword（multi-field） |
+| 日期 | date（统一格式） |
+
+### 分片策略
+
+- 单分片大小建议 10~50GB
+- 总分片数不超过 `(节点数 × 3)`
+- 副本数：生产环境至少 1 个副本
+
+### 常见反模式
+
+- **禁止 wildcard 前缀查询**：`*keyword` 性能极差，改用 keyword 类型 + term 查询
+- **禁止深度聚合**：聚合桶数超过 10000 时需优化分片策略或减少聚合维度
+- **禁止大结果集排序**：排序字段无 doc values 时会触发 fielddata 加载，导致 OOM
+- **禁止频繁更新**：ES 更新成本高（标记删除 + 重建），高频更新场景考虑合并写入
+
+### 数据实时性
+
+ES 默认 `refresh_interval` 为 1 秒，数据写入 1 秒后才能被搜索到。批量导入场景可临时调大（如 `30s`）以提升写入性能。
+
+## 检查清单
+
+设计 ES 索引时，请确认以下各项：
+- [ ] 集群命名是否符合规范
+- [ ] 索引设计是否明确指定 mapping
+- [ ] 是否禁用 dynamic mapping
+- [ ] 分片大小是否在 10~50GB 范围内
+- [ ] 字段类型选择是否合理
+- [ ] 是否避免 wildcard 前缀查询
+

package/cbb/dev-standards/skills/mysql-design-specs/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: mysql-design-specs
+description: "【必须调用】MySQL 数据库设计规范。方案设计、编码实现、Code Review 三个阶段均须参照——涵盖 OpenSpec propose/apply/verify、Superpowers 头脑风暴/writing-plans/executing-plans/requesting-code-review/receiving-code-review、编写技术方案或详细设计、直接编码、直接代码审查。强制触发信号：CREATE TABLE、bigint(20)、tinyint(4)、is_valid、PRIMARY KEY、UNIQUE KEY、建表、加字段、加索引、设计表结构、DDL、表结构——无论是主动建表、在文档/Wiki/方案中编写 DDL、还是从其他地方复制 DDL，都必须校验。内容包括 Zebra 分库分表规范和业务表设计惯例。SQL 编写与事务控制参见 coding-specs。"
+---
+
+# 数据库规范
+
+提供数据库表设计、索引设计等规范。
+
+## 强制触发规则
+
+**本 skill 的调用不是"建议"而是"强制"**——即使 DDL 是你从别处复制粘贴的、即使它嵌入在 Wiki 文档中而非 .sql 文件，只要内容包含 `CREATE TABLE` 或 DDL 定义，就必须先 invoke 本 skill 验证。不要假设已有的 DDL 就是符合规范的。
+
+## 使用场景
+
+当你需要：
+- 设计数据库表结构
+- 设计索引
+- 编写 DDL 语句（建表、加字段、改字段、加索引）
+- **更新包含 DDL 的 Wiki 文档或技术方案**
+- **在任何文件中出现或修改 CREATE TABLE 语句**
+
+## 规范内容
+
+### 表设计
+
+#### 必备字段
+
+```sql
+CREATE TABLE `myb_business_entity` (
+  `id` bigint unsigned NOT NULL AUTO_INCREMENT COMMENT '主键id',
+  -- 业务字段 --
+  `deleted` tinyint NOT NULL DEFAULT 0 COMMENT '0-未删除，1-已删除',
+  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '修改时间',
+  PRIMARY KEY (`id`),
+  KEY `idx_updatetime` (`update_time`),
+  KEY `idx_createtime` (`create_time`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='业务实体描述';
+```
+
+#### 字段约束
+
+- 主键必须使用 `bigint unsigned`
+- 必须有 `create_time` 和 `update_time` 字段
+- 状态字段必须使用 `tinyint`，禁止使用字符串
+- 逻辑删除使用 `deleted` 字段，类型为 `tinyint`
+
+#### 字段规范
+
+- 小数类型使用 `decimal`，禁止 `float` 和 `double`
+- 字符串长度 < 5000 使用 `varchar`，>= 5000 使用 `text`
+- 字符串长度几乎相等时使用 `char` 定长类型
+- **整数类型（bigint、int、tinyint、smallint、mediumint）禁止设置显示宽度**，如 `bigint(20)` 应写为 `bigint`，`tinyint(2)` 应写为 `tinyint`（MySQL 8.0.17+ 已忽略显示宽度，写宽度反而造成误导）
+- 字段允许为空时必须有默认值
+- 字段和表必须有 COMMENT
+- 新增非空字段必须提供默认值或对历史数据刷数
+
+#### 命名规范
+
+- 表名必须以业务域缩写开头，如 `myb_xx_xx`、`yzg_xx_xx`、`ka_xx_xx`
+- 表名、字段名使用小写字母或小写+数字组合
+- 禁止数字开头、禁止表名复数、禁止两个下划线中间只出现数字
+- 禁用 MySQL 保留字
+
+### 索引设计
+
+| 索引类型 | 前缀 | 示例 |
+|----------|------|------|
+| 主键索引 | pk_ | pk_id |
+| 唯一索引 | uk_ | uk_email |
+| 普通索引 | idx_ | idx_user_name |
+
+- 联合索引遵循最左前缀原则，高选择性字段放前面
+- 字段区分度 < 10% 不创建单独索引
+- TEXT/BLOB 禁止创建索引
+- 非字典类数据查询必须走索引
+- 禁止重复索引和无效索引
+
+## 检查清单
+
+设计数据库表结构或编写 DDL 时，请确认以下各项：
+- [ ] 主键是否使用 bigint unsigned
+- [ ] 是否有 create_time 和 update_time
+- [ ] 状态字段是否使用 tinyint
+- [ ] 整数类型（bigint/int/tinyint/smallint/mediumint）是否去掉了显示宽度
+- [ ] 索引设计是否合理
+- [ ] 字段类型和命名是否符合规范
+

package/cbb/lib/install/claude-code.js

@@ -0,0 +1,20 @@
+/**
+ * Claude Code 适配器
+ *
+ * 将编码规范分发到 .claude/rules/ 目录
+ */
+
+const path = require('path');
+const os = require('os');
+
+module.exports = {
+  name: 'claude-code',
+  displayName: 'Claude Code',
+  rulesDir: '.claude/rules',
+  skillsDir: '.claude/skills',
+  commandsDir: '.claude/commands/opsx',
+  // 用户级 settings，写入全局生效，不污染项目目录
+  settingsFile: path.join(os.homedir(), '.claude', 'settings.json'),
+  settingsFileIsUserLevel: true,
+  hookEvents: ['UserPromptSubmit'],
+};

package/cbb/lib/install/cleanup.js

@@ -0,0 +1,64 @@
+'use strict';
+
+/**
+ * 升级 / 卸载时清单驱动的文件清理决策。
+ *
+ * 独立成模块是为了便于单元测试（init.js 是脚本式入口，不便直接 require）。
+ */
+
+/**
+ * 受保护、任何清单驱动的清理都不得删除的路径。
+ *
+ * 背景：旧版本（commit 5bab2e9 之前）会生成 AGENTS.md / CLAUDE.md，
+ * 并把整文件路径写入安装清单（.cbb/.managed-by-cbb）。当时若用户已有
+ * 自有的 CLAUDE.md，旧逻辑会把本包的路由片段“合并”进去后再登记到清单。
+ *
+ * 5bab2e9 移除了这两类文件的生成，新版本不再把它们加入新清单。
+ * 于是升级时“清理旧清单中、新清单里没有的路径”这一逻辑会把这两个文件
+ * 当作废弃文件直接删除——连同用户自有的文档内容一并销毁（数据丢失）。
+ *
+ * 由于本包已不再追踪它当初注入了哪一段内容，无法安全地“只移除本包部分”，
+ * 因此最稳妥的做法是：这两个根目录的用户文档文件在任何清单清理中都不删除，
+ * 由用户自行决定是否保留。
+ */
+const PROTECTED_FROM_CLEANUP = new Set(['CLAUDE.md', 'AGENTS.md']);
+
+/**
+ * 计算需要从磁盘删除的清单路径。
+ *
+ * @param {Iterable<string>} managedPaths 旧清单中记录的全部相对路径
+ * @param {Set<string>} keepSet 本次仍由本包管理、或已被智能处理（应保留）的路径
+ * @returns {string[]} 应当删除的相对路径（已排除 keepSet 与受保护文件）
+ */
+function pathsToDelete(managedPaths, keepSet) {
+  const result = [];
+  for (const p of managedPaths) {
+    if (keepSet.has(p)) continue;
+    if (PROTECTED_FROM_CLEANUP.has(p)) continue;
+    result.push(p);
+  }
+  return result;
+}
+
+/**
+ * 计算清单中“受保护、本次不会被删除”的路径，用于在卸载时提示用户自行处理。
+ *
+ * @param {Iterable<string>} managedPaths 旧清单中记录的全部相对路径
+ * @param {Set<string>} keepSet 本次仍由本包管理、或已被智能处理的路径
+ * @returns {string[]} 受保护且不在 keepSet 中的相对路径
+ */
+function protectedKeptPaths(managedPaths, keepSet) {
+  const result = [];
+  for (const p of managedPaths) {
+    if (keepSet.has(p)) continue;
+    if (!PROTECTED_FROM_CLEANUP.has(p)) continue;
+    result.push(p);
+  }
+  return result;
+}
+
+module.exports = {
+  PROTECTED_FROM_CLEANUP,
+  pathsToDelete,
+  protectedKeptPaths,
+};