@jspg-ai/coding-bb 0.0.1

package/cbb/tools/cbb-plantuml-authoring/references/drawing-templates.md

@@ -0,0 +1,479 @@
+# PlantUML 绘图模板
+
+可复制的成品模板,直接改文字即可。配色/skinparam 已调好。SKILL.md 的"绘图质量规范"给原则,本文件给具体模板。
+
+## 目录
+- [通用 skinparam 主题(放图顶)](#通用-skinparam-主题)
+- [Material Design 色阶调色板](#material-design-色阶调色板)
+- [活动图(带分区+改动点高亮)](#活动图)
+- [时序图(带 box 分组+participant 上色)](#时序图)
+- [时序图 alt 多分支(多错误码场景)](#时序图-alt-多分支)
+- [类图(带 package+改动点高亮)](#类图)
+- [状态图](#状态图)
+- [组件/部署图](#组件部署图)
+- [应用架构图(嵌套 package+色阶分层)](#应用架构图)
+- [改动点高亮约定回顾](#改动点高亮约定回顾)
+
+---
+
+## 通用 skinparam 主题
+
+每张图顶部贴这段,统一观感:
+
+```
+skinparam defaultFontSize 13
+skinparam roundCorner 10
+skinparam shadowing false
+skinparam activity {
+  BackgroundColor #FAFAFA
+  BorderColor #888888
+  FontColor #222222
+}
+skinparam sequence {
+  ArrowColor #555555
+  ParticipantBorderColor #555555
+  ParticipantBackgroundColor #FAFAFA
+}
+skinparam class {
+  BackgroundColor #FAFAFA
+  BorderColor #888888
+}
+```
+
+---
+
+## 活动图
+
+业务流程/状态流转首选。带 `partition` 分区 + 改动点高亮 + `legend`。
+
+```
+@startuml
+skinparam backgroundColor #FEFEFE
+skinparam defaultFontSize 13
+skinparam roundCorner 10
+skinparam shadowing false
+skinparam PartitionBorderThickness 1
+skinparam activity {
+  BackgroundColor #FFFFFF
+  BorderColor #999999
+  FontColor #222222
+}
+
+partition "下单阶段" #FFF3E0 {
+  start
+  :用户提交订单;
+  #LightBlue:校验库存(核心);
+  if (库存充足?) then (是)
+    :创建订单;
+  else (否)
+    #Salmon:提示缺货;
+    stop
+  endif
+}
+
+partition "支付阶段" #E8F5E9 {
+  #LightGreen:发起支付(新增);
+  :等待支付结果;
+  if (支付成功?) then (是)
+    :订单完成;
+  else (否)
+    #Gold:超时关单(修改阈值);
+  endif
+  stop
+}
+
+legend top right
+  |= 颜色 |= 含义 |
+  |<#LightGreen>| 新增 |
+  |<#Gold>| 修改 |
+  |<#LightBlue>| 关键路径 |
+  |<#Salmon>| 异常 |
+endlegend
+@enduml
+```
+
+要点:
+- `partition "名" #Color { }` 给每个分区**不同背景色**(Material 浅色),用背景色分组破"瘦长"感
+- `skinparam PartitionBorderThickness 1` 细框线,比大框轻(PlantUML partition 不支持虚线边框,用细线近似)
+- `legend top right` 放顶部(活动图竖排长时,底部 legend 难看到)
+- 线性无分支步骤合并成单节点(如"标准化+保存+更新"),partition 数量控制在 3-4 个,避免纵向堆叠过长
+- 活动图**不支持** `left to right direction`(见踩坑),横排用背景色分组+步骤精简,不要用 direction
+
+---
+
+## 时序图
+
+多系统/多角色交互。带 `box` 分组 + `autonumber` + participant 上色。
+
+```
+@startuml
+skinparam defaultFontSize 13
+autonumber
+
+box "客户端" #LightBlue
+  participant "App" as app
+end box
+box "服务端" #FAFAFA
+  participant "网关" as gw
+  participant "订单服务" as order #LightGreen
+  participant "支付服务" as pay
+end box
+
+app -> gw: 下单请求
+gw -> order: 创建订单
+order -> pay: 发起支付 #LightGreen
+note over order: 本次新增:直连支付
+pay --> order: 支付结果
+order --> gw: 订单状态
+gw --> app: 响应
+
+note over app, pay: 修订点:支付链路改为订单服务直连(原经网关)
+@enduml
+```
+
+要点:`box` 圈子系统、`autonumber` 编号便于沟通、新增 participant 上 `#LightGreen`、消息变更用 `note over` 标注(消息箭头不支持色块)。
+
+---
+
+## 类图
+
+领域模型。带 `package` 分包 + 改动点高亮。
+
+```
+@startuml
+skinparam defaultFontSize 13
+skinparam class {
+  BackgroundColor #FAFAFA
+  BorderColor #888888
+}
+
+package "订单域" {
+  class Order {
+    +id: Long
+    +status: OrderStatus
+    +create(): void
+  }
+  class OrderItem {
+    +productId: Long
+    +quantity: Integer
+  }
+  class OrderStatus <<new>> #LightGreen {
+    UNPAID
+    PAID
+    CLOSED
+  }
+}
+
+package "支付域" {
+  class Payment <<modified>> #Gold {
+    +pay(): void
+  }
+}
+
+Order "1" *-- "N" OrderItem
+Order --> OrderStatus
+Order --> Payment
+
+legend right
+  |= 颜色 |= 含义 |
+  |<#LightGreen>| 新增类 |
+  |<#Gold>| 修改类 |
+endlegend
+@enduml
+```
+
+要点:`package` 分域、关系用 multiplicities(`"1" *-- "N"`)、新增/修改类用 stereotype `<<new>>`/`<<modified>>` + 色块、`legend` 说明。
+
+---
+
+## 状态图
+
+对象状态机。状态用色区分正常/异常态。
+
+```
+@startuml
+skinparam defaultFontSize 13
+
+state "待支付" as Unpaid
+state "已支付" as Paid #LightBlue
+state "已发货" as Shipped
+state "已完成" as Done #LightGreen
+state "已取消" as Cancelled #Salmon
+
+[*] --> Unpaid
+Unpaid --> Paid : 支付成功
+Unpaid --> Cancelled : 超时/取消
+Paid --> Shipped : 发货
+Shipped --> Done : 确认收货
+Cancelled --> [*]
+Done --> [*]
+@enduml
+```
+
+要点:终态/异常态用约定色、转换标触发事件。
+
+---
+
+## 组件/部署图
+
+系统依赖拓扑。
+
+```
+@startuml
+skinparam defaultFontSize 13
+skinparam component {
+  BackgroundColor #FAFAFA
+  BorderColor #888888
+}
+
+package "KA Capacity" {
+  [容量服务] as cap #LightBlue
+  [派单服务] as dispatch
+}
+
+database "MySQL" as db
+queue "Kafka" as mq
+[网关] as gw
+
+gw --> cap
+cap --> db
+cap --> mq
+dispatch --> db
+@enduml
+```
+
+要点:用 `[组件]`/`database`/`queue` 区分类型、新增/核心组件上色。
+
+---
+
+## Material Design 色阶调色板
+
+配色原则:**同色系深浅表达层级**(浅色 = 外层 package/box,深色 = 内层组件;层级越深色越浓),**跨图色系一致**(同一子系统在所有图里用同色系)。5 色系 × 3 档,直接抄:
+
+| 色系(用途建议) | 浅(package/box) | 中(component/participant) | 深(原子/底层) |
+|---|---|---|---|
+| 橙系(前端/触发层) | `#FFF3E0` | `#FFE0B2` | `#FFCC80` |
+| 绿系(业务前台层) | `#E8F5E9` | `#C8E6C9` | `#A5D6A7` |
+| 蓝系(用户中心/核心域) | `#E3F2FD` | `#90CAF9` | `#64B5F6` |
+| 紫系(现有系统/外部依赖) | `#F3E5F5` | `#E1BEE7` | `#CE93D8` |
+| 青系(回调/异步) | `#E0F2F1` | `#80CBC4` | `#4DB6AC` |
+
+箭头语义色(时序图箭头着色,同语义同色):
+- `#1976D2`(蓝)= 主流程/正向
+- `#F57C00`(橙)= 取消/异常/recheck
+- `#00695C`(青绿)= 回调/上传
+- `#C62828`(红)= 失败/拒绝
+
+用法:`participant "X" as x #90CAF9`(participant 上色)、`A -[#F57C00]-> B : recheck`(箭头着色)、`box "场景A" #E8F5E9`(box 背景)。
+
+---
+
+## 时序图 alt 多分支
+
+多错误码/多分支决策场景,用嵌套 `alt/else`,每个 else 对应一种返回。比活动图 if 更适合"同一调用多种结果"。
+
+```
+@startuml
+skinparam backgroundColor #FEFEFE
+title 登录流程(多错误码)
+
+actor "管理员" as Admin
+participant "前端" as FE #FFE0B2
+participant "鉴权服务" as Auth #90CAF9
+database "Redis" as Redis
+
+Admin -> FE : 输入账号密码
+FE -> Auth : 登录请求
+
+== 凭据校验 ==
+Auth -> Auth : 校验用户名密码
+
+alt 凭据校验通过
+    Auth -> Auth : 校验员工状态
+    Auth -> Auth : 校验公司状态
+    alt 全部校验通过
+        Auth -> Redis : 存储 Token
+        Auth --> FE : 返回 Token
+    else 员工/公司已禁用
+        Auth --> FE : 错误(已禁用)
+    end
+else 密码错误/账号不存在
+    Auth --> FE : 错误(凭据无效)
+end
+
+FE --> Admin : 跳转首页或显示错误
+@enduml
+```
+
+要点:`== 段名 ==` 分段、`note right of X` 收纳步骤细节(此处略)、每个 `else` 对应一种错误返回、嵌套 `alt` 表达"大分支里再分小分支"。
+
+---
+
+## 应用架构图
+
+应用分层 + 应用间调用 + 职责边界。`package` 分层(可嵌套),`-down->` 表达自上而下,色阶区分层。对照真实好图提炼。
+
+```
+@startuml
+skinparam backgroundColor #FEFEFE
+skinparam componentStyle rectangle
+skinparam arrowThickness 2
+title 应用拓扑架构图
+
+package "前端层" as Frontend #FFF3E0 {
+    component "货主APP" as shipperApp #FFE0B2
+    component "司机APP" as driverApp #FFE0B2
+    component "管理后台" as admin #FFE0B2
+}
+
+package "业务前台应用层" as BizLayer #E8F5E9 {
+    component "saas-app\n货主/司机端" as saasApp #C8E6C9
+    component "admin-app\n运营后台" as adminApp #A5D6A7
+}
+
+package "用户中心" as UserCenter #E3F2FD {
+    package "前台应用层" as UCFront #BBDEFB {
+        component "鉴权服务" as authApp #90CAF9
+    }
+    package "底层领域层" as UCDomain #90CAF9 {
+        component "用户原子能力" as infoServer #64B5F6
+    }
+}
+
+package "现有系统" as Existing #F3E5F5 {
+    component "trade-company-app" as companyApp #E1BEE7
+}
+
+database "MySQL" as mysql #FFECB3
+database "Redis" as redis #FFCDD2
+
+shipperApp -down-> saasApp : REST
+driverApp -down-> saasApp : REST
+admin -down-> adminApp : REST
+
+saasApp -down-> infoServer : RPC原子
+adminApp -down-> authApp : RPC登录
+adminApp -down-> companyApp : RPC
+
+authApp -down-> infoServer : RPC校验
+infoServer -down-> mysql
+authApp -down-> redis
+@enduml
+```
+
+要点:
+- `package` 分层,层间色系递进(橙→绿→蓝→紫),同层组件同色
+- `package` 嵌套表达"大系统含子系统分层"(用户中心内套前台/领域两层)
+- `-down->` 显式方向,标签写"调用类型"(`: REST`/`: RPC登录`)
+- `database`/`queue` 放最底层,用关键字区分类型
+- `skinparam componentStyle rectangle` 用矩形(默认是 UML 组件图标,架构图用矩形更干净)
+
+技术架构图同此画法,把"应用"换成"技术栈/中间件节点"即可(如 Nginx/Gateway/MySQL/Redis/Kafka + 部署节点)。
+
+---
+
+## 修改现有功能的流程图(强制 4 件套模板)
+
+技术方案里"修改 XX 流程"类需求,流程图必须带 4 件套:**上下文边界 + 颜色高亮 + 删除分支画出来 + 图下 4 段文字说明**。详见 SKILL.md「补充·修改现有功能的流程图(强制 4 件套)」。
+
+```
+@startuml
+skinparam backgroundColor #FEFEFE
+skinparam defaultFontSize 13
+skinparam roundCorner 10
+skinparam shadowing false
+skinparam activity {
+  BackgroundColor #FFFFFF
+  BorderColor #999999
+  FontColor #222222
+}
+
+title 6.X xxx 流程(修改后)
+
+start
+
+' 1. 入口:用 note 标注"被谁调、触发条件"
+:上游触发 doXxx;
+note right: 触发条件 = xxx\n调度频率 = xxx\n由 xxx 自动调用
+
+' 2. 如果触发入口到变更点之间有未改动非重要节点,用 ... 省略
+' (... 这里可省略若干非重要节点 ...)
+
+' 3. 真正的变更逻辑
+:doXxx;
+
+if (新条件?) then (是)
+  #Gold:新动作(修改后保留);
+  #Gold:返回 NEED_CANCEL;
+  note right: 本次修改:xxx
+  stop
+elseif ([DEL] 旧条件?) then ([DEL])
+  #LightGray:[DEL] 旧动作;
+  note right #FFCDD2: 原版有该判断,本次删除\n删除原因:xxx\n详见 PRD xxx
+else (否)
+  #LightBlue:返回 CONTINUE;
+  stop
+endif
+
+' 4. legend 颜色图例(强制)
+legend right
+  |= 颜色 |= 含义 |
+  |<#Gold>| 本次修改后保留 |
+  |<#LightGray>| 本次删除 |
+  |<#LightBlue>| 未变更(原版即有) |
+endlegend
+
+@enduml
+```
+
+图下必须配 4 段结构化文字说明(详见 SKILL.md 4 件套第 4 条):
+
+```
+**变更摘要**(必填,删/改/增 各列 1-2 条):
+- 删除:xxx 流程中的 xxx 判断分支
+- 修改:xxx 流程的 xxx 条件(从 A 改为 B)
+- 新增:xxx 流程新增 xxx 步骤
+
+**变更动机**(必填,引用 PRD/Issue 链接):
+- 旧版痛点:司机比预计时间晚到时,系统误判为已到装货地
+- 引用:PRD https://wiki.amh-group.com/pages/viewpage.action?pageId=xxx
+
+**影响范围**(必填):
+- 任务/接口:xxxService#xxx(Java 类#方法)
+- 数据:ka_xxx 表(无变更)
+- 灰度:先发 1 台,观察 1 天
+- 监控:新增告警 xxx
+
+**回滚方案**(必填):
+- 回退到旧版 commit xxx
+- 兜底开关:Lion 配置 ymm-ka-xxx.enabled = false
+- 数据:无需回滚
+```
+
+要点(画图前自检):
+- **入口用 note 标注"被谁调"**:禁止只画内部逻辑,前面是黑盒
+- **触发入口到变更点之间**未改动且非重要节点用 ... 省略
+- **删除的分支必须画出来**:用 #LightGray + [DEL] 前缀 + note 说明删除原因
+- **legend 强制**:任何修订版流程图都必须带颜色图例
+- **图下 4 段说明**:变更摘要 / 变更动机 / 影响范围 / 回滚方案,缺一段返工
+
+反面教材:图下方只写"改动:删除时间判断分支"一行——这不够,读者不知道为什么改、有没有风险、怎么回滚都不知道。
+
+---
+
+## 改动点高亮约定回顾
+
+修订现有图(如方案迭代、代码变更说明)时,改动必须显眼且可解释:
+
+| 含义 | 颜色 | 活动图 | 时序图 | 类图 |
+|---|---|---|---|---|
+| 新增 | `#LightGreen` | `#LightGreen:动作;` | `participant X as x #LightGreen` + `note over` | `class X <<new>> #LightGreen` |
+| 修改 | `#Gold` | `#Gold:动作;` | `note over x: 修改说明` | `class X <<modified>> #Gold` |
+| 删除 | `#LightGray` | `#LightGray:[DEL]动作;` | `note over x: 已删除` | 注释标 `<<deleted>>` |
+| 关键路径 | `#LightBlue` | `#LightBlue:动作;` | participant 上色 | — |
+| 异常/警告 | `#Salmon` | `#Salmon:动作;` | `note over x #Salmon: 警告` | — |
+
+规则:
+- 每张含改动的图**必须**加 `legend`,说明颜色含义
+- 颜色语义全工程一致,不要这张图 green=新增、那张图 green=修改
+- 纯新建图(非修订)不用改动点高亮,用关键路径/异常色即可

package/cbb/tools/cbb-wiki-ops/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: cbb-wiki-ops
+description: Wiki (wiki.amh-group.com) 命令行操作工具。遇到 wiki.amh-group.com 链接时**必须**使用本技能，禁止用 WebFetch（Wiki 需认证，WebFetch 必然失败）。触发场景：读取/查询/搜索 Wiki 页面、列子页/评论/空间/版本/附件、创建/更新页面、创建评论、任何涉及 wiki.amh-group.com 的操作。所有操作通过 `cbb wiki` 子命令完成。即使用户只给了 Wiki 链接没有明确说"用 wiki 工具"，也要优先用本技能而非 WebFetch。
+---
+
+# 行为规则
+
+## 1. 环境检查（脚本自带 5 分钟 TTL 缓存）
+
+脚本内部已实现文件缓存（`~/.cbb/.auth-status`，5 分钟 TTL），重复调用开销接近 0：
+
+```bash
+node .claude/skills/cbb-wiki-ops/scripts/check-auth.js
+```
+
+| 输出 | 含义 | 下一步 |
+|------|------|--------|
+| `AUTH_OK` | 环境变量已配置 | 继续执行用户请求的 `cbb wiki` 操作 |
+| `AUTH_MISSING` | 未配置凭据 | → §2 认证配置 |
+
+注意：只在 `AUTH_OK` 后才执行 `cbb wiki` 命令。如果执行时遇到 401/403，按 §3 处理。
+
+## 2. 认证配置（首次使用）
+
+**停止当前流程**，向用户展示：
+
+> Wiki 认证未配置。请提供你的 @amh-group.com 邮箱，以及在 https://wiki.amh-group.com/plugins/tokens/view.action 生成的 Personal Access Token。拿到后二选一：
+
+**方式 A — 环境变量（推荐，复制即用）：**
+```cmd
+setx CBB_WIKI_EMAIL "你的邮箱@amh-group.com"
+setx CBB_WIKI_TOKEN "你的PAT"
+```
+> 设置后需重启工具会话生效。
+
+**方式 B — 配置文件：**
+创建 `~/.cbb/wiki-config.json`，内容：`{"email": "邮箱@amh-group.com", "token": "PAT"}`
+
+用户确认配置完成后，重新执行 `cbb wiki user --current` 验证通过，再继续原操作。
+
+## 3. 凭据过期（401/403）
+
+提示用户重新生成令牌（同上地址），更新后重试。
+
+## 4. 页面不存在（404）
+
+核实 pageId 是否正确，或用户对该空间是否有访问权限。
+
+## 5. 版本冲突（409）
+
+直接重新执行命令（update 子命令会自动取最新版本号 +1）。
+
+---
+
+# 命令参考
+
+## 查询
+
+### 读页面
+```bash
+cbb wiki get <pageId>              # 标题/空间/版本（正文折叠）
+cbb wiki get <pageId> --full       # 含完整 XHTML 正文
+```
+
+### 列子页
+```bash
+cbb wiki children <pageId> [--limit=50] [--start=0]
+```
+
+### CQL 搜索
+```bash
+cbb wiki search "type=page AND title~\"关键词\"" [--limit=20]
+cbb wiki search "type=page AND text~\"关键词\"" --excerpt=highlight
+cbb wiki search "type=page AND space=KEY" --order=lastmodified desc
+```
+
+**CQL 语法速查：**
+- `type=page|space|user|comment`
+- `title~"关键词"` — 标题模糊；`text~"关键词"` — 全文搜索
+- `space=KEY` — 限定空间；`parent=<pageId>` — 限定父页面
+- `lastmodified>=startOfDay(-7d)` — 时间范围
+- `order=lastmodified desc|asc` — 排序
+
+### 列空间
+```bash
+cbb wiki spaces [--limit=100] [--type=global]
+```
+
+### 列评论
+```bash
+cbb wiki comments <pageId> [--limit=50]
+```
+
+### 查用户
+```bash
+cbb wiki user --current
+cbb wiki user --account-id=<accountId>
+cbb wiki user --username=<name>
+```
+
+### 历史版本
+```bash
+cbb wiki versions <pageId> [--limit=20]
+```
+
+## 附件
+
+```bash
+cbb wiki attachments <pageId> list [--limit=50]
+cbb wiki attachments <pageId> upload --file=<path> [--comment="说明"]
+cbb wiki attachments <pageId> delete --attachment-id=<id>
+```
+
+> 下载附件：Basic 认证下不可用，请在浏览器打开页面下载。
+
+## 写操作
+
+### 创建页面
+```bash
+cbb wiki create --parent-id <父页面Id> --title "标题" --file <markdown文件路径>
+```
+读取 Markdown 文件，自动转换为 Confluence XHTML 后创建。
+
+### 更新页面
+```bash
+cbb wiki update --page-id <pageId> --file <markdown文件路径>
+```
+读取 Markdown 文件，自动转换为 Confluence XHTML 后更新（自动取版本号 +1）。
+
+### 创建评论
+```bash
+cbb wiki comment <pageId> --body-file=<xhtml文件路径> [--parent=<父评论Id>]
+```
+评论 body 须为 Confluence Storage XHTML 格式。

package/cbb/tools/cbb-wiki-ops/scripts/check-auth.js

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+// cbb-wiki-ops 环境检查脚本
+// 检查 Wiki 认证是否已配置（环境变量或配置文件）
+// 带 TTL 文件缓存，避免每次重复检测
+// 输出 AUTH_OK 或 AUTH_MISSING
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const CACHE_FILE = path.join(os.homedir(), '.cbb', '.auth-status');
+const TTL_MS = 5 * 60 * 1000; // 5 分钟
+
+function doCheck() {
+  const envOk = process.env.CBB_WIKI_EMAIL && process.env.CBB_WIKI_TOKEN;
+  const configPath = path.join(os.homedir(), '.cbb', 'wiki-config.json');
+  const fileOk = fs.existsSync(configPath);
+  return (envOk || fileOk) ? 'AUTH_OK' : 'AUTH_MISSING';
+}
+
+function readCache() {
+  try {
+    const data = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf-8'));
+    if (data.status && data.checkedAt && Date.now() - data.checkedAt < TTL_MS) {
+      return data.status;
+    }
+  } catch (_) { /* 缓存文件不存在或解析失败，走实际检查 */ }
+  return null;
+}
+
+function writeCache(status) {
+  try {
+    fs.mkdirSync(path.dirname(CACHE_FILE), { recursive: true });
+    fs.writeFileSync(CACHE_FILE, JSON.stringify({
+      status,
+      checkedAt: Date.now(),
+    }));
+  } catch (_) { /* 缓存写入失败不影响输出 */ }
+}
+
+const cached = readCache();
+const status = cached || doCheck();
+if (!cached) writeCache(status);
+console.log(status);