@guru-ai-product/ai-product-kit 0.2.251113215925 → 0.2.251117160442

package/bin/setup.js

@@ -5,6 +5,15 @@ const path = require('node:path');
 
 const packageRoot = path.resolve(__dirname, '..');
 const bundledSkillsDir = path.join(packageRoot, 'skills');
+const AGENTS_FILENAME = 'AGENTS.md';
+const AGENTS_TEMPLATE_PATH = path.join(
+  packageRoot,
+  'skills',
+  'aipk_init_project',
+  'template',
+  'AGENTS_TEMPLATE.md'
+);
+const AGENTS_TEMPLATE_PLACEHOLDER = '{{skills_section}}';
 
 function log(message) {
   process.stdout.write(`[ai-product-kit] ${message}\n`);
@@ -84,6 +93,169 @@ function main() {
   removeGuruDirectories(targetDir);
   copyBundledSkills(targetDir);
   log('Skills directory updated.');
+  ensureAgentsMd();
 }
 
 main();
+
+function ensureAgentsMd() {
+  const agentsPath = path.join(process.cwd(), AGENTS_FILENAME);
+  let content;
+  if (!fs.existsSync(agentsPath)) {
+    content = buildDefaultAgentsContent();
+    fs.writeFileSync(agentsPath, content, 'utf8');
+    log('Created AGENTS.md');
+  } else {
+    content = fs.readFileSync(agentsPath, 'utf8');
+  }
+
+  const skills = collectSkillMetadata();
+  const newSection = renderAgentsTemplateForSkills(skills);
+  const updated = replaceSkillsSection(content, newSection);
+
+  if (updated !== content) {
+    fs.writeFileSync(agentsPath, updated, 'utf8');
+    log(`Updated AGENTS.md with ${skills.length} skill(s)`);
+  } else {
+    log('AGENTS.md already up to date');
+  }
+}
+
+function buildDefaultAgentsContent() {
+  return renderAgentsTemplateForSkills([]);
+}
+
+function renderAgentsTemplateForSkills(skills) {
+  const template = loadAgentsTemplate();
+  if (!template.includes(AGENTS_TEMPLATE_PLACEHOLDER)) {
+    exitWithError(`AGENTS template missing ${AGENTS_TEMPLATE_PLACEHOLDER} placeholder`);
+  }
+  const entries = generateSkillEntries(skills);
+  return template.replace(AGENTS_TEMPLATE_PLACEHOLDER, entries);
+}
+
+function loadAgentsTemplate() {
+  if (!fs.existsSync(AGENTS_TEMPLATE_PATH)) {
+    exitWithError('AGENTS template file is missing from the package.');
+  }
+  return fs.readFileSync(AGENTS_TEMPLATE_PATH, 'utf8');
+}
+
+function collectSkillMetadata() {
+  if (!fs.existsSync(bundledSkillsDir)) {
+    return [];
+  }
+
+  const entries = fs.readdirSync(bundledSkillsDir, { withFileTypes: true });
+  /** @type {{ name: string; description: string; location: string }[]} */
+  const skills = [];
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const skillDir = path.join(bundledSkillsDir, entry.name);
+    const metadata = parseSkillFrontMatter(skillDir);
+    const name = metadata?.name || entry.name;
+    const description =
+      metadata?.description ||
+      `AI Product Kit skill ${name} (${entry.name})`;
+    skills.push({ name, description, location: 'project' });
+  }
+
+  return skills;
+}
+
+function parseSkillFrontMatter(skillDir) {
+  const skillFile = path.join(skillDir, 'SKILL.md');
+  if (!fs.existsSync(skillFile)) {
+    return null;
+  }
+
+  const content = fs.readFileSync(skillFile, 'utf8');
+  const match = content.match(/^---\s*[\r\n]+([\s\S]*?)[\r\n]+---/);
+  if (!match) {
+    return null;
+  }
+
+  return parseFrontMatter(match[1]);
+}
+
+function parseFrontMatter(block) {
+  const lines = block.split(/\r?\n/);
+  const metadata = {};
+
+  let index = 0;
+  while (index < lines.length) {
+    const rawLine = lines[index];
+    const line = rawLine.trim();
+    if (!line || line.startsWith('#')) {
+      index += 1;
+      continue;
+    }
+    const colonIndex = line.indexOf(':');
+    if (colonIndex === -1) {
+      index += 1;
+      continue;
+    }
+    const key = line.slice(0, colonIndex).trim();
+    let value = line.slice(colonIndex + 1).trim();
+    index += 1;
+    if (value === '|' || value === '>') {
+      const collected = [];
+      while (index < lines.length) {
+        const nextLine = lines[index];
+        if (!nextLine.trim()) {
+          break;
+        }
+        collected.push(nextLine.replace(/^[ \t]+/, ''));
+        index += 1;
+      }
+      value = collected.join('\n').trim();
+    } else {
+      if (
+        (value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))
+      ) {
+        value = value.slice(1, -1);
+      }
+    }
+
+    if (value) {
+      metadata[key] = value;
+    }
+  }
+
+  return metadata;
+}
+
+function generateSkillEntries(skills) {
+  const sorted = [...skills].sort((a, b) => a.name.localeCompare(b.name));
+  return sorted
+    .map(
+      (skill) => `<skill>
+<name>${skill.name}</name>
+<description>${skill.description}</description>
+<location>${skill.location}</location>
+</skill>`
+    )
+    .join('\n\n');
+}
+
+function replaceSkillsSection(content, newSection) {
+  const xmlRegex = /<skills_system[\s\S]*?<\/skills_system>/;
+  if (xmlRegex.test(content)) {
+    return content.replace(xmlRegex, newSection);
+  }
+
+  const htmlRegex = /<!-- SKILLS_TABLE_START -->[\s\S]*?<!-- SKILLS_TABLE_END -->/;
+  if (htmlRegex.test(content)) {
+    const inner = newSection
+      .replace(/<skills_system[^>]*>/, '')
+      .replace('</skills_system>', '')
+      .trim();
+    return content.replace(htmlRegex, `<!-- SKILLS_TABLE_START -->\n${inner}\n<!-- SKILLS_TABLE_END -->`);
+  }
+
+  return content.trimEnd() + '\n\n' + newSection + '\n';
+}

package/mcp/skills/aipk_init_project/template/AGENTS_TEMPLATE.md

@@ -69,4 +69,4 @@ Use these MCP tools to load a Skill by name. The server maps known Skill names t
 </mcp_skills>
 <!-- MCP_SKILLS_TABLE_END -->
 
-<!-- rule: run node tools/build_package update-mcp to refresh this table -->
+<!-- rule: use node tools/build_package update-skills to refresh this table -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guru-ai-product/ai-product-kit",
-  "version": "0.2.251113215925",
+  "version": "0.2.251117160442",
   "description": "Sync the AI Product Kit Skill bundle through npx without cloning the repository.",
   "bin": {
     "ai-product-kit": "bin/setup.js",

package/skills/aipk_design/GURU_AI.md

@@ -1,10 +1,12 @@
 # GURU AI Snapshot
 
-Last refreshed: 2025-11-13T13:59:26.059Z
+Last refreshed: 2025-11-17T08:04:42.861Z
 
 | File | Last Modified (UTC) |
 | --- | --- |
-| `SKILL.md` | 2025-11-13T13:11:54.681Z |
+| `format-requirement-pages-with-design/requirement-page-table-format.md` | 2025-11-17T06:21:56.025Z |
+| `format-requirement-pages-with-design/SKILL.md` | 2025-11-17T06:43:43.341Z |
+| `SKILL.md` | 2025-11-17T06:17:37.196Z |
 | `update-requirements-from-design/scripts/sharp-runtime/node_modules/.bin/semver` | 2025-11-13T12:53:04.813Z |
 | `update-requirements-from-design/scripts/sharp-runtime/node_modules/.package-lock.json` | 2025-11-13T12:53:10.727Z |
 | `update-requirements-from-design/scripts/sharp-runtime/node_modules/@img/colour/color.cjs` | 2025-11-13T12:53:05.063Z |
@@ -119,4 +121,4 @@ Last refreshed: 2025-11-13T13:59:26.059Z
 | `update-requirements-from-design/scripts/sharp-runtime/package.json` | 2025-11-13T12:53:10.715Z |
 | `update-requirements-from-design/scripts/split-design-boards.js` | 2025-11-13T13:11:29.610Z |
 | `update-requirements-from-design/scripts/sync-design-to-requirements.js` | 2025-11-13T13:11:32.947Z |
-| `update-requirements-from-design/SKILL.md` | 2025-11-13T13:59:11.730Z |
+| `update-requirements-from-design/SKILL.md` | 2025-11-17T06:12:02.571Z |

package/skills/aipk_design/SKILL.md

@@ -18,6 +18,11 @@ description: Central hub for automation-ready design-to-requirement workflows. W
   - 包含 `split-design-boards.js`（自动切分合成图）与 `sync-design-to-requirements.js`（资产映射与批量入库）等自动化工具。
   - **适用场景**：任务中提到"基于设计图更新需求"、"收到合成设计稿"、"根据视觉稿修改需求"时立即使用。
 
+- **Format Requirement Pages with Design**（`./format-requirement-pages-with-design/`）
+  - 将需求文档中的页面说明和设计图按照标准表格格式组织。遵循两列表格格式（页面说明 | 设计图），支持多图处理、页面标题外部放置等规范。
+  - 包含 `requirement-page-table-format.md`（详细的表格格式规范和示例）参考文档。
+  - **适用场景**：任务中提到"将设计图放入表格"、"格式化需求页面"、"整理页面说明和设计图"时立即使用。
+
 如需扩展新的设计场景，请在 `skills/aipk_design/` 下创建子目录，按照模板完成 `SKILL.md`、`references/` 等结构，并在本文件的"当前可用的设计 Skill"中登记用途与入口路径。
 
 ## 使用方式

package/skills/aipk_design/format-requirement-pages-with-design/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: format-requirement-pages-with-design
+description: Format requirement document pages with design images into standardized tables. Use when requirement documents contain design images and need to be organized into a two-column table format (page description | design image) following the project's table formatting standards.
+---
+
+# 需求页面表格格式化 Skill
+
+**适用场景**：当需求文档中包含设计图时，将页面说明和设计图按照标准表格格式组织。当你看到任务中提到"将设计图放入表格"、"格式化需求页面"、"整理页面说明和设计图"或类似描述时，立即使用本 Skill。
+
+## 1. 技能定位
+
+- **适用场景**：需求文档中包含设计图，需要将页面说明和设计图组织成标准表格格式
+- **目标人群**：需求文档维护者、AI 协作写手、设计对接 PM
+- **价值主张**：统一需求文档中页面说明和设计图的展示格式，提高文档可读性和一致性
+
+## 2. 快速上手
+
+### 2.1 核心规则
+
+1. **表格结构**：每个页面使用一个独立的 HTML 表格（`<table>`），包含两列（页面说明 | 设计图）
+2. **页面标题位置**：页面标题必须放在表格外部，作为表格的标题
+3. **多图处理**：如果一个页面有多张设计图，每张图必须单独占一行（`<tr>`），后续行页面说明列使用空的 `<td></td>`
+4. **换行格式**：表格单元格内使用 `<br>` 标签进行换行
+5. **图片引用**：使用 HTML `<img>` 标签，不使用 Markdown 图片语法
+
+### 2.2 基本格式示例
+
+```html
+##### 4.3.2.1 🆕 新增上传全身照页面
+
+<table>
+<tr>
+<th>页面说明</th>
+<th>设计图</th>
+</tr>
+<tr>
+<td><strong>UI设计</strong>：<br>- 顶部：引导页进度条...</td>
+<td><img src="./assets/1-上传全身照-1.png" alt=""></td>
+</tr>
+</table>
+```
+
+### 2.3 多图格式示例
+
+```html
+##### 4.3.2.1 🆕 新增上传全身照页面
+
+<table>
+<tr>
+<th>页面说明</th>
+<th>设计图</th>
+</tr>
+<tr>
+<td><strong>UI设计</strong>：<br>- 顶部：引导页进度条...<br><br><strong>界面文案</strong>：<br>- 主标题："Upload photo for feedback"</td>
+<td><img src="./assets/1-上传全身照-1.png" alt=""></td>
+</tr>
+<tr>
+<td></td>
+<td><img src="./assets/1-上传全身照备份-1.png" alt=""></td>
+</tr>
+</table>
+```
+
+## 3. 标准流程
+
+<table>
+<tr>
+<th>阶段</th>
+<th>说明</th>
+<th>交付物</th>
+</tr>
+<tr>
+<td>识别</td>
+<td>识别需求文档中包含设计图的页面</td>
+<td>待格式化页面列表</td>
+</tr>
+<tr>
+<td>提取</td>
+<td>提取每个页面的说明内容和设计图引用</td>
+<td>页面说明文本、设计图路径</td>
+</tr>
+<tr>
+<td>格式化</td>
+<td>按照表格格式规范组织内容</td>
+<td>格式化的表格代码</td>
+</tr>
+<tr>
+<td>验证</td>
+<td>检查表格格式是否符合规范</td>
+<td>验证通过的表格式需求文档</td>
+</tr>
+</table>
+
+## 4. 详细规范
+
+详细的格式规范、示例和注意事项请参考 [表格格式规范文档](./requirement-page-table-format.md)。该文档包含：
+
+- 完整的表格结构规范
+- 多张设计图的处理方式
+- 页面说明内容的格式要求
+- 设计图引用格式
+- 正确和错误的示例对比
+- 完整的检查清单
+
+## 5. AI 协作要点
+
+### 5.1 识别场景
+
+当遇到以下情况时，应使用本 Skill：
+
+- 需求文档中包含设计图引用
+- 需要将页面说明和设计图组织成表格
+- 需要统一需求文档的格式规范
+
+### 5.2 处理步骤
+
+1. **扫描文档**：识别所有包含设计图的页面
+2. **提取内容**：提取每个页面的说明文本和设计图路径
+3. **应用格式**：按照规范将内容组织成表格
+4. **验证检查**：使用检查清单验证格式正确性
+
+### 5.3 检查清单
+
+详细的检查清单请参考 [表格格式规范文档](./requirement-page-table-format.md) 中的"检查清单"章节。
+
+## 6. 附加资源
+
+- [表格格式规范参考](./requirement-page-table-format.md) - 详细的格式规范、示例和检查清单
+- [需求文档撰写标准](../../../docs/guide_writing_standard/SKILL.md) - 项目文档撰写标准

package/skills/aipk_design/format-requirement-pages-with-design/requirement-page-table-format.md

@@ -0,0 +1,250 @@
+# 需求文档页面表格格式规范
+
+## 概述
+
+本文档规范了在需求文档中如何将页面说明和设计图组织成 HTML 表格格式，以提高文档的可读性和渲染兼容性。
+
+## 基本格式
+
+### 表格结构
+
+每个页面使用一个独立的 HTML 表格，包含两列：
+
+```html
+<table>
+<tr>
+<th>页面说明</th>
+<th>设计图</th>
+</tr>
+<tr>
+<td>[页面说明内容]</td>
+<td>[设计图引用]</td>
+</tr>
+</table>
+```
+
+### 页面标题位置
+
+**页面标题必须放在表格外部**，作为表格的标题。
+
+**正确示例**：
+
+```html
+##### 4.3.2.1 🆕 新增上传全身照页面
+
+<table>
+<tr>
+<th>页面说明</th>
+<th>设计图</th>
+</tr>
+<tr>
+<td><strong>UI设计</strong>：<br>- 顶部：引导页进度条...</td>
+<td><img src="./assets/1-上传全身照-1.png" alt=""></td>
+</tr>
+</table>
+```
+
+**错误示例**：
+
+```html
+##### 4.3.2.1 🆕 新增上传全身照页面
+
+<table>
+<tr>
+<th>页面标题</th>
+<th>页面说明</th>
+<th>设计图</th>
+</tr>
+<tr>
+<td>新增上传全身照页面</td>
+<td><strong>UI设计</strong>：...</td>
+<td><img src="./assets/1-上传全身照-1.png" alt=""></td>
+</tr>
+</table>
+```
+
+## 多张设计图的处理
+
+### 规则
+
+如果一个页面有多张设计图，**每张图必须单独占一行**，避免将左侧页面说明列撑得太高。
+
+### 格式
+
+第一行包含完整的页面说明和第一张图，后续行页面说明列为空，只包含对应的设计图。
+
+**格式示例**：
+
+```html
+<table>
+<tr>
+<th>页面说明</th>
+<th>设计图</th>
+</tr>
+<tr>
+<td><strong>UI设计</strong>：<br>- 顶部：引导页进度条...<br><br><strong>界面文案</strong>：<br>- 主标题："Upload photo for feedback"<br>...</td>
+<td><img src="./assets/1-上传全身照-1.png" alt=""></td>
+</tr>
+<tr>
+<td></td>
+<td><img src="./assets/1-上传全身照备份-1.png" alt=""></td>
+</tr>
+</table>
+```
+
+### 多图页面示例
+
+**示例1：两张图**
+
+```html
+##### 4.3.2.1 🆕 新增上传全身照页面
+
+<table>
+<tr>
+<th>页面说明</th>
+<th>设计图</th>
+</tr>
+<tr>
+<td><strong>UI设计</strong>：<br>- 顶部：引导页进度条和返回按钮<br>- 中央：功能示意图展示...<br><br><strong>界面文案</strong>：<br>- 主标题："Upload photo for feedback"<br>...</td>
+<td><img src="./assets/1-上传全身照-1.png" alt=""></td>
+</tr>
+<tr>
+<td></td>
+<td><img src="./assets/1-上传全身照备份-1.png" alt=""></td>
+</tr>
+</table>
+```
+
+**示例2：四张图**
+
+```html
+##### 4.3.2.6 🆕 结果修改页面
+
+<table>
+<tr>
+<th>页面说明</th>
+<th>设计图</th>
+</tr>
+<tr>
+<td><strong>UI设计</strong>：<br>- 复用现有手动输入页面的UI组件<br>- 预填充AI识别结果<br><br><strong>界面文案</strong>：<br>- 主标题："Review and edit your information"<br>...</td>
+<td><img src="./assets/7-性别-1.png" alt=""></td>
+</tr>
+<tr>
+<td></td>
+<td><img src="./assets/8-年龄-1.png" alt=""></td>
+</tr>
+<tr>
+<td></td>
+<td><img src="./assets/9-身高-1.png" alt=""></td>
+</tr>
+<tr>
+<td></td>
+<td><img src="./assets/10-身高-1.png" alt=""></td>
+</tr>
+</table>
+```
+
+## 页面说明内容格式
+
+### 使用HTML换行标签
+
+在表格单元格中，使用 `<br>` 标签进行换行，而不是使用 Markdown 的换行。
+
+**正确示例**：
+
+```html
+<table>
+<tr>
+<th>页面说明</th>
+<th>设计图</th>
+</tr>
+<tr>
+<td><strong>UI设计</strong>：<br>- 顶部：引导页进度条<br>- 中央：功能示意图<br><br><strong>界面文案</strong>：<br>- 主标题："Upload photo for feedback"</td>
+<td><img src="./assets/1.png" alt=""></td>
+</tr>
+</table>
+```
+
+**错误示例**：
+
+```html
+<table>
+<tr>
+<th>页面说明</th>
+<th>设计图</th>
+</tr>
+<tr>
+<td><strong>UI设计</strong>：
+- 顶部：引导页进度条
+- 中央：功能示意图
+
+<strong>界面文案</strong>：
+- 主标题："Upload photo for feedback"</td>
+<td><img src="./assets/1.png" alt=""></td>
+</tr>
+</table>
+```
+
+### 列表格式
+
+在表格单元格中，列表项使用 `-` 开头，并用 `<br>` 分隔。
+
+**示例**：
+
+```html
+<table>
+<tr>
+<th>页面说明</th>
+<th>设计图</th>
+</tr>
+<tr>
+<td><strong>界面文案</strong>：<br>- 主标题："Upload photo for feedback"<br>- 被扫描后的功能示意图文案：<br>  - 性别："Female"<br>  - 年龄："20"</td>
+<td><img src="./assets/1.png" alt=""></td>
+</tr>
+</table>
+```
+
+## 设计图引用格式
+
+### 基本格式
+
+使用 HTML `<img>` 标签：
+
+```html
+<img src="./assets/image-name.png" alt="">
+```
+
+### 带描述文本的格式
+
+如果需要描述文本，使用 `alt` 属性：
+
+```html
+<img src="./assets/image-name.png" alt="描述文本">
+```
+
+**示例**：
+
+```html
+<img src="./assets/12-传统方式上传-性别.png" alt="传统方式上传-性别">
+```
+
+## 注意事项
+
+1. **表格格式**：使用 HTML `<table>` 标签，不使用 Markdown 表格语法
+2. **页面标题位置**：页面标题（如 `##### 4.3.2.1`）必须放在表格外部
+3. **多图处理**：多张图时，每张图单独一行（`<tr>`），后续行页面说明列使用空的 `<td></td>`
+4. **换行格式**：表格单元格内使用 `<br>` 标签换行
+5. **图片引用**：使用 HTML `<img>` 标签，`src` 属性使用相对路径，`alt` 属性可添加描述文本
+6. **表格对齐**：保持表格格式整洁，列宽适中
+
+## 检查清单
+
+在创建或修改页面表格时，请检查：
+
+- [ ] 使用 HTML `<table>` 标签，不使用 Markdown 表格语法
+- [ ] 页面标题在表格外部
+- [ ] 表格只有两列（`<th>页面说明</th>` 和 `<th>设计图</th>`）
+- [ ] 多张图时，每张图单独一行（`<tr>`），后续行页面说明列为空 `<td></td>`
+- [ ] 表格单元格内使用 `<br>` 进行换行
+- [ ] 图片使用 `<img>` 标签，`src` 路径正确且可访问
+- [ ] 表格格式整洁，列宽适中