pdm-maintainer技能使用说明 - 让AI直接产出可编辑的PowerDesigner数据库设计PDM文件

最近做一个供应链系统的设计，现在项目组里面需求人员和产品经理的需求文档，以及相关的设计文档几乎全部由AI来完成交付，人工参与审核；

但是涉及到数据库设计，涉及到专业PowerDesigner工具的使用，以前也一直是人来做的，现在有大模型了，于是让大模型分析了以前几个项目的PDM文件，总结出文件特点，给出以前做设计时候需要注意的点，然后生成一份儿全新的pdm维护的技能。

使用该技能对新的项目进行生成PDM文件，节省大量自己手动编辑文件的过程，而且该技能也补充了修改PDM文件的功能。

一、这个技能是做什么的？

一句话：帮你安全地查看和修改 PowerDesigner 的 .pdm 数据库设计文件，保证改完之后用 PowerDesigner 打开不会出错、不会出现表叠在一起（表层叠）的情况。

背景：为什么需要这个技能？

• .pdm
   是 PowerDesigner（一款数据库设计工具）的物理数据模型文件，本质是一份无缩进、非常长的 XML。
• 手动改 PDM 极易翻车
  ：PDM 内部用编号（o75 这种）互相引用，改错一个编号，PowerDesigner 就打不开、或者表/关系丢失。新增表如果漏掉画布坐标，多张表会堆叠在同一位置（表层叠）。
• 这个技能提供一个 Python 脚本 pdm_tools.py，把"读、增、改、查、校验"都做成命令，自动处理编号、坐标、颜色，改完始终合法。

二、它能做什么（能力一览）

三、快速上手（3 分钟）

第 0 步：准备

技能已安装到全局，脚本路径是：

~/.claude/skills/pdm-maintainer/scripts/pdm_tools.py

建议先设一个短别名（可选，在终端执行一次，或写进 ~/.zshrc）：

bash
alias pdm='python3 ~/.claude/skills/pdm-maintainer/scripts/pdm_tools.py'

设好后下面的命令都能用 pdm xxx 代替一长串路径。未设别名则用完整路径，本文档两种写法都给。

第 1 步：看一眼模型里有什么

bash
# 用别名：
pdm summary 餐厅项目数据库设计v3.0.pdm

# 或完整路径：
python3 ~/.claude/skills/pdm-maintainer/scripts/pdm_tools.py summary 餐厅项目数据库设计v3.0.pdm

输出示例：

模型名称 : 餐厅项目数据库设计v3.0
DBMS     : MySQL 5.0
表数量   : 47
列数量   : 745
外键关系 : 19

第 2 步：看某张表的字段

bash
pdm show 餐厅项目数据库设计v3.0.pdm FDSP_RESTA_INFO

会列出这张"餐厅信息表"的所有字段（列名、中文名、类型、是否可空、备注）、主键、以及它和别的表的外键关系。

第 3 步：放心地加一张新表

bash
pdm add-table 餐厅项目数据库设计v3.0.pdm \
  --code MY_NEW_TABLE --name "我的新表" --comment "测试用" \
  --fill "#FF0080" \
  --columns '[{"code":"ID","name":"主键","type":"VARCHAR(50)","pk":true},
              {"code":"NAME","name":"名称","type":"VARCHAR(90)","not_null":true}]'

执行后会：

• 新增表数据（表名 MY_NEW_TABLE、2 列、主键 ID）
• 自动在画布上给它一个不与现有表重叠的位置（避免表层叠）
• 填充色设为 #FF0080（粉色，可改成任意颜色，见第六节）
• 自动备份原文件为 .pdm.bak

💡 写入类命令都支持 --dry-run：先打印将插入的内容、不写文件，确认无误再去掉这个参数正式执行。

四、全部命令详解

下面所有命令的第一个参数都是 PDM 文件路径。<table> 表示表的 Code（数据库表名）或内部 Id 都行。

🔍 读取类（不改文件，安全）

bash
# 模型概览
pdm summary  <文件.pdm>

# 列出所有表
pdm tables   <文件.pdm>

# 查看某张表结构
pdm show     <文件.pdm> <表名>

# 列出所有外键关系
pdm refs     <文件.pdm>

# 列出颜色分组（看哪些表属于哪个业务模块）
pdm colors   <文件.pdm>

# 校验文件完整性（改完文件后建议跑一次）
pdm validate <文件.pdm>

✏️ 写入类（自动备份 .pdm.bak，建议先加 --dry-run）

1）新增表

bash
pdm add-table <文件.pdm> \
  --code ORDER_INFO \                     # 必填：表名（数据库里的名字）
  --name "订单表" \                         #   中文名/显示名（简短）
  --fill "#FF0080" \                       #   填充色（#RRGGBB 或整数，可选）
  --columns '[                             # 必填：列定义 JSON 数组
    {"code":"ORDER_ID","name":"订单号","type":"VARCHAR(50)","pk":true},
    {"code":"USER_ID","name":"用户","type":"VARCHAR(50)","not_null":true},
    {"code":"STATUS","name":"状态","type":"CHAR(1)","comment":"0待支付；1已支付；2已取消"},
    {"code":"AMOUNT","name":"金额","type":"DECIMAL(18,2)","comment":"订单总金额，含税"},
    {"code":"CREATE_TIME","name":"创建时间","type":"DATETIME","default":"CURRENT_TIMESTAMP"}
  ]'

💡 字段命名约定：name 保持简短（一个词/短语）；comment仅在需要补充时才写（枚举取值、业务规则、技术说明），与 name 不必一致、不要重复；自解释字段（如"创建时间"）不用写 comment。

列 JSON 里每个字段的可选项：

2）给已有表加一列

bash
pdm add-column <文件.pdm> ORDER_INFO \
  --code MEMO --name "备注" --type"VARCHAR(200)" --comment "订单备注"
# 可选：--length --default --not-null

3）新增外键关系（父表主键 → 子表外键列）

bash
pdm add-ref <文件.pdm> \
  --parent USER_INFO \        # 父表（被引用的主表，"一"方）
  --child ORDER_INFO \        # 子表（含外键列的从表，"多"方）
  --parent-col USER_ID \      # 父表的列（通常是主键）
  --child-col USER_ID \       # 子表的外键列
  --cardinality "0..*"# 基数，默认 0..*

要求父表已有主键。会自动生成画布上的连线。

4）改某张表的颜色（把表归类到某个业务模块）

bash
pdm set-color <文件.pdm> ORDER_INFO --fill "#FF0080"
# 也可改边框线色：--line "#0000FF"

五、典型工作流

场景 A：接手一个 PDM，先摸清现状

bash
pdm summary  数据库.pdm        # 多少表、多少外键
pdm tables   数据库.pdm        # 有哪些表
pdm colors   数据库.pdm        # 表按颜色分成哪些业务模块
pdm show     数据库.pdm 某表名   # 看具体某张表
pdm refs     数据库.pdm        # 表与表之间什么关系

场景 B：新增一张业务表并接入关系

bash
# 1) 先看色板，决定新表归哪个模块、用什么颜色
pdm colors 数据库.pdm

# 2) dry-run 预览将要插入的内容（不写盘）
pdm add-table 数据库.pdm --code NEW_TBL --name "新表" --fill "#8080FF" \
  --columns '[{"code":"ID","name":"主键","type":"VARCHAR(50)","pk":true}]' --dry-run

# 3) 确认无误，正式写入（去掉 --dry-run）
pdm add-table 数据库.pdm --code NEW_TBL --name "新表" --fill "#8080FF" \
  --columns '[{"code":"ID","name":"主键","type":"VARCHAR(50)","pk":true}]'

# 4) 建外键，把新表关联到已有表
pdm add-ref 数据库.pdm --parent 某主表 --child NEW_TBL --parent-col ID --child-col PID

# 5) 校验
pdm validate 数据库.pdm

场景 C：重新归类已有表的颜色

bash
pdm colors   数据库.pdm                 # 看现有模块色
pdm set-color 数据库.pdm 某表 --fill "#FF00FF"# 改成目标模块色

场景 D：从零开始建一个新库（⚠️ 必看）

千万不要手写整份 PDM——PDM 里有一大套 DBMS 配置（TargetID、TargetModels、模型选项、DisplayPreferences…），编造任一项都会让 PowerDesigner 打不开。正确做法是用 new 命令，它基于已验证可打开的骨架创建：

bash
# 方式一：内置 MySQL 5.0 骨架（自带真实 DBMS 配置）
pdm new 新库.pdm --name "我的数据库"

# 方式二：克隆项目里任意已知能打开的 PDM 骨架（保留它的 DBMS/选项，清空表与外键）
pdm new 新库.pdm --name "我的数据库" --from 餐厅项目数据库设计v3.0.pdm

# 然后正常加表、加外键
pdm add-table 新库.pdm --code USER --name "用户" \
  --columns '[{"code":"ID","name":"主键","type":"VARCHAR(50)","pk":true}]'
pdm validate 新库.pdm

场景 E：表已经层叠了，怎么整理

bash
pdm layout 数据库.pdm --cols 6     # 一键把所有表框排成 6 列网格，无重叠

等价于在 PowerDesigner 里手动点"格式化排列/自动布局"，但脚本批量处理更快、更可控。

场景 F：建立弱关联（无法用外键表达的指向关系）

有些业务关联建不了外键——例如一个字段按类型指向多张不同的表，或两表仅有逻辑关联而无约束。这时用 Traceability Link（追溯链接） 标注，PowerDesigner 中显示为虚线：

bash
# 表级弱关联：两表之间建一条虚线关联
pdm add-trace 数据库.pdm --from FDSP_CHNL_INVENTORY_DETAIL --to FDSP_BUSI_COST_INFO

# 列级弱关联：某列指向另一张表（"字段指向多表"的常见建模）
pdm add-trace 数据库.pdm --from ORDER_INFO --from-col BIZ_REF_ID --to SUPPLY_INFO

# 查看已有的弱关联
pdm traces 数据库.pdm

与外键互不冲突：同一对表可以既有外键、又有 Traceability Link。弱关联只标注关系、不产生约束。

六、关于颜色（区分业务模块）

PowerDesigner 里同业务模块的表会用同一种填充色，一眼就能区分功能域。本文件夹的文件实测色板（以 v3.0 为例）：

• 用 pdm colors 查看当前文件的完整色板。
• 新增表用 add-table --fill "#RRGGBB" 指定颜色；不填会用默认的浅奶油色（表示"待归类"）。
• 改已有表颜色用 set-color --fill。
• 颜色写法两种都支持：#RRGGBB（如 #FF0080）或十进制整数（如 8388863）。

七、新手常见疑问

Q0：生成的 PDM 用 PowerDesigner 打不开？几乎都是因为从零手写 XML 时编造了 DBMS TargetID（PowerDesigner 不认识这个 ID 就拒绝打开）。解决办法：用 pdm new 创建（自带真实 MySQL 5.0 配置），或 pdm new --from 某个能打开的.pdm 克隆骨架，不要手写整份 PDM。

Q1：改坏了文件怎么办？每个写入命令执行前都会自动备份为 xxx.pdm.bak，把 .bak 改回 .pdm 即可还原。重要文件建议改之前再手动复制一份。

Q2：命令敲完没把握，怕改错？所有写入命令加 --dry-run，只预览不写盘，看清楚再去掉它正式执行。改完用 pdm validate 复查。

Q3：PowerDesigner 打开后表叠在一起？本技能新增表时会自动算不重叠坐标。如果还是层叠（常见于改过的旧文件、或不是本技能加的表），直接 pdm layout 文件.pdm 一键重排成网格即可，无需在 PowerDesigner 里手动拖。

Q4：能修改列类型 / 删除表 / 删除列吗？当前脚本直接支持"读、加表、加列、加外键、改色、重排、建库"。修改类型/重命名/删除需要手动编辑 XML（参见技能内 references/pdm-format.md 的"常见陷阱"），核心原则：不要动对象编号 oXXX，否则所有引用会断。

Q5：每次都要敲一长串脚本路径？设个别名就好：alias pdm='python3 ~/.claude/skills/pdm-maintainer/scripts/pdm_tools.py'。

八、技能文件在哪 / 如何更新

技能内部结构：

pdm-maintainer/
├── SKILL.md                    # 给 Claude 读的规则（触发条件、用法）
├── references/pdm-format.md    # PDM 格式完整参考（字段含义、陷阱）
└── scripts/pdm_tools.py        # 本文档讲的所有命令都在这里

更新技能（改了源码后重新打包并重装）：

bash
python3 ~/.claude/skills/skill-creator/scripts/package_skill.py \
    ./pdm-maintainer .
unzip -o ./pdm-maintainer.skill -d ~/.claude/skills/

在 Claude Code 里自动调用：新开会话后，直接用自然语言提需求即可，例如"看一下 v3.0 有哪些表"“给 v3.0 加一张订单表”——Claude 会自动识别并使用本技能。

九、安装

提供两种安装方式，二选一即可。

方式一：npx skills add（推荐，跨 Agent 通用）

本仓库兼容 skills.sh 的 skills CLI（vercel-labs 出品，同时支持 Claude Code、Codex、Cursor、OpenCode 等）。无需先安装任何东西，直接：

bash
# 安装到当前项目（.claude/skills/，随项目共享）
npx skills add weblogicjava/swz-skills

# 或安装到用户全局（~/.claude/skills/，所有项目可用）
npx skills add weblogicjava/swz-skills -g

# 只列出仓库里有哪些 skill，不安装
npx skills add weblogicjava/swz-skills --list

# 指定只装某个 skill（仓库有多个 skill 时）
npx skills add weblogicjava/swz-skills --skill pdm-maintainer

安装后该 skill 即可被 Claude Code 按需调用。其他常用命令：npx skills list（查看已装）、npx skills update（更新）、npx skills remove（卸载）。

方式二：Claude Code 原生插件市场

通过 /plugin 斜杠命令（交互）或 claude plugin CLI（脚本化）安装：

bash
# 1) 添加本仓库为插件市场
/plugin marketplace add weblogicjava/swz-skills

# 2) 安装插件
/plugin install pdm-maintainer@swz-skills

或使用 CLI（适合 CI / 脚本）：

bash
claude plugin marketplace add weblogicjava/swz-skills
claude plugin install pdm-maintainer@swz-skills

安装后以 <插件名>:<skill名> 命名空间调用：/pdm-maintainer:pdm-maintainer。本地校验 schema（推送前在仓库根目录运行）：claude plugin validate .

十、还有疑问？

• 想了解 PDM 文件内部结构（表/列/主键/外键/颜色/坐标的 XML 写法）→ 看 pdm-maintainer/references/pdm-format.md
• 想看脚本全部选项 → python3 ~/.claude/skills/pdm-maintainer/scripts/pdm_tools.py --help
• 想看某个命令的参数 → pdm <命令> -h，例如 pdm add-table -h