@zeyue0329/xiaoma-cli 1.0.49 → 1.0.66

package/demo/xiaoma-bug-circle-resolve/workflow.md

@@ -0,0 +1,254 @@
+# Bug Circle Resolve Workflow
+
+**Goal:** 全自动循环处理**指定项目**下所有AI测试平台推送的新增状态(defect_status=0)Bug，无需任何人工介入，直到队列清空。
+
+**Your Role:** 你是Bug处理调度器。你的职责是：校验 jiraId 参数 → 查询当前项目的 Bug 队列 → 为每个Bug启动独立Agent子进程处理 → 确认处理结果 → 继续下一个 → 输出最终报告。全程无需用户参与。
+
+**所有输出使用简体中文。**
+
+---
+
+## 参数说明
+
+本 skill 支持以下参数：
+
+| 参数 | 是否必填 | 传参形式 | 说明 | 示例 |
+|------|---------|---------|------|------|
+| `jiraId` | **必填** | **位置参数（唯一 token）** | JIRA 项目 ID，多项目共库场景下的硬隔离边界。**所有 `t_defect_info` 的 SELECT/UPDATE/COUNT 都必须带 `AND jira_id = '{{jiraId}}'`**，子 Agent 也必须继承此参数。 | `GYLPJ-1153` |
+
+### args 解析规则（Claude 必须严格遵守）
+
+把 skill 传入的 `args` 按空格切分成 token 列表后：
+1. 取**第一个 token**：
+   - 若**不含 `=`**，视为 `jiraId` 的值（位置参数语法，**推荐形式**）。
+   - 若形如 `jiraId=xxx`，解析为 `jiraId`（兼容旧语法）。
+   - 若形如 `otherKey=xxx`（任何其它键值对），说明位置参数缺失，视为**未提供 jiraId**。
+2. 本 skill 只接受 `jiraId` 一个参数。若 args 中出现任何第二个 token（无论形式），视为非法输入，立刻中断并提示用户只需传一个 jiraId。
+3. 若最终 `jiraId` 仍为空或空字符串，**立刻拒绝执行**，禁止开始循环（否则会把其他项目的 Bug 一并拉下来误改代码、误改状态）。
+
+### 调用示例
+
+```
+# 推荐：位置参数（最简洁）
+/xiaoma-bug-circle-resolve GYLPJ-1153
+
+# 兼容旧语法（仍可用）
+/xiaoma-bug-circle-resolve jiraId=GYLPJ-1153
+```
+
+---
+
+## 核心架构：Agent 隔离处理
+
+**为什么不需要 `/clear`：** 每个Bug的分析和修复都委托给**独立的 Agent 子进程**。Agent 天然拥有隔离的上下文空间，处理完即释放，不会污染主对话。主对话只负责轻量的调度循环。
+
+```
+主对话（调度器，上下文极小）
+  ├── Agent #1 → 处理 Bug A（独立上下文，完成后释放）
+  ├── Agent #2 → 处理 Bug B（独立上下文，完成后释放）
+  ├── Agent #3 → 处理 Bug C（独立上下文，完成后释放）
+  └── ...直到队列清空
+```
+
+---
+
+## 核心规则（严格遵守）
+
+1. **每个Bug由独立Agent处理** — 使用 Agent 工具启动 general-purpose 子进程，将Bug的完整信息和处理指令传给Agent，Agent独立完成分析、修复、验证、状态更新
+2. **主循环保持轻量** — 主对话只做：查询队列 → 启动Agent → 读取Agent结果 → 查询剩余 → 继续或结束
+3. **串行处理** — 一次处理一个Bug，等Agent完成后再处理下一个，避免并发修改冲突
+4. **全自动无人工介入** — 从开始到结束，用户无需执行任何命令
+
+---
+
+## 数据库信息
+
+- **MySQL缺陷库**: `mcp__xiaoma-dev-mysql__mysql_query` — 查询/更新Bug状态
+- **Oracle业务库**: `mcp__oracle_zqyl_pj_incentive_test4__execute_query` — 验证业务数据
+- **缺陷表**: `t_defect_info`
+- **待处理条件**: `defect_status = 0 AND is_del = 0 AND jira_id = '{{jiraId}}'`（**jira_id 强制过滤**）
+- **状态枚举**: 0=新增, 1=已验证, 2=已修复, 3=非缺陷(测试误报)
+- **项目隔离字段**: `jira_id`（varchar(64)，JIRA 项目 ID），多项目共库时用于区分
+
+---
+
+## WORKFLOW
+
+<workflow>
+
+<step n="1" goal="校验 jiraId 并检查当前项目下待处理Bug队列">
+
+  <action>**前置校验**：按本文件顶部的「args 解析规则」从 args 中解析出 `jiraId`。若未解析到（args 为空），立刻中断并输出：
+  `批量循环处理必须将 jiraId 作为第一个参数传入，例如：/xiaoma-bug-circle-resolve GYLPJ-1153`
+  禁止在没有 jiraId 的情况下继续执行任何 t_defect_info 查询或循环。
+  </action>
+
+  <action>查询当前项目（jiraId={{jiraId}}）缺陷统计：
+  ```sql
+  SELECT
+    SUM(CASE WHEN defect_status = 0 THEN 1 ELSE 0 END) as pending,
+    SUM(CASE WHEN defect_status = 2 THEN 1 ELSE 0 END) as fixed,
+    SUM(CASE WHEN defect_status = 3 THEN 1 ELSE 0 END) as false_positive,
+    COUNT(*) as total
+  FROM t_defect_info WHERE is_del = 0 AND jira_id = '{{jiraId}}';
+  ```
+  </action>
+
+  <check if="pending == 0">
+    <action>当前项目无待处理缺陷，直接进入 Step 3 输出最终报告</action>
+  </check>
+
+  <check if="pending > 0">
+    <action>查询当前项目下待处理缺陷列表：
+    ```sql
+    SELECT defect_id, title, severity, module_path
+    FROM t_defect_info
+    WHERE is_del = 0 AND defect_status = 0 AND jira_id = '{{jiraId}}'
+    ORDER BY create_time ASC;
+    ```
+    </action>
+
+    <action>向用户展示概况（必须包含"当前项目 jiraId：{{jiraId}}"一行）并告知即将开始全自动处理</action>
+    <action>进入 Step 2 开始循环</action>
+  </check>
+
+</step>
+
+<step n="2" goal="循环处理每个Bug（全自动）">
+
+  <!-- 循环开始：查询当前项目下最早的待处理Bug完整信息 -->
+  <action>查询当前项目（jiraId={{jiraId}}）下最早的一条待处理Bug的完整详情：
+  ```sql
+  SELECT * FROM t_defect_info
+  WHERE is_del = 0 AND defect_status = 0 AND jira_id = '{{jiraId}}'
+  ORDER BY create_time ASC LIMIT 1;
+  ```
+  </action>
+
+  <check if="无结果">
+    <action>队列已空，进入 Step 3</action>
+  </check>
+
+  <!-- 输出当前处理进度 -->
+  <action>输出：正在处理 {{defect_id}} — {{title}}</action>
+
+  <!-- 启动独立 Agent 处理这个Bug -->
+  <critical>
+  使用 Agent 工具启动一个 general-purpose 子进程来处理这个Bug。
+  Agent 的 prompt 必须包含以下完整信息，使其能独立工作：
+
+  1. **Bug完整信息 + 项目上下文**：将查询到的 defect_id, title, steps, module_path, url, error_front, error_apis, defect_type, severity **以及当前处理的 jiraId={{jiraId}}** 全部传给Agent。Agent 必须把 jiraId 视为硬约束，所有 SQL 都要带 `AND jira_id = '{{jiraId}}'`。
+  2. **处理指令**：按以下步骤执行——
+     a. 根据 module_path 和 url 定位代码（前端在 zqyl-manager/src/main/views/pjs/incentive/，后端在 zqyl-pj-incentive/src/main/）
+     b. 使用 Explore Agent 探索相关前端页面组件、后端Controller/Service/Mapper代码
+     c. 使用 Oracle MCP Server (mcp__oracle_zqyl_pj_incentive_test4__execute_query) 验证数据库数据
+     d. 分析根因，判定：真实缺陷 or 测试误报
+     e. 如为真实缺陷：使用 Edit 工具修复代码，修复范围限定在缺陷涉及的代码
+     f. 验证修复逻辑正确性
+     g. 使用 MySQL MCP Server (mcp__xiaoma-dev-mysql__mysql_query) 更新Bug状态（**UPDATE 必须带 jira_id 过滤**）：
+        - 真实缺陷已修复：
+          `UPDATE t_defect_info SET defect_status = 2 WHERE defect_id = '{{defect_id}}' AND jira_id = '{{jiraId}}' AND is_del = 0;`
+        - 测试误报：
+          `UPDATE t_defect_info SET defect_status = 3 WHERE defect_id = '{{defect_id}}' AND jira_id = '{{jiraId}}' AND is_del = 0;`
+     h. 返回处理结果摘要：defect_id、jiraId、判定结果、修改的文件列表、验证结果
+  3. **项目规范**：遵循 CLAUDE.md 编码规范，禁止Lombok、禁止MyBatis-Plus、返回ResultData等
+  4. **常见缺陷模式参考**：
+     - 模糊查询不符合预期 → SQL用 = 而非 LIKE，改为 LIKE '%' || #{param} || '%'
+     - 字段未显示/缺少列 → 前端 header 配置缺少字段
+     - 字段值展示错误 → prop映射错误或SQL字段别名错误
+     - 查询不出数据 → SQL条件逻辑错误、MQ消费时字段未映射
+     - 表头名称错误 → header label 配置错误
+     - 点击按钮报错 → 接口调用参数或后端异常
+  5. **代码结构映射**：
+     - 签发业务归属表 → 前端 issueAttribution/，后端 IssueAttributionController, IssueAttributionMapper.xml
+     - 背书业务归属表 → 前端 endorseAttribution/，后端 EndorseAttributionController
+     - 融资台账 → 前端 financeLedger/，后端 FinanceLedgerController
+  </critical>
+
+  <!-- Agent 完成后 -->
+  <action>读取 Agent 返回的处理结果摘要</action>
+  <action>输出该Bug的处理结果（简要一行）</action>
+
+  <!-- 检查是否还有剩余 -->
+  <action>查询当前项目下剩余待处理数量：
+  ```sql
+  SELECT COUNT(*) as remaining FROM t_defect_info
+  WHERE is_del = 0 AND defect_status = 0 AND jira_id = '{{jiraId}}';
+  ```
+  </action>
+
+  <check if="remaining > 0">
+    <action>继续循环 — 回到 Step 2 顶部处理下一个Bug</action>
+  </check>
+
+  <check if="remaining == 0">
+    <action>队列已空，进入 Step 3</action>
+  </check>
+
+</step>
+
+<step n="3" goal="输出最终处理报告">
+
+  <action>查询当前项目（jiraId={{jiraId}}）下所有缺陷的最终状态：
+  ```sql
+  SELECT defect_id, title,
+    CASE defect_status
+      WHEN 0 THEN '待处理'
+      WHEN 2 THEN '已修复'
+      WHEN 3 THEN '非缺陷(测试误报)'
+      ELSE '其他'
+    END as status_text,
+    update_time
+  FROM t_defect_info
+  WHERE is_del = 0 AND jira_id = '{{jiraId}}'
+  ORDER BY defect_status ASC, update_time DESC;
+  ```
+  </action>
+
+  <action>查询当前项目统计汇总：
+  ```sql
+  SELECT
+    SUM(CASE WHEN defect_status = 0 THEN 1 ELSE 0 END) as pending,
+    SUM(CASE WHEN defect_status = 2 THEN 1 ELSE 0 END) as fixed,
+    SUM(CASE WHEN defect_status = 3 THEN 1 ELSE 0 END) as false_positive
+  FROM t_defect_info WHERE is_del = 0 AND jira_id = '{{jiraId}}';
+  ```
+  </action>
+
+  <action>输出最终报告：
+
+  ```
+  ========================================
+  全部Bug处理完毕
+  ========================================
+
+  项目ID（jiraId）：{{jiraId}}
+
+  已修复: {{fixed}} 条
+  测试误报: {{false_positive}} 条
+  剩余待处理: {{pending}} 条
+
+  处理明细:
+  | 缺陷ID | 标题 | 处理结果 | 更新时间 |
+  |--------|------|---------|---------|
+  | ...    | ...  | ...     | ...     |
+
+  当前项目（{{jiraId}}）下新增状态的测试Bug已处理完毕，全程无需人工介入。
+  ```
+
+  </action>
+
+</step>
+
+</workflow>
+
+---
+
+## 注意事项
+
+1. **jiraId 是硬隔离边界** — 批量循环处理必须指定 jiraId，**所有 `t_defect_info` 的 SELECT/UPDATE/COUNT 都必须带 `AND jira_id = '{{jiraId}}'`**，子 Agent 的 prompt 和 UPDATE 语句也必须继承该值，否则会跨项目误改代码和状态
+2. **Agent 隔离是关键** — 每个Bug在独立Agent子进程中处理，自带隔离上下文，无需 `/clear`，不会相互干扰
+3. **全自动** — 用户只需调用一次 `/xiaoma-bug-circle-resolve GYLPJ-1153`（首个位置参数即 jiraId），之后全程自动直到当前项目队列清空
+4. **串行安全** — 一次只处理一个Bug，避免并发修改同一文件产生冲突
+5. **容错** — Agent处理失败时Bug状态仍为0，下次循环自动重试
+6. **Agent prompt 质量** — 传给Agent的prompt必须包含Bug完整信息 + jiraId + 项目上下文 + 处理指令，使其能完全独立工作

package/demo/xiaoma-bug-resolve/SKILL.md

@@ -0,0 +1,6 @@
+---
+name: xiaoma-bug-resolve
+description: 'Resolve AI test platform bugs: query MySQL for defects, analyze root cause, fix code, verify with Playwright, update bug status. Use when the user says "resolve bug", "fix test bug", or "处理测试bug".'
+---
+
+Follow the instructions in [workflow.md](workflow.md).

package/demo/xiaoma-bug-resolve/workflow.md

@@ -0,0 +1,269 @@
+# Bug Resolve Workflow
+
+**Goal:** 从 AI 测试平台推送的缺陷中，按时间正序取出第一条待处理 Bug，分析是否为真实缺陷，修复并验证，最后更新缺陷状态。
+
+**Your Role:** 你是一名全栈开发工程师，负责分析、修复和验证 AI 测试平台推送的缺陷。你需要精确定位问题根因，编写高质量修复代码，并通过测试验证修复效果。
+
+**所有输出使用简体中文。**
+
+---
+
+## 参数说明
+
+本 skill 支持以下可选参数（通过调用时传入或交互式获取）：
+
+| 参数 | 说明 | 示例 |
+|------|------|------|
+| `testUrl` | Playwright 测试用的前端页面基础地址 | `http://localhost:8080/zqyl_manager` |
+| `authToken` | 登录认证 token（Bearer token） | `eyJhbGciOiJI...` |
+| `defectId` | 指定处理的缺陷ID（不传则自动取时间最早的待处理缺陷） | `DEF0158` |
+
+如果用户未提供 `testUrl` 和 `authToken`，在需要 Playwright 测试时主动向用户索要。
+
+---
+
+## 数据库信息
+
+### MySQL 缺陷库（xiaoma-dev-mysql）
+
+**缺陷表：`t_defect_info`**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | bigint | 主键 |
+| defect_id | varchar(64) | 缺陷唯一标识 |
+| run_id | varchar(64) | 关联运行ID |
+| jira_id | varchar(64) | JIRA项目ID |
+| title | varchar(512) | 缺陷描述 |
+| module_path | varchar(256) | 所属模块 |
+| severity | tinyint | 严重等级：1紧急, 2高, 3中, 4低 |
+| defect_type | varchar(32) | 缺陷类型：前端, 后端 |
+| steps | text | 重现步骤 |
+| case_no | varchar(64) | 关联用例编号 |
+| case_name | varchar(256) | 关联用例名称 |
+| error_front | text | 前端错误日志 |
+| url | varchar(1024) | 页面URL |
+| error_apis | text | 接口报错信息 |
+| discover_time | datetime | 缺陷发现时间 |
+| defect_status | tinyint | **状态：0新增, 1已验证, 2已修复, 3非缺陷（测试误报）** |
+| is_del | tinyint | 删除标记：0未删除, 1已删除 |
+
+---
+
+## WORKFLOW
+
+<workflow>
+
+<step n="1" goal="查询待处理缺陷并获取第一条Bug详情">
+
+  <action>使用 `mcp__xiaoma-dev-mysql__mysql_query` 工具查询所有待处理缺陷概要：
+  ```sql
+  SELECT id, defect_id, title, defect_status, severity, defect_type, module_path, discover_time, create_time
+  FROM t_defect_info
+  WHERE is_del = 0 AND defect_status = 0
+  ORDER BY create_time ASC;
+  ```
+  </action>
+
+  <check if="有指定 defectId 参数">
+    <action>按指定 defectId 查询缺陷详情</action>
+  </check>
+  <check if="未指定 defectId">
+    <action>取查询结果中时间最早（第一条）的缺陷</action>
+  </check>
+
+  <action>查询该缺陷的完整详情：
+  ```sql
+  SELECT * FROM t_defect_info WHERE defect_id = '{{target_defect_id}}' AND is_del = 0;
+  ```
+  </action>
+
+  <action>输出缺陷摘要信息：
+  - 缺陷ID、标题、严重度、类型
+  - 模块路径、页面URL
+  - 重现步骤（steps字段完整展示）
+  - 前端错误日志（error_front，如有）
+  - 接口报错信息（error_apis，如有）
+  </action>
+
+  <check if="没有待处理缺陷">
+    <action>告知用户当前没有待处理的缺陷，流程结束</action>
+  </check>
+
+</step>
+
+<step n="2" goal="分析缺陷根因">
+
+  <action>根据缺陷信息确定需要探索的代码区域：
+  - 根据 `module_path` 确定业务模块
+  - 根据 `url` 确定前端页面路径
+  - 根据 `defect_type` 确定前端/后端
+  - 根据 `error_apis` 确定相关API接口
+  </action>
+
+  <action>使用 Explore Agent 并行探索相关代码：
+  1. **前端代码**：找到页面组件、搜索表单配置、API调用方式
+  2. **后端代码**：找到 Controller → Application Service → Mapper，定位SQL/业务逻辑
+  3. **数据库**：通过 Oracle MCP Server 验证数据和SQL逻辑
+  </action>
+
+  <action>综合分析后得出结论，分为三种情况：
+  - **真实缺陷**：代码确实存在问题，需要修复
+  - **测试误报（非缺陷）**：代码逻辑正确，测试用例本身有误或测试数据问题
+  - **需要更多信息**：无法确定，需要向用户确认
+  </action>
+
+  <action>向用户展示分析结论，包括：
+  - 根因说明（哪个文件、哪一行、什么问题）
+  - 判定结果（真实缺陷 / 测试误报）
+  - 如为真实缺陷，展示修复方案
+  </action>
+
+</step>
+
+<step n="3" goal="修复缺陷（仅真实缺陷执行此步骤）">
+
+  <check if="判定为测试误报">
+    <action>跳过此步骤，直接进入 Step 5 更新状态</action>
+  </check>
+
+  <action>按照分析结果执行代码修复：
+  - 使用 Edit 工具修改相关文件
+  - 修复范围严格限定在缺陷涉及的代码，不做额外重构
+  - 遵循项目 CLAUDE.md 中的编码规范
+  </action>
+
+  <action>列出所有修改的文件和修改内容摘要</action>
+
+</step>
+
+<step n="4" goal="验证修复结果">
+
+  <action>根据缺陷类型选择验证方式：</action>
+
+  <!-- 数据库层验证（优先执行） -->
+  <action>如涉及SQL/查询逻辑变更：
+  - 通过 Oracle MCP Server 直接执行修复后的SQL逻辑
+  - 验证查询结果是否符合预期
+  - 记录验证结果
+  </action>
+
+  <!-- Playwright 页面验证（如需） -->
+  <check if="缺陷涉及页面交互且用户提供了 testUrl">
+    <action>使用 Playwright 工具进行端到端验证：
+    1. 导航到目标页面（使用 testUrl）
+    2. 如需登录，使用 authToken 注入认证信息
+    3. 按照缺陷的重现步骤操作
+    4. 验证结果是否符合预期
+    </action>
+  </check>
+
+  <check if="缺陷涉及页面交互但未提供 testUrl 或 authToken">
+    <action>向用户索要 Playwright 测试所需信息：
+    - 测试环境前端地址（testUrl）
+    - 登录认证 token（authToken）
+    提示用户：请提供测试地址和登录token，格式如：
+    `testUrl=http://localhost:8080/zqyl_manager authToken=eyJhbGci...`
+    </action>
+  </check>
+
+  <check if="本地无法构建/部署后端">
+    <action>说明已通过数据库SQL直接验证修复逻辑正确性，
+    端到端验证需等后端部署到测试环境后执行</action>
+  </check>
+
+  <action>输出验证结果摘要</action>
+
+</step>
+
+<step n="5" goal="更新缺陷状态">
+
+  <check if="真实缺陷且已修复验证通过">
+    <action>更新缺陷状态为已修复（defect_status = 2）：
+    ```sql
+    UPDATE t_defect_info SET defect_status = 2 WHERE defect_id = '{{target_defect_id}}' AND is_del = 0;
+    ```
+    </action>
+  </check>
+
+  <check if="判定为测试误报">
+    <action>更新缺陷状态为非缺陷（defect_status = 3）：
+    ```sql
+    UPDATE t_defect_info SET defect_status = 3 WHERE defect_id = '{{target_defect_id}}' AND is_del = 0;
+    ```
+    </action>
+  </check>
+
+  <action>验证状态更新成功：
+  ```sql
+  SELECT defect_id, title, defect_status FROM t_defect_info WHERE defect_id = '{{target_defect_id}}';
+  ```
+  </action>
+
+  <action>输出最终处理结果：
+
+  **处理完成**
+
+  | 项目 | 内容 |
+  |------|------|
+  | 缺陷ID | {{defect_id}} |
+  | 缺陷标题 | {{title}} |
+  | 判定结果 | 真实缺陷 / 测试误报 |
+  | 处理方式 | 已修复代码 / 标记为非缺陷 |
+  | 状态更新 | defect_status → 2(已修复) / 3(非缺陷) |
+  | 修改文件 | {{modified_files_list}} |
+  | 验证结果 | 通过 / 待部署后验证 |
+
+  </action>
+
+  <!-- 检查是否还有更多待处理缺陷 -->
+  <action>查询剩余待处理缺陷数量：
+  ```sql
+  SELECT COUNT(*) as remaining FROM t_defect_info WHERE is_del = 0 AND defect_status = 0;
+  ```
+  告知用户剩余待处理缺陷数量，询问是否继续处理下一条。
+  </action>
+
+</step>
+
+</workflow>
+
+---
+
+## 项目特定信息
+
+### 代码结构映射
+
+根据缺陷的 `module_path` 和 `url` 定位代码位置：
+
+| 模块关键字 | 前端页面路径 | 后端Controller | Mapper XML |
+|-----------|-------------|---------------|------------|
+| 签发业务归属表 | `views/pjs/incentive/issueAttribution/` | `IssueAttributionController` | `IssueAttributionMapper.xml` |
+| 背书业务归属表 | `views/pjs/incentive/endorseAttribution/` | `EndorseAttributionController` | `EndorseAttributionMapper.xml` |
+| 融资台账 | `views/pjs/incentive/financeLedger/` | `FinanceLedgerController` | `FinanceLedgerMapper.xml` |
+| 费用方案 | `views/pjs/incentive/feePlan/` | `FeePlanController` | `FeePlanMapper.xml` |
+
+### 常见缺陷模式
+
+| 缺陷描述关键字 | 可能根因 | 修复方向 |
+|--------------|---------|---------|
+| 模糊查询不符合预期 | SQL使用 `=` 而非 `LIKE` | 改为 `LIKE '%' \|\| #{param} \|\| '%'` |
+| 字段未显示/缺少列 | 前端表头配置缺少字段 | 在 ylTableData.header 中添加列定义 |
+| 字段值展示错误 | 前端取值prop映射错误或后端SQL字段别名错误 | 修正prop或SQL alias |
+| 查询不出数据 | 查询条件逻辑错误（AND/OR）、字段映射错误 | 修正SQL条件逻辑 |
+| 表头名称错误 | 前端 header label 配置错误 | 修改 header 中对应列的 label |
+| 点击按钮报错 | 接口调用参数错误或后端接口异常 | 检查前端调用和后端接口 |
+
+### 数据库连接
+
+- **MySQL（缺陷库）**：使用 `mcp__xiaoma-dev-mysql__mysql_query` 工具
+- **Oracle（业务库）**：使用 `mcp__oracle_zqyl_pj_incentive_test4__execute_query` 工具
+
+### 状态码枚举
+
+| defect_status | 含义 | 场景 |
+|--------------|------|------|
+| 0 | 新增 | AI测试平台推送的初始状态 |
+| 1 | 已验证 | 人工确认为真实缺陷 |
+| 2 | 已修复 | 代码已修复并验证通过 |
+| 3 | 非缺陷 | 测试误报，非真实缺陷 |

package/demo/xiaoma-prd-saas-zh/README.md

@@ -0,0 +1,57 @@
+# 中文 SaaS B2B PRD 样例 — 灵协 Linkly
+
+本目录是一份完整的 XiaoMa-CLI PRD 标准化样例集，对应 `project-types.csv` 中的 `saas_b2b` 类型。它演示从产品简报 → 研究 → PRD → Epics → 验证报告的端到端工件链，作为 AI 生成 PRD 时的对照基准与人类作者的参考样板。
+
+## 虚构场景
+
+**灵协 Linkly** — 面向中型企业（年营收 5 亿-50 亿）客户成功（Customer Success）团队的 AI 客户旅程协作平台。核心能力：跨系统聚合的客户旅程画布、LLM 驱动的高风险对话摘要、可解释的客户健康度评分与触达建议。
+
+| 维度       | 取值                                           |
+| ---------- | ---------------------------------------------- |
+| 产品类型   | saas_b2b                                       |
+| 目标领域   | general（含轻度 fintech/healthcare 客户合规）  |
+| 复杂度     | medium                                         |
+| 项目阶段   | greenfield · MVP 计划 2026 H2                  |
+| 预期规模   | 单租户 ≤ 200 人 · 总租户 100-500 · 单租户 1k 并发 |
+
+## 目录文件
+
+| 文件                                    | 类型           | 作用                                         |
+| --------------------------------------- | -------------- | -------------------------------------------- |
+| [README.md](./README.md)                | 元说明         | 本文件                                       |
+| [product-brief.md](./product-brief.md)  | 上游产物（CB） | Analyst `*product-brief` 的产出样例          |
+| [market-research-2026-q1.md](./market-research-2026-q1.md) | 上游产物（MR） | 市场研究节选 |
+| [domain-research.md](./domain-research.md) | 上游产物（DR） | 领域研究（含合规要点）                       |
+| [prd.md](./prd.md)                      | **主样例**     | 9 章节 + 24 FR + 10 NFR + Traceability Matrix |
+| [prd-bad-examples.md](./prd-bad-examples.md) | 反模式集    | 对应 AP-01..AP-05 的坏例 + 修复对照          |
+| [epics.md](./epics.md)                  | 下游样例       | FR→Epic→Story 拆分演示                       |
+| [validation-report.md](./validation-report.md) | 校验报告 | `xiaoma-validate-prd` 13 维得分卡示例        |
+
+## 阅读建议
+
+- **第一次读 PRD 标准化方案：** 直接看 [prd.md](./prd.md)，对照 `prd-purpose.md` 与 `prd-skeleton-reference.md` 体感 9 章节结构。
+- **想理解 AI 化的对照基准：** [prd.md](./prd.md) ↔ [prd-bad-examples.md](./prd-bad-examples.md) 同节对比，每个反模式都标注了 AP 编号。
+- **想验证 rubric 设计：** 看 [validation-report.md](./validation-report.md)，13 维得分卡基于 `prd-quality-rubric.csv` 计算。
+- **想看上下游衔接：** 从 [product-brief.md](./product-brief.md) 出发，对照 [prd.md](./prd.md) 的 §1-§3 字段映射，再看 [epics.md](./epics.md) 中的 FR→Epic 拆分。
+
+## 与工作流的关系
+
+本目录文件**不被任何工作流自动加载**——它们是参考样例，不是模板或配置。开发者可以：
+
+1. 复制 [product-brief.md](./product-brief.md) 到 `{planning_artifacts}/`，跑 `pm *create-prd`，diff 输出与 [prd.md](./prd.md) 对比结构一致性。
+2. 复制 [prd-bad-examples.md](./prd-bad-examples.md) 中片段拼成的"坏 PRD"，跑 `pm *validate-prd`，验证 rubric 是否命中预期 blockers。
+3. 把 [prd.md](./prd.md) 作为新项目的起点，按团队实际场景增删字段。
+
+## 注意事项
+
+- 所有数字（baseline、target、SLA 等）均为**虚构示例**，不代表真实产品承诺。
+- "灵协 Linkly" 与文中所有公司名、客户名、案例均为示例。
+- 文件中的术语（CSM、健康度、触达等）遵循国内 SaaS 行业常见命名，但具体定义见 [prd.md §5.2](./prd.md)。
+
+## 维护
+
+样例与 `prd-purpose.md` / `prd-quality-rubric.csv` 同期演进：
+
+- prd-purpose.md 增新反模式 → prd-bad-examples.md 增对应坏例
+- prd-quality-rubric.csv 调整权重/阈值 → validation-report.md 重算得分卡
+- project-types.csv saas_b2b 行变更 → prd.md §7 同步