Design List（动态列表规格设计器）

产出动态列表的规格文档（List Spec）。支持纯文本、图片、文档（Word/PDF/Excel）输入。

> ⚠️ 本技能只产出 list-spec.md，不构建列表。构建（列配置 JSON、查询条件、提交平台）由 pacp-build-list 完成。本技能的终点就是规格文档落盘。

职责边界

终点：spec 落盘到 .pacp/specs/动态渲染/{业务名}__列表.md + 明确告知用户「规格文档已生成在 动态渲染/{业务名}__列表.md，确认无误后可用 pacp-build-list 构建列表」。

5.x 平台知识权威源

> spec 词汇表（列词汇、宽度语义、查询条件词汇）背后的平台渲染契约、LX 类型机制、平台陷阱等知识，权威源在 pacp-dynamic-wiki skill：
>
> - 选词时不确定某列词汇对应哪个 display.type → wiki 的 5x/list-render-contract.md
> - 涉及选择器配置（LX=2）→ wiki 的 5x/platform-mechanisms.md §LX 类型机制 + 5x/list-script-guide.md §4 选择器列表
> - 涉及宽度语义 → wiki 的 5x/list-render-contract.md §列宽规范
>
> ZCode 会根据 description 自动触发 wiki skill。本 skill 的词汇表只声明「spec 用什么词」，词汇→平台契约的映射规则详见 wiki。

重要约束：远程配置任务，不读任何源码

> 本技能的数据来源是：远程 API（按需探查）+ 本 SKILL.md + 用户提供。禁止读取任何源码——既包括本 Skill 的 lib/scripts，也包括当前项目（cwd）里的业务代码。

统一工作根目录：.pacp/

> [!important] 所有 pacp-* skill 共用 .pacp/ 作为工作根目录
> 替代原有的 BwaiClient.createWorkspace()（系统临时目录）机制。统一到项目内固定路径。

定位方式：AI 运行时的 cwd（当前工作目录）下的 .pacp/。

> [!warning] cwd 边界
> "别探查项目结构"约束依然成立——AI 只往 .pacp/ 读写工作文件，不触碰项目内其他任何文件。"用 cwd" 只是算路径，不是探查。

目录结构：

{cwd}/.pacp/
  specs/                    ← list-spec.md 产出位置（本 skill 写入，pacp-build-list 读取）
    动态渲染/                 ← 本 skill 的隔离子文件夹（与表单 spec 同目录，靠文件名后缀区分）
      {业务名}__列表.md         ← 列表 spec（如：调查询问通知书__列表.md）
      {业务名}__表单.md         ← 表单 spec（pacp-design-form 产出，本 skill 的「关联表单」字段引用其文件名）
  session.json              ← 共享会话凭证（本 skill 探查时写入，build 复用）
  active/                   ← 进行中的工作区（探查结果、trace 等）
    {业务名}_{时间戳}/
      api-trace.jsonl
      table-info.md

衔接方式：本技能把 spec 写入 .pacp/specs/动态渲染/{业务名}__列表.md，返回业务名给用户。pacp-build-list 接收业务名定位 spec（查 动态渲染/{业务名}__列表.md）。

> [!important] 文件名命名约定：列表 spec 统一加 __列表 后缀
> 一个业务名可能对应多个表单和列表（如"调查询问通知书"有录入表单 + 列表）。列表 spec 文件名统一为 {业务名}__列表.md，与表单 spec {业务名}__表单.md 同目录靠后缀区分。
> - 表单 spec：调查询问通知书__表单.md（pacp-design-form 产出）
> - 列表 spec：调查询问通知书__列表.md（本 skill 产出）
>
> 业务名可包含区分词：同业务多列表时，业务名本身带区分（如执法案件_立案、执法案件_审批），文件名如执法案件_立案__列表.md。

> [!important] session 跨 skill 共享
> 探查需要 session 时：调 pacp-system-login 获取 → 写入 .pacp/session.json。pacp-build-list 启动时读此文件复用，过期则重新获取。session.json 是可选缓存优化，不是必需。
>
> 登录强制 chrome-devtools MCP：获取 JSESSIONID 只接受用户直接提供 或 pacp-system-login（基于 chrome-devtools MCP）。不接受其他不可靠方式。

探查策略（可选）

> [!important] 探查是可选项
> 只有用户没有提供表名和列名时才探查。

> [!note] 探查是可递进的多步流程
> 「没给表名 → 探查表」只是第一步：列出候选表供用户选定。用户选定表后若仍未给列名，再进入「探查列」。即探查按需分步推进，不是一次性完成。

探查能力复用：本技能通过相对路径 require('../pacp-build-list/lib/bwai_client.js') 复用 BwaiClient（两 skill 同处 skills/ 目录）。需登录时调 pacp-system-login skill。

表名探查（可选）

1. 用户明确给出表名 → 直接用
2. 用户给业务描述 → getTables 模糊匹配（唯一匹配直接用 / 多匹配列出候选让用户选 / 零匹配问用户）
3. 用户未给 → 直接问

处理流程

1. 意图解析 → 2. [可选]探查表/列 → 3. 产出 Spec 草稿 → 4. 质量门自检 → 5. 与用户核对至定稿 → 6. 落盘

阶段1 意图解析 + 产出 Spec 草稿

从用户口语 + 表注释提取，产出 Spec MD 草稿：元信息（主表/关联表/关联关系/关联表单/主键）+ 列定义 + 查询条件 + 操作按钮。

Spec 草稿标注不确定点——草稿里对 AI 推断的列类型/宽度/查询条件，主动标「⚠️ 推断」引导用户高效核对，减少来回。

> [!note] Spec 复用入口
> 用户说「基于 XX 的 spec 改」时，让其给 .pacp/specs/动态渲染/ 下的业务名或直接贴内容，AI 读取已有 spec 作为起点而非从零产出；全新需求则从用户口语产出。

阶段2 [可选] 探查

仅当用户没给表名/列名时执行（见上方探查策略表）。探查结果保存到 .pacp/active/{业务名}_{时间戳}/table-info.md。

阶段3 产出 Spec 草稿

按下方「List Spec 结构化契约」产出草稿。

阶段4 质量门自检

产出草稿后、展示给用户前，必须跑一遍质量门自检清单（见下方「质量门」）。缺项则先补全再展示。

阶段5 与用户核对至定稿

• AI 展示 Spec 草稿，用户指出修改点（草稿展示 + 自然语言迭代，不用结构化确认）
• 迭代至用户说「可以」即定稿
• 代码集编号用户当场给不出 → Spec 标「待定」，延后到 build 阶段

阶段6 落盘

定稿后落盘到 .pacp/specs/动态渲染/{业务名}__列表.md（子文件夹不存在则自动创建），返回业务名给用户。

List Spec 结构化契约

# List Spec：{列表名}

## 元信息                          ← 必填段
- 列表标题：{必填}
- 列表用途：{普通/选择器}            ← 新增，默认"普通"，省略即普通；填"选择器"时触发 build 走 LX=2 + confirmClick 配置（见下方「选择器配置段规则」）
- 主表：{表名}                      ← 必填，单表时唯一数据来源
- 关联表：{表名列表，仅多表联查时填，如 T_ZF_JCJL}
- 关联关系：{仅多表联查时填，逐行列出表间字段对应，如 T_ZF_JCJL.AJ_XH → T_ZF_AJ.XH}   ← build 据此拼 JOIN 的 ON 条件，缺失则停止询问
- 数据源：默认 jdbc/default
- 主键：{已有表填实际主键字段名；平台新建表默认 XH（平台统一主键）}
- 关联表单：{表单 spec 文件名 / 无}   ← 填表单 spec 文件名（去.md），如 调查询问通知书__表单；设计阶段即可填（文件名稳定，不依赖表单是否已构建）
- 风格：{无}                        ← 列表通常无风格，预留

> [!important] 关联表单的衔接机制（设计阶段可用）
> 表单和列表常在设计阶段并行产出，此时表单尚未构建、没有 templateId。因此列表 spec **不直接填 templateId**，而是填表单 spec 的文件名（如 `调查询问通知书__表单`）。
> - **设计阶段**：design-list 填表单 spec 文件名，不依赖表单是否已构建
> - **构建阶段**：build-list 读 `{文件名}.md` 的构建记录段取 templateId；若表单未构建（无构建记录段），提示用户「请先用 build-form 构建关联表单」
> - **文件名稳定**：表单 spec 落盘后文件名不变，是可靠的跨 spec 引用标识（比业务名更精确，支持同业务多表单）

> [!important] 多表联查的语义化描述（不含 SQL，但需记录关联关系）
> spec 保持纯需求层，**不写 JOIN 语句**，但需记录表间关联关系供 build 拼 JOIN。多表联查时：
> - 元信息「主表」填主表名，「关联表」填关联表名列表
> - 元信息「关联关系」逐行列出字段对应（如 T_ZF_JCJL.AJ_XH → T_ZF_AJ.XH），多对关联逐行列全
> - 关联关系格式约定：`关联表.外键字段 → 主表.主键字段`（等值连接，方向仅表引用语义，填反不影响 ON 正确性）
> - 列定义中每个字段标注来源表（见列定义规则）
> - build 阶段按「关联关系」拼 JOIN 的 ON 条件（表别名由 build 自动派生），不靠命名猜测；关联关系缺失则停止并询问用户

## 列定义                          ← 必填段，至少1个数据列
### {字段名} {显示名}               ← 每列一个小标题；系统列用 [序号]/[选择框]/[操作] 作字段名
- 来源表：{表名}                    ← 多表联查时必填（标注字段来自哪张表）；单表可省；系统列留空
- 列类型：{词汇}                    ← 必填，用列词汇表；系统列填 序号/选择框/操作
- 代码集编号：{编号}                ← 仅代码集列必填（如 DMJ_AJLB），其余留空
- 宽度：{语义}                      ← 必填：窄/中/宽/日期/序号/选择框/操作
- 显示：是/否                       ← 是否默认显示

## 查询条件                        ← 可选段
### {字段名} {显示名}
- 输入类型：{词汇}                  ← 普通文本/下拉/日期区间/代码集
- 操作符：{LIKE/=/RANGE}            ← 普通文本用 LIKE，下拉/代码集用 =，日期区间用 RANGE
- 代码集编号：{编号}                ← 代码集查询必填；下拉默认走代码集（填编号），纯静态枚举留空
- 选项：{男/女}                     ← 仅纯静态枚举下拉必填（逐项列出），其余留空
- 快速匹配：是/否                   ← 标"是"的字段聚合进顶部快速匹配区（按 LIKE 模糊匹配）

## 操作按钮                        ← 可选段
- 工具栏按钮：{新增/导出/批量删除 + 自定义按钮}
- 操作列按钮：{编辑/删除 + 自定义按钮}

> [!important] CRUD 列表（关联表单）的工具栏按钮必须显式写全
> 当列表关联表单（元信息「关联表单」非「无」）走 CRUD 模式时，工具栏的「新增」「批量删除」是**标准 CRUD 按钮，必须显式写在 spec 里**，不能依赖 build 的 associateForm 自动补全。
>
> 理由：**spec 必须与最终制成品 1:1 对应**。制成品右上角有什么按钮，spec 就得写什么。靠 build 端"自觉"补全会导致 spec 与制成品不一致，失去规格文档的意义（实战踩坑：spec 只写「新增」，associateForm 因守卫逻辑跳过「批量删除」注入，制成品缺按钮）。
>
> CRUD 列表工具栏标配（缺一不可，除非业务明确不需要）：
> - `新增`：打开空白表单录入
> - `批量删除`：勾选多行后批量删除（依赖「选择框列」）
>
> 操作列标配：`编辑`（单行编辑）、`删除`（单行删除）。
>
> **示例**：
> ```markdown
> ## 操作按钮
> - 工具栏按钮：新增、批量删除
> - 操作列按钮：编辑、删除
> ```

### 自定义按钮 {按钮名}             ← 每个自定义按钮一项（可选；默认按钮无需展开）
- 位置：{工具栏 / 操作列}
- 图标：{可选，语义描述，如「流程」「打印」}
- 点击行为：{打开表单 / 打开弹窗 / 调用接口 / 流程处理}   ← 必填
- 关联对象：{打开表单填关联表单 spec 文件名；调用接口/流程填语义描述}
- 启用条件：{可选，如「仅状态=已立案可用」}

## 排序与分页                      ← 可选段
- 默认排序：{字段} {ASC/DESC}
- 每页条数：{20（默认）/ 50 / 100}

## 选择器配置                      ← 可选段，仅「列表用途：选择器」时必填（见下方「选择器配置段规则」）
- 多选：{是/否}
- 可回填字段（能力声明）：{字段名逗号分隔}
- 筛选条件：{可选，弹窗时固定的查询条件，自然语言描述}
- 默认排序：{可选，弹窗内默认排序}

## 构建记录                        ← build-list 构建成功后回写（design-list 落盘时留空）
- 列表 XH：{构建后由 build-list 回写——修改入口据此反查 spec}
- 构建时间：{YYYY-MM-DD HH:mm}
- 关联表单 templateId：{构建时解析写入，便于审计}
- 备注：{可选，如覆盖构建/字段变更}

列词汇表（封闭，build 映射为列组件）

> [!important] 列词汇分层（参照表单的表现词汇表）
> 第一层：标准词汇（封闭）——优先用：
> - 数据列：普通文本/数字/日期/代码集/长文本
> - 系统列：序号/选择框/操作（spec 强制显式声明，用户可控是否显示、宽度；build 读 spec 注入，仅异常缺失时兜底）
>
> 第二层：自定义列（开放）——原样记录用户用词 + 标注「⚠️ 自定义」
>
> 兜底：都映射不到 → AI 自行决定（build 阶段，不卡住）

> [!note] 系统列的显式声明规则（强制声明 + 防御兜底）
> 序号/选择框/操作三列必须写进 spec 列定义（质量门硬性必检，不依赖 build 自动注入）。用户可控制：
> - 是否显示（显示：否 则 build 不注入该列）
> - 宽度（用宽度语义词汇表的"序号"/"选择框"/"操作"）
> - 操作列的按钮配置（写在操作按钮段）
> 若用户无定制需求，design-list 默认按惯例生成（序号 5% + 选择框 5% + 操作 12%）。
> build-list 的防御兜底：仅当 spec 异常缺失系统列段时才按惯例默认注入；正常情况一律以 spec 声明为准。

> [!important] 选择框列与批量删除按钮的配套关系（CRUD 列表）
> 「选择框列」和「工具栏批量删除按钮」是配套的——批量删除依赖勾选行，没有选择框列批量删除就无法操作。两者要么都写、要么都不写。
>
> - CRUD 列表（关联表单）：标配写「选择框列」+「批量删除按钮」（除非业务明确不需要批量操作）
> - 纯查询列表（无关联表单）：通常不需要选择框列和批量删除
> - 选择器列表（列表用途=选择器）：不需要选择框列（选择器自带单选/多选交互，不走批量删除）
>
> 实战踩坑：spec 只写「选择框列」没写「批量删除」，或反过来只写「批量删除」没写「选择框列」，都会导致制成品残缺。spec 必须完整声明两者。

宽度语义词汇表（封闭，build 映射为精确 width）

查询条件词汇表（封闭）

List Spec 选择器配置段规则

> [!important] 选择器配置段：列表作为弹窗选择器时的特殊配置（可选段）
> 当元信息「列表用途」填「选择器」时，此段必填。该列表会被表单的「列表选择」规则引用，点击后弹出供用户选数据回填父表单。
>
> 与普通列表的差异：选择器列表 build 时走 LX=2（弹窗列表）+ 实现 confirmClick 脚本（确认按钮回调，把选中行数据传回父表单）。普通列表（LX=1/3）不能当选择器。
>
> 承载原则：本段是父子接口契约——选择器列表声明"我能提供哪些字段给父表单回填"（能力声明），父表单的列表选择规则从中挑选映射（消费选择）。这与列定义的「列类型」对等：声明能力，不写实现。

段结构契约

## 选择器配置
- 多选：是/否
- 可回填字段（能力声明）：XH, JCXMMC, JCXMLX, JCFF    ← 字段名逗号分隔；"能力声明"强调这是"能提供什么"，非白名单限制
- 筛选条件：                                ← 可选，弹窗时固定的查询条件
  - SFYX = '1'（只显示有效项）
- 默认排序：{可选，弹窗内默认排序}

设计要点

可回填字段（能力声明）：字段名后的「（能力声明）」括注是必须写的，不是可选——它明确告诉读者"这是列表能提供给父表单的字段能力，不是'只允许回填这几个'的白名单"。省掉这个括注，中文语境下逗号分隔的清单容易被误读为限制清单。这些字段必须已在列定义段存在（质量门校验）。含义查列定义即可，不重复标注。

为什么不与列定义合并：两者维度不同——列定义声明"列表显示哪些列"，可回填字段声明"哪些列可以回填给父表单"。有些列只展示不可回填（如计算列、聚合列），有些字段不展示但可回填（如主键 XH 通常不在列表显示，但选择器必须能回填它）。

隐藏列（不展示但需可回填的字段）：当某个字段（典型如主键 XH）需要作为可回填字段但列表不展示时，必须在列定义段以 显示：否 显式声明为隐藏列。质量门「可回填字段在列定义中存在」会校验这点。隐藏列写法：

### XH 主键
- 来源表：T_DEMO_GYS
- 列类型：普通文本
- 宽度：窄
- 显示：否
- 说明：主键，列表不展示，但作为可回填字段供父表单取选中行 XH

筛选条件 vs 查询条件：查询条件段是"用户可输入的搜索条件"，选择器配置的筛选条件是"弹窗时系统固定的过滤，不让用户改"。两者语义不同，不合并。

被父表单引用的方式：父表单 spec 的「数据处理规则 → 列表选择」规则用列表 spec 文件名引用本列表 spec（如「选择源：供应商选择__列表」），build 阶段按文件名查 .pacp/specs/动态渲染/{文件名}.md 的构建记录取 XH 作为 dynamicId。用文件名而非业务名，与列表 spec 的「关联表单」字段用表单 spec 文件名引用方向对称，避免同业务多列表时歧义。

质量门：List Spec 完整性自检清单

> [!important] 质量门是 AI 自检（结构完整），用户核对是业务对齐（内容正确）。两者都要：
> 质量门通过 → 展示给用户核对 → 用户说「可以」→ 落盘。
> 质量门不通过 → 不展示，先补全。

产出 spec 草稿后、落盘前，必须跑一遍自检清单：

□ 元信息段：主表名已确认（用户给 / 探查确认）
□ 元信息段：主键已确认（平台新建表默认 XH；已有表填实际主键字段名）
□ 元信息段：[多表联查时] 关联关系已逐行列出（如 T_ZF_JCJL.AJ_XH → T_ZF_AJ.XH）
□ 列定义段：至少有 1 个数据列（序号/选择框/操作为系统列，需显式声明但不计入数据列下限）
□ 列定义段：每个数据列要素齐全——字段名 + 显示名 + 列类型 + 宽度语义 + 显示
□ 列定义段：[多表联查时] 每个字段标注了来源表
□ 列定义段：系统列（序号/选择框/操作）已显式声明（强制，质量门硬性）
□ 代码集列：代码集编号已填（用户给）或标注"待定"（延后到 build 阶段）
□ [有关联表单时]：关联表单字段填的是表单 spec 文件名（如 调查询问通知书__表单，非 templateId——templateId 是构建产物，设计阶段没有）
□ [有关联表单时]：CRUD 标配完整——工具栏含「新增」+「批量删除」按钮，列定义含「选择框列」，操作列含「编辑」+「删除」（spec 与制成品 1:1 对应，不靠 build 自动补全）
□ [有「批量删除」按钮时]：列定义必须含「选择框列」（批量删除依赖勾选行，两者配套）
□ [有查询条件时]：每个查询字段——字段名 + 输入类型 + 操作符 齐全
□ [有自定义按钮时]：每个自定义按钮要素齐全——按钮名 + 位置 + 点击行为 + 关联对象
□ [列表用途：选择器 时]：选择器配置段存在
□ [选择器配置]：可回填字段清单非空，且每个字段在列定义中存在

缺项处理：不落盘，逐项追问用户。代码集编号当场给不出 → 允许标「待定」延后（唯一软项，其余硬性）。

API 速查（探查时按需使用）

> 以下仅探查时使用，通过 require('../pacp-build-list/lib/bwai_client.js') 引入。

const { BwaiClient } = require('../pacp-build-list/lib/bwai_client');
const client = new BwaiClient(BASE_URL, SESSION_ID);

// 探查表名
const tables = await client.getTables();  // [{ TABLE_NAME, TABLE_COMMENT }]

// 探查列
const columns = await client.getColumns('表名');  // [{ COLUMN_NAME, COLUMN_COMMENT, DATA_TYPE }]

// 探查主键（多表联查时主表主键必查，用于填元信息「主键」）
const pk = await client.getPrimaryKey('表名');  // 主键列名字符串

// 代码集核验（可选）
const codeClassList = await client.getCommonCodeClassList({ pageSize: 10000 });

图片与文档输入

当用户传入图片或文档（Word/PDF/Excel）路径时，按 references/doc-and-image-input.md 规范提取列表结构信息（列名/显示名/查询条件/按钮），产出 spec（非构建配置）。

> [!important] 与原 pacp-build-list 的差异
> 原本 skill 的图片/文档解析若产出的是列表配置 JSON（走构建），本技能迁移后产出的是 list-spec.md（规格文档），不走构建。图片/文档解析的最终产物是 spec 的列定义 + 查询条件，而非 columns 数组。