feat: sync full workspace including web modules, docs, and configurations to Gitea
Optimized the root .gitignore to exclude virtual environments, node modules, and temp folders to ensure clean and lightweight version tracking. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
王冕
288
axhub-make/skills/ai-studio-project-converter/SKILL.md
Normal file
288
axhub-make/skills/ai-studio-project-converter/SKILL.md
Normal file
@@ -0,0 +1,288 @@
|
||||
---
|
||||
name: ai-studio-project-converter
|
||||
description: 将 Google AI Studio 生成的 React 项目转换为本项目页面组件的流程规范；在处理 Import Map、样式迁移、依赖安装、环境变量与验收时使用。
|
||||
---
|
||||
|
||||
# AI Studio 项目转换规范
|
||||
|
||||
将 Google AI Studio 生成的零配置 React 应用转换为本项目页面组件，保持视觉效果和功能，符合本项目开发规范。
|
||||
|
||||
## 核心目标
|
||||
|
||||
- 保持页面视觉一致性
|
||||
- 移除 AI Studio 特定入口与 HTML 模板
|
||||
- 产出可在本项目中运行的页面组件
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 步骤 1：运行预处理脚本
|
||||
|
||||
```bash
|
||||
node scripts/ai-studio-converter.mjs <ai-studio-project-dir> [output-name]
|
||||
|
||||
# 示例
|
||||
node scripts/ai-studio-converter.mjs "temp/my-ai-studio-project" my-page
|
||||
```
|
||||
|
||||
**脚本会自动完成**：
|
||||
- 完整复制 AI Studio 项目到 `src/prototypes/[页面名]/`
|
||||
- 分析项目结构（Import Map、自定义样式、依赖等）
|
||||
- 生成 AI 工作文档（`.ai-studio-tasks.md`）
|
||||
- 生成详细数据（`.ai-studio-analysis.json`）
|
||||
- **不修改任何代码**（100% 安全）
|
||||
|
||||
### 步骤 2：按任务清单完成转换
|
||||
|
||||
脚本会生成 `.ai-studio-tasks.md` 文件，包含：
|
||||
- 项目概况统计
|
||||
- 5 个具体任务清单
|
||||
- Import Map 依赖映射
|
||||
- 环境变量配置提示
|
||||
- 验收测试步骤
|
||||
|
||||
按任务清单与本规范示例执行转换。
|
||||
|
||||
## 转换要点
|
||||
|
||||
### AI Studio 项目特征
|
||||
|
||||
**典型目录结构**：
|
||||
```
|
||||
ai-studio-project/
|
||||
├── assets/ # 静态资源（可选）
|
||||
├── components/ # UI 组件
|
||||
├── App.tsx # 主应用组件
|
||||
├── index.tsx # React 挂载入口
|
||||
├── index.html # HTML 模板（Import Map + Tailwind CDN）
|
||||
├── constants.ts # 常量定义（可选）
|
||||
├── types.ts # 类型定义（可选）
|
||||
├── vite.config.ts # Vite 配置（可选）
|
||||
└── metadata.json # 项目元数据（可选）
|
||||
```
|
||||
|
||||
**技术栈**：
|
||||
- **框架**：React 19（Function Components + Hooks）
|
||||
- **语言**：TypeScript
|
||||
- **模块**：Native ESM（Import Map，通常是 esm.sh CDN）
|
||||
- **样式**：Tailwind CSS（CDN Runtime Mode）
|
||||
- **图标**：Lucide React
|
||||
- **配置**：Vite（如果有 vite.config.ts）
|
||||
|
||||
### 关键文件特征
|
||||
|
||||
**index.html**：
|
||||
```html
|
||||
<script src="https://cdn.tailwindcss.com"></script>
|
||||
<script type="importmap">
|
||||
{
|
||||
"imports": {
|
||||
"react": "https://esm.sh/react@19",
|
||||
"lucide-react": "https://esm.sh/lucide-react"
|
||||
}
|
||||
}
|
||||
</script>
|
||||
<style>/* 可能包含自定义样式 */</style>
|
||||
<link href="https://fonts.googleapis.com/..."> <!-- 可能包含外部字体 -->
|
||||
```
|
||||
|
||||
### 本项目页面组件规范
|
||||
|
||||
默认先转换为普通 React 页面组件。只有在需求明确要求接入 Axhub / Axure 运行时能力时，才引入 `forwardRef<AxureHandle, AxureProps>`、`useImperativeHandle` 和 `axure-types`。
|
||||
|
||||
**默认格式（推荐）**：
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* @name 页面名称
|
||||
*
|
||||
* 参考资料：
|
||||
* - /rules/development-guide.md
|
||||
* - /skills/default-resource-recommendations/SKILL.md
|
||||
*/
|
||||
|
||||
import './style.css';
|
||||
import React from 'react';
|
||||
|
||||
export default function PageName() {
|
||||
// 组件逻辑
|
||||
|
||||
return (
|
||||
// JSX 内容
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
**仅在以下场景才接入 Axure API**：
|
||||
- 页面需要被 Axhub / Axure 接管
|
||||
- 需要配置面板、外部数据源、事件回调或动作触发
|
||||
- 用户明确要求保持与现有 Axure 组件一致的接口形式
|
||||
|
||||
此时再参考 `/rules/axure-api-guide.md`，使用如下包装形式：
|
||||
|
||||
```typescript
|
||||
import React, { forwardRef, useImperativeHandle } from 'react';
|
||||
import type { AxureProps, AxureHandle } from '../../common/axure-types';
|
||||
|
||||
const Component = forwardRef<AxureHandle, AxureProps>(function PageName(innerProps, ref) {
|
||||
useImperativeHandle(ref, function () {
|
||||
return {
|
||||
getVar: function () { return undefined; },
|
||||
fireAction: function () {},
|
||||
eventList: [],
|
||||
actionList: [],
|
||||
varList: [],
|
||||
configList: [],
|
||||
dataList: []
|
||||
};
|
||||
}, []);
|
||||
|
||||
return (
|
||||
// JSX 内容
|
||||
);
|
||||
});
|
||||
|
||||
export default Component;
|
||||
```
|
||||
|
||||
### 转换主应用组件
|
||||
|
||||
**AI Studio 原始代码**：
|
||||
```typescript
|
||||
// App.tsx
|
||||
import { useState } from 'react';
|
||||
import Header from './components/Header';
|
||||
|
||||
export default function App() {
|
||||
const [count, setCount] = useState(0);
|
||||
return <div><Header /></div>;
|
||||
}
|
||||
```
|
||||
|
||||
**转换为本项目默认规范**：
|
||||
```typescript
|
||||
/**
|
||||
* @name 页面名称
|
||||
*
|
||||
* 参考资料：
|
||||
* - /rules/development-guide.md
|
||||
* - /skills/default-resource-recommendations/SKILL.md
|
||||
*/
|
||||
|
||||
import './style.css';
|
||||
import React, { useState } from 'react';
|
||||
import Header from './components/Header';
|
||||
|
||||
export default function PageName() {
|
||||
const [count, setCount] = useState(0);
|
||||
|
||||
return <div><Header /></div>;
|
||||
}
|
||||
```
|
||||
|
||||
**关键转换点**：
|
||||
1. 添加文件头部注释（`@name` 和参考资料）
|
||||
2. 默认保持普通 React 组件写法，优先最小改造
|
||||
3. 仅在明确需要 Axhub / Axure 接管时，才增加 `forwardRef<AxureHandle, AxureProps>` 与 `useImperativeHandle`
|
||||
4. 保持原有的 JSX、Hooks 和 Tailwind 类名不变
|
||||
5. 若补接 Axure API，需同步参考 `/rules/axure-api-guide.md`
|
||||
|
||||
### 处理样式
|
||||
|
||||
从 `index.html` 提取样式信息，创建 `style.css`：
|
||||
|
||||
```css
|
||||
@import "tailwindcss";
|
||||
|
||||
/* 提取 <style> 标签中的自定义样式 */
|
||||
/* 例如：自定义动画、字体、选择器样式等 */
|
||||
|
||||
/* 如果有外部字体，添加 @import */
|
||||
@import url('https://fonts.googleapis.com/css2?family=...');
|
||||
```
|
||||
|
||||
### 依赖管理
|
||||
|
||||
从 `index.html` 的 Import Map 提取依赖：
|
||||
|
||||
```bash
|
||||
# 常见依赖：lucide-react, framer-motion 等
|
||||
# 排除：react, react-dom（本项目已有）
|
||||
pnpm add [识别到的依赖列表]
|
||||
```
|
||||
|
||||
**CDN 到 npm 包映射**：
|
||||
- `https://esm.sh/lucide-react` → `lucide-react`
|
||||
- `https://esm.sh/framer-motion` → `framer-motion`
|
||||
- `https://esm.sh/@google/genai` → `@google/generative-ai`
|
||||
|
||||
### 环境变量处理
|
||||
|
||||
将 `process.env.*` 转换为 `import.meta.env.VITE_*`：
|
||||
- 检查 `vite.config.ts` 中的 `define` 配置
|
||||
- 告知用户需要配置的环境变量
|
||||
- 提供 `.env.local` 示例
|
||||
|
||||
### 移除 AI Studio 特定文件
|
||||
|
||||
**必须移除**：
|
||||
- `index.html`（提取信息后删除）
|
||||
- `index.tsx`（本项目有自己的入口）
|
||||
- `metadata.json`（可选保留作为参考）
|
||||
|
||||
## 验收标准
|
||||
|
||||
转换完成后运行验收脚本：
|
||||
|
||||
```bash
|
||||
node scripts/check-app-ready.mjs /prototypes/[页面名]
|
||||
```
|
||||
|
||||
**验收要求**：
|
||||
- 状态为 READY
|
||||
- 页面能正常渲染
|
||||
- 无控制台错误
|
||||
- 交互功能正常
|
||||
- 样式显示正确
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 依赖缺失
|
||||
```bash
|
||||
# 根据报告中的依赖列表安装
|
||||
pnpm add [依赖名称]
|
||||
```
|
||||
|
||||
### Import Map 转换
|
||||
- 检查 `.ai-studio-analysis.json` 中的 CDN 依赖映射
|
||||
- 确保所有 CDN 依赖已转换为 npm 包
|
||||
|
||||
### 样式问题
|
||||
- 确认 `style.css` 包含 `@import "tailwindcss"`
|
||||
- 检查 index.html 的 `<style>` 标签是否已提取
|
||||
|
||||
### 环境变量
|
||||
- 将 `process.env.*` 改为 `import.meta.env.VITE_*`
|
||||
- 配置 `.env.local` 文件
|
||||
|
||||
## 参考资源
|
||||
|
||||
- **开发规范**：`/rules/development-guide.md`
|
||||
- **调试指南**：`/rules/debugging-guide.md`
|
||||
- **Tailwind CSS**：`/skills/default-resource-recommendations/SKILL.md`
|
||||
|
||||
## 详细转换流程（供参考）
|
||||
|
||||
### 步骤 1：分析项目结构
|
||||
|
||||
脚本会自动扫描识别：
|
||||
- 主应用：`App.tsx`
|
||||
- 入口文件：`index.tsx`（需移除）
|
||||
- HTML 模板：`index.html`（提取依赖和样式信息）
|
||||
- 组件文件：`components/**/*.tsx`
|
||||
- 配置文件：`vite.config.ts`（提取路径别名）
|
||||
- 常量/类型：`constants.ts`, `types.ts`（如果存在）
|
||||
- 静态资源：`assets/**`
|
||||
|
||||
### 步骤 2：调试验收
|
||||
|
||||
运行验收脚本，根据结果修复问题。
|
||||
76
axhub-make/skills/axure-export-workflow/SKILL.md
Normal file
76
axhub-make/skills/axure-export-workflow/SKILL.md
Normal file
@@ -0,0 +1,76 @@
|
||||
---
|
||||
name: axure-export-workflow
|
||||
description: 在“导出到 Axure”前的代码检查失败场景下，按固定流程修复规范问题并完成 Axure 模式注释标识；当用户要求修复导出检测错误、补齐 @mode axure、补充 Skill 参考路径时使用。
|
||||
---
|
||||
|
||||
# Axure 导出修复工作流
|
||||
|
||||
本 Skill 只处理 **导出 Axure 场景** 的代码修复与合规改造，不处理第三方导出（如 Figma）。
|
||||
|
||||
## 适用场景
|
||||
|
||||
- 用户在“导出到 Axure”前触发 code-review 失败
|
||||
- 需要让代码快速通过当前规范检查
|
||||
- 需要补齐 Axure 模式头注释标识
|
||||
|
||||
## 目标
|
||||
|
||||
1. 优先修复 `error` 问题，再处理 `warning`
|
||||
2. 在不改变业务功能的前提下完成改造
|
||||
3. 让目标文件可通过现有检测链路
|
||||
|
||||
## 固定执行流程（低自由度）
|
||||
|
||||
### 步骤 1：锁定修改范围
|
||||
|
||||
- 只修改报错目标文件（通常是 `src/components/<name>/index.tsx` 或 `src/prototypes/<name>/index.tsx`）
|
||||
- 不主动重构无关代码
|
||||
- 不修改第三方导出相关代码
|
||||
|
||||
### 步骤 2：按优先级修复检查项
|
||||
|
||||
- 先修复所有 `error`（必须通过）
|
||||
- 再处理 `warning`（建议修复）
|
||||
- 每项修复都要保持原有功能与交互行为一致
|
||||
|
||||
### 步骤 3：补齐头部注释（Axure 模式）
|
||||
|
||||
若文件用于 Axure 导出改造，头部注释必须包含：
|
||||
|
||||
- `@name`
|
||||
- `@mode axure`
|
||||
- 参考资料中的 Skill 路径：`/skills/axure-export-workflow/SKILL.md`
|
||||
- 默认导出名必须是 `Component`（使用 `export default Component`）
|
||||
|
||||
可使用以下模板：
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* @name 组件或页面名称
|
||||
* @mode axure
|
||||
*
|
||||
* 参考资料：
|
||||
* - /rules/development-guide.md
|
||||
* - /skills/axure-export-workflow/SKILL.md
|
||||
* - /rules/axure-api-guide.md (如需集成 Axure API)
|
||||
*/
|
||||
```
|
||||
|
||||
### 步骤 4：Axure API 处理策略
|
||||
|
||||
- Axure API 是 **可选项**
|
||||
- 不要为了“通过导出检测”强行引入 `forwardRef<AxureHandle, AxureProps>`
|
||||
- 仅在需求明确要求 Axure 交互能力时，才按 `axure-api-guide.md` 集成
|
||||
|
||||
### 步骤 5：交付前自检
|
||||
|
||||
- 已修复全部 error
|
||||
- warning 已评估并尽量修复
|
||||
- 头注释已包含 `@mode axure` 与 Skill 路径
|
||||
- 文件能通过当前导出前检查逻辑
|
||||
|
||||
## 非目标（不要做）
|
||||
|
||||
- 不扩展到 Figma 或其他第三方导出链路
|
||||
- 不改构建插件和检查规则策略
|
||||
- 不进行大规模样式重写或架构重构
|
||||
34
axhub-make/skills/axure-prototype-workflow/SKILL.md
Normal file
34
axhub-make/skills/axure-prototype-workflow/SKILL.md
Normal file
@@ -0,0 +1,34 @@
|
||||
---
|
||||
name: axure-prototype-workflow
|
||||
description: 使用本项目MCP 提取 Axure 原型资产、生成主题/数据/文档、还原页面与生成业务文档的流程规范；当用户提供 Axure 原型链接或提出资产提取、原型还原、主题/数据模型/文档生成、交互引导需求时使用。
|
||||
---
|
||||
|
||||
# Axure 原型处理助手规范
|
||||
|
||||
本技能采用渐进披露：先判断用户需求，再只打开相关文档。
|
||||
|
||||
## 快速分流
|
||||
|
||||
- 资产提取总流程（编排入口）：`skills/axure-prototype-workflow/asset-extraction.md`
|
||||
- 主题生成规则：`skills/axure-prototype-workflow/theme-generation.md`
|
||||
- 文档生成规则：`skills/axure-prototype-workflow/doc-generation.md`
|
||||
- 数据生成规则：`skills/axure-prototype-workflow/data-generation.md`
|
||||
- 原型还原/优化/视觉复刻：`skills/axure-prototype-workflow/prototype-restoration.md`
|
||||
|
||||
## 通用前置（任何场景都需要）
|
||||
|
||||
1. 检测 MCP 安装状态：尝试调用任意 MCP 工具（如 `get_axure_sitemap`），失败则提示用户安装本项目MCP。
|
||||
2. 检测原型索引状态（可选）：使用 `search_axure` 测试原型是否已索引。
|
||||
3. 获取原型链接：如用户未提供原型链接，提示用户提供 Axure 原型 URL。
|
||||
4. 需要页面范围判断或选择核心页面时，先获取站点地图（`get_axure_sitemap`）。
|
||||
|
||||
## 通用约束
|
||||
|
||||
- 优先使用本项目MCP；失败再尝试当前环境内可用的其他工具。
|
||||
- 资源获取禁止批量/并发请求，必须等一个完成后再获取下一个。
|
||||
- 未经用户明确确认，不主动扩展需求或抓取可选数据。
|
||||
|
||||
## 参考资源
|
||||
|
||||
- `theme-guide.md`
|
||||
- `development-guide.md`
|
||||
@@ -0,0 +1,81 @@
|
||||
# Axure 资产提取总流程（编排）
|
||||
|
||||
本文件只负责流程编排、默认策略和用户交互节奏。
|
||||
具体生成规则请分别读取子文档：
|
||||
|
||||
- 主题生成：`skills/axure-prototype-workflow/theme-generation.md`
|
||||
- 文档生成：`skills/axure-prototype-workflow/doc-generation.md`
|
||||
- 数据生成：`skills/axure-prototype-workflow/data-generation.md`
|
||||
|
||||
## 输出目录约束
|
||||
|
||||
- 主题：`src/themes/<theme-key>/`
|
||||
- 文档：`src/docs/`
|
||||
- 数据：`src/database/`
|
||||
|
||||
## 标准执行顺序
|
||||
|
||||
1. 获取站点地图：调用 `get_axure_sitemap`，确定页面范围、核心页面和优先级。
|
||||
2. 与用户确认范围：默认执行“主题 + 文档 + 数据”；若用户只要部分产物，按用户范围裁剪。
|
||||
3. 主题生成：读取 `theme-generation.md`，先完成主题资产。
|
||||
4. 文档生成：读取 `doc-generation.md`，产出页面地图/项目概览/业务文档（按需）。
|
||||
5. 数据生成：读取 `data-generation.md`，生成/更新数据模型。
|
||||
6. 交付总结：列出文件路径、已完成项、未完成项和后续可选动作。
|
||||
|
||||
## 默认方案（用户未明确需求）
|
||||
|
||||
1. 提取主题并生成 `DESIGN.md`
|
||||
2. 生成页面地图与项目概览文档
|
||||
3. 识别并输出数据模型
|
||||
|
||||
## 用户交互话术
|
||||
|
||||
### 初始确认
|
||||
|
||||
```
|
||||
您好，我可以帮您从 Axure 原型提取主题、文档和数据。
|
||||
|
||||
我会按以下顺序执行：
|
||||
1) 主题提取与规范文档
|
||||
2) 项目文档生成
|
||||
3) 数据模型生成
|
||||
|
||||
请提供 Axure 原型链接，或告诉我只需要其中某一部分。
|
||||
```
|
||||
|
||||
### 需求确认
|
||||
|
||||
```
|
||||
已获取站点地图，共 [X] 个页面。
|
||||
|
||||
默认将执行：主题 + 文档 + 数据。
|
||||
如果你只需要其中一部分，请直接告诉我（例如“只做主题”）。
|
||||
```
|
||||
|
||||
### 进度通知
|
||||
|
||||
```
|
||||
正在处理...
|
||||
✓ 已完成站点地图分析
|
||||
✓ 已完成主题生成
|
||||
⏳ 正在生成文档与数据模型...
|
||||
```
|
||||
|
||||
### 完成总结
|
||||
|
||||
```
|
||||
✅ 已完成资产提取。
|
||||
|
||||
产物路径：
|
||||
- 主题：src/themes/<theme-key>/
|
||||
- 文档：src/docs/
|
||||
- 数据：src/database/
|
||||
|
||||
如需继续，我可以按指定页面执行原型还原。
|
||||
```
|
||||
|
||||
## 执行原则
|
||||
|
||||
- 先确认范围，再写文件。
|
||||
- 任何跨页面合并（主题/数据）都要做冲突消解并说明取舍。
|
||||
- 若信息不足，先声明不确定项，再让用户选择补充或采用默认值。
|
||||
@@ -0,0 +1,47 @@
|
||||
# Axure 数据生成规则
|
||||
|
||||
用于从 Axure 页面内容识别数据结构并生成 JSON 数据表。
|
||||
不负责主题和文档正文生成。
|
||||
|
||||
## 识别步骤
|
||||
|
||||
1. 识别数据密集页面（列表/详情/表单/报表）。
|
||||
2. 用 `get_axure_text` 提取文本结构与字段线索。
|
||||
3. 跨页面合并同类实体并去重字段。
|
||||
4. 确定字段类型与取值样式，生成示例记录。
|
||||
|
||||
## 输出规范（强约束）
|
||||
|
||||
输出目录：`src/database/`
|
||||
|
||||
文件约束：
|
||||
- 文件名英文，如 `orders.json`
|
||||
- `tableName` 中文，如 `"订单表"`
|
||||
- 每个文件必须是对象，结构如下：
|
||||
|
||||
```json
|
||||
{
|
||||
"tableName": "表名（中文）",
|
||||
"records": [
|
||||
{ "id": 1, "字段1": "值1" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## 字段归一规则
|
||||
|
||||
1. 字段名优先中文，且与界面文案一致。
|
||||
2. 同义字段统一命名（例如“手机号/手机号码”二选一）。
|
||||
3. 同字段跨记录类型必须一致。
|
||||
4. `id` 唯一；同表内类型保持一致（全部 number 或全部 string）。
|
||||
|
||||
## 记录数量建议
|
||||
|
||||
- 每表 10-30 条记录。
|
||||
- 既要覆盖常规值，也要包含边界值（如空状态、极端长度、异常状态）。
|
||||
|
||||
## 质量检查
|
||||
|
||||
- JSON 可解析且结构完整（包含 `tableName` + `records`）
|
||||
- 字段是否与页面真实语义一致
|
||||
- 记录是否满足唯一性与类型一致性
|
||||
44
axhub-make/skills/axure-prototype-workflow/doc-generation.md
Normal file
44
axhub-make/skills/axure-prototype-workflow/doc-generation.md
Normal file
@@ -0,0 +1,44 @@
|
||||
# Axure 文档生成规则
|
||||
|
||||
用于生成项目文档与业务文档。
|
||||
不负责主题 token 提取与数据建模细节。
|
||||
|
||||
## 文档类型
|
||||
|
||||
默认产物：
|
||||
- `src/docs/page-map.md`
|
||||
- `src/docs/project-overview.md`
|
||||
|
||||
用户明确要求时可追加：
|
||||
- Domain Model（领域模型）
|
||||
- Business Relationship Model（业务关系模型）
|
||||
- Business Flow / Process（业务流程）
|
||||
- State Machine / Lifecycle（状态生命周期）
|
||||
- Permission / Access Model（权限模型）
|
||||
|
||||
## 页面地图文档规范
|
||||
|
||||
1. 按 sitemap 层级输出。
|
||||
2. 页面名称必须可点击并指向原型 URL（若可用）。
|
||||
3. 每个页面附一句用途说明（不超过 30 字）。
|
||||
|
||||
## 项目概览文档规范
|
||||
|
||||
至少包含：
|
||||
- 项目名称与范围
|
||||
- 页面数量与模块拆分
|
||||
- 核心用户流程
|
||||
- 主题风格摘要（引用主题产物）
|
||||
- 数据模型摘要（引用数据表）
|
||||
|
||||
## 业务文档规范
|
||||
|
||||
1. 先声明建模边界（系统内/系统外）。
|
||||
2. 再给出模型图或结构化清单。
|
||||
3. 对不确定项显式标记“待确认”。
|
||||
|
||||
## 质量检查
|
||||
|
||||
- 文档路径必须在 `src/docs/`
|
||||
- 文件命名使用 kebab-case
|
||||
- 内容与页面资产一致，不得凭空扩写关键业务规则
|
||||
@@ -0,0 +1,108 @@
|
||||
# Axure 页面还原
|
||||
|
||||
用于基于 Axure 原型截图的页面视觉还原。
|
||||
|
||||
**核心方法**：看图 → 写代码 → 交付。
|
||||
|
||||
## 默认目标
|
||||
|
||||
- **1:1 像素级还原**：完全还原截图的视觉与布局
|
||||
- **独立实现**：不参考本项目已有主题和生成流程，本指南是一个独立的页面还原流程，不需要读取和遵循 `rules/development-guide.md` 以外的项目文档
|
||||
|
||||
## 核心流程
|
||||
|
||||
1. **确认前置条件**
|
||||
- 确认模型支持视觉识别（不支持则立即告知用户）
|
||||
- 确认可以直接读取图片内容（不需要转换，不支持则立即告知用户）
|
||||
- 生成页面名称（规范：小写字母、数字、连字符）
|
||||
|
||||
2. **获取截图**
|
||||
- 先确认当前模型支持视觉识别；不支持时立即告知用户，并询问是否改为仅基于文本+主题还原。
|
||||
- 使用 `get_axure_screenshot` 下载截图到本项目：
|
||||
- `downloadDirectory`：指向 `temp/axure-screenshots/` 的绝对路径（不存在时先创建）
|
||||
- `projectUrl`：**必须先调用 `get-axure-sitemap` 获取项目地图，使用返回的 `projectUrl`**
|
||||
- `pageUrl`：页面路径（如 `首页.html`）
|
||||
- `filename`：可选，指定保存的文件名
|
||||
- 若下载失败，尝试前环境内可用的其他截图工具；若仍失败，必须告知用户并让其决定是否继续。
|
||||
|
||||
3. **验证图片读取能力**
|
||||
- 尝试读取已下载的截图文件
|
||||
- **如果无法直接读取本地图片**（工具不支持或返回错误），必须：
|
||||
- 立即停止流程
|
||||
- 告知用户："无法读取本地图片，请将 `[图片绝对路径]` 复制到对话框后提交"
|
||||
- 等待用户提交图片后再继续
|
||||
- 禁止假设或猜测图片内容
|
||||
- 禁止通过 Base64 编码读取图片内容
|
||||
|
||||
4. **生成页面代码**
|
||||
|
||||
**辅助数据获取**（可选，生成仍以图片为主）：
|
||||
- 主题：`get_page_theme`（校验样式）
|
||||
- 仅用于交叉校验，和截图识别结果不一致时，以截图为准
|
||||
- 多页面合并：优先 3-5 个核心页面，按页面权重合并统计
|
||||
- 噪声过滤：排除图片/图标/装饰性元素，弱化低频与异常值
|
||||
- 量化归一：颜色按相近色合并，间距/圆角按常见网格值聚类
|
||||
- 置信度阈值：低于阈值的 token 不进入最终主题
|
||||
- 文本：`get_axure_text`（校验文案）
|
||||
- 交互：`get_axure_interactions`（补充交互）
|
||||
**约束**：资源获取禁止批量/并发，必须等一个完成后再获取下一个
|
||||
|
||||
- 直接基于截图生成页面代码
|
||||
- 在代码生成过程中内部完成：
|
||||
- 识别布局结构（Header/Sidebar/Content 等）
|
||||
- 识别组件（Button/Input/Table/Card 等）
|
||||
- 提取样式（颜色、字体、间距、圆角、阴影等）
|
||||
- 识别交互（点击、悬停、状态切换等）
|
||||
|
||||
**输出文件**：
|
||||
- `src/prototypes/<page-name>/index.tsx`
|
||||
- `src/prototypes/<page-name>/style.css`（必须包含 `@import "tailwindcss";`）
|
||||
- `src/prototypes/<page-name>/components/`（根据需要）
|
||||
|
||||
**核心代码规范**（必须遵守）：
|
||||
```typescript
|
||||
// index.tsx 结构
|
||||
/**
|
||||
* @name 页面显示名称
|
||||
*/
|
||||
import './style.css';
|
||||
import React from 'react';
|
||||
|
||||
const Component = function PageName() {
|
||||
return <div>...</div>;
|
||||
};
|
||||
|
||||
export default Component;
|
||||
```
|
||||
```css
|
||||
/* style.css 必须以此开头 */
|
||||
@import "tailwindcss";
|
||||
```
|
||||
- 变量名必须是 `Component`，使用 `export default Component`
|
||||
- 详细规范见 `rules/development-guide.md`
|
||||
|
||||
5. **验收页面还原**
|
||||
- 运行验收命令：`node scripts/check-app-ready.mjs /prototypes/[页面名]`
|
||||
- 提供预览 URL
|
||||
- 确认页面基础功能正常（无编译错误、可正常访问）
|
||||
|
||||
6. **生成规格文档**
|
||||
- 基于已验收通过的页面代码生成规格文档
|
||||
- 输出文件：`src/prototypes/<page-name>/spec.md`
|
||||
- 文档内容应包括：
|
||||
- 页面结构说明
|
||||
- 组件清单
|
||||
- 样式规范（颜色、字体、间距等）
|
||||
- 交互说明
|
||||
- 数据需求（如有）
|
||||
|
||||
7. **最终交付**
|
||||
- 告知用户页面还原和规格文档已完成
|
||||
- 说明可进行二次生成（修复问题或优化重构）
|
||||
|
||||
## 代码规范
|
||||
- 优先使用 Tailwind CSS V4 还原
|
||||
- 遵循 `rules/development-guide.md`
|
||||
- 样式独立实现，不依赖系统主题
|
||||
|
||||
---
|
||||
@@ -0,0 +1,50 @@
|
||||
# Axure 主题生成规则
|
||||
|
||||
用于从 Axure 原型提取并生成主题资产。
|
||||
只处理主题相关内容，不处理文档与数据建模细节。
|
||||
|
||||
## 输入与范围
|
||||
|
||||
1. 先从 `get_axure_sitemap` 确定页面集合。
|
||||
2. 选择 3-5 个视觉代表性页面（首页、登录页、主功能页）。
|
||||
3. 对每个页面收集截图与主题信息（`get_page_theme`）。
|
||||
|
||||
## 主题合并策略
|
||||
|
||||
1. 色彩：按出现频率合并，保留主色、辅色、语义色（成功/警告/错误）。
|
||||
2. 字体：统一主字体与层级（字号、字重、行高）。
|
||||
3. 间距：提炼常用 spacing scale，避免离散值过多。
|
||||
4. 形态：统一圆角、描边、阴影等级。
|
||||
|
||||
若多页面存在冲突：
|
||||
- 以核心业务页面优先；
|
||||
- 记录冲突与取舍到 `DESIGN.md`。
|
||||
|
||||
## 输出文件（强约束）
|
||||
|
||||
输出目录：`src/themes/<theme-key>/`
|
||||
|
||||
必需：
|
||||
- `globals.css` 或 `designToken.json`（二选一）
|
||||
- `DESIGN.md`
|
||||
- `index.tsx`
|
||||
|
||||
额外约束：
|
||||
- 若输出 `designToken.json`，必须包含 `name` 字段。
|
||||
- `index.tsx` 必须可演示主题关键 token（颜色、字体、圆角、间距、阴影）。
|
||||
|
||||
## DESIGN.md 最低结构
|
||||
|
||||
1. 视觉关键词与品牌气质
|
||||
2. 色彩系统（主色/辅色/语义色）
|
||||
3. 排版系统（字体族与层级）
|
||||
4. 组件风格（按钮/输入/卡片/表格等）
|
||||
5. 状态与交互反馈
|
||||
6. 适配策略（桌面/移动）
|
||||
|
||||
## 质量检查
|
||||
|
||||
- 文件路径是否落在 `src/themes/<theme-key>/`
|
||||
- token 命名是否一致且可读
|
||||
- `DESIGN.md` 是否可指导后续实现
|
||||
- `index.tsx` 是否与 token 同步
|
||||
56
axhub-make/skills/create-workflow/SKILL.md
Normal file
56
axhub-make/skills/create-workflow/SKILL.md
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
name: create-workflow
|
||||
description: Axhub Make 创建内容入口；当用户要创建原型/组件、文档、主题或数据表时，根据提示词分流到对应引用文档，并按需渐进式加载。
|
||||
---
|
||||
|
||||
# Axhub Make 创建内容工作流
|
||||
|
||||
你正在协助用户在 Axhub Make 中创建新资源。请先阅读 `/AGENTS.md` 获取项目结构、命名规范与基础约束。
|
||||
|
||||
## 核心原则
|
||||
|
||||
- 先识别创建目标，再只加载一个最相关的引用文档。
|
||||
- 不要一次性读取全部引用文档。
|
||||
- 如果用户在一个请求里同时提到多个资源，先判断主产物，再按需补充读取其他引用文档。
|
||||
- 当主任务已经确定时，其他资源默认作为参考输入，而不是切换工作流。
|
||||
- 只有当用户明确改变目标，或当前任务确实需要额外创建另一类资源时，才加载第二个引用文档。
|
||||
|
||||
## 意图分流
|
||||
|
||||
| 用户意图 / 关键词 | 加载文档 | 典型产物 |
|
||||
| --- | --- | --- |
|
||||
| 原型、页面、组件、做个页面、做个组件 | `./references/create-prototype.md` | `src/prototypes/...` 或 `src/components/...` |
|
||||
| 文档、PRD、说明文档、需求文档、手册 | `./references/create-document.md` | `src/docs/...` |
|
||||
| 主题、设计系统、配色、design token、DESIGN.md | `./references/create-theme.md` | `src/themes/...` |
|
||||
| 数据、数据表、JSON、mock 数据、示例数据 | `./references/create-data.md` | `src/database/...` |
|
||||
|
||||
## 分流优先级
|
||||
|
||||
1. 用户明确点名输出目录或文件类型时，按目标产物分流：
|
||||
- 提到 `spec.md`、`index.tsx`、页面、组件 -> 原型 / 组件
|
||||
- 提到 `DESIGN.md`、`designToken.json`、`globals.css` -> 主题
|
||||
- 提到 `.json` 数据表、`records`、mock 数据 -> 数据
|
||||
- 提到 PRD、说明文档、手册、Markdown -> 文档
|
||||
2. 如果同一提示里既有“创建原型”又有“参考主题 / 文档 / 数据”，优先加载原型工作流，把主题 / 文档 / 数据当作上下文资料。
|
||||
3. 如果用户只说“帮我创建一个”，目标不明确时，不要盲猜，先用下方模板补齐。
|
||||
|
||||
## 模糊意图时的首次回复模板
|
||||
|
||||
```text
|
||||
收到，我可以帮你创建内容。
|
||||
|
||||
先告诉我这次主要要创建哪一类：
|
||||
1. 原型 / 组件
|
||||
2. 文档
|
||||
3. 主题
|
||||
4. 数据表
|
||||
|
||||
再补一句你的目标和使用场景，我就按对应流程继续。
|
||||
```
|
||||
|
||||
## 引用文档
|
||||
|
||||
- `./references/create-prototype.md`
|
||||
- `./references/create-document.md`
|
||||
- `./references/create-theme.md`
|
||||
- `./references/create-data.md`
|
||||
69
axhub-make/skills/create-workflow/references/create-data.md
Normal file
69
axhub-make/skills/create-workflow/references/create-data.md
Normal file
@@ -0,0 +1,69 @@
|
||||
# 创建数据
|
||||
|
||||
创建页面可直接消费的数据表的标准流程，数据统一存放在 `src/database/` 目录。
|
||||
|
||||
## 角色定位
|
||||
|
||||
你将作为 **数据架构师 × 产品经理（复合型）**，协助用户完成数据表的设计与创建。
|
||||
|
||||
## 核心流程
|
||||
|
||||
收到用户需求 -> 阅读规范 -> 需求对齐 -> 设计数据结构 -> 输出数据文件
|
||||
|
||||
### 步骤 1：阅读规范文档
|
||||
|
||||
**必须完整阅读以下文档**：
|
||||
|
||||
1. **`/rules/resource-management-guide.md`** 资源管理规范
|
||||
- 了解资产目录结构与数据放置规则
|
||||
2. **`/src/database/README.md`** 数据库规范
|
||||
- 数据表格式、字段约束、命名规则
|
||||
|
||||
### 步骤 2：需求对齐
|
||||
|
||||
首次回复必须使用以下模板，等待用户补充信息后再继续：
|
||||
|
||||
```text
|
||||
收到，准备创建数据表。
|
||||
|
||||
请详细描述您的需求：
|
||||
- 数据表用途（用户列表、产品目录、订单记录等）
|
||||
- 主要字段
|
||||
- 示例数据（如有）
|
||||
```
|
||||
|
||||
### 步骤 3：数据表设计与输出
|
||||
|
||||
- 设计数据结构与字段定义
|
||||
- 生成示例数据记录
|
||||
- 输出 JSON 格式的数据文件
|
||||
|
||||
## 数据表结构（强约束）
|
||||
|
||||
每个文件必须是 JSON 对象，包含 `tableName` + `records`：
|
||||
|
||||
```json
|
||||
{
|
||||
"tableName": "表名（中文）",
|
||||
"records": [
|
||||
{ "id": 1, "字段1": "值1", "字段2": "值2" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**最小一致性规则**：
|
||||
|
||||
- `records` 必须是数组；每条记录必须包含唯一的 `id`
|
||||
- 字段名优先中文并与页面一致
|
||||
- 同字段同类型
|
||||
- 图片字段用相对路径（如 `images/xxx.png`），不要 base64
|
||||
|
||||
## 输出文件
|
||||
|
||||
- `src/database/<table-name>.json` - 数据表文件
|
||||
- 文件名使用英文（如 `users.json`）
|
||||
- `tableName` 使用中文（如 "用户表"）
|
||||
|
||||
## 参考
|
||||
|
||||
`rules/resource-management-guide.md` | `src/database/README.md`
|
||||
@@ -0,0 +1,48 @@
|
||||
# 创建文档
|
||||
|
||||
创建项目文档的标准流程，文档统一存放在 `src/docs/` 目录。
|
||||
|
||||
## 角色定位
|
||||
|
||||
你将作为 **文档工程师 × 产品经理（复合型）**，协助用户完成文档的创建与结构化整理。
|
||||
|
||||
## 核心流程
|
||||
|
||||
收到用户需求 -> 阅读资源规则 -> 需求对齐 -> 生成文档
|
||||
|
||||
### 步骤 1：阅读规范文档
|
||||
|
||||
**必须完整阅读以下文档**：
|
||||
|
||||
1. **`/rules/resource-management-guide.md`** 资源管理规范
|
||||
- 了解资产目录结构与文档放置规则
|
||||
2. **`/rules/documentation-guide.md`** 文档编写规范
|
||||
- 文档格式、命名、结构等要求
|
||||
|
||||
### 步骤 2：需求对齐
|
||||
|
||||
首次回复必须使用以下模板，等待用户补充信息后再继续：
|
||||
|
||||
```text
|
||||
收到，准备创建文档。
|
||||
|
||||
请详细描述您的需求：
|
||||
- 文档类型（需求文档、设计说明、用户手册等）
|
||||
- 目标读者
|
||||
- 主要内容方向
|
||||
```
|
||||
|
||||
### 步骤 3：文档生成
|
||||
|
||||
- 根据用户需求组织文档结构
|
||||
- 参考已有项目文档和数据源补充上下文
|
||||
- 输出 Markdown 格式的文档
|
||||
|
||||
## 输出文件
|
||||
|
||||
- `src/docs/<doc-name>.md` - 文档文件
|
||||
- `src/docs/assets/` - 文档配图等附属资源（如需要）
|
||||
|
||||
## 参考
|
||||
|
||||
`rules/resource-management-guide.md` | `rules/documentation-guide.md`
|
||||
@@ -0,0 +1,61 @@
|
||||
# 创建原型 / 组件
|
||||
|
||||
创建一个新的原型页面或 UI 组件的标准流程。
|
||||
|
||||
## 角色定位
|
||||
|
||||
你将作为 **UI/UX 设计架构师 × 前端工程师（复合型）**，协助用户完成原型或组件的创建。
|
||||
|
||||
## 核心流程
|
||||
|
||||
收到用户需求 -> 阅读规范 -> 设计（spec.md） -> 开发（index.tsx） -> 验收
|
||||
|
||||
### 步骤 1：阅读规范文档
|
||||
|
||||
**必须完整阅读以下文档**，不可跳过：
|
||||
|
||||
1. **`/rules/design-guide.md`** 设计流程
|
||||
- 资料收集、业务场景识别、数据源查找、内容规划、视觉设计
|
||||
2. **`/rules/development-standards.md`** 开发规范
|
||||
- 文件结构、依赖引用、样式规范、导出规范
|
||||
- 完成后必须对照此文档检查实现
|
||||
3. **`/docs/templates/spec-template.md`** 规格文档模板
|
||||
- 使用此模板生成 `spec.md`
|
||||
|
||||
### 步骤 2：需求对齐
|
||||
|
||||
首次回复必须使用以下模板，等待用户补充信息后再继续：
|
||||
|
||||
```text
|
||||
收到，准备创建原型或组件。
|
||||
|
||||
请详细描述您的需求：
|
||||
```
|
||||
|
||||
### 步骤 3：设计与规格文档
|
||||
|
||||
- 根据用户需求完成布局与视觉方向设计
|
||||
- 产出 `spec.md` 规格文档
|
||||
|
||||
### 步骤 4：开发与验收
|
||||
|
||||
- 根据 spec 实现原型 / 组件代码
|
||||
- 运行验收流程确认功能正常
|
||||
|
||||
## 输出文件
|
||||
|
||||
如果目标是原型：
|
||||
|
||||
- `src/prototypes/<page-name>/spec.md` - 规格文档
|
||||
- `src/prototypes/<page-name>/index.tsx` - 页面组件
|
||||
- `src/prototypes/<page-name>/style.css` - 样式文件
|
||||
|
||||
如果目标是组件：
|
||||
|
||||
- `src/components/<component-name>/spec.md` - 规格文档
|
||||
- `src/components/<component-name>/index.tsx` - 组件实现
|
||||
- `src/components/<component-name>/style.css` - 样式文件
|
||||
|
||||
## 参考
|
||||
|
||||
`rules/design-guide.md` | `rules/development-standards.md`
|
||||
53
axhub-make/skills/create-workflow/references/create-theme.md
Normal file
53
axhub-make/skills/create-workflow/references/create-theme.md
Normal file
@@ -0,0 +1,53 @@
|
||||
# 创建主题
|
||||
|
||||
创建项目主题的标准流程，主题统一存放在 `src/themes/` 目录。
|
||||
|
||||
## 角色定位
|
||||
|
||||
你将作为 **UI/UX 设计师 × 主题架构师（复合型）**，协助用户完成设计主题的创建。
|
||||
|
||||
## 核心流程
|
||||
|
||||
收到用户需求 -> 阅读规范 -> 需求对齐 -> 设计主题 -> 输出主题文件
|
||||
|
||||
### 步骤 1：阅读规范文档
|
||||
|
||||
**必须完整阅读以下文档**：
|
||||
|
||||
1. **`/rules/resource-management-guide.md`** 资源管理规范
|
||||
- 了解资产目录结构与主题放置规则
|
||||
2. **`/rules/theme-guide.md`** 主题开发规范
|
||||
- 主题文件结构、设计令牌格式、CSS 变量规范
|
||||
|
||||
### 步骤 2：需求对齐
|
||||
|
||||
首次回复必须使用以下模板，等待用户补充信息后再继续：
|
||||
|
||||
```text
|
||||
收到，准备创建主题。
|
||||
|
||||
请详细描述您的需求：
|
||||
- 风格方向（现代 / 极简 / 活泼 / 商务等）
|
||||
- 主色系偏好
|
||||
- 参考案例或网站（如有）
|
||||
```
|
||||
|
||||
### 步骤 3：主题设计与输出
|
||||
|
||||
- 设计颜色体系（Primary、Secondary、Neutral、Semantic）
|
||||
- 定义字体搭配（标题、正文、代码）
|
||||
- 设计间距、圆角、阴影等视觉变量
|
||||
- 产出设计规范文档与主题文件
|
||||
|
||||
## 输出文件
|
||||
|
||||
主题目录结构 `src/themes/<theme-key>/`：
|
||||
|
||||
- `DESIGN.md` - 设计规范文档
|
||||
- `designToken.json` - 设计令牌（必须包含 `name` 字段）
|
||||
- `globals.css` - 全局 CSS 变量
|
||||
- `index.tsx` - 主题组件（如需要）
|
||||
|
||||
## 参考
|
||||
|
||||
`rules/resource-management-guide.md` | `rules/theme-guide.md`
|
||||
13
axhub-make/skills/default-resource-recommendations/SKILL.md
Normal file
13
axhub-make/skills/default-resource-recommendations/SKILL.md
Normal file
@@ -0,0 +1,13 @@
|
||||
---
|
||||
name: default-resource-recommendations
|
||||
description: 默认图表/图标/字体/动画资源推荐，按需查阅 references 中对应文档。
|
||||
---
|
||||
|
||||
# 默认资源推荐
|
||||
|
||||
按需查阅以下文档（不要一次性全部加载）：
|
||||
|
||||
- `references/default-chart-libraries.md`
|
||||
- `references/default-icon-libraries.md`
|
||||
- `references/default-font-combinations.md`
|
||||
- `references/default-animation-libraries.md`
|
||||
@@ -0,0 +1,68 @@
|
||||
# 默认动画库推荐
|
||||
|
||||
**使用时机**：仅在需要复杂动画交互 且 用户未指定动画方案 且 主题中无自定义动画系统时使用。
|
||||
|
||||
## ⚠️ 重要提醒：动画不是必须的！
|
||||
|
||||
- 少量简单动画 → 直接使用 CSS 原生动画（`transition`、`@keyframes`、`animation`）
|
||||
- Tailwind 项目 → 优先使用内置的 `transition-*`、`animate-*` 类
|
||||
- 只有在动画数量多或交互复杂时，才考虑引入动画库
|
||||
|
||||
## 🎬 推荐列表
|
||||
|
||||
| 动画库 | 推荐理由 | AI 生成友好度 | 核心劣势 | 适用场景 |
|
||||
|-------|---------|--------------|---------|---------|
|
||||
| **CSS 原生动画** | ⚡️ 零依赖首选<br>浏览器原生支持，无包体积，性能最优。 | 🌟🌟🌟🌟🌟<br>AI 对 CSS 动画极度熟悉 | 复杂时序控制困难，<br>手势交互需额外代码 | 默认首选。<br>Hover、Focus、简单过渡。 |
|
||||
| **Tailwind Animate**<br>(tailwindcss-animate) | ⚡️ Shadcn/UI 默认方案<br>纯 Class 控制，零 JS 心智负担。 | 🌟🌟🌟🌟🌟<br>AI 只需拼 class，几乎不会翻车 | 表达力有限，<br>无法处理复杂时序和状态 | 下拉、Toast、Modal、<br>Tooltip 等基础过渡。 |
|
||||
| **Framer Motion** | 👑 React 动画事实标准<br>声明式 API + Layout 动画 + 手势系统。 | 🌟🌟🌟🌟🌟<br>训练数据极多，AI 可稳定生成复杂动画 | 包体积偏大，<br>学习成本略高 | 复杂交互原型、页面转场、<br>拖拽排序、微交互系统。 |
|
||||
| **AutoAnimate**<br>(@formkit/auto-animate) | ✨ 一行代码魔法动画<br>DOM 变化即动画，极致省心。 | 🌟🌟🌟🌟<br>AI 基本不用理解动画原理 | 不可控，<br>难以产品级精调 | 列表 CRUD、表格增删、<br>卡片排序。 |
|
||||
|
||||
## 🎯 选择策略
|
||||
|
||||
**按需求复杂度匹配**：
|
||||
|
||||
1. **不需要动画** → 不引入任何动画库 ✅
|
||||
2. **需要动画但数量少（< 5 处）** → **CSS 原生动画** ✅
|
||||
3. **大量动画** → 按复杂度选择：
|
||||
- **简单过渡** → **Tailwind Animate**
|
||||
- **列表增删** → **AutoAnimate**
|
||||
- **手势/布局/复杂时序** → **Framer Motion**
|
||||
|
||||
## 💡 CSS 原生动画示例
|
||||
|
||||
```css
|
||||
/* 简单 Hover 效果 - 无需任何库 */
|
||||
.button {
|
||||
transition: all 0.2s ease;
|
||||
}
|
||||
.button:hover {
|
||||
transform: scale(1.05);
|
||||
}
|
||||
|
||||
/* 淡入动画 */
|
||||
@keyframes fadeIn {
|
||||
from { opacity: 0; transform: translateY(10px); }
|
||||
to { opacity: 1; transform: translateY(0); }
|
||||
}
|
||||
.card {
|
||||
animation: fadeIn 0.3s ease-out;
|
||||
}
|
||||
```
|
||||
|
||||
```html
|
||||
<!-- Tailwind 内置动画 - 无需额外依赖 -->
|
||||
<div class="transition-all duration-300 hover:scale-105">
|
||||
Hover 放大
|
||||
</div>
|
||||
<div class="animate-pulse">
|
||||
加载占位符
|
||||
</div>
|
||||
```
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
1. **性能优先**：动画过多会影响性能，尤其在移动端
|
||||
2. **避免过度使用**：克制使用动画，仅在提升 UX 时添加
|
||||
3. **按需引入**：Framer Motion 较大，确认需要复杂动画再引入
|
||||
4. **一致性**：同一项目尽量使用统一的动画方案
|
||||
5. **可访问性**：尊重用户的 `prefers-reduced-motion` 设置
|
||||
@@ -0,0 +1,36 @@
|
||||
# 默认图表库推荐
|
||||
|
||||
**使用时机**：仅在用户未指定图表库 且 项目中无现有图表方案时使用。
|
||||
|
||||
## 📊 推荐列表
|
||||
|
||||
| 图表库 | 推荐理由 | 核心优劣 | 适用场景 |
|
||||
|-------|---------|---------|---------|
|
||||
| **Recharts** | 🌟 首选通用方案<br>React 原生，组件化极好，代码最干净。 | ✅ 组件化设计，代码简洁<br>✅ React 原生，易于集成<br>⚠️ 复杂交互（3D、地理）支持较弱 | 常规折线、柱状、面积图。<br>**兜底必选**。 |
|
||||
| **Tremor** | Tailwind 绝配<br>专为 Dashboard 设计，样式极美，开箱即用。 | ✅ API 极简，上手快<br>✅ 与 Tailwind 完美融合<br>⚠️ 定制性低，仅支持预设图表类型 | 现代 SaaS 风格的 KPI 面板、统计卡片。 |
|
||||
| **Ant Design Charts**<br>(@ant-design/plots) | B 端业务神器<br>基于 G2，交互强，默认样式符合国内审美。 | ✅ 图表类型丰富，交互强<br>✅ 国内 B 端审美<br>⚠️ 包体积大，非 React 原生 (Canvas)<br>⚠️ 需锁定 v2 版本避免混淆 | 后台管理系统，复杂漏斗图、桑基图。 |
|
||||
| **ECharts**<br>(echarts-for-react) | 重型全能王<br>图表类型最全（地图/3D），渲染性能最强。 | ✅ 图表类型最全，性能强<br>✅ 文档和示例丰富<br>⚠️ 难与 Tailwind 融合<br>⚠️ 配置项繁琐 | 数据大屏、复杂的地理可视化、炫酷特效。 |
|
||||
|
||||
## 🎯 选择策略
|
||||
|
||||
**按需匹配**：
|
||||
1. **没想好/通用场景** → 直接用 **Recharts**
|
||||
2. **需要漂亮的 Dashboard** → 用 **Tremor**
|
||||
3. **国内 B 端后台** → 用 **Ant Design Charts**
|
||||
4. **需要地图/3D/大屏** → 用 **ECharts**
|
||||
|
||||
## 📦 安装命令
|
||||
|
||||
```bash
|
||||
# Recharts (推荐默认安装)
|
||||
pnpm add recharts
|
||||
|
||||
# Tremor
|
||||
pnpm add @tremor/react
|
||||
|
||||
# Ant Design Charts
|
||||
pnpm add @ant-design/plots
|
||||
|
||||
# ECharts
|
||||
pnpm add echarts echarts-for-react
|
||||
```
|
||||
@@ -0,0 +1,49 @@
|
||||
# 默认字体组合推荐
|
||||
|
||||
**使用时机**：仅在用户未指定字体方案 且 主题中无自定义字体定义时使用。
|
||||
|
||||
## 🔤 推荐列表
|
||||
|
||||
| 字体组合 | 推荐理由 | 中文环境表现 (Windows/Mac) | 适用场景 |
|
||||
|---------|---------|--------------------------|---------|
|
||||
| **Inter + System Sans**<br>(系统默认黑体) | ⚡️ 性能之王 (首选)<br>英文用 Inter (Tailwind 默认)，中文回退到系统字体 (PingFang/YaHei)。<br>无网络延迟。 | • Mac: 苹方 (完美)<br>• Win: 微软雅黑 (清晰)<br>利用系统渲染，字迹最锐利。 | **UI 界面、按钮、导航栏**。<br>绝大多数 SaaS 产品的默认选择。 |
|
||||
| **Noto Sans SC**<br>(思源黑体) | 🎨 视觉一致性<br>Google Fonts 开源。解决 Windows 下微软雅黑字重缺失（只有 Regular/Bold）的问题。 | 双端一致<br>在 Windows 上也能显示出极细(Light)或极粗(Black)的优美字重。 | **营销页面、高保真原型**。<br>当用户不想看微软雅黑那个"笨重"的样子时。 |
|
||||
| **JetBrains Mono**<br>(代码字体) | 💻 开发者最爱<br>开源等宽字体，连字特性（Ligatures）极美，阅读代码不累。 | 极佳<br>主要显示英文代码，中文备注会回退到系统黑体，互不干扰。 | **代码编辑器、JSON 预览**、<br>Markdown 里的代码块。 |
|
||||
| **Noto Serif SC**<br>(思源宋体) | 📄 文档沉浸感<br>现代风格的宋体，屏幕阅读优化极佳，比系统自带的"宋体"更清晰。 | 双端一致<br>适合长文阅读，有一种"打印刊物"的高级感。 | **PRD 文档模式、阅读模式**。<br>模拟书籍或正式公文的排版。 |
|
||||
|
||||
## 🎯 选择策略
|
||||
|
||||
**按场景匹配**：
|
||||
|
||||
1. **UI 界面（默认）** → **Inter + System Sans**
|
||||
- 按钮、表单、导航、卡片
|
||||
- 无需额外加载，性能最优
|
||||
|
||||
2. **营销页/高保真原型** → **Noto Sans SC**
|
||||
- 需要精确控制字重
|
||||
- 追求视觉一致性
|
||||
|
||||
3. **代码展示** → **JetBrains Mono**
|
||||
- 代码编辑器
|
||||
- 技术文档中的代码块
|
||||
|
||||
4. **长文阅读** → **Noto Serif SC**
|
||||
- 文章、博客、文档
|
||||
- 需要"纸质感"的阅读体验
|
||||
|
||||
## 💡 实现注意事项
|
||||
|
||||
1. **性能优先**：默认使用系统字体，避免加载延迟
|
||||
2. **字重一致性**：Windows 下微软雅黑只有 400/700，如需更多字重需用 Web Font
|
||||
3. **中英混排**：确保英文字体在 font-family 前面，中文字体在后面作为回退
|
||||
4. **字体加载优化**：
|
||||
- 使用 `font-display: swap` 避免字体加载阻塞
|
||||
- 按需加载字重，不要全部引入
|
||||
- 考虑使用 `@fontsource` npm 包而非 Google Fonts CDN（国内访问更快）
|
||||
|
||||
## ⚠️ 常见陷阱
|
||||
|
||||
- ❌ 不要同时加载多个 Web Font，会严重影响性能
|
||||
- ❌ 不要在 UI 界面使用宋体，阅读体验差
|
||||
- ❌ 不要在代码块使用非等宽字体，会导致对齐错乱
|
||||
- ✅ 优先使用系统字体 + Inter 组合，除非有明确的视觉一致性需求
|
||||
@@ -0,0 +1,27 @@
|
||||
# 默认图标库推荐
|
||||
|
||||
**使用时机**：仅在用户未指定图标库 且 主题中无自定义图标系统时使用。
|
||||
|
||||
## 🎨 推荐列表
|
||||
|
||||
| 图标库 | 推荐理由 | 风格特点 | 核心优劣 | 适用场景 |
|
||||
|-------|---------|---------|---------|---------|
|
||||
| **Lucide React** | 🌟 目前最流行 (No.1)<br>Shadcn/UI 默认图标库，极轻量，SVG 质量极高。 | 线性、圆润、现代<br>(Stroke based) | ✅ Tailwind 类名直接控制样式<br>✅ 包体积小，Tree-shaking 友好 | **Axhub Make 默认首选**。<br>适合所有现代 Web 原型。 |
|
||||
| **Ant Design Icons** | Ant Design 组件库官方配套，图标极多。 | 偏粗、商务、稳重<br>(实心/线框/双色) | ✅ 图标丰富，双色图标独特<br>⚠️ 包体积大，需配合 Antd 使用 | 必须配合 Ant Design 组件使用，<br>或需要双色图标时。 |
|
||||
| **Heroicons** | Tailwind 团队开发，无缝集成。 | 简洁、中性<br>(Outline/Solid) | ✅ Tailwind 原生支持<br>⚠️ 图标数量相对较少 | 追求 Tailwind 原生体验。 |
|
||||
| **React Icons** | 万能聚合器<br>包含 FontAwesome, Material 等几十个库。 | 风格杂乱，<br>取决于引入的子库 | ✅ 图标库最全<br>⚠️ 容易导致打包体积过大 | 需要非常冷门的图标<br>（如特定品牌 Logo）。 |
|
||||
|
||||
## 🎯 选择策略
|
||||
|
||||
**按需匹配**：
|
||||
1. **默认/不确定** → 直接用 **Lucide React**
|
||||
2. **用了 Ant Design 组件库** → 用 **Ant Design Icons**
|
||||
3. **Tailwind 纯粹主义者** → 用 **Heroicons**
|
||||
4. **需要特殊品牌图标** → 用 **React Icons**
|
||||
|
||||
|
||||
## ⚠️ 注意事项
|
||||
|
||||
1. **避免混用**：同一个项目只用一个图标库，保持视觉一致性
|
||||
2. **按需导入**：使用具名导入而非 `import *`，优化打包体积
|
||||
3. **优先推荐**：Lucide React（轻量、现代、Tailwind 友好）
|
||||
261
axhub-make/skills/design-bid-proposals/SKILL.md
Normal file
261
axhub-make/skills/design-bid-proposals/SKILL.md
Normal file
@@ -0,0 +1,261 @@
|
||||
---
|
||||
name: design-bid-proposals
|
||||
description: 默认生成 3 个可直接落地的设计比稿方向；如果用户明确要求 2 个、5 个或其他数量，必须按用户要求生成。该技能只负责比稿规则、分案策略和 prompt 约束，不提供独立脚本。实际执行时沿用现有 Gemini CLI 方式：先写 prompt 文件，再逐次调用 Gemini 完成规划轮、单方案轮和汇总轮。
|
||||
---
|
||||
|
||||
# Design Bid Proposals
|
||||
|
||||
## 适用场景
|
||||
|
||||
当用户希望：
|
||||
|
||||
- 默认拿到多个方案进行比稿
|
||||
- 比较多个 UI/UX 方向，而不是只要单一方案
|
||||
- 在不偏离明确需求的前提下做多方向探索
|
||||
- 需要清晰说明多案差异点与推荐推进方向
|
||||
|
||||
此技能同时适用于：
|
||||
|
||||
- `src/prototypes/<slug>/` 原型新建
|
||||
- `src/components/<slug>/` 组件新建
|
||||
|
||||
## 与 Gemini CLI 的关系
|
||||
|
||||
本技能**不提供独立脚本**。
|
||||
|
||||
执行方式对齐现有 `/skills/gemini-cli-uiux/SKILL.md`：
|
||||
|
||||
- 必须通过 Gemini CLI 执行，不退化为普通聊天生成
|
||||
- 先写本地 prompt 文件，再逐次调用 Gemini
|
||||
- 长上下文优先通过本地文件路径让 Gemini 读取
|
||||
- 最终直接写文件，回复里只给必要摘要
|
||||
|
||||
如果已经选中了 `/skills/gemini-cli-uiux/SKILL.md`，则本技能只补充“比稿多案”的规则，不重复定义 Gemini 的通用执行规范。
|
||||
|
||||
## 硬性规则
|
||||
|
||||
- 默认生成 `3` 个方向，但如果用户明确要求其他数量，必须按用户要求生成
|
||||
- 方案数量永远以用户明确要求为准；只有用户未指定时才回落到默认 3 案
|
||||
- 每个方向都要各自落成文件，不是只给文字说明
|
||||
- 多案必须保持同一个业务问题与目标，不得偏题
|
||||
- 用户已明确锁定的要求只能作为共同约束，不能拿来做差异化
|
||||
- 差异只能从 `3–6` 个未锁死维度里拉开
|
||||
- 多案至少满足：`P0` 有 1 个核心差异，`P1` 有 1 个核心差异
|
||||
- `P2` 只能增强差异，不能成为多案唯一差异来源
|
||||
- 若多个方案只是换皮、换色、换插画或换动效，判定为不合格，必须重做
|
||||
- Gemini 执行时，禁止用一条 prompt 同时要求输出多个方案正文
|
||||
- 规划轮只允许输出维度矩阵；每个方案都必须由独立 Gemini 调用分别生成
|
||||
- 只要命中了本技能，就默认强制进入比稿模式；除非用户明确表示 `退出比稿`、`不需要对比`、`只要单方案`、`直接落地一稿` 等，否则不得退回单稿流程
|
||||
|
||||
## 方案数量规则
|
||||
|
||||
### 默认规则
|
||||
|
||||
如果用户没有明确指定数量，默认生成 `3` 个方案：
|
||||
|
||||
- `A 稳健型`
|
||||
- `B 平衡型`
|
||||
- `C 突破型`
|
||||
|
||||
### 用户指定数量
|
||||
|
||||
如果用户明确指定数量，例如 `2`、`4`、`5`，必须严格按用户要求生成。
|
||||
|
||||
推荐的默认梯度如下：
|
||||
|
||||
- `2 案`：`稳健型`、`突破型`
|
||||
- `3 案`：`稳健型`、`平衡型`、`突破型`
|
||||
- `4 案`：`基准型`、`稳健型`、`差异型`、`突破型`
|
||||
- `5 案`：`基准型`、`稳健型`、`平衡型`、`差异型`、`突破型`
|
||||
- `6+ 案`：在上述基础上继续扩展 `探索型`、`概念型`、`愿景型` 等梯度
|
||||
|
||||
如果用户自己给了命名或分档方式，优先使用用户的命名，不要强行套默认梯度。
|
||||
|
||||
## 三层差异化框架
|
||||
|
||||
### P0 骨架层
|
||||
|
||||
决定界面的物理形态，是最优先拉开差异的层级。
|
||||
|
||||
- 空间形态与容器：`平铺式 (Page)` / `叠层式 (Drawer/Modal)` / `灵活空间 (Split-view/Canvas)`
|
||||
- 任务动线：`线性引导 (Step-by-step)` / `模块枢纽 (Dashboard)` / `并行操作 (Inline/Multi-task)`
|
||||
|
||||
### P1 肌肉层
|
||||
|
||||
决定内容分布和操作手感。
|
||||
|
||||
- 信息层级与密度：`高密度全量铺陈` / `核心收纳与隐藏` / `极简聚焦单点`
|
||||
- 操作交互范式：`纯点击与表单输入` / `快捷手势与微操作` / `高级拖拽与直接操纵`
|
||||
|
||||
### P2 皮囊层
|
||||
|
||||
决定界面的气质与细节感受。
|
||||
|
||||
- 视觉语言：`系统原生极简` / `现代卡片便当盒` / `探索性视觉`
|
||||
- 微反馈：`工具化零动效` / `顺滑过渡` / `沉浸式物理反馈`
|
||||
|
||||
## 默认三案定义
|
||||
|
||||
仅当用户没有指定数量时，使用下面的默认三案定义。
|
||||
|
||||
### A 稳健型 / Benchmark-led
|
||||
|
||||
- 默认参考 2–3 个行业领先产品，抽取共性范式
|
||||
- 优先复用已被验证的布局、模块组织、信息层级和视觉表达
|
||||
- 强调熟悉、可信、低理解成本、低决策风险
|
||||
- 可以借鉴成熟方案，但不能高相似度照搬单一竞品
|
||||
|
||||
### B 平衡型 / Balanced
|
||||
|
||||
- 在成熟范式上做适度优化
|
||||
- 平衡品牌表达、可用性、商业目标与实现成本
|
||||
- 适合大多数评审与交付场景
|
||||
|
||||
### C 突破型 / Differentiation-first
|
||||
|
||||
- 追求记忆点、表达力与差异化
|
||||
- 可以在结构、交互或视觉上更大胆
|
||||
- 仍然必须满足用户已明确的需求和约束
|
||||
|
||||
## 执行流程
|
||||
|
||||
### 1. 先锁定共同约束
|
||||
|
||||
先整理：
|
||||
|
||||
- 产品目标与成功标准
|
||||
- 页面或组件范围
|
||||
- 用户已明确表达的想法、参考、品牌调性、功能要求
|
||||
- 用户是否明确要求了方案数量
|
||||
- 不能改动的内容
|
||||
|
||||
如果信息不足，优先用 `references/bid-requirements-checklist.md` 做补齐。
|
||||
|
||||
### 2. 选择 3–6 个可变化维度
|
||||
|
||||
必须先判断哪些维度是：
|
||||
|
||||
- `已锁定`：用户明确要求，多案必须保持一致
|
||||
- `可变化`：可用来制造差异
|
||||
|
||||
仅从可变化维度中选择 3–6 个，用于多案拉开差异。
|
||||
|
||||
### 3. 先规划，再分案，再汇总
|
||||
|
||||
本技能只提供模板，不负责执行脚本。
|
||||
|
||||
推荐把 prompt 文件写到临时目录，例如：
|
||||
|
||||
- `tmp/design-bid-proposals/<slug>/01-planning.md`
|
||||
- `tmp/design-bid-proposals/<slug>/02-option-1.md`
|
||||
- `tmp/design-bid-proposals/<slug>/03-option-2.md`
|
||||
- `tmp/design-bid-proposals/<slug>/...`
|
||||
- `tmp/design-bid-proposals/<slug>/99-summary.md`
|
||||
|
||||
然后按顺序逐次调用 Gemini CLI。
|
||||
|
||||
### 3.1 Gemini 执行红线
|
||||
|
||||
当使用 Gemini CLI 时，必须遵守以下顺序：
|
||||
|
||||
1. `规划轮` 只输出锁定项、差异维度和方案矩阵
|
||||
2. 每个方案轮只生成当前方案，不得同时输出其他方案正文
|
||||
3. `汇总轮` 只负责对比和总结，不得补写多个方案正文
|
||||
|
||||
如果某次 Gemini 输出里同时出现多个方案正文，视为执行错误，必须废弃该结果并重新单独调用。
|
||||
|
||||
### 3.2 Gemini 调用方式
|
||||
|
||||
参考 `/skills/gemini-cli-uiux/SKILL.md`，使用 Gemini CLI 顺序执行。
|
||||
|
||||
示例：
|
||||
|
||||
```bash
|
||||
gemini -m gemini-3-pro -p "请严格阅读并执行文件：tmp/design-bid-proposals/<slug>/01-planning.md"
|
||||
```
|
||||
|
||||
然后依次执行每个单方案 prompt：
|
||||
|
||||
```bash
|
||||
gemini -m gemini-3-pro -p "请严格阅读并执行文件：tmp/design-bid-proposals/<slug>/02-option-1.md"
|
||||
gemini -m gemini-3-pro -p "请严格阅读并执行文件：tmp/design-bid-proposals/<slug>/03-option-2.md"
|
||||
```
|
||||
|
||||
最后执行汇总 prompt：
|
||||
|
||||
```bash
|
||||
gemini -m gemini-3-pro -p "请严格阅读并执行文件：tmp/design-bid-proposals/<slug>/99-summary.md"
|
||||
```
|
||||
|
||||
如果当前环境无法显式指定模型，但 Gemini CLI 仍可运行，则继续执行，并在最终回复里说明实际情况。
|
||||
|
||||
## 输出目录规则
|
||||
|
||||
### 默认三案
|
||||
|
||||
当方案数量为 `3` 且使用默认梯度时，目录固定为：
|
||||
|
||||
- `src/prototypes/<slug>-a-safe/`
|
||||
- `src/prototypes/<slug>-b-balanced/`
|
||||
- `src/prototypes/<slug>-c-bold/`
|
||||
|
||||
或：
|
||||
|
||||
- `src/components/<slug>-a-safe/`
|
||||
- `src/components/<slug>-b-balanced/`
|
||||
- `src/components/<slug>-c-bold/`
|
||||
|
||||
### 用户指定其他数量
|
||||
|
||||
如果用户指定为非 3 案，目录使用编号形式：
|
||||
|
||||
- `src/prototypes/<slug>-option-1/`
|
||||
- `src/prototypes/<slug>-option-2/`
|
||||
- ...
|
||||
- `src/prototypes/<slug>-option-n/`
|
||||
|
||||
或：
|
||||
|
||||
- `src/components/<slug>-option-1/`
|
||||
- `src/components/<slug>-option-2/`
|
||||
- ...
|
||||
- `src/components/<slug>-option-n/`
|
||||
|
||||
每个方向目录都必须包含：
|
||||
|
||||
- `spec.md`
|
||||
- `index.tsx`
|
||||
|
||||
按需可增加：
|
||||
|
||||
- `components/`
|
||||
|
||||
## 最终回复格式
|
||||
|
||||
最终回复必须包含：
|
||||
|
||||
1. 本次生成方式：`Gemini CLI` / `子代理` / `当前代理`
|
||||
2. 实际模型，或无法显式指定模型的原因
|
||||
3. 所有输出目录
|
||||
4. 每个方案一句话概述
|
||||
5. 按实际方案数量生成的 Markdown 差异表
|
||||
6. 推荐优先推进方向
|
||||
|
||||
差异表列数必须与实际方案数量一致。
|
||||
|
||||
## 质量检查
|
||||
|
||||
- 多案是否保持同一业务目标
|
||||
- 是否按用户要求的数量生成；如果用户未指定，是否回落到默认 3 案
|
||||
- 多案是否只从未锁死维度拉开差异
|
||||
- `P0` 和 `P1` 是否都有实质差异
|
||||
- 稳健/基准型是否参考了行业领先产品的成熟范式
|
||||
- 所有方向目录是否都生成了 `spec.md` 和 `index.tsx`
|
||||
- 最终回复是否写明了生成方式与按实际数量生成的差异表
|
||||
|
||||
## 资源
|
||||
|
||||
- `references/bid-requirements-checklist.md`
|
||||
- `references/bid-planning-template.md`
|
||||
- `references/bid-option-template.md`
|
||||
- `references/bid-summary-template.md`
|
||||
@@ -0,0 +1,59 @@
|
||||
# 单方案生成 Prompt 模板
|
||||
|
||||
你现在只负责生成一个设计比稿方向，不要生成其他方案。
|
||||
|
||||
## 输入
|
||||
|
||||
- 任务类型：{{TARGET_TYPE}}
|
||||
- 方案代号：{{OPTION_CODE}}
|
||||
- 方案名称：{{OPTION_NAME}}
|
||||
- 方案类型：{{OPTION_PROFILE}}
|
||||
- 方案定位：{{OPTION_POSITIONING}}
|
||||
- 输出目录：{{OUTPUT_DIR}}
|
||||
- 用户锁定要求：
|
||||
|
||||
{{LOCKED_REQUIREMENTS}}
|
||||
|
||||
- 本方案差异维度：
|
||||
|
||||
{{OPTION_DIMENSIONS}}
|
||||
|
||||
- 本方案偏置建议：
|
||||
|
||||
{{OPTION_GUIDANCE}}
|
||||
|
||||
- 用户 brief：
|
||||
|
||||
{{BRIEF}}
|
||||
|
||||
## 目标
|
||||
|
||||
请只生成当前方案的交付内容，确保：
|
||||
|
||||
- 不偏离用户锁定需求
|
||||
- 只基于当前方案维度进行设计
|
||||
- 与其他方案形成明显区别
|
||||
- 能直接落地为 `spec.md` 和 `index.tsx`
|
||||
- 不要同时生成另外几个方案
|
||||
- 不要输出多方案总表或总览
|
||||
- 不要出现其他方案的标题、代号或正文
|
||||
|
||||
## 输出要求
|
||||
|
||||
按以下结构输出，使用 Markdown：
|
||||
|
||||
1. `# {{OPTION_NAME}}`
|
||||
2. 一句话概述
|
||||
3. 目标印象
|
||||
4. 结构与信息策略
|
||||
5. 交互策略
|
||||
6. 视觉与反馈策略
|
||||
7. 风险与取舍
|
||||
8. `## spec.md`
|
||||
9. `## index.tsx`
|
||||
|
||||
其中：
|
||||
|
||||
- `spec.md` 必须是完整可写入的规格文档正文
|
||||
- `index.tsx` 必须是完整可写入的实现代码正文
|
||||
- 不要输出其他方案的内容
|
||||
@@ -0,0 +1,68 @@
|
||||
# 比稿规划轮 Prompt 模板
|
||||
|
||||
你是设计比稿规划器。请先理解用户需求，再锁定与方案数量一致的差异化矩阵。
|
||||
|
||||
## 输入
|
||||
|
||||
- 任务类型：{{TARGET_TYPE}}
|
||||
- 基础 slug：{{BASE_SLUG}}
|
||||
- 请求的方案数量：{{REQUESTED_PROPOSAL_COUNT}}
|
||||
- 输出根目录：{{OUTPUT_ROOT}}
|
||||
- 方案列表：
|
||||
|
||||
{{OPTION_LIST}}
|
||||
|
||||
- 用户 brief：
|
||||
|
||||
{{BRIEF}}
|
||||
|
||||
## 任务
|
||||
|
||||
1. 提取用户已经明确锁定的需求，列为 `locked_requirements`
|
||||
2. 从以下候选中判断哪些可以作为差异维度：
|
||||
- 空间形态与容器
|
||||
- 任务动线
|
||||
- 信息层级与密度
|
||||
- 操作交互范式
|
||||
- 视觉语言
|
||||
- 微反馈
|
||||
3. 只选出 3–6 个未锁死维度，列为 `selected_dimensions`
|
||||
4. 按 `requested_proposal_count` 为所有方案建立差异矩阵，并严格使用给定的输出目录
|
||||
5. 本轮只做规划，不生成任何方案正文，不输出 `spec.md` 或 `index.tsx` 内容
|
||||
6. 如果 `requested_proposal_count = 3` 且方案列表是默认三案，可按稳健 / 平衡 / 突破梯度规划
|
||||
7. 如果 `requested_proposal_count != 3`，必须严格按给定方案列表输出，不要擅自改成三案
|
||||
8. 保证：
|
||||
- 不偏离用户已明确需求
|
||||
- 多案至少有 1 个 P0 差异、1 个 P1 差异
|
||||
- P2 不能成为唯一差异来源
|
||||
|
||||
## 输出要求
|
||||
|
||||
只输出 JSON，不要输出解释文字。
|
||||
|
||||
JSON 结构必须包含：
|
||||
|
||||
```json
|
||||
{
|
||||
"requested_proposal_count": 5,
|
||||
"locked_requirements": ["..."],
|
||||
"selected_dimensions": ["..."],
|
||||
"options": [
|
||||
{
|
||||
"code": "O1",
|
||||
"name": "方案 1｜基准型",
|
||||
"positioning": "...",
|
||||
"output_dir": "...",
|
||||
"dimensions": {
|
||||
"空间形态与容器": "...",
|
||||
"任务动线": "..."
|
||||
}
|
||||
}
|
||||
],
|
||||
"validation": {
|
||||
"p0_difference": true,
|
||||
"p1_difference": true,
|
||||
"notes": ["..."]
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,41 @@
|
||||
# 比稿前置检查清单
|
||||
|
||||
在生成多个方案之前，先确认以下信息是否齐全。
|
||||
|
||||
## 目标与范围
|
||||
|
||||
- 产品或业务目标是什么
|
||||
- 成功标准是什么
|
||||
- 本次是原型还是组件
|
||||
- 页面、模块或组件范围是什么
|
||||
|
||||
## 已锁定约束
|
||||
|
||||
- 用户已经明确要求的功能点
|
||||
- 用户已经明确要求的结构或布局
|
||||
- 用户已经明确要求的品牌与视觉倾向
|
||||
- 用户已经明确给出的参考案例
|
||||
- 用户是否明确指定了方案数量
|
||||
- 不允许偏离的业务边界
|
||||
|
||||
## 可变化空间
|
||||
|
||||
- 哪些维度还没有被用户锁定
|
||||
- 哪些维度最适合用来拉开差异
|
||||
- 是否足够支撑用户要求的方案数量；若用户未指定，则默认支撑 3 案
|
||||
- 是否仍能把差异控制在 3–6 个核心维度内
|
||||
|
||||
## 产出要求
|
||||
|
||||
- 基础 slug
|
||||
- 目标目录是 `src/prototypes` 还是 `src/components`
|
||||
- 是否需要拆分 `components/`
|
||||
- 是否存在必须覆盖的状态或异常场景
|
||||
|
||||
## 比稿检查
|
||||
|
||||
- 多案是否围绕同一问题展开
|
||||
- 多案是否不是简单换皮
|
||||
- 如果用户未指定，是否使用默认 3 案
|
||||
- 如果用户指定了数量，是否严格按用户要求生成
|
||||
- 最终是否需要 Markdown 差异表
|
||||
@@ -0,0 +1,47 @@
|
||||
# 比稿汇总轮 Prompt 模板
|
||||
|
||||
你是比稿汇总器。你会收到规划结果和所有单方案结果，请统一输出汇总说明。
|
||||
|
||||
## 输入
|
||||
|
||||
- 任务类型：{{TARGET_TYPE}}
|
||||
- 基础 slug：{{BASE_SLUG}}
|
||||
- 请求的方案数量：{{REQUESTED_PROPOSAL_COUNT}}
|
||||
- 本次生成方式：{{GENERATION_METHOD}}
|
||||
- 实际模型说明：{{MODEL_INFO}}
|
||||
- 方案列表：
|
||||
|
||||
{{OPTION_LIST}}
|
||||
|
||||
- 规划结果：
|
||||
|
||||
{{PLANNING_RESULT}}
|
||||
|
||||
- 方案结果：
|
||||
|
||||
{{OPTION_RESULTS}}
|
||||
|
||||
## 任务
|
||||
|
||||
输出最终汇总说明，内容必须包含：
|
||||
|
||||
1. 本次生成方式
|
||||
2. 实际模型说明
|
||||
3. 所有输出目录
|
||||
4. 每个方案一句话概述
|
||||
5. 按实际方案数量生成的 Markdown 差异表
|
||||
6. 推荐优先推进方向
|
||||
|
||||
## 差异表格式
|
||||
|
||||
必须使用以下表头和分隔线：
|
||||
|
||||
{{DIFF_TABLE_HEADER}}
|
||||
{{DIFF_TABLE_DIVIDER}}
|
||||
|
||||
## 额外要求
|
||||
|
||||
- 明确指出这些方案不是换皮，而是在 P0/P1 上有实质差异
|
||||
- 推荐方向要说明为什么
|
||||
- 如果 `requested_proposal_count != 3`，不要在总结里错误地改回三案叙事
|
||||
- 输出使用 Markdown
|
||||
171
axhub-make/skills/design-review/SKILL.md
Normal file
171
axhub-make/skills/design-review/SKILL.md
Normal file
@@ -0,0 +1,171 @@
|
||||
---
|
||||
name: design-review
|
||||
description: 对原型和组件进行设计规范一致性审查，识别违规元素并建议将新增设计模式纳入主题。在需要检查设计质量、规范合规性或识别可复用设计模式时使用。
|
||||
---
|
||||
|
||||
# 设计 Review
|
||||
|
||||
对项目中的原型和组件进行设计规范一致性审查，产出结构化 Review 报告。
|
||||
|
||||
## 角色定位
|
||||
|
||||
你将作为 **设计质量审查员 × 主题架构师（复合型）**，协助用户完成设计 Review。
|
||||
|
||||
## 核心流程
|
||||
|
||||
确定范围与依据 → 执行审查 → 生成报告 → 追加日志
|
||||
|
||||
### 步骤 1：确定审查依据
|
||||
|
||||
按以下优先级确定设计审查的依据（设计规范）：
|
||||
|
||||
1. **用户指定** → 用户明确提供的设计规范文档、主题或 DESIGN.md
|
||||
2. **项目默认主题** → `AGENTS.md` 中定义的默认主题目录下的设计系统文件
|
||||
|
||||
**加载依据文件**：
|
||||
|
||||
进入确定的主题目录（如 `src/themes/<theme-key>/`），按以下顺序加载：
|
||||
|
||||
1. `DESIGN.md` — 设计规范文档（核心依据，优先级最高）
|
||||
2. `globals.css` 或 `designToken.json` — 设计令牌定义（二选一，以主题内实际存在的文件为准）
|
||||
3. `components/` — 主题组件（如有）
|
||||
4. `templates/` — 页面模板（如有）
|
||||
|
||||
> **如果项目无默认主题且用户未指定依据**，则仅执行通用设计质量检查（一致性、可访问性、响应式等），不执行主题合规性检查。
|
||||
|
||||
### 步骤 2：确定审查范围
|
||||
|
||||
按以下优先级确定审查的原型/组件范围：
|
||||
|
||||
1. **用户明确指定** → 用户直接点明了目标原型或目录
|
||||
- "Review 一下首页" → 仅审查首页原型
|
||||
- "检查所有按钮组件" → 仅审查 `src/components/` 下的按钮相关组件
|
||||
2. **用户模糊描述** → 用户给出方向但未精确指定
|
||||
- "最近改的那些页面帮我检查一下" → 按时间戳扫描最近变更的原型/组件
|
||||
3. **用户未指定范围（默认）** → 执行增量扫描（见下方默认流程）
|
||||
|
||||
**默认增量扫描流程**：
|
||||
|
||||
1. **读取上次 Review 时间** → 从 `src/docs/review-log.md` 获取最后一条日志的时间戳
|
||||
2. **扫描变更文件** → 以该时间戳为基准，检测自上次 Review 以来发生变更的文件
|
||||
- 扫描范围：`src/prototypes/`、`src/components/`
|
||||
- 使用 `find` 或 `git diff --name-only` 等方式获取变更文件列表
|
||||
3. **生成待审清单** → 展示待审查的原型/组件列表，等待用户确认
|
||||
|
||||
**首次执行**：若 `review-log.md` 不存在或为空，则扫描所有原型和组件。
|
||||
|
||||
### 步骤 3：展示待审清单
|
||||
|
||||
向用户展示范围检测结果，格式如下：
|
||||
|
||||
```text
|
||||
📋 上次设计 Review：YYYY-MM-DD HH:mm（或「首次 Review」）
|
||||
🎨 审查依据：<主题名> DESIGN.md
|
||||
|
||||
📝 待审查范围：
|
||||
|
||||
🔸 原型：
|
||||
- xxx-page（新增 / 修改）
|
||||
- yyy-page（修改）
|
||||
|
||||
🔸 组件：
|
||||
- zzz-button（新增）
|
||||
|
||||
是否按以上范围执行 Review？
|
||||
```
|
||||
|
||||
等待用户确认后再继续。用户可在此时调整范围。
|
||||
|
||||
### 步骤 4：执行审查
|
||||
|
||||
用户确认后，逐个审查目标原型/组件，分两个维度产出发现。
|
||||
|
||||
> **子代理委托（推荐）**：当待审范围包含 **3 个及以上** 原型/组件时，建议为每个目标分别启动一个子代理（browser_subagent 或等效机制），并行执行审查。每个子代理负责：
|
||||
> 1. 读取目标原型/组件的全部源码（`.tsx` / `.css` / `.module.css` 等）
|
||||
> 2. 依据下方规则执行 Part A 检查
|
||||
> 3. 返回结构化的发现列表（JSON 或 Markdown 表格）
|
||||
>
|
||||
> 主流程汇总所有子代理结果后，统一生成 Part B 建议和最终报告。
|
||||
|
||||
#### Part A：规范合规性检查
|
||||
|
||||
##### 检查依据优先级
|
||||
|
||||
每个主题的规范不同，因此 **以步骤 1 加载的 DESIGN.md 中定义的规则为准**，而非下方通用检查表。
|
||||
|
||||
具体优先级：
|
||||
|
||||
1. **主题 DESIGN.md 中的「禁止做法」/ 「使用约束 · 必须遵守」** → 对应 🔴 Critical
|
||||
2. **主题 DESIGN.md 中的「建议做法」** → 违反时对应 🟡 Warning
|
||||
3. **主题 DESIGN.md 中定义的 Design Token**（颜色、间距、圆角、阴影、排版等） → 硬编码偏离时对应 🟡 Warning
|
||||
4. **主题 DESIGN.md 中定义的组件体系** → 自行重写已有组件对应 🔵 Info
|
||||
5. **下方通用检查表** → 仅作为 DESIGN.md 未涵盖维度的补充
|
||||
|
||||
##### 通用检查表（补充）
|
||||
|
||||
> 以下维度仅在主题 DESIGN.md 未对该维度做出明确规定时使用。如 DESIGN.md 已有更具体的要求，以 DESIGN.md 为准。
|
||||
|
||||
| 检查维度 | 检查内容 |
|
||||
|---------|---------|
|
||||
| **色彩** | 是否使用了设计系统定义的颜色变量；是否存在硬编码颜色值 |
|
||||
| **字体** | 字体家族、字号、字重是否符合设计系统定义 |
|
||||
| **间距** | 内外边距是否使用标准间距值 |
|
||||
| **圆角** | border-radius 是否使用设计系统定义的标准值 |
|
||||
| **阴影** | box-shadow 是否使用设计系统定义的阴影层级 |
|
||||
| **组件使用** | 是否复用了主题已提供的组件（Button、Card、Input 等），而非自行重写 |
|
||||
| **布局** | 是否遵循设计系统的布局模式和栅格规范 |
|
||||
| **可访问性** | 色彩对比度（WCAG 2.1 AA）、语义化标签、交互元素可达性 |
|
||||
| **响应式** | 是否遵循设计系统的断点规范 |
|
||||
|
||||
##### 严重度分级
|
||||
|
||||
- 🔴 **Critical** — 违反主题「禁止做法」或「必须遵守」的强制规则
|
||||
- 🟡 **Warning** — 偏离「建议做法」或硬编码了 Design Token 已定义的值
|
||||
- 🔵 **Info** — 优化建议（如可复用已有组件但自行实现了类似组件）
|
||||
|
||||
#### Part B：主题扩展建议
|
||||
|
||||
识别原型/组件中值得纳入设计系统的新模式：
|
||||
|
||||
| 识别维度 | 说明 |
|
||||
|---------|------|
|
||||
| **新增设计元素** | 原型中出现的、设计系统尚未定义的颜色、字体、间距等，且有复用价值 |
|
||||
| **新增组件模式** | 原型中自行实现的 UI 组件，如果有通用性，建议提取到主题 `components/` |
|
||||
| **重复模板** | 多个原型中出现类似的页面结构/布局模式，建议提取为主题 `templates/` |
|
||||
| **新增交互模式** | 与现有组件不同的交互模式（如新的表单验证、加载态等） |
|
||||
|
||||
### 步骤 5：生成 Review 报告
|
||||
|
||||
使用 `/skills/design-review/references/review-report-template.md` 模板，生成结构化报告并直接展示给用户。
|
||||
|
||||
报告应包含：
|
||||
- 审查摘要（范围、依据、统计）
|
||||
- Part A 规范违规清单（表格）
|
||||
- Part B 主题扩展建议清单（表格）
|
||||
- 建议优先级排序
|
||||
|
||||
### 步骤 6：追加 Review 日志
|
||||
|
||||
审查完成后，在 `src/docs/review-log.md` 追加一条日志记录。
|
||||
|
||||
- 日志模板来源：`src/docs/templates/review-log-template.md`
|
||||
- 若 `review-log.md` 不存在，先基于模板创建
|
||||
- 日志采用紧凑格式，一行一条
|
||||
- 当 `review-log.md` 达到或超过 `500` 行时，删除最旧的 `50` 行业务日志，再追加 `trim` 日志记录裁剪动作
|
||||
- 日志只追加，不改写历史
|
||||
|
||||
## 输出文件
|
||||
|
||||
- Review 报告：直接在对话中展示（不写入文件）
|
||||
- Review 日志：`src/docs/review-log.md`（追加）
|
||||
|
||||
## 约束
|
||||
|
||||
1. **只读审查** — Review 过程不修改任何原型或组件代码，仅产出建议
|
||||
2. **不修改主题** — Part B 仅提出建议，不自动修改主题文件
|
||||
3. **用户确认** — 范围和依据必须经用户确认后再执行审查
|
||||
4. **增量优先** — 默认只审查上次 Review 以来的变更，避免重复审查
|
||||
|
||||
## 参考
|
||||
|
||||
`rules/design-guide.md` | `rules/theme-guide.md` | `rules/memory-system-guide.md`
|
||||
@@ -0,0 +1,53 @@
|
||||
# 设计 Review 报告
|
||||
|
||||
## 审查摘要
|
||||
|
||||
| 项目 | 内容 |
|
||||
|------|------|
|
||||
| **审查时间** | YYYY-MM-DD HH:mm |
|
||||
| **审查范围** | （列出审查的原型/组件） |
|
||||
| **审查依据** | （主题名称 + DESIGN.md / globals.css 等） |
|
||||
| **上次 Review** | YYYY-MM-DD HH:mm（或「首次 Review」） |
|
||||
|
||||
### 统计
|
||||
|
||||
| 指标 | 数值 |
|
||||
|------|------|
|
||||
| 审查原型/组件数 | N |
|
||||
| 🔴 Critical 问题 | N |
|
||||
| 🟡 Warning 问题 | N |
|
||||
| 🔵 Info 建议 | N |
|
||||
| 主题扩展建议 | N |
|
||||
|
||||
---
|
||||
|
||||
## Part A：规范合规性问题
|
||||
|
||||
> 以下为原型/组件中不符合设计规范的问题清单。
|
||||
|
||||
| # | 文件 | 问题描述 | 维度 | 严重度 | 建议修改 |
|
||||
|---|------|---------|------|--------|---------|
|
||||
| 1 | `src/prototypes/xxx/index.tsx` | 使用硬编码颜色 `#ff0000` 而非变量 `--destructive` | 色彩 | 🔴 Critical | 替换为 `var(--destructive)` |
|
||||
| 2 | `src/components/yyy/index.tsx` | 字号 `13px` 不在设计系统定义的字号梯度中 | 字体 | 🟡 Warning | 使用 `text-sm`（14px） |
|
||||
| 3 | `src/prototypes/zzz/index.tsx` | 自行实现了 Button 组件，主题已提供 | 组件使用 | 🔵 Info | 复用 `components/Button` |
|
||||
|
||||
---
|
||||
|
||||
## Part B：主题扩展建议
|
||||
|
||||
> 以下为原型/组件中出现的新设计模式，建议纳入主题以提升复用性。
|
||||
|
||||
| # | 元素类型 | 来源 | 描述 | 建议操作 |
|
||||
|---|---------|------|------|---------|
|
||||
| 1 | 新组件 | `src/prototypes/xxx/index.tsx` | 可折叠面板组件，3 个原型中重复出现 | 提取到 `themes/<theme>/components/Accordion.tsx` |
|
||||
| 2 | 新颜色 | `src/prototypes/yyy/style.css` | 渐变背景色 `linear-gradient(...)` 多处使用 | 添加到 `DESIGN.md` 色彩系统 & `globals.css` |
|
||||
| 3 | 页面模板 | `src/prototypes/aaa/`, `src/prototypes/bbb/` | 相似的列表页布局结构 | 提取为 `themes/<theme>/templates/ListTemplate.tsx` |
|
||||
|
||||
---
|
||||
|
||||
## 优先处理建议
|
||||
|
||||
1. **优先修复** 🔴 Critical 问题（直接违反设计规范）
|
||||
2. **建议处理** 🟡 Warning 问题（提升一致性）
|
||||
3. **酌情提取** Part B 中复用频率高（≥2 处）的组件和模板
|
||||
4. **后续跟进** 🔵 Info 建议（优化性质）
|
||||
278
axhub-make/skills/figma-make-exporter/SKILL.md
Normal file
278
axhub-make/skills/figma-make-exporter/SKILL.md
Normal file
@@ -0,0 +1,278 @@
|
||||
---
|
||||
name: figma-make-exporter
|
||||
description: 将本项目页面补齐为可导出 Figma Make 资产的结构，并产出可直接下载的 `名称.fig` 文件；适用于保留原始 Figma Make 资产、同步导出壳子和生成 canvas.fig。
|
||||
---
|
||||
|
||||
# Figma 导出壳子规范
|
||||
|
||||
本技能用于把当前页面补齐为可导出的 Figma Make 资产结构，并确保最终通过后台导出接口拿到的产物是 `名称.fig`。
|
||||
|
||||
这里的最终下载产物不是 `.make` 压缩包，而是项目目录中的 `canvas.fig` 二进制文件。后台会直接把它以 `名称.fig` 的文件名下载给用户。
|
||||
|
||||
## 核心目标
|
||||
|
||||
- 让当前页面具备稳定的 Figma 导出资产
|
||||
- 确保导出的 `canvas.fig` 与当前 Axhub 页面内容一致
|
||||
- 保留所有原始 Figma Make 资产，避免后续无法再次回写导出
|
||||
|
||||
## 关键原则
|
||||
|
||||
1. **先同步页面，再执行 pack**
|
||||
|
||||
如果当前页面的真实入口是根目录 `index.tsx` / `style.css`，而导出壳子使用的是 `src/App.tsx` / `src/index.css`，那么必须先把两者同步，再运行 `canvas-fig-sync.mjs pack`。
|
||||
|
||||
不要只更新根目录页面却直接回写旧的 `src/App.tsx`，否则导出的 `.fig` 内容会和当前页面不一致。
|
||||
|
||||
2. **优先做“薄壳”同步**
|
||||
|
||||
只要结构允许，优先让导出壳子复用当前页面入口，而不是再维护一套容易漂移的拷贝：
|
||||
|
||||
- `src/App.tsx` 优先作为薄包装，直接复用当前页面主组件或共享组件
|
||||
- `src/index.css` 优先复用或导入根目录 `style.css` 的真实样式来源
|
||||
- 如果必须复制代码，也要在本次任务里一起更新到一致
|
||||
|
||||
3. **保留原始资产**
|
||||
|
||||
如果目录里已经存在以下文件，必须保留：
|
||||
|
||||
- `canvas.fig`
|
||||
- `meta.json`
|
||||
- `ai_chat.json`
|
||||
- `thumbnail.png`
|
||||
- `canvas.code-manifest.json`
|
||||
- `images/`
|
||||
|
||||
4. **使用固定目录结构**
|
||||
|
||||
为了降低后续维护成本，页面目录采用固定职责分层：
|
||||
|
||||
```text
|
||||
<page>/
|
||||
├── index.tsx # Axhub 运行时适配层
|
||||
├── style.css # 根入口样式转发层
|
||||
└── src/
|
||||
├── App.tsx # Figma 导出薄壳
|
||||
├── main.tsx # Vite 挂载层
|
||||
├── index.css # Figma 入口样式层
|
||||
├── components/ # 页面视觉与交互主体
|
||||
└── styles/ # 共享样式
|
||||
```
|
||||
|
||||
固定约束：
|
||||
|
||||
- 根目录 `index.tsx` 只做 Axhub 运行时适配，不再复制一套页面视觉实现
|
||||
- `src/App.tsx` 只做 Figma 导出薄壳，不再复制一套页面业务逻辑
|
||||
- 共享页面主体应尽量落在 `src/components/**`
|
||||
- 共享样式应尽量落在 `src/styles/**`
|
||||
|
||||
如果你在生成或改造这些文件，请直接在 `index.tsx`、`src/App.tsx`、`src/main.tsx` 顶部写清楚职责注释，提醒后续维护者不要让两套入口漂移
|
||||
|
||||
5. **执行本技能后的最终项目必须符合上述固定结构**
|
||||
|
||||
这不是建议项，而是验收约束。
|
||||
|
||||
如果当前项目结构不满足这套职责分层，执行本技能时应先重构到该结构，再继续生成或回写 `canvas.fig`。
|
||||
|
||||
## 当前导出产物
|
||||
|
||||
后台导出接口：
|
||||
|
||||
```text
|
||||
GET /api/export-make?path=prototypes/<page-name>
|
||||
```
|
||||
|
||||
接口行为：
|
||||
|
||||
- 使用 `canvas-fig-sync.mjs pack` 把当前源码回写到 `canvas.fig`
|
||||
- 刷新 `canvas.code-manifest.json`
|
||||
- 更新 `meta.json.exported_at`
|
||||
- 直接下载 `canvas.fig`，文件名为 `名称.fig`
|
||||
|
||||
## 使用场景
|
||||
|
||||
### 场景 A：项目由 Figma Make 导入，已有 `canvas.fig`
|
||||
|
||||
此时目标不是新建结构，而是把当前页面同步回已有导出壳子，然后重新回写 `canvas.fig`。
|
||||
|
||||
**步骤**：
|
||||
|
||||
1. 检查并同步当前页面和导出壳子
|
||||
|
||||
重点核对：
|
||||
|
||||
- 根目录 `index.tsx`
|
||||
- 根目录 `style.css`
|
||||
- 导出壳子 `src/App.tsx`
|
||||
- 导出壳子 `src/index.css`
|
||||
- 导出壳子依赖的 `src/components/**`、`src/pages/**`、`src/styles/**`
|
||||
|
||||
2. 回写 `canvas.fig`
|
||||
|
||||
```bash
|
||||
node scripts/canvas-fig-sync.mjs pack \
|
||||
--fig src/prototypes/<page-name>/canvas.fig \
|
||||
--from src/prototypes/<page-name> \
|
||||
--prune-missing \
|
||||
--sanitize-for-export
|
||||
```
|
||||
|
||||
3. 刷新 manifest
|
||||
|
||||
```bash
|
||||
node scripts/canvas-fig-sync.mjs inspect \
|
||||
--fig src/prototypes/<page-name>/canvas.fig \
|
||||
--manifest src/prototypes/<page-name>/canvas.code-manifest.json
|
||||
```
|
||||
|
||||
4. 更新 `meta.json`
|
||||
|
||||
至少保证：
|
||||
|
||||
- `file_name`
|
||||
- `exported_at`
|
||||
- `client_meta`
|
||||
- `developer_related_links`
|
||||
|
||||
5. 确保 `ai_chat.json` 至少为 `{}`，并保留 `images/`
|
||||
|
||||
### 场景 B：原生 Axhub 页面，没有 `canvas.fig`
|
||||
|
||||
此时需要先补齐 Figma 导出壳子，再生成 `canvas.fig`。
|
||||
|
||||
**目标结构**：
|
||||
|
||||
```text
|
||||
src/prototypes/<page-name>/
|
||||
├── index.tsx
|
||||
├── style.css
|
||||
├── canvas.fig
|
||||
├── meta.json
|
||||
├── ai_chat.json
|
||||
├── canvas.code-manifest.json
|
||||
├── images/
|
||||
├── package.json
|
||||
├── vite.config.ts
|
||||
├── index.html
|
||||
└── src/
|
||||
├── App.tsx
|
||||
├── main.tsx
|
||||
├── index.css
|
||||
├── components/
|
||||
├── pages/
|
||||
└── styles/
|
||||
```
|
||||
|
||||
**步骤**：
|
||||
|
||||
1. 先补齐导出壳子
|
||||
|
||||
要求：
|
||||
|
||||
- `src/App.tsx` 必须表达当前页面真实内容，而不是空模板
|
||||
- `src/index.css` 必须覆盖当前页面真实样式，而不是无关默认样式
|
||||
- 若可以复用根目录入口，优先做薄壳复用
|
||||
|
||||
2. 创建 `meta.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"client_meta": {
|
||||
"background_color": { "r": 0.96, "g": 0.96, "b": 0.96, "a": 1 },
|
||||
"thumbnail_size": { "width": 400, "height": 300 },
|
||||
"render_coordinates": { "x": 0, "y": 0, "width": 1280, "height": 960 }
|
||||
},
|
||||
"file_name": "<项目显示名>",
|
||||
"developer_related_links": [],
|
||||
"exported_at": "<ISO 8601 时间>"
|
||||
}
|
||||
```
|
||||
|
||||
3. 创建空的 `ai_chat.json`
|
||||
|
||||
```json
|
||||
{}
|
||||
```
|
||||
|
||||
4. 创建 `images/` 目录，并同步图片资源
|
||||
|
||||
```bash
|
||||
mkdir -p src/prototypes/<page-name>/images
|
||||
```
|
||||
|
||||
5. 使用模板生成基础 `canvas.fig`
|
||||
|
||||
```bash
|
||||
cp scripts/templates/empty-canvas.fig src/prototypes/<page-name>/canvas.fig
|
||||
node scripts/canvas-fig-sync.mjs pack \
|
||||
--fig src/prototypes/<page-name>/canvas.fig \
|
||||
--from src/prototypes/<page-name> \
|
||||
--prune-missing \
|
||||
--sanitize-for-export
|
||||
```
|
||||
|
||||
6. 生成 manifest
|
||||
|
||||
```bash
|
||||
node scripts/canvas-fig-sync.mjs inspect \
|
||||
--fig src/prototypes/<page-name>/canvas.fig \
|
||||
--manifest src/prototypes/<page-name>/canvas.code-manifest.json
|
||||
```
|
||||
|
||||
## `meta.json` 规范
|
||||
|
||||
```ts
|
||||
interface MetaJson {
|
||||
client_meta: {
|
||||
background_color: { r: number; g: number; b: number; a: number };
|
||||
thumbnail_size: { width: number; height: number };
|
||||
render_coordinates: { x: number; y: number; width: number; height: number };
|
||||
};
|
||||
file_name: string;
|
||||
developer_related_links: [];
|
||||
exported_at: string;
|
||||
}
|
||||
```
|
||||
|
||||
## `canvas-fig-sync.mjs` 参考
|
||||
|
||||
### inspect
|
||||
|
||||
```bash
|
||||
node scripts/canvas-fig-sync.mjs inspect --fig <canvas.fig> [--manifest <file>]
|
||||
```
|
||||
|
||||
### extract
|
||||
|
||||
```bash
|
||||
node scripts/canvas-fig-sync.mjs extract --fig <canvas.fig> --out <project-dir> [--source-root src]
|
||||
```
|
||||
|
||||
### pack
|
||||
|
||||
```bash
|
||||
node scripts/canvas-fig-sync.mjs pack --fig <canvas.fig> --from <project-dir> [--out <new.fig>] [--prune-missing] [--sanitize-for-export]
|
||||
```
|
||||
|
||||
关键行为：
|
||||
|
||||
- 只更新磁盘上存在的文件对应的 CODE_FILE 节点
|
||||
- 更新时同时回写 `sourceCode` 与 `collaborativeSourceCode`，避免 Figma 后续导出仍然读取到旧协同代码
|
||||
- 默认情况下，缺失文件会保留原始 `canvas.fig` 中的内容
|
||||
- 对导出场景，建议显式加上 `--prune-missing`，这样磁盘上不存在的旧 `CODE_FILE` 节点会被裁掉，最终 `.fig` 更接近当前真实项目
|
||||
- 对最终要回导 Figma Make 的产物，建议同时加上 `--sanitize-for-export`，这样会清空旧的 `CODE_LIBRARY` 聊天/代码历史、清理 `CODE_INSTANCE.codeSnapshot` 预览缓存、重建 `importedCodeFiles`，并裁掉悬空 `CODE_COMPONENT`
|
||||
- 同一路径对应多个 CODE_FILE 节点时会统一更新
|
||||
|
||||
## 验收标准
|
||||
|
||||
- `node scripts/canvas-fig-sync.mjs inspect --fig <canvas.fig>` 可以成功执行
|
||||
- 导出的 `canvas.fig` 对应当前页面，而不是旧壳子内容
|
||||
- `meta.json.exported_at` 为最新时间
|
||||
- `src/App.tsx` / `src/index.css` 与根目录页面不存在明显漂移
|
||||
- 后台最终下载文件名为 `名称.fig`
|
||||
|
||||
## 注意事项
|
||||
|
||||
- `canvas.fig` 是二进制文件，不能手改
|
||||
- 运行 `pack` 前，先确认导出壳子已经同步到当前页面
|
||||
- 若目录内已有 `images/` 的 hash 命名文件，不要随意重命名
|
||||
- 如果是导入项目，后续整理页面结构时也不能删除原始 Figma Make 资产
|
||||
239
axhub-make/skills/figma-make-project-converter/SKILL.md
Normal file
239
axhub-make/skills/figma-make-project-converter/SKILL.md
Normal file
@@ -0,0 +1,239 @@
|
||||
---
|
||||
name: figma-make-project-converter
|
||||
description: 将 Figma Make 导出的 Vite + React 项目转换为本项目页面组件或主题的流程规范；在处理 @/ 路径、package@version 别名、globals.css 样式迁移与主题提取时使用。
|
||||
---
|
||||
|
||||
# Figma Make 项目转换规范
|
||||
|
||||
将 Figma Make 导出的 Vite + React 项目转换为本项目页面组件或主题，尽量保持视觉效果、样式 token 和组件结构。
|
||||
|
||||
## 核心目标
|
||||
|
||||
- 保持页面视觉与层级结构一致
|
||||
- 移除对 Figma Make 原始 Vite 入口和版本化 alias 的依赖
|
||||
- 产出可在本项目中继续演化的页面组件或主题
|
||||
|
||||
## 使用方式
|
||||
|
||||
### 步骤 1：运行预处理脚本
|
||||
|
||||
推荐输入来源：
|
||||
|
||||
- 优先使用 **Figma 原始导出的 ZIP 工程包**
|
||||
- 由系统先解压 ZIP，再把解压后的项目目录传给本脚本
|
||||
- 不建议手工解压后再挑文件、删文件或重组目录，否则容易破坏 Figma 原始项目结构，降低后续导入稳定性
|
||||
|
||||
```bash
|
||||
node scripts/figma-make-converter.mjs <figma-make-project-dir> [output-name]
|
||||
|
||||
# 示例
|
||||
node scripts/figma-make-converter.mjs "temp/my-figma-make-project" my-page
|
||||
node scripts/figma-make-converter.mjs "temp/my-figma-make-project" brand-theme --target-type themes
|
||||
```
|
||||
|
||||
脚本会自动完成：
|
||||
- 完整复制 Figma Make 项目到 `src/prototypes/[页面名]/` 或 `src/themes/[theme-key]/`
|
||||
- 排除 `node_modules`、`.npm-local-cache`、`build`
|
||||
- 转换 `@/` 为相对路径
|
||||
- 将源码中的 `package@version` 导入改为裸包名
|
||||
- 分析组件、页面、依赖、CSS、设计文档
|
||||
- 生成 AI 工作文档和分析报告
|
||||
|
||||
### 步骤 2：按任务清单完成转换
|
||||
|
||||
重点查看：
|
||||
- `.figma-make-tasks.md`
|
||||
- `.figma-make-analysis.json`
|
||||
- 主题模式下的 `.figma-make-theme-tasks.md`
|
||||
|
||||
## Figma Make 项目特征
|
||||
|
||||
典型结构：
|
||||
|
||||
```text
|
||||
figma-make-project/
|
||||
├── src/
|
||||
│ ├── App.tsx
|
||||
│ ├── main.tsx
|
||||
│ ├── index.css
|
||||
│ ├── DESIGN_SYSTEM_GUIDE.md
|
||||
│ ├── TOKEN_REFERENCE.md
|
||||
│ ├── components/
|
||||
│ ├── pages/
|
||||
│ ├── styles/globals.css
|
||||
│ └── guidelines/
|
||||
├── index.html
|
||||
├── package.json
|
||||
└── vite.config.ts
|
||||
```
|
||||
|
||||
导入时应把这套原始 ZIP 中的目录结构视为权威结构，尤其是：
|
||||
|
||||
- `src/App.tsx`
|
||||
- `src/main.tsx`
|
||||
- `src/index.css`
|
||||
- `src/styles/globals.css`
|
||||
- `src/components/**`
|
||||
- `src/pages/**`
|
||||
- `src/guidelines/**`
|
||||
- `package.json`
|
||||
- `vite.config.ts`
|
||||
- `index.html`
|
||||
|
||||
说明：
|
||||
|
||||
- `Attributions.md`、`guidelines/Guidelines.md`、`README.md`、`TOKEN_REFERENCE.md`、`DESIGN_SYSTEM_GUIDE.md` 这类文件在 Figma 原始导出中是正常组成部分，不应误判为异常垃圾文件
|
||||
- 转换时的重点不是删掉这些文件，而是识别哪些文件是页面真实依赖，哪些是说明文档
|
||||
|
||||
关键判断：
|
||||
- 这是 **Vite + React** 项目，不是 Next.js
|
||||
- 不需要处理 `"use client"`
|
||||
- `vite.config.ts` 里的 `package@version` alias 只是导出兼容层，不应作为最终运行前提
|
||||
|
||||
## 保留导出所需的原始文件
|
||||
|
||||
如果导入后的目录中已经包含以下 Figma Make 原始资产，后续转换时必须保留，不要删除或覆盖为无关内容：
|
||||
|
||||
- `canvas.fig`：Figma Make 的二进制设计数据，用于后续回写源码并导出 `名称.fig`
|
||||
- `meta.json`：项目元数据，至少保留 `file_name`、`exported_at`、`client_meta`
|
||||
- `ai_chat.json`：AI 聊天历史，可为空对象 `{}`
|
||||
- `thumbnail.png`：项目缩略图
|
||||
- `canvas.code-manifest.json`：`canvas.fig` 中 `CODE_FILE` 的索引清单
|
||||
- `images/`：设计稿图片资源，通常为 hash 命名，不要随意重命名
|
||||
|
||||
如果脚本分析报告里出现 `figmaMakeAssets` 字段，说明这些文件已经被保留在导入目录中，AI 在后续整理页面结构时仍需继续保留它们。
|
||||
|
||||
## 页面转换规则
|
||||
|
||||
### 固定目录结构
|
||||
|
||||
为了兼顾 Axhub 运行时和后续 `.fig` 导出，页面目录默认采用以下固定结构：
|
||||
|
||||
```text
|
||||
<page>/
|
||||
├── index.tsx # Axhub runtime adapter only
|
||||
├── style.css # root style bridge only
|
||||
└── src/
|
||||
├── App.tsx # Figma export shell only
|
||||
├── main.tsx # Vite mount only
|
||||
├── index.css # Figma style bridge only
|
||||
├── components/ # shared page implementation
|
||||
└── styles/ # shared page styles
|
||||
```
|
||||
|
||||
转换时请遵守：
|
||||
|
||||
- 页面真实视觉和交互主体优先沉淀到 `src/components/**`
|
||||
- 根目录 `index.tsx` 只负责 Axhub 运行时数据、事件、变量适配
|
||||
- `src/App.tsx` 只负责挂载共享页面主体
|
||||
- `style.css` / `src/index.css` 尽量只做样式桥接，不重复堆业务样式
|
||||
- 在 `index.tsx`、`src/App.tsx`、`src/main.tsx` 顶部写职责注释，提醒后续维护者不要让入口漂移
|
||||
|
||||
执行本技能后的最终项目必须符合这套固定结构；如果当前输出仍是双入口各自维护一套页面逻辑，视为转换未完成。
|
||||
|
||||
### 页面组件规范
|
||||
|
||||
默认先转换为普通 React 页面组件。只有明确需要接入 Axhub / Axure 运行时能力时，才额外引入 `forwardRef` 和 `axure-types`。
|
||||
|
||||
推荐格式：
|
||||
|
||||
```tsx
|
||||
import './style.css';
|
||||
import React from 'react';
|
||||
|
||||
export default function PageName() {
|
||||
return <div />;
|
||||
}
|
||||
```
|
||||
|
||||
### 入口收敛
|
||||
|
||||
- 优先从 `src/App.tsx` 收敛为本项目的 `index.tsx`
|
||||
- `src/main.tsx` 只作为原始挂载入口参考，不保留为最终运行入口
|
||||
- 若 `src/pages/` + 路由很多，最终仍要收敛为本项目单入口页面组件
|
||||
- 如果页面后续还要重新导出为 Figma 资产，务必反向维护一个与根目录 `index.tsx` 同步的导出壳子 `src/App.tsx`
|
||||
- 最稳妥的方式是让 `src/App.tsx` 尽量薄，只做包装或直接复用当前页面组件，避免出现两套页面逻辑长期漂移
|
||||
|
||||
### 路径与 alias
|
||||
|
||||
- `@/` 统一视为 `./src`
|
||||
- 若源码里还残留 `package@version` 导入，继续改为裸包名
|
||||
- `vite.config.ts` 可以保留作参考，但最终组件不能依赖其中 alias 才能运行
|
||||
|
||||
## 样式处理规则
|
||||
|
||||
Figma Make 的 `src/index.css` 常常是 Tailwind v4 构建产物，默认不要直接搬运为最终 `style.css`。
|
||||
|
||||
### `style.css` 生成策略
|
||||
|
||||
最终页面的 `style.css` 采用：
|
||||
|
||||
```css
|
||||
@import "tailwindcss";
|
||||
```
|
||||
|
||||
然后以 `src/styles/globals.css` 为主要样式来源继续整理。
|
||||
|
||||
规则：
|
||||
- `src/styles/globals.css` 是主样式来源
|
||||
- `src/index.css` 只作为视觉回归参考
|
||||
- 若 `globals.css` 缺失，再结合组件现有样式补齐
|
||||
- 如果页面后续还要重新导出 `.fig`，需要同时保证导出壳子使用的 `src/index.css` 与最终 `style.css` 保持一致，至少不能明显漂移
|
||||
|
||||
## 依赖处理
|
||||
|
||||
保留需要的运行依赖，默认排除：
|
||||
- `react`
|
||||
- `react-dom`
|
||||
- `next-themes`
|
||||
|
||||
如果分析报告里有这些包以外的依赖，按需执行：
|
||||
|
||||
```bash
|
||||
pnpm add <依赖名>
|
||||
```
|
||||
|
||||
## 主题导入规则
|
||||
|
||||
当目标是 `themes` 时，优先从以下来源提取 token：
|
||||
- `DESIGN_SYSTEM_GUIDE.md`
|
||||
- `TOKEN_REFERENCE.md`
|
||||
- `src/styles/globals.css`
|
||||
- 组件里的 CSS 变量和设计语义
|
||||
|
||||
期望产物：
|
||||
- `src/themes/<theme-key>/globals.css` 或 `designToken.json`
|
||||
- `src/themes/<theme-key>/DESIGN-SPEC.md`
|
||||
- `src/themes/<theme-key>/index.tsx`
|
||||
|
||||
同时可按需补充：
|
||||
- `src/docs/`
|
||||
- `src/database/`
|
||||
|
||||
## 验收标准
|
||||
|
||||
页面模式：
|
||||
|
||||
```bash
|
||||
node scripts/check-app-ready.mjs /prototypes/<page-name>
|
||||
```
|
||||
|
||||
验收要求：
|
||||
- 页面正常渲染
|
||||
- 无控制台错误
|
||||
- 主视觉与原项目基本一致
|
||||
- 不再依赖原始 Vite alias 才能运行
|
||||
|
||||
主题模式：
|
||||
- token 文件存在且结构完整
|
||||
- `DESIGN-SPEC.md` 说明清晰
|
||||
- 主题演示入口能体现核心 token 效果
|
||||
|
||||
## 常见注意点
|
||||
|
||||
- 不要把 `src/index.css` 直接当最终 `style.css`
|
||||
- 不要继续保留对 `package@version` alias 的运行时依赖
|
||||
- 不要把完整多页面路由壳层原封不动塞进最终页面组件
|
||||
- 优先利用设计文档和 CSS 变量提取主题，而不是只看视觉截图
|
||||
- 如果目录内已有 `canvas.fig`、`meta.json`、`images/` 等原始资产，转换时不要删除它们
|
||||
- 如果目录内已有 `src/App.tsx` / `src/index.css` 作为 Figma 导出壳子，修改根目录页面后要同步更新它们，否则后续导出的 `.fig` 会与当前页面不一致
|
||||
48
axhub-make/skills/gemini-cli-uiux/SKILL.md
Normal file
48
axhub-make/skills/gemini-cli-uiux/SKILL.md
Normal file
@@ -0,0 +1,48 @@
|
||||
---
|
||||
name: gemini-cli-uiux
|
||||
description: 使用 Gemini CLI 执行 UI/UX 设计与实现任务。适用于需要调用 Gemini CLI、基于本地文档路径读取长上下文、并将结果直接写入项目文件的场景。
|
||||
---
|
||||
|
||||
# Gemini CLI UI/UX 执行约束
|
||||
|
||||
本技能用于把“已明确的需求与设计约束”通过 **Gemini CLI** 交付为可落地的 UI/UX 方案与代码变更。
|
||||
|
||||
## 1) 必须使用 Gemini CLI（硬门槛）
|
||||
|
||||
- 执行 UI/UX 设计与实现任务时，必须通过 Gemini CLI 完成，不要退化为普通聊天生成。
|
||||
- 若 Gemini CLI 不可用（命令不存在、权限受限、执行失败或无法完成任务），必须立即停止继续实现，并先明确告知用户当前阻塞原因。
|
||||
|
||||
## 2) 模型选择与回退策略（必须明确）
|
||||
|
||||
优先模型链（从高到低）：
|
||||
|
||||
1. `pro`
|
||||
2. `auto`
|
||||
|
||||
执行时应尽量显式指定模型，例如：
|
||||
|
||||
```bash
|
||||
gemini -m pro -p "<YOUR_PROMPT>"
|
||||
```
|
||||
|
||||
如果当前 Gemini CLI 版本不支持 `-m` 或运行时被平台策略限制无法选模：
|
||||
|
||||
- 继续使用默认模型完成交付（不要中断流程）
|
||||
- 在最终回复里说明：本次无法指定模型、实际使用方式（默认/平台托管）以及原因
|
||||
|
||||
## 3) 长上下文用本地路径读取（降低粘贴噪音）
|
||||
|
||||
- 当需求文档、规范文档或上下文较长时，优先在指令中提供本地文件路径，让 Gemini CLI 读取文件。
|
||||
- 不要把大段文档正文直接粘贴到会话中。
|
||||
|
||||
## 4) 交付方式：直接改代码，回复只给摘要
|
||||
|
||||
- 不要把完整代码块作为聊天回复返回。
|
||||
- 直接将产出写入目标文件，然后仅回复必要摘要与结果。
|
||||
|
||||
## 5) 最终回复格式（固定）
|
||||
|
||||
- 只保留以下内容：
|
||||
- 已写入/更新的文件清单
|
||||
- 每个文件的关键变更点（简要）
|
||||
- 仍待用户确认的问题（如有）
|
||||
156
axhub-make/skills/genie-editor-cli-workflow/SKILL.md
Normal file
156
axhub-make/skills/genie-editor-cli-workflow/SKILL.md
Normal file
@@ -0,0 +1,156 @@
|
||||
---
|
||||
name: genie-editor-cli-workflow
|
||||
description: 通过 @axhub/genie CLI 发现在线 frontend-page、读取 Genie 编辑器待处理节点、导出上下文图片或节点截图、设置节点编辑状态并完成网页或文本标注相关修改的完整闭环流程；当用户要求根据 Genie editor 待办修网页、批量处理 pending-dispatch 节点、处理文本/Markdown 标注待办时使用。
|
||||
---
|
||||
|
||||
# Genie Editor CLI 网页 / 文本标注修改规范
|
||||
|
||||
先读编辑器待办 → 改页面或文本 → 回写状态 → 复核剩余待办。
|
||||
|
||||
## 前置条件
|
||||
|
||||
需要 `@axhub/genie` ≥ 0.2.2。如果用户尚未安装或启动，提示：
|
||||
|
||||
```bash
|
||||
# 安装（首次）
|
||||
npm install -g @axhub/genie
|
||||
|
||||
# 启动服务（指定项目目录）
|
||||
npx @axhub/genie --cwd /path/to/project
|
||||
|
||||
# 确认服务在线
|
||||
npx @axhub/genie status --json
|
||||
```
|
||||
|
||||
如果 `status --json` 返回 `running: false` 或命令不存在，立即告诉用户当前阻塞点，不要假装继续。
|
||||
|
||||
## 快速分流
|
||||
|
||||
- 需要具体命令模板和字段说明 → 打开 `references/cli-reference.md`
|
||||
- 需要处理网页编辑器待办并改代码 → 直接按下方主流程执行
|
||||
|
||||
## 主流程
|
||||
|
||||
### 1. 确认服务可用
|
||||
|
||||
```bash
|
||||
npx @axhub/genie status --json
|
||||
```
|
||||
|
||||
确认 `running: true` 后，记录本次任务使用的 `channel`、`targetClientId`。
|
||||
|
||||
### 2. 找客户端，锁定目标页面
|
||||
|
||||
```bash
|
||||
npx @axhub/genie editor clients list --channel <channel>
|
||||
```
|
||||
|
||||
- 只有一个客户端 → 直接使用
|
||||
- 多个客户端 → 用 `pageUrl`、`sessionId`、用户给出的 `targetClientId` 缩小范围
|
||||
- 无法安全判断 → 向用户补一个简短问题
|
||||
|
||||
整个任务复用同一个 `channel + targetClientId`。
|
||||
|
||||
### 3. 全局扫描
|
||||
|
||||
至少拿这两份数据：
|
||||
|
||||
```bash
|
||||
npx @axhub/genie editor snapshot --channel <ch> --target-client-id <id>
|
||||
npx @axhub/genie editor nodes list --channel <ch> --target-client-id <id> --status pending-dispatch,dirty
|
||||
```
|
||||
|
||||
按此优先级处理节点：`pending-dispatch` → `dirty` → `error` → 疑似卡住的 `editing`。
|
||||
|
||||
扫描结果为空时，告诉用户当前没有可消费的 editor 待办，不要硬编待办。
|
||||
|
||||
### 4. 领取节点（editing）
|
||||
|
||||
开始处理某节点前：
|
||||
|
||||
```bash
|
||||
npx @axhub/genie editor editing set \
|
||||
--channel <ch> --target-client-id <id> \
|
||||
--element-key <key> --state editing \
|
||||
--provider codex --task-request-id <unique-id>
|
||||
```
|
||||
|
||||
要求：
|
||||
- 每个节点生成唯一 `taskRequestId`
|
||||
- `provider` 固定用 `codex`
|
||||
- 无论成功失败，结束时都要发一次 `--state idle`（当作 `finally` 语义）
|
||||
|
||||
### 5. 收集上下文，决定怎么改
|
||||
|
||||
每个节点至少看 `elementKey`、`label`、`changeState`、`taskState`、`hasNote`、`hasImages`、`changeKinds`。
|
||||
|
||||
按需补充：
|
||||
1. 有上下文图片 → `editor context-images export`
|
||||
2. 节点位置不明确 → `editor node screenshot`
|
||||
3. 截图返回的是 `absolutePath`，直接用 `view_file` 查看
|
||||
|
||||
注意 `context-images` 是页面级共享上下文，不一定能精确映射到单个节点。
|
||||
|
||||
### 6. 实施代码修改
|
||||
|
||||
拿到节点信息后，在当前项目里完成编辑。
|
||||
|
||||
原则：
|
||||
- 优先处理用户明确要求或影响最大的节点
|
||||
- 多个节点属于同一块 UI → 合并为一个实现批次
|
||||
- 多个节点互相独立 → 可拆给子代理（仅负责实现，不负责客户端发现和状态回写）
|
||||
- 无法安全定位节点 → 先截图 → 再交叉判断 → 仍不行就告诉用户阻塞点
|
||||
|
||||
### 7. 验证
|
||||
|
||||
至少做一轮回读：
|
||||
|
||||
```bash
|
||||
npx @axhub/genie editor snapshot --channel <ch> --target-client-id <id>
|
||||
npx @axhub/genie editor nodes list --channel <ch> --target-client-id <id> --status pending-dispatch,dirty,error,editing
|
||||
```
|
||||
|
||||
如果节点代码已改但 backlog 仍显示 `dirty`/`pending-dispatch`，不要假装已完成。明确说明：
|
||||
- 页面实现已完成
|
||||
- 编辑器 backlog 仍显示未消费
|
||||
- 当前 CLI `editing.set` 只支持 `editing`/`idle` 两种状态值
|
||||
|
||||
### 8. 释放 editing 状态
|
||||
|
||||
对每个已领取节点：
|
||||
|
||||
```bash
|
||||
npx @axhub/genie editor editing set \
|
||||
--channel <ch> --target-client-id <id> \
|
||||
--element-key <key> --state idle \
|
||||
--provider codex --task-request-id <unique-id>
|
||||
```
|
||||
|
||||
任务未完成也要释放，同时在总结里写清未完成原因。
|
||||
|
||||
## 多节点并行策略
|
||||
|
||||
适合并行：不同页面区块、改动文件不重叠、上下文已足够清楚。
|
||||
|
||||
不适合并行：同一组件树深度耦合、依赖同一套重构、还没搞清各节点位置。
|
||||
|
||||
主代理保留：客户端选择、节点领取/释放、最终复核。
|
||||
|
||||
## 失败处理
|
||||
|
||||
遇到服务离线、找不到客户端、节点不存在、截图失败、无法定位节点等情况，优先说明问题，不要伪造完成。
|
||||
|
||||
部分完成时，清楚列出已完成/未完成节点及原因。
|
||||
|
||||
## 交付要求
|
||||
|
||||
最终回复至少包含：
|
||||
- 使用的 `channel + targetClientId`
|
||||
- 本轮处理过的 `elementKey`
|
||||
- 修改了哪些文件
|
||||
- 做了哪些验证
|
||||
- 还有哪些节点仍未处理或状态异常
|
||||
|
||||
## 参考
|
||||
|
||||
- `references/cli-reference.md`
|
||||
@@ -0,0 +1,205 @@
|
||||
# CLI 命令参考
|
||||
|
||||
所有命令通过 `npx @axhub/genie` 调用，要求版本 ≥ 0.2.1。
|
||||
|
||||
建议在 shell 中定义变量减少重复输入：
|
||||
|
||||
```bash
|
||||
CHANNEL="project-a"
|
||||
TARGET_CLIENT_ID=""
|
||||
```
|
||||
|
||||
## 1. 服务检查
|
||||
|
||||
```bash
|
||||
npx @axhub/genie status --json
|
||||
```
|
||||
|
||||
确认 `running: true`，记录 `endpoint.apiBaseUrl`。
|
||||
|
||||
## 2. 列出在线客户端
|
||||
|
||||
```bash
|
||||
npx @axhub/genie editor clients list \
|
||||
--channel "$CHANNEL"
|
||||
```
|
||||
|
||||
重点关注：`clientId`、`sessionId`、`pageUrl`、`capabilities`。
|
||||
|
||||
只有目标客户端在线且具备 `editor.*` 能力时，后续命令才有意义。
|
||||
|
||||
## 3. 获取编辑器快照
|
||||
|
||||
```bash
|
||||
npx @axhub/genie editor snapshot \
|
||||
--channel "$CHANNEL" \
|
||||
--target-client-id "$TARGET_CLIENT_ID"
|
||||
```
|
||||
|
||||
关注字段：`resource`、`selectedElement`、`modifiedElements`、`textChanges`、`styleChanges`、`statusSummary`。
|
||||
|
||||
## 4. 列出待处理节点
|
||||
|
||||
### 处理待办
|
||||
|
||||
```bash
|
||||
npx @axhub/genie editor nodes list \
|
||||
--channel "$CHANNEL" \
|
||||
--target-client-id "$TARGET_CLIENT_ID" \
|
||||
--status pending-dispatch,dirty
|
||||
```
|
||||
|
||||
### 排查卡住节点
|
||||
|
||||
```bash
|
||||
npx @axhub/genie editor nodes list \
|
||||
--channel "$CHANNEL" \
|
||||
--target-client-id "$TARGET_CLIENT_ID" \
|
||||
--status editing,error,completed
|
||||
```
|
||||
|
||||
### 精确查询
|
||||
|
||||
```bash
|
||||
npx @axhub/genie editor nodes list \
|
||||
--channel "$CHANNEL" \
|
||||
--target-client-id "$TARGET_CLIENT_ID" \
|
||||
--element-key "hero-card"
|
||||
```
|
||||
|
||||
每个节点的关键字段：
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `elementKey` | 节点唯一标识 |
|
||||
| `label` | CSS 选择器路径 |
|
||||
| `changeState` | `clean` / `dirty` / `handled` |
|
||||
| `taskState` | `idle` / `editing` / `completed` / `error` |
|
||||
| `hasNote` | 是否有标注文字 |
|
||||
| `hasImages` | 是否附带图片 |
|
||||
| `changeKinds` | 修改类型：`text` / `style` / `class` |
|
||||
| `dirtySince` | 变脏时间戳 |
|
||||
| `lastHandledAt` | 上次处理时间 |
|
||||
|
||||
状态别名：
|
||||
|
||||
- `pending-dispatch` = `changeState=dirty && taskState=idle`
|
||||
- `dirty` / `handled` / `editing` / `completed` / `error` 直接匹配对应字段
|
||||
|
||||
## 5. 节点截图
|
||||
|
||||
```bash
|
||||
npx @axhub/genie editor node screenshot \
|
||||
--channel "$CHANNEL" \
|
||||
--target-client-id "$TARGET_CLIENT_ID" \
|
||||
--element-key "hero-card" \
|
||||
--output-dir /tmp/axhub-genie-shot
|
||||
```
|
||||
|
||||
返回 `absolutePath`（本地文件路径）、`mimeType`、`width`、`height`、`size`。
|
||||
|
||||
用途：仅靠 `label` 无法定位节点时，通过截图视觉确认。
|
||||
|
||||
## 6. 导出上下文图片
|
||||
|
||||
```bash
|
||||
npx @axhub/genie editor context-images export \
|
||||
--channel "$CHANNEL" \
|
||||
--target-client-id "$TARGET_CLIENT_ID" \
|
||||
--output-dir /tmp/axhub-genie-context
|
||||
```
|
||||
|
||||
返回每张图片的 `absolutePath`、`mimeType`、`size`。
|
||||
|
||||
注意：这是页面级共享上下文，未必能精准映射到单个 `elementKey`，需结合 note、label、截图交叉判断。
|
||||
|
||||
## 7. 设置节点编辑状态
|
||||
|
||||
### 开始处理
|
||||
|
||||
```bash
|
||||
npx @axhub/genie editor editing set \
|
||||
--channel "$CHANNEL" \
|
||||
--target-client-id "$TARGET_CLIENT_ID" \
|
||||
--element-key "hero-card" \
|
||||
--state editing \
|
||||
--provider codex \
|
||||
--task-request-id "codex_hero-card_$(date +%s)"
|
||||
```
|
||||
|
||||
### 处理结束
|
||||
|
||||
```bash
|
||||
npx @axhub/genie editor editing set \
|
||||
--channel "$CHANNEL" \
|
||||
--target-client-id "$TARGET_CLIENT_ID" \
|
||||
--element-key "hero-card" \
|
||||
--state idle \
|
||||
--provider codex \
|
||||
--task-request-id "codex_hero-card_done_$(date +%s)"
|
||||
```
|
||||
|
||||
说明：
|
||||
- `--state` 只允许 `editing` 或 `idle`
|
||||
- `editing.set` 控制 `taskState`，不直接改变 `changeState`
|
||||
- 结束后仍需重新读 `nodes list` 确认节点最终状态
|
||||
|
||||
## 8. 推荐执行顺序
|
||||
|
||||
```bash
|
||||
npx @axhub/genie status --json
|
||||
npx @axhub/genie editor clients list --channel "$CHANNEL"
|
||||
npx @axhub/genie editor snapshot --channel "$CHANNEL" --target-client-id "$TARGET_CLIENT_ID"
|
||||
npx @axhub/genie editor nodes list --channel "$CHANNEL" --target-client-id "$TARGET_CLIENT_ID" --status pending-dispatch,dirty
|
||||
```
|
||||
|
||||
然后按节点循环：
|
||||
|
||||
1. `editor editing set --state editing`
|
||||
2. 如有需要，拉 `context-images export`
|
||||
3. 如仍难定位，拉 `node screenshot`
|
||||
4. 修改代码
|
||||
5. 重新拉 `snapshot` 与 `nodes list`
|
||||
6. `editor editing set --state idle`
|
||||
|
||||
## 9. 最终复核
|
||||
|
||||
结束前至少再跑一次：
|
||||
|
||||
```bash
|
||||
npx @axhub/genie editor nodes list \
|
||||
--channel "$CHANNEL" \
|
||||
--target-client-id "$TARGET_CLIENT_ID" \
|
||||
--status pending-dispatch,dirty,error,editing
|
||||
```
|
||||
|
||||
如果列表仍有项，区分说明：
|
||||
- 页面改动是否已完成
|
||||
- 编辑器 backlog 是否仍残留
|
||||
- 哪些节点只是退出了 `editing`，但仍是 `dirty`
|
||||
|
||||
## 10. CLI 通用参数
|
||||
|
||||
| 参数 | 说明 |
|
||||
|------|------|
|
||||
| `--api-base <url>` | 显式指定 API Base，默认自动发现 |
|
||||
| `--api-key <key>` | API Key（如开启鉴权） |
|
||||
| `--channel <name>` | 目标业务通道 |
|
||||
| `--target-client-id <id>` | 目标前端页面实例 |
|
||||
| `--timeout-ms <ms>` | 请求超时 |
|
||||
| `--json` | 显式声明 JSON 输出（editor 命令默认 JSON） |
|
||||
| `--output-dir <path>` | 截图/图片导出目录 |
|
||||
|
||||
统一成功返回格式：
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"requestId": "editor_001",
|
||||
"channel": "project-a",
|
||||
"targetClientId": "figma-123",
|
||||
"data": { ... }
|
||||
}
|
||||
```
|
||||
|
||||
失败时 `ok: false` + `error.code` + `error.message`，CLI 以非 0 退出码结束。
|
||||
241
axhub-make/skills/local-axure-workflow/SKILL.md
Normal file
241
axhub-make/skills/local-axure-workflow/SKILL.md
Normal file
@@ -0,0 +1,241 @@
|
||||
---
|
||||
name: local-axure-workflow
|
||||
description: 处理本地导出的 Axure 原型资源并生成主题、数据模型与页面还原的流程规范；在需要基于 sitemap.json 与本地页面资源进行分析与还原时使用。
|
||||
---
|
||||
|
||||
# 本地 Axure 资源处理规范
|
||||
|
||||
处理本地导出的 Axure 原型资源，包括主题提取、数据模型识别和页面还原。
|
||||
|
||||
## 核心能力
|
||||
|
||||
1. **主题提取与合并**：从多个页面提取 design tokens，合并生成统一主题文件
|
||||
2. **数据模型识别**：从页面内容识别数据结构，生成数据库文件
|
||||
3. **页面还原**：基于截图、主题、内容的精确还原
|
||||
4. **MCP 补充**：可选使用 MCP 工具获取在线资源（如 sitemap.json 包含 projectUrl）
|
||||
|
||||
## 本地资源目录结构
|
||||
|
||||
```
|
||||
<project-dir>/
|
||||
├── sitemap.json # 站点地图
|
||||
└── page-<index>-<name>/ # 页面目录
|
||||
├── assets/
|
||||
│ ├── images/ # 图片资源
|
||||
│ └── fonts/ # 字体资源（如有）
|
||||
├── theme.json # 设计令牌（Top10）
|
||||
├── content.md # 页面内容（Markdown）
|
||||
└── screenshot.png # 页面截图
|
||||
```
|
||||
|
||||
### 关键文件说明
|
||||
|
||||
- **sitemap.json**：项目名称、页面列表、原型 URL（如有）
|
||||
- **theme.json**：设计令牌（colors、typography、spacing、radius、shadow 等）
|
||||
- **doms.toon**：DOM 节点映射（TOON 格式，仅在需要精确还原时使用）
|
||||
- **styles.toon**：样式池（TOON 格式，仅在需要完整样式时使用）
|
||||
- **content.md**：页面内容（Markdown 格式）
|
||||
- **screenshot.png**：页面截图（还原主要依据）
|
||||
|
||||
## 工作流程
|
||||
|
||||
### 阶段 0：定位资源目录
|
||||
|
||||
用户未提供目录路径时，使用 `listDirectory` 工具查找 `temp/` 下的项目目录（通常在二级目录下包含 sitemap.json）。找到后读取 sitemap.json 获取项目名称，询问用户是否处理该项目；如不是则请求提供正确路径。
|
||||
|
||||
### 阶段 1：识别资源
|
||||
|
||||
验证目录结构（检查 sitemap.json），解析站点地图，明确用户需求（默认：提取主题、识别数据、生成文档）。
|
||||
|
||||
### 阶段 2：提取设计主题
|
||||
|
||||
选择 3-5 个核心页面（首页、登录页、主要功能页），读取各页面的 `theme.json` 并结合 `screenshot.png` 分析视觉风格，合并主题数据（颜色、字体、间距、圆角、阴影），总结设计语言并生成设计规范。
|
||||
|
||||
**输出**：`src/themes/<theme-key>/`（包含 `globals.css` 或 `designToken.json`（designToken.json 必须包含 `name` 字段）、`DESIGN.md`、`index.tsx`，符合 `theme-guide.md` 规范）
|
||||
|
||||
### 阶段 3：识别数据模型
|
||||
|
||||
识别数据密集型页面（列表页、表单页、详情页），读取 `content.md` 提取文本内容，从表格列名、表单标签、重复模式中识别数据结构，跨页面验证并合并字段。
|
||||
|
||||
**输出**：`src/database/<table-name>.json`
|
||||
- 文件名使用英文（如 `users.json`）
|
||||
- `tableName` 使用中文（如 "用户表"）
|
||||
|
||||
**数据表结构（强约束）**：每个文件必须是 JSON 对象（不要输出为纯数组），包含 `tableName` + `records`。
|
||||
|
||||
```json
|
||||
{
|
||||
"tableName": "表名（中文）",
|
||||
"records": [
|
||||
{ "id": 1, "字段1": "值1", "字段2": "值2" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**最小一致性规则（用于减少错误）**：
|
||||
- `records` 必须是数组；每条记录必须包含唯一的 `id`（允许 number 或 string，同表保持类型一致）。
|
||||
- 字段名优先中文并与页面一致；同义字段不混用（如“手机号/手机号码”二选一）。
|
||||
- 同字段同类型；图片字段用相对路径（如 `images/xxx.png`），不要 base64。
|
||||
|
||||
### 阶段 4：生成项目文档
|
||||
|
||||
生成站点地图文档（保持层级结构，页面名称可点击）和项目简介文档（基本信息、设计风格、数据模型概览）。
|
||||
|
||||
**输出**：`src/docs/`
|
||||
|
||||
## 页面还原指南
|
||||
|
||||
选择还原页面（用户指定或从站点地图选择 1-2 个核心页面）。
|
||||
|
||||
**核心方法**：看图 → 写代码 → 交付。
|
||||
|
||||
### 核心流程（必须跑完）
|
||||
|
||||
1. **确认前置条件**
|
||||
- 确认模型支持视觉识别（不支持则立即告知用户）
|
||||
- 确认可以直接读取图片内容（不需要转换，不支持则立即告知用户）
|
||||
- 生成页面名称（规范：小写字母、数字、连字符）
|
||||
|
||||
2. **获取截图**
|
||||
- 本地优先：使用页面目录下的 `screenshot.png`
|
||||
- 若本地缺失且 `sitemap.json` 含 `projectUrl`，可使用 MCP 获取在线截图（仅在本地不足时）
|
||||
|
||||
3. **验证图片读取能力**
|
||||
- 尝试读取 `screenshot.png`
|
||||
- **如果无法直接读取本地图片**（工具不支持或返回错误），必须：
|
||||
- 立即停止流程
|
||||
- 告知用户："无法读取本地图片，请将 `[图片绝对路径]` 复制到对话框后提交"
|
||||
- 等待用户提交图片后再继续
|
||||
- 禁止假设或猜测图片内容
|
||||
- 禁止通过 Base64 编码读取图片内容
|
||||
|
||||
4. **生成页面代码**
|
||||
|
||||
**辅助数据获取**（可选，生成仍以图片为主）：
|
||||
- 主题：`theme.json`（校验样式）
|
||||
- 文本：`content.md`（校验文案）
|
||||
|
||||
- 直接基于截图生成页面代码
|
||||
- 在代码生成过程中内部完成：
|
||||
- 识别布局结构（Header/Sidebar/Content 等）
|
||||
- 识别组件（Button/Input/Table/Card 等）
|
||||
- 提取样式（颜色、字体、间距、圆角、阴影等）
|
||||
- 识别交互（点击、悬停、状态切换等）
|
||||
|
||||
**输出文件**：
|
||||
- `src/prototypes/<page-name>/index.tsx`
|
||||
- `src/prototypes/<page-name>/style.css`（必须包含 `@import "tailwindcss";`）
|
||||
- `src/prototypes/<page-name>/components/`（根据需要）
|
||||
|
||||
**核心代码规范**（必须遵守）：
|
||||
- 变量名必须是 `Component`，使用 `export default Component`
|
||||
- 详细规范见 `rules/development-guide.md`
|
||||
|
||||
5. **验收页面还原**
|
||||
- 运行验收命令：`node scripts/check-app-ready.mjs /prototypes/[页面名]`
|
||||
- 提供预览 URL
|
||||
- 确认页面基础功能正常（无编译错误、可正常访问）
|
||||
|
||||
6. **生成规格文档**
|
||||
- 基于已验收通过的页面代码生成规格文档
|
||||
- 输出文件：`src/prototypes/<page-name>/spec.md`
|
||||
- 文档内容应包括：
|
||||
- 页面结构说明
|
||||
- 组件清单
|
||||
- 样式规范（颜色、字体、间距等）
|
||||
- 交互说明
|
||||
- 数据需求（如有）
|
||||
|
||||
7. **最终交付**
|
||||
- 告知用户页面还原和规格文档已完成
|
||||
- 说明可进行二次生成（修复问题或优化重构）
|
||||
|
||||
### 还原策略（本地数据优先级）
|
||||
|
||||
1. **截图**（最高优先级）：视觉识别布局、颜色、间距。
|
||||
2. **主题**：应用 `theme.json` 的 design tokens。
|
||||
3. **内容**：用 `content.md` 校准文案（不影响布局与交互）。
|
||||
4. **节点细节**：仅在需要精确结构/定位时使用 `doms.toon`。
|
||||
5. **基础设计走查与修复**：按设计与前端规范检查明显问题并修复；若修复会改变原设计意图，先向用户确认。
|
||||
|
||||
### 默认目标与可选优化
|
||||
|
||||
- **默认目标**：在用户未提出额外要求时，尽量 1:1 像素级还原截图/原型的视觉与布局（不主动“改版”）。
|
||||
- **可选优化**：如需同时做“优化设计/交互”，请在需求里明确说明；否则仅做还原与基础走查修复。
|
||||
|
||||
**输出**：符合 `rules/development-guide.md` 规范的页面组件
|
||||
|
||||
|
||||
## MCP 工具补充
|
||||
|
||||
sitemap.json 包含 projectUrl 时，可使用本项目MCP 工具获取在线资源（本地资源优先，仅在不足或需要最新数据时使用）。
|
||||
|
||||
## 用户交互指南
|
||||
|
||||
### 目录验证失败
|
||||
|
||||
```
|
||||
⚠️ 未找到有效的 Axure 资源目录。
|
||||
请确认目录包含 sitemap.json 和页面目录。
|
||||
```
|
||||
|
||||
### 需求确认
|
||||
|
||||
```
|
||||
✓ 已识别资源目录，共 [X] 个页面。
|
||||
|
||||
默认方案：
|
||||
- 从核心页面提取设计主题并生成设计规范文档
|
||||
- 识别数据模型
|
||||
- 生成项目文档
|
||||
|
||||
回复"接受"按默认方案执行，或告诉我您的具体需求。
|
||||
```
|
||||
|
||||
### 进度通知
|
||||
|
||||
```
|
||||
正在处理...
|
||||
✓ 已解析站点地图
|
||||
✓ 已提取主题数据
|
||||
⏳ 正在分析数据模型...
|
||||
```
|
||||
|
||||
### 完成总结
|
||||
|
||||
```
|
||||
✅ 已完成！
|
||||
|
||||
生成的资产：
|
||||
- 设计主题：src/themes/<theme-key>/
|
||||
- 设计规范文档：src/themes/<theme-key>/DESIGN.md
|
||||
- 数据模型：src/database/
|
||||
- 项目文档：src/docs/
|
||||
|
||||
后续建议：
|
||||
💡 我还可以为您：
|
||||
- 还原页面：告诉我需要还原的页面名称
|
||||
- 生成业务文档：领域模型、业务流程等
|
||||
|
||||
需要吗？
|
||||
```
|
||||
|
||||
### 关键原则
|
||||
|
||||
- 主动查找 temp 目录下的最新资源
|
||||
- 主动确认重要操作
|
||||
- 及时反馈进度
|
||||
- 清晰总结成果
|
||||
- 提供选项而非强制
|
||||
- 友好处理错误
|
||||
- 引导后续操作
|
||||
|
||||
## 注意事项
|
||||
|
||||
- TOON 数据量大，仅在必要时解析
|
||||
- 主题提取使用 3-5 个页面，数据模型需跨页面验证
|
||||
- 页面还原以截图为主要依据
|
||||
|
||||
## 参考
|
||||
|
||||
`theme-guide.md` | `development-guide.md`
|
||||
79
axhub-make/skills/pencil-import-workflow/SKILL.md
Normal file
79
axhub-make/skills/pencil-import-workflow/SKILL.md
Normal file
@@ -0,0 +1,79 @@
|
||||
---
|
||||
name: pencil-import-workflow
|
||||
description: 使用 Pencil MCP 读取当前打开的 .pen 文件与 Frame（无需上传），让用户确认导入范围与输出结构后，生成 Axhub Make 原型目录（spec.md + index.tsx）并验收。
|
||||
---
|
||||
|
||||
# Pencil 导入工作流
|
||||
|
||||
本技能用于“从 Pencil 设计稿导入并生成 Axhub Make 原型代码”的交互编排。
|
||||
重点是：**先通过 MCP 读取当前打开的 Pencil 文件与 Frame，再让用户确认导入范围与输出结构，最后才写文件**。
|
||||
|
||||
## 前置条件
|
||||
|
||||
1. Pencil 桌面端已打开目标 `.pen` 文件
|
||||
2. MCP 已可用（如不可用参考：`/skills/mcp-installer/SKILL.md`）
|
||||
|
||||
## 标准流程（必须按顺序）
|
||||
|
||||
### 1) 检测 Pencil MCP 可用性
|
||||
|
||||
- 优先调用：`mcp__pencil__get_editor_state`
|
||||
- 若不确定工具前缀/命名空间：先使用 MCP 的 `list_tools`（或等价能力）列出可用工具，找到 pencil 相关工具后再调用
|
||||
- 若工具不可用/调用失败：
|
||||
- 停止后续步骤
|
||||
- 提示用户打开 Pencil 并选中目标 Frame 后重试
|
||||
|
||||
### 2) 获取当前 selection 与候选 Frame
|
||||
|
||||
- 若 selection 中包含 Frame：候选 = selection Frames
|
||||
- 若 selection 为空或不是 Frame：
|
||||
- 使用 `mcp__pencil__batch_get` 在当前文件中搜索/列出 Frame 候选（“已有的 frame”）
|
||||
|
||||
输出给用户的候选信息至少包含：
|
||||
- 序号
|
||||
- frameId
|
||||
- frameName
|
||||
- 尺寸（若可得）
|
||||
|
||||
候选较少时（可选）：使用 `mcp__pencil__get_screenshot` 辅助用户辨认。
|
||||
|
||||
如果候选过多导致无法确认：
|
||||
- 要求用户回到 Pencil 先选中需要导入的 Frame（可多选）
|
||||
- 然后重新读取 selection
|
||||
|
||||
### 3) 让用户确认（阻塞点，确认前不写文件）
|
||||
|
||||
必须等待用户明确回答以下 2 类问题：
|
||||
|
||||
1. 导入范围：全部 / 子集（用序号或 frameId 指定）/ 回到 Pencil 重新选择
|
||||
2. 输出结构（二选一，不要推荐）：
|
||||
- A. 单原型多屏：生成 1 个 `src/prototypes/<name>/`，在 `index.tsx` 内提供导航切换各 Screen
|
||||
- B. 多原型批量：每个 Frame 生成 1 个 `src/prototypes/<proto-name>/`
|
||||
|
||||
同时确认命名规则：
|
||||
- `<name>` / `<proto-name>` 如何从 Frame 名称派生为 kebab-case
|
||||
- 重名冲突处理规则（后缀、序号或用户指定）
|
||||
|
||||
### 4) 生成原型产物
|
||||
|
||||
对每个生成的原型目录，至少输出：
|
||||
- `src/prototypes/<name>/spec.md`
|
||||
- `src/prototypes/<name>/index.tsx`
|
||||
- （可选）`src/prototypes/<name>/style.css`
|
||||
|
||||
`spec.md` 必须记录 Pencil 来源信息（可得则写）：
|
||||
- `.pen` 标识/路径（若能获取）
|
||||
- 导入的 frameId 列表、frameName 列表
|
||||
- Screen 到实现模块的映射
|
||||
|
||||
> 如需更强的“先完成原型、再 1:1 回建 Pencil 并强制后续同步”约束，可参考：`/skills/pencil-sync-after-prototype-workflow/SKILL.md`（技能名：`pencil-sync-after-prototype-workflow`）。
|
||||
|
||||
### 5) 验收
|
||||
|
||||
对每个生成的原型运行：
|
||||
|
||||
```bash
|
||||
node scripts/check-app-ready.mjs /prototypes/<name>
|
||||
```
|
||||
|
||||
直到状态为 `READY`。
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
name: pencil-sync-after-prototype-workflow
|
||||
description: 在本项目新建或重构 `src/prototypes/*`、`src/components/*` 时，执行“先按既有流程完成原型，再 1:1 创建 Pencil 文件，并强制后续同步”的编排约束；当需要为已完成原型补齐 Pencil 设计稿或维护代码与设计双向同步时使用。
|
||||
---
|
||||
|
||||
# 原型后置 Pencil 同步
|
||||
|
||||
本技能只补充顺序约束，不重复已有细节规范。
|
||||
|
||||
## MCP 前置检查（必须）
|
||||
|
||||
在执行任何生成 `.pen` / 截图验收相关工作前：
|
||||
|
||||
1. 先尝试调用任意 Pencil MCP 工具（例如 `get_editor_state` / `open_document` / `get_screenshot`）。
|
||||
2. 若 MCP 工具不可用或调用失败：立刻停止后续步骤，并告知用户需要先开启/安装本项目 MCP 环境（至少要能调用 Pencil MCP），否则无法继续生成设计稿。
|
||||
|
||||
## 触发条件
|
||||
|
||||
- 新建 `prototype/component`
|
||||
- 原型已按既有流程完成，需要补齐对应 Pencil 设计稿
|
||||
- 既有页面结构重做，必须同步更新代码与 Pencil
|
||||
|
||||
## 流程 + 检查（合并）
|
||||
|
||||
1. 准备目标路径
|
||||
- 目标目录：`src/prototypes/<name>/` 或 `src/components/<name>/`
|
||||
- `<name>` 使用小写字母、数字、连字符
|
||||
|
||||
2. 先按既有流程完成原型
|
||||
- 先按现有规则完成 `spec.md`
|
||||
- 再完成 `index.tsx`
|
||||
- 运行验收命令，确保当前原型已可交付
|
||||
|
||||
3. 再完成 `.pen`（阻塞步骤）
|
||||
- 在目标目录生成 `<name>.pen`
|
||||
- 以当前已完成的 `spec.md` + `index.tsx` 为唯一基线，1:1 回建 Pencil 文件
|
||||
- 结构、尺寸、区块层级、文案、主要交互命名必须与现有原型一致
|
||||
- 若 `.pen` 与 `spec.md` / `index.tsx` 不一致，先修正差异再继续
|
||||
|
||||
4. 回写 `spec.md`
|
||||
- 补充 Pencil 信息：`.pen` 路径、主画板、模块映射
|
||||
- 明确记录该目录进入“代码/Pencil 双向同步”维护状态
|
||||
|
||||
5. 在 `index.tsx` 顶部补充同步注释
|
||||
- 文件顶部必须增加注释，明确说明：更新当前原型时，必须同步更新同目录的 `.pen` 与 `spec.md`
|
||||
- 注释需包含具体文件名 `<name>.pen`，避免后续维护遗漏
|
||||
|
||||
6. 后续更新约束
|
||||
- 以后任何对 `spec.md`、`.pen`、`index.tsx` 的修改，都必须三者同步
|
||||
- 若只改了代码未改 Pencil，不视为完成交付
|
||||
|
||||
## 验收命令
|
||||
|
||||
```bash
|
||||
node scripts/check-app-ready.mjs /prototypes/<name>
|
||||
node scripts/check-app-ready.mjs /components/<name>
|
||||
```
|
||||
|
||||
## 交付定义
|
||||
|
||||
- 必须同时存在并同步：`spec.md`、`.pen`、`index.tsx`
|
||||
- `index.tsx` 顶部必须存在 Pencil 同步注释
|
||||
- `check-app-ready.mjs` 结果为 `READY`
|
||||
- 交付时返回三个文件路径
|
||||
131
axhub-make/skills/project-guide/SKILL.md
Normal file
131
axhub-make/skills/project-guide/SKILL.md
Normal file
@@ -0,0 +1,131 @@
|
||||
---
|
||||
name: project-guide
|
||||
description: Axhub Make 项目全流程引导 — 判断项目状态，指导用户高效使用
|
||||
---
|
||||
|
||||
# Axhub Make 项目引导
|
||||
|
||||
你正在协助用户使用 Axhub Make。请先阅读 `AGENTS.md` 获取项目工作流程和规范索引。
|
||||
|
||||
## 📚 项目参考资料
|
||||
|
||||
用户遇到问题时，可以在以下位置查找答案：
|
||||
|
||||
| 位置 | 作用 |
|
||||
|------|------|
|
||||
| `AGENTS.md` | 项目总入口，描述工作流程（新建原型、资源管理）、重要原则和项目结构 |
|
||||
| `rules/` | 各领域的详细规范：开发规范、设计规范、文档规范、主题规范、调试指南等 |
|
||||
| `scripts/` | 构建脚本与工具脚本：入口扫描、批量构建、代码审查、格式转换等自动化工具 |
|
||||
| `skills/` | 项目技能与工作流：包含创建原型、主题、文档、数据表、设计审查、记忆沉淀等完整操作流程 |
|
||||
|
||||
---
|
||||
|
||||
## 🔍 项目状态检测
|
||||
|
||||
当用户意图不明确、是新人、或请求指导时，执行以下检查：
|
||||
|
||||
### 检查 1：是否为新项目
|
||||
|
||||
- 查看 `src/prototypes/` 目录
|
||||
- 目录为空或仅包含 `ref-*` 前缀的参考原型 → **新项目**
|
||||
- 存在用户自己创建的原型 → **已有项目**
|
||||
|
||||
### 检查 2：项目信息是否完善
|
||||
|
||||
- 读取 `.axhub/make/axhub.config.json` 中的 `projectInfo.name` 和 `projectInfo.description`
|
||||
- 如果为空或为默认值 → **建议补充项目名称和一句话简介**
|
||||
|
||||
### 检查 3：是否有默认主题
|
||||
|
||||
- 查看 `src/themes/` 目录是否有主题文件夹
|
||||
- 没有 → **建议创建并设置默认主题**
|
||||
- 有主题但未设置默认 → **建议设置默认主题**
|
||||
|
||||
### 检查 4：内容是否需要沉淀
|
||||
|
||||
- 对比原型数量与文档/数据表数量
|
||||
- 原型较多但 `src/docs/` 和 `src/database/` 内容较少 → **建议整理项目文档和数据表**
|
||||
|
||||
### 检查 5：设计是否需要 Review
|
||||
|
||||
- 有新增或近期修改的原型且未进行过 review → **建议进行一次设计 Review**
|
||||
|
||||
### 检查 6：是否开启 Git 版本管理（仅已有项目）
|
||||
|
||||
> 此检查仅在判定为"已有项目"（非新人引导）时执行。
|
||||
|
||||
- 检查项目根目录是否存在 `.git` 目录
|
||||
- 不存在 → **建议用户开启 Git 版本管理**，说明好处：
|
||||
- 防止误操作导致代码丢失，可随时回退到任意历史版本
|
||||
- 方便追踪每次修改的内容和原因
|
||||
- 支持多人协作时的分支管理
|
||||
- 已存在 → 无需额外操作
|
||||
|
||||
## 🚀 推荐流程
|
||||
|
||||
### 新项目用户
|
||||
|
||||
1. **补充项目基本信息** — 名称和一句话简介
|
||||
2. **先试试创建 1-2 个原型**
|
||||
3. **创建主题**（前几个原型之后）
|
||||
4. **逐步扩展到 5-10 个模块/页面**
|
||||
|
||||
### 已有项目用户（最佳实践循环）
|
||||
|
||||
```
|
||||
完善项目信息（名称、简介）
|
||||
↓
|
||||
创建并设置默认主题（如果没有）
|
||||
↓
|
||||
创建 5-10 个功能模块/页面原型
|
||||
↓
|
||||
定期让 AI Review 设计一致性
|
||||
↓
|
||||
沉淀项目资产（整理文档、数据、主题）
|
||||
↓
|
||||
创建更多原型 → Review → 沉淀 → 循环
|
||||
```
|
||||
|
||||
### 推荐检查点
|
||||
|
||||
| 阶段 | 触发条件 | 推荐动作 |
|
||||
|------|----------|----------|
|
||||
| 起步 | 新项目，无任何原型 | 先创建 1-2 个原型 |
|
||||
| 基础 | 有 2-3 个原型但无主题 | 创建默认主题 |
|
||||
| 扩展 | 有主题、3+ 原型 | 扩展到 5-10 个模块 |
|
||||
| 整理 | 5+ 原型但文档/数据少 | 沉淀文档和数据 |
|
||||
| 审查 | 有新增原型未 review | 设计 Review |
|
||||
| 循环 | 以上均完成 | 继续迭代 |
|
||||
|
||||
## 💬 对话技巧
|
||||
|
||||
| 主题 | 建议 | 理由 |
|
||||
| --- | --- | --- |
|
||||
| 沟通素材 | 尽量多给截图；方便的话用语音输入法描述需求 | 视觉信息比文字描述更精确，语音输入效率比打字高 3-5 倍 |
|
||||
| 会话方式 | 一个任务一个对话窗口，避免多任务混在一起 | 上下文越集中，AI 的输出质量越高；混合任务容易导致遗漏和互相干扰 |
|
||||
| 资料提供 | 手里有链接、截图、文档的优先给 | 减少 AI 猜测和反复确认，一次给足参考能显著减少来回轮次 |
|
||||
| MCP 工具 | 建议安装 Chrome DevTools MCP 或 Playwright MCP | AI 可直接检查和操控浏览器，省去"帮我截个图看看"的来回沟通 |
|
||||
|
||||
## 💡 推荐模型
|
||||
|
||||
| 模型 | 特点 |
|
||||
|------|------|
|
||||
| Claude Opus 4.6 | 综合能力强，代码和推理均优秀，首选推荐 |
|
||||
| Gemini 2.5 Pro | Google 旗舰，长上下文处理出色 |
|
||||
| GPT-5.4 | OpenAI 最新，指令遵循能力强 |
|
||||
| Kimi K2.5 | 中文理解优秀，适合中文密集场景 |
|
||||
| GLM-5.1 | 国产开源榜首，免费可用 |
|
||||
|
||||
## 📋 首次回复模板
|
||||
|
||||
```text
|
||||
我可以先带你一起用 Axhub Make 开始工作。
|
||||
|
||||
先给你几个重要的建议：
|
||||
1. 尽量多给我截图、链接或文档，还有使用语音输入，提高沟通效率
|
||||
2. 一个任务尽量放在一个对话里，效果会更稳定
|
||||
|
||||
如果你愿意，顺手告诉我这个项目的名称，或者用一句话介绍它是做什么的、给谁用。我可以先帮你整理并写进项目配置。
|
||||
|
||||
我们现在就可以先试试生成一个原型，或者先一起整理现有项目资料。
|
||||
```
|
||||
185
axhub-make/skills/project-memory/SKILL.md
Normal file
185
axhub-make/skills/project-memory/SKILL.md
Normal file
@@ -0,0 +1,185 @@
|
||||
---
|
||||
name: project-memory
|
||||
description: 项目整理 — 整理项目文档、主题、数据等后置资源，保持项目资产清晰可追溯
|
||||
---
|
||||
|
||||
# 项目整理
|
||||
|
||||
本技能定义项目整理的变更检测、维护顺序、边界约束与日志要求。
|
||||
|
||||
## 🎯 目标
|
||||
|
||||
- 在不重复劳动的前提下持续维护项目的文档、主题、数据等后置资源
|
||||
- 保持项目资产结构清晰、可追溯、可渐进扩展
|
||||
- 通过日志记录维护动作，为后续协作提供依据
|
||||
|
||||
## 🔍 变更检测（增量扫描）
|
||||
|
||||
执行项目整理时，首先执行**增量变更检测**，而不是全量维护。
|
||||
|
||||
### 范围确定
|
||||
|
||||
用户可能附带范围说明，Agent 需按以下优先级确定扫描范围：
|
||||
|
||||
1. **用户明确指定范围**：用户直接点明了目标，例如：
|
||||
- "帮我整理一下首页相关的文档"→ 仅扫描首页原型及其关联资源
|
||||
- "同步一下主题和数据"→ 仅扫描 `src/themes/` 和 `src/database/`
|
||||
- "更新 xxx-page 的文档"→ 仅扫描该原型及其关联文档
|
||||
2. **用户模糊描述**：用户给出了方向但未精确指定，例如：
|
||||
- "最近改的那些页面帮我整理一下"→ 按时间戳扫描最近变更的原型/组件
|
||||
- "把文档都更新一下"→ 扫描所有文档及其关联的原型变更
|
||||
3. **用户未指定范围（默认）**：执行全量增量扫描（见下方默认检测流程）
|
||||
|
||||
### 默认检测流程
|
||||
|
||||
当用户未指定范围时，执行以下默认流程：
|
||||
|
||||
1. **读取上次执行时间**：从 `src/docs/memory-log.md` 中获取最后一条日志的时间戳
|
||||
2. **扫描变更文件**：以该时间戳为基准，检测自上次执行以来发生变更的文件
|
||||
- 默认扫描范围：`src/components/`、`src/prototypes/`、`src/themes/`、`src/database/`、`src/docs/`、`src/common/`
|
||||
- 使用 `find` 或 `git diff --name-only` 等方式获取变更文件列表
|
||||
3. **分类变更**：将变更文件按类型归类
|
||||
- 原型 / 组件变更（`src/prototypes/`、`src/components/`）
|
||||
- 文档变更（`src/docs/`）
|
||||
- 主题变更（`src/themes/`）
|
||||
- 数据变更（`src/database/`）
|
||||
- 公共模块变更（`src/common/`）
|
||||
4. **生成建议清单**：根据变更文件关联分析，给出需要更新的建议
|
||||
|
||||
### 建议清单格式
|
||||
|
||||
向用户展示变更检测结果，格式如下：
|
||||
|
||||
```text
|
||||
📋 上次项目整理：YYYY-MM-DD HH:mm
|
||||
📝 检测到以下变更：
|
||||
|
||||
🔸 原型/组件变更：
|
||||
- xxx-page（新增 / 修改）
|
||||
- yyy-component（修改）
|
||||
|
||||
🔸 建议更新：
|
||||
- [ ] 更新 project-overview.md 索引（新增了 xxx-page）
|
||||
- [ ] 更新 page-map.md（页面结构变化）
|
||||
- [ ] 同步 xxx 主题配置（关联组件已变更）
|
||||
- [ ] 更新 orders.json 数据（页面数据源变化）
|
||||
|
||||
是否按以上建议执行？
|
||||
```
|
||||
|
||||
### 首次执行
|
||||
|
||||
若 `memory-log.md` 不存在或为空（首次执行），则执行全量扫描，建议初始化所有后置资源。
|
||||
|
||||
## 🚦 执行边界
|
||||
|
||||
- 项目整理只处理页面或原型完成后的后置补充工作
|
||||
- 不回头重做页面、原型或其主体实现
|
||||
- 若已有文档结构不合理，可合并、拆分或补充子文档，但要保留总入口可追溯性
|
||||
- 仅更新与变更文件相关的后置资源，不做无关的全量刷新
|
||||
- 对用户沟通时，优先使用"我可以继续帮你整理并记住 xxx"这类自然表达
|
||||
|
||||
## 🧭 固定维护顺序
|
||||
|
||||
用户确认建议清单后，按以下顺序执行（仅执行与变更相关的步骤）：
|
||||
|
||||
### 1. Git 快照
|
||||
|
||||
- 先检查项目是否启用 git 版本管理
|
||||
- 若是 git 仓库且存在未提交改动，先提交当前未提交版本
|
||||
- 若无未提交改动，则跳过
|
||||
- 快照提交信息固定格式：
|
||||
|
||||
```text
|
||||
chore: snapshot before project-memory <YYYY-MM-DD HH:mm>
|
||||
```
|
||||
|
||||
### 2. 项目说明入口
|
||||
|
||||
- 检查 `src/docs/project-overview.md` 是否存在
|
||||
- 若不存在，则基于模板创建
|
||||
- 若存在，则**仅更新与本次变更相关的部分**（如新增页面索引、调整阅读顺序等）
|
||||
- `src/docs/project-overview.md` 必须保持轻量，只承担"项目总览 + 阅读索引 + 关键待办"职责
|
||||
- 建议每次维护时顺手检查一次该文件行数
|
||||
- 当该文件出现以下任一情况时，必须重新整理并优化：
|
||||
- 文件行数已达到或超过 `1000` 行
|
||||
- 明显可以拆分到专题子文档后再由总入口做索引
|
||||
- 优化原则：优先采用"分包拆分 + 摘要汇总"的方式处理，保留高价值摘要，把细节迁移到专题子文档，在总入口中只保留索引、结论和必要待办；不使用单纯删减式压缩来处理主文档
|
||||
- 优化目标：应通过拆分专题文档与收敛摘要，把总入口优先控制在 `800` 行以内
|
||||
|
||||
### 3. 子文档维护
|
||||
|
||||
- **仅维护与本次变更相关的专题子文档**
|
||||
- 根据变更检测结果判断哪些子文档需要更新
|
||||
- 优先维护以下建议文档（按需）：
|
||||
- `page-map.md`
|
||||
- `information-architecture.md`
|
||||
- `business-flow.md`
|
||||
- `data-model.md`
|
||||
- `permission-model.md`
|
||||
- `state-lifecycle.md`
|
||||
|
||||
### 4. 主题维护
|
||||
|
||||
- 仅在变更检测发现主题相关变更时执行
|
||||
- 若项目已有主题，更新主题文档、主题索引与相关引用
|
||||
- 若项目尚无主题，但当前场景需要主题支撑，则创建最小主题骨架
|
||||
- 主题默认维护位置：`src/themes/`
|
||||
|
||||
### 5. 数据维护
|
||||
|
||||
- 仅在变更检测发现数据相关变更时执行
|
||||
- 更新 `src/database/` 中与页面、文档、主题相关的数据
|
||||
- 数据文件必须遵循 `src/database/README.md`
|
||||
- 维护后需同步更新总入口中的数据索引
|
||||
|
||||
### 6. 维护日志
|
||||
|
||||
- 每次项目整理都要追加维护日志
|
||||
- 日志默认文件：`src/docs/memory-log.md`
|
||||
- 日志模板来源：`src/docs/templates/memory-log-template.md`
|
||||
- 日志采用紧凑格式，一行一条，避免长段自然语言说明
|
||||
- 当 `src/docs/memory-log.md` 达到或超过 `1000` 行时，必须先删除最旧的 `100` 行业务日志，再追加一条 `trim` 日志记录本次裁剪动作，最后再写入本次维护日志
|
||||
- 裁剪日志也属于正式日志，不能省略
|
||||
- 除命中上述裁剪规则外，日志只追加，不改写历史
|
||||
|
||||
## 📝 日志格式
|
||||
|
||||
日志固定为单行，字段顺序如下：
|
||||
|
||||
```text
|
||||
YYYY-MM-DD HH:mm | kind | sum | doc | theme | data | git | todo
|
||||
```
|
||||
|
||||
字段要求：
|
||||
|
||||
- `kind`：`upd` 表示普通维护，`trim` 表示日志裁剪
|
||||
- `sum`：更新摘要，尽量控制在 `20` 字以内
|
||||
- `doc`：文档变更，只写文件名、专题名或 `-`
|
||||
- `theme`：主题变更，只写主题名、目录名或 `-`
|
||||
- `data`：数据变更，只写数据文件名、表名或 `-`
|
||||
- `git`：短提交号或 `-`
|
||||
- `todo`：后续待办或 `-`
|
||||
|
||||
记录原则：
|
||||
|
||||
- 能用短词就不用长句，能用文件名就不用解释性段落
|
||||
- 未变化字段统一写 `-`
|
||||
- 若一次改动较多，优先记录"入口文档 / 主题 / 数据"的关键索引，不在日志中展开细节
|
||||
|
||||
示例：
|
||||
|
||||
```text
|
||||
2026-03-16 14:20 | upd | 更新总览索引 | project-overview,page-map | - | orders.json | a1b2c3d | 补权限模型
|
||||
2026-03-16 14:25 | trim | 删旧100行 | - | - | - | - | 保留较新记录
|
||||
```
|
||||
|
||||
## ✨ 质量检查点
|
||||
|
||||
- [ ] 已执行增量变更检测并展示建议清单
|
||||
- [ ] 用户已确认建议清单
|
||||
- [ ] 若为 git 仓库且存在未提交改动，已先做快照提交
|
||||
- [ ] 已检查或维护 `src/docs/project-overview.md`（仅变更相关部分）
|
||||
- [ ] 已按需调整专题子文档结构（仅变更相关部分）
|
||||
- [ ] 已同步维护主题与数据（仅变更相关部分）
|
||||
- [ ] 已按紧凑格式追加 `src/docs/memory-log.md`
|
||||
28
axhub-make/skills/screenshot-page-workflow/SKILL.md
Normal file
28
axhub-make/skills/screenshot-page-workflow/SKILL.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
name: screenshot-page-workflow
|
||||
description: 基于网页或 App 截图进行视觉分析与原型还原的流程规范；在需要截图识别、资产提取（功能/交互/业务分析）、页面代码生成与验收时使用。
|
||||
---
|
||||
|
||||
# 截图原型还原规范
|
||||
|
||||
本技能采用渐进披露：先判断用户需求，再只打开相关文档。
|
||||
|
||||
## 快速分流
|
||||
|
||||
- 资产提取（功能/交互/业务分析）：`skills/screenshot-page-workflow/asset-extraction.md`
|
||||
- 原型还原/代码实现：`skills/screenshot-page-workflow/prototype-restoration.md`
|
||||
|
||||
## 通用前置（任何场景都需要）
|
||||
|
||||
1. 视觉能力检测：模型不支持视觉时必须立即告知用户并停止截图流程。
|
||||
2. 接收截图：支持拖拽/粘贴/路径；临时保存到 `temp/screenshots/`。
|
||||
|
||||
## 通用约束
|
||||
|
||||
- 截图分析完全依赖视觉能力，不支持时不得继续。
|
||||
- 未经用户确认不扩展需求。
|
||||
- 及时说明当前进度与限制。
|
||||
|
||||
## 参考资源
|
||||
|
||||
- `development-guide.md`
|
||||
149
axhub-make/skills/screenshot-page-workflow/asset-extraction.md
Normal file
149
axhub-make/skills/screenshot-page-workflow/asset-extraction.md
Normal file
@@ -0,0 +1,149 @@
|
||||
# 截图资产提取流程
|
||||
|
||||
目标：基于截图进行视觉分析，产出设计主题、设计规范文档与数据模型等资产。只描述“做什么”（WHAT），不描述“如何实现”（HOW）。
|
||||
|
||||
## 工作流程
|
||||
|
||||
### 1) 视觉能力检测
|
||||
|
||||
模型不支持视觉时，用户提供截图后立即告知并停止
|
||||
|
||||
### 2) 接收截图
|
||||
|
||||
- 支持拖拽/粘贴/路径提供的截图
|
||||
- 优先收集 3-5 个核心页面（首页/登录/主要功能页）以便识别统一视觉语言
|
||||
- 临时保存到 `temp/screenshots/` 并验证文件格式和大小
|
||||
|
||||
### 3) 本地图片读取能力验证
|
||||
|
||||
- 尝试读取已提供的本地截图文件
|
||||
- **如果无法直接读取本地图片**（工具不支持或返回错误），必须：
|
||||
- 立即停止流程
|
||||
- 告知用户："无法读取本地图片，请将 `[图片绝对路径]` 复制到对话框后提交"
|
||||
- 等待用户提交图片后再继续
|
||||
- 禁止假设或猜测图片内容
|
||||
- 禁止通过 Base64 编码读取图片内容
|
||||
### 4) 视觉分析（截图为最高优先级）
|
||||
|
||||
**文本内容**
|
||||
- 识别可见文本
|
||||
- 判断文本层级（标题、正文、辅助文本）
|
||||
- 理解文本语义与上下文
|
||||
|
||||
**布局结构**
|
||||
- 整体布局方式（栅格、弹性布局）
|
||||
- 区域划分与层级关系
|
||||
- 组件排列与对齐方式
|
||||
|
||||
**组件识别**
|
||||
- 识别 UI 组件类型（按钮、输入框、卡片、导航等）
|
||||
- 组件状态（默认、悬停、禁用等）
|
||||
- 交互元素与功能
|
||||
|
||||
**设计细节**
|
||||
- 字体样式与大小
|
||||
- 间距和留白
|
||||
- 圆角和边框
|
||||
- 阴影和层次
|
||||
- 颜色使用与主题
|
||||
- 设计语言总结（品牌气质、视觉关键词、形状语言、排版节奏、组件风格）
|
||||
|
||||
### 5) 提取设计主题
|
||||
|
||||
基于视觉分析提取设计系统：
|
||||
|
||||
**颜色系统**
|
||||
- 主色/辅助色/中性色
|
||||
- 生成色阶（50-900）
|
||||
- 语义化颜色（成功/警告/错误）
|
||||
|
||||
**排版系统**
|
||||
- 字体家族和权重
|
||||
- 字号层级
|
||||
- 行高和字间距
|
||||
|
||||
**间距系统**
|
||||
- 常用间距值
|
||||
- 间距规范
|
||||
|
||||
**其他 Token**
|
||||
- 圆角规范
|
||||
- 阴影层级
|
||||
- 边框样式
|
||||
|
||||
**输出位置**：`src/themes/<theme-key>/`
|
||||
**必需文件**：
|
||||
- `globals.css` 或 `designToken.json`（`designToken.json` 必须包含 `name` 字段，二选一，遵循 `theme-guide.md`）
|
||||
- `DESIGN.md`（基于多页面截图总结设计规范）
|
||||
- `index.tsx`（主题演示页）
|
||||
|
||||
### 6) 提取数据模型（可选）
|
||||
|
||||
截图包含列表/表格/表单时识别数据结构并生成数据库文件。
|
||||
|
||||
**输出位置**：`src/database/`
|
||||
**文件命名**：英文文件名（如 `users.json`、`products.json`）
|
||||
|
||||
**文件格式**：
|
||||
```json
|
||||
{
|
||||
"tableName": "表名（中文）",
|
||||
"records": [
|
||||
{ "id": 1, "字段1": "值1", "字段2": "值2" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**关键原则**：
|
||||
- 文件名使用英文；`tableName` 使用中文。
|
||||
- 字段名优先中文。
|
||||
- 从截图提取真实数据，不足时生成合理模拟数据。
|
||||
- 每个表生成 10-30 条记录。
|
||||
|
||||
## 默认方案（用户未明确需求时）
|
||||
|
||||
- 提取设计主题并生成设计规范文档
|
||||
- 识别数据模型（如有）
|
||||
|
||||
## 用户交互指南
|
||||
|
||||
### 初始对话
|
||||
|
||||
```
|
||||
您好！我可以帮您基于截图提取资产（设计主题 / 设计规范文档 / 数据模型）。
|
||||
|
||||
请提供截图，我将通过视觉分析提取资产。
|
||||
```
|
||||
|
||||
### 需求确认
|
||||
|
||||
```
|
||||
✓ 已分析截图。
|
||||
|
||||
默认方案：
|
||||
- 提取设计主题并生成设计规范文档
|
||||
- 识别数据模型（如有）
|
||||
|
||||
回复"接受"按默认方案执行，或告诉我您的具体需求。
|
||||
```
|
||||
|
||||
### 进度通知
|
||||
|
||||
```
|
||||
正在分析截图...
|
||||
✓ 已识别文本和布局结构
|
||||
✓ 已分析组件类型和设计细节
|
||||
✓ 已提取设计主题
|
||||
⏳ 正在生成数据模型...
|
||||
```
|
||||
|
||||
### 完成总结
|
||||
|
||||
```
|
||||
✅ 已完成！
|
||||
|
||||
生成的资产：
|
||||
- 设计主题：src/themes/<theme-key>/
|
||||
- 设计规范文档：src/themes/<theme-key>/DESIGN.md
|
||||
- 数据模型：src/database/（如有）
|
||||
```
|
||||
@@ -0,0 +1,85 @@
|
||||
# 截图页面还原与实现
|
||||
|
||||
基于截图生成可维护的页面代码资产。
|
||||
|
||||
**核心方法**：看图 → 写代码 → 交付。
|
||||
|
||||
## 默认目标与可选优化
|
||||
|
||||
- **默认目标**：在用户未提出额外要求时，尽量 1:1 像素级还原截图的视觉与布局（不主动“改版”）。
|
||||
- **可选优化**：如需我同时做“优化设计/交互”（信息结构调整、视觉升级、交互补全、可用性优化等），请在需求里明确说明；否则仅做还原与基础走查修复。
|
||||
|
||||
## 核心流程
|
||||
|
||||
1. **确认前置条件**
|
||||
- 确认模型支持视觉识别（不支持则立即告知用户）
|
||||
- 确认可以直接读取图片内容（不需要转换，不支持则立即告知用户）
|
||||
- 生成页面名称（规范：小写字母、数字、连字符）
|
||||
|
||||
2. **获取截图**
|
||||
- 使用用户提供的截图（本地路径或对话中上传）
|
||||
- 如仅提供外链或不可读路径，需请用户提供可读的本地文件或重新上传
|
||||
|
||||
3. **验证图片读取能力**
|
||||
- 尝试读取已提供的截图文件
|
||||
- **如果无法直接读取本地图片**（工具不支持或返回错误），必须：
|
||||
- 立即停止流程
|
||||
- 告知用户："无法读取本地图片，请将 `[图片绝对路径]` 复制到对话框后提交"
|
||||
- 等待用户提交图片后再继续
|
||||
- 禁止假设或猜测图片内容
|
||||
- 禁止通过 Base64 编码读取图片内容
|
||||
|
||||
4. **生成页面代码**
|
||||
|
||||
- 直接基于截图生成页面代码
|
||||
- 在代码生成过程中内部完成：
|
||||
- 识别布局结构（Header/Sidebar/Content 等）
|
||||
- 识别组件（Button/Input/Table/Card 等）
|
||||
- 提取样式（颜色、字体、间距、圆角、阴影等）
|
||||
- 识别交互（点击、悬停、状态切换等）
|
||||
|
||||
**输出文件**：
|
||||
- `src/prototypes/<page-name>/index.tsx`
|
||||
- `src/prototypes/<page-name>/style.css`（必须包含 `@import "tailwindcss";`）
|
||||
- `src/prototypes/<page-name>/components/`（根据需要）
|
||||
|
||||
**核心代码规范**（必须遵守）：
|
||||
```typescript
|
||||
// index.tsx 结构
|
||||
/**
|
||||
* @name 页面显示名称
|
||||
*/
|
||||
import './style.css';
|
||||
import React from 'react';
|
||||
|
||||
const Component = function PageName() {
|
||||
return <div>...</div>;
|
||||
};
|
||||
|
||||
export default Component;
|
||||
```
|
||||
```css
|
||||
/* style.css 必须以此开头 */
|
||||
@import "tailwindcss";
|
||||
```
|
||||
- 变量名必须是 `Component`，使用 `export default Component`
|
||||
- 详细规范见 `rules/development-guide.md`
|
||||
|
||||
5. **验收页面还原**
|
||||
- 运行验收命令：`node scripts/check-app-ready.mjs /prototypes/[页面名]`
|
||||
- 提供预览 URL
|
||||
- 确认页面基础功能正常（无编译错误、可正常访问）
|
||||
|
||||
6. **生成规格文档**
|
||||
- 基于已验收通过的页面代码生成规格文档
|
||||
- 输出文件：`src/prototypes/<page-name>/spec.md`
|
||||
- 文档内容应包括：
|
||||
- 页面结构说明
|
||||
- 组件清单
|
||||
- 样式规范（颜色、字体、间距等）
|
||||
- 交互说明
|
||||
- 数据需求（如有）
|
||||
|
||||
7. **最终交付**
|
||||
- 告知用户页面还原和规格文档已完成
|
||||
- 说明可进行二次生成（修复问题或优化重构）
|
||||
81
axhub-make/skills/skills-management/SKILL.md
Normal file
81
axhub-make/skills/skills-management/SKILL.md
Normal file
@@ -0,0 +1,81 @@
|
||||
---
|
||||
name: skills-management
|
||||
description: Axhub Make 技能管理入口，用于维护项目技能清单、技能分类与技能文档，并在修改前执行备份。
|
||||
---
|
||||
|
||||
# 技能管理
|
||||
|
||||
你正在协助用户维护 Axhub Make 项目的技能体系。
|
||||
|
||||
## 核心原则
|
||||
|
||||
- 修改任何技能清单或技能文档前，必须先做备份。
|
||||
- 先判断用户要改的是“官方默认清单”还是“用户自定义清单”。
|
||||
- 用户自定义清单存在时，程序优先读取它；不存在时才回退到对应的 `*.default.json`。
|
||||
- 如果用户想恢复官方默认技能，优先从对应的 `*.default.json` 和官方 skill 目录取回内容。
|
||||
|
||||
## 修改前备份
|
||||
|
||||
在执行任何修改前，先创建时间戳备份目录：
|
||||
|
||||
```bash
|
||||
mkdir -p .axhub/make/backups/skills/<timestamp>/
|
||||
```
|
||||
|
||||
默认备份对象：
|
||||
|
||||
- 当前要修改的 manifest 文件
|
||||
- 当前要修改的 skill 目录
|
||||
|
||||
备份时保留原相对路径，便于后续直接恢复。
|
||||
|
||||
## 判断规则
|
||||
|
||||
### 情况 1：用户要改“官方默认”
|
||||
|
||||
适用场景：
|
||||
|
||||
- “这个技能默认就要带上”
|
||||
- “我们发布给所有项目都要有”
|
||||
- “恢复官方默认技能列表”
|
||||
|
||||
处理方式：
|
||||
|
||||
- 读取 `./references/skill-asset-map.md`
|
||||
- 修改对应的 `*.default.json`
|
||||
- 如果涉及技能正文，修改 `apps/axhub-make/skills/<skill-id>/`
|
||||
|
||||
### 情况 2：用户要改“当前项目自定义”
|
||||
|
||||
适用场景：
|
||||
|
||||
- “只在我这个项目里改”
|
||||
- “不要影响后续默认发布”
|
||||
- “我自己先覆盖一下技能列表”
|
||||
|
||||
处理方式：
|
||||
|
||||
- 读取 `./references/change-playbook.md`
|
||||
- 修改对应的不带 `.default` 的 manifest 文件
|
||||
- 若该自定义清单不存在，先参考对应的 `*.default.json` 创建完整副本，再在此基础上修改
|
||||
|
||||
> 注意：自定义清单一旦存在，就会完整替代对应的默认清单；它不是增量补丁。
|
||||
|
||||
## 恢复官方默认技能
|
||||
|
||||
如果用户要把某个技能恢复为官方默认状态：
|
||||
|
||||
1. 打开对应的 `*.default.json`
|
||||
2. 找到目标技能条目
|
||||
3. 打开官方技能目录 `apps/axhub-make/skills/<skill-id>/`
|
||||
4. 将默认条目和官方 skill 文档重新复制到用户当前需要维护的位置
|
||||
|
||||
如果用户当前已经有自定义 manifest，推荐做法是：
|
||||
|
||||
- 先用对应的 `*.default.json` 作为基底复制出完整清单
|
||||
- 再把用户仍然需要的自定义改动重新加回去
|
||||
|
||||
## 引用文档
|
||||
|
||||
- `./references/skill-asset-map.md`
|
||||
- `./references/change-playbook.md`
|
||||
@@ -0,0 +1,93 @@
|
||||
# 技能维护操作手册
|
||||
|
||||
## 修改前统一备份
|
||||
|
||||
先创建备份目录：
|
||||
|
||||
```bash
|
||||
mkdir -p .axhub/make/backups/skills/<timestamp>/
|
||||
```
|
||||
|
||||
然后备份本次要改的内容：
|
||||
|
||||
- manifest 文件
|
||||
- skill 目录
|
||||
|
||||
建议保留原相对路径，便于恢复。
|
||||
|
||||
## 常见操作
|
||||
|
||||
### 1. 新增首页“项目 Skills”卡片
|
||||
|
||||
要改：
|
||||
|
||||
- `apps/axhub-make/.axhub/make/skills/install-skills-manifest.default.json`
|
||||
- 如有新技能正文，再新增 `apps/axhub-make/skills/<skill-id>/`
|
||||
|
||||
适用于“要作为官方默认发布”的情况。
|
||||
|
||||
### 2. 只在当前项目覆盖首页“项目 Skills”
|
||||
|
||||
要改：
|
||||
|
||||
- `apps/axhub-make/.axhub/make/skills/install-skills-manifest.json`
|
||||
|
||||
如果文件不存在：
|
||||
|
||||
- 先参考 `install-skills-manifest.default.json` 创建完整副本
|
||||
- 再按当前项目需要修改
|
||||
|
||||
### 3. 修改新建组件/原型里的技能列表
|
||||
|
||||
官方默认：
|
||||
|
||||
- `skills-manifest.default.json`
|
||||
|
||||
当前项目自定义：
|
||||
|
||||
- `skills-manifest.json`
|
||||
|
||||
### 4. 修改新建文档里的技能列表
|
||||
|
||||
官方默认：
|
||||
|
||||
- `doc-skills-manifest.default.json`
|
||||
|
||||
当前项目自定义：
|
||||
|
||||
- `doc-skills-manifest.json`
|
||||
|
||||
### 5. 修改新建主题里的技能列表
|
||||
|
||||
官方默认：
|
||||
|
||||
- `theme-skills-manifest.default.json`
|
||||
|
||||
当前项目自定义：
|
||||
|
||||
- `theme-skills-manifest.json`
|
||||
|
||||
### 6. 修改某个技能正文
|
||||
|
||||
要改：
|
||||
|
||||
- `apps/axhub-make/skills/<skill-id>/SKILL.md`
|
||||
- `apps/axhub-make/skills/<skill-id>/references/...`
|
||||
|
||||
### 7. 恢复官方默认技能到当前项目
|
||||
|
||||
如果用户想恢复默认：
|
||||
|
||||
1. 打开对应的 `*.default.json`
|
||||
2. 找到需要恢复的技能条目
|
||||
3. 到 `apps/axhub-make/skills/<skill-id>/` 取回官方文档
|
||||
4. 如果当前项目有自定义 manifest，先以 `*.default.json` 为基底重建完整清单，再补回仍需要的自定义项
|
||||
|
||||
## 不要混淆的概念
|
||||
|
||||
- “项目 Skills”卡片列表由 `install-skills-manifest.*.json` 控制
|
||||
- “新建组件 / 原型”技能列表由 `skills-manifest.*.json` 控制
|
||||
- “新建文档”技能列表由 `doc-skills-manifest.*.json` 控制
|
||||
- “新建主题”技能列表由 `theme-skills-manifest.*.json` 控制
|
||||
|
||||
它们不是同一份文件。
|
||||
@@ -0,0 +1,66 @@
|
||||
# 技能资产地图
|
||||
|
||||
本文档说明 Axhub Make 项目里“技能相关资产”分别存放在哪里，以及它们各自控制什么。
|
||||
|
||||
## 官方默认清单
|
||||
|
||||
目录：`apps/axhub-make/.axhub/make/skills/`
|
||||
|
||||
- `skills-manifest.default.json`
|
||||
- 控制“新建组件 / 新建原型”对话框里的技能列表
|
||||
- `doc-skills-manifest.default.json`
|
||||
- 控制“新建文档”流程里的技能列表
|
||||
- `theme-skills-manifest.default.json`
|
||||
- 控制“新建主题”流程里的技能列表
|
||||
- `install-skills-manifest.default.json`
|
||||
- 控制首页“项目 Skills”里的项目技能卡片
|
||||
|
||||
这些文件是官方维护和发布的默认来源。
|
||||
|
||||
## 用户自定义清单
|
||||
|
||||
目录：`apps/axhub-make/.axhub/make/skills/`
|
||||
|
||||
- `skills-manifest.json`
|
||||
- `doc-skills-manifest.json`
|
||||
- `theme-skills-manifest.json`
|
||||
- `install-skills-manifest.json`
|
||||
|
||||
程序读取规则固定为：
|
||||
|
||||
- 先读同名自定义 `.json`
|
||||
- 若不存在，再读对应的 `.default.json`
|
||||
|
||||
> 自定义清单一旦存在，就完整替代对应的默认清单。
|
||||
|
||||
## 官方技能正文目录
|
||||
|
||||
目录：`apps/axhub-make/skills/`
|
||||
|
||||
每个技能的官方正文位于：
|
||||
|
||||
- `apps/axhub-make/skills/<skill-id>/SKILL.md`
|
||||
- `apps/axhub-make/skills/<skill-id>/references/...`
|
||||
|
||||
如果用户要恢复官方默认技能，请从这里获取技能文档与引用文档。
|
||||
|
||||
## 前端读取入口
|
||||
|
||||
桥接文件：
|
||||
|
||||
- `apps/prototype-admin/src/index/config/skillManifests.ts`
|
||||
|
||||
该文件负责在构建时选择“自定义清单”或“默认清单”。
|
||||
|
||||
## 项目 Skills 安装来源
|
||||
|
||||
首页“项目 Skills”安装按钮最终会从以下目录安装技能：
|
||||
|
||||
- `apps/axhub-make/skills/<skill-id>/`
|
||||
|
||||
因此：
|
||||
|
||||
- `install-skills-manifest.default.json` / `install-skills-manifest.json` 里的 `id`
|
||||
- 官方技能目录名 `apps/axhub-make/skills/<skill-id>/`
|
||||
|
||||
这两者必须保持一致。
|
||||
56
axhub-make/skills/third-party/ant-design/SKILL.md
vendored
Normal file
56
axhub-make/skills/third-party/ant-design/SKILL.md
vendored
Normal file
@@ -0,0 +1,56 @@
|
||||
---
|
||||
name: ant-design
|
||||
description: Single-file decision guide for antd 6.x, Ant Design Pro 5/ProComponents, and Ant Design X v2. Use for component selection, theming/tokens, SSR, a11y, performance, routing/access/CRUD, and AI/chat UI patterns.
|
||||
---
|
||||
|
||||
# Ant Design
|
||||
|
||||
## S - Scope
|
||||
- Target: `antd@^6` + React 18-19, with `ant-design-pro@^5` / `@ant-design/pro-components` and `@ant-design/x@^2` when needed.
|
||||
- Focus: decision guidance only; no end-user tutorials.
|
||||
- Source policy: official docs only; no undocumented APIs or internal `.ant-*` coupling.
|
||||
|
||||
### Default assumptions
|
||||
- Language: TypeScript.
|
||||
- Styling: tokens first, then `classNames`/`styles`; avoid global overrides.
|
||||
- Provider: one root `ConfigProvider` unless strict isolation is required.
|
||||
|
||||
### Mandatory rules
|
||||
- For component questions, first map the component name to the official route slug `{components}` (lowercase kebab-case, e.g. `TreeSelect -> tree-select`, `Button -> button`), then request docs in this order (CN first, EN fallback):
|
||||
1. `https://ant.design/components/{components}-cn`
|
||||
2. `https://ant.design/components/{components}`
|
||||
- Examples: `tree-select-cn -> tree-select`, `button-cn -> button`.
|
||||
- Use only documented antd/Pro/X APIs.
|
||||
- Do not invent props/events/component names.
|
||||
- Do not rely on internal DOM or `.ant-*` selectors.
|
||||
- Theme priority: global tokens -> component tokens -> alias tokens.
|
||||
|
||||
## P - Process
|
||||
### 1) Classify
|
||||
- Identify layer: core antd, Pro, or X.
|
||||
- Confirm version, rendering mode (CSR/SSR/streaming), and data scale.
|
||||
|
||||
### 2) Request docs
|
||||
- For each component, request `-cn.md` first, then `.md` fallback.
|
||||
- If multiple components are involved, request each component page before deciding.
|
||||
|
||||
### 3) Decide
|
||||
- Provider baseline: CSR -> `ConfigProvider`; SSR -> `ConfigProvider` + `StyleProvider`.
|
||||
- Theming baseline: global tokens -> component tokens -> `classNames`/`styles`.
|
||||
- Output recommendation + risk + verification points (SSR/a11y/perf).
|
||||
|
||||
## O - Output
|
||||
- Provide short decision rationale (1-3 sentences).
|
||||
- Include minimal provider/theming strategy.
|
||||
- Include concrete SSR/a11y/perf checks.
|
||||
- For Pro: include route/menu/access and CRUD schema direction.
|
||||
- For X: include message/tool schema and streaming state direction.
|
||||
|
||||
## Regression checklist
|
||||
- [ ] One root `ConfigProvider`; SSR style order/hydration verified.
|
||||
- [ ] Tokens first; no broad global `.ant-*` overrides.
|
||||
- [ ] Table has stable `rowKey`; sort/filter/pagination entry is unified.
|
||||
- [ ] Select remote mode disables local filter when using remote search.
|
||||
- [ ] Upload controlled/uncontrolled mode is explicit with failure/retry path.
|
||||
- [ ] Pro route/menu/access remain consistent with backend enforcement.
|
||||
- [ ] X streaming supports stop/retry and deterministic tool rendering.
|
||||
53
axhub-make/skills/third-party/anything-to-notebooklm/.gitignore
vendored
Normal file
53
axhub-make/skills/third-party/anything-to-notebooklm/.gitignore
vendored
Normal file
@@ -0,0 +1,53 @@
|
||||
# Python
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*$py.class
|
||||
*.so
|
||||
.Python
|
||||
env/
|
||||
venv/
|
||||
ENV/
|
||||
build/
|
||||
develop-eggs/
|
||||
dist/
|
||||
downloads/
|
||||
eggs/
|
||||
.eggs/
|
||||
lib/
|
||||
lib64/
|
||||
parts/
|
||||
sdist/
|
||||
var/
|
||||
wheels/
|
||||
*.egg-info/
|
||||
.installed.cfg
|
||||
*.egg
|
||||
|
||||
# MCP Server (will be cloned during install)
|
||||
# Keep the directory but ignore its contents
|
||||
wexin-read-mcp/
|
||||
|
||||
# IDE
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
.DS_Store
|
||||
|
||||
# Logs
|
||||
*.log
|
||||
|
||||
# Environment
|
||||
.env
|
||||
.env.local
|
||||
|
||||
# Temporary files
|
||||
tmp/
|
||||
temp/
|
||||
*.tmp
|
||||
|
||||
# macOS
|
||||
.DS_Store
|
||||
.AppleDouble
|
||||
.LSOverride
|
||||
21
axhub-make/skills/third-party/anything-to-notebooklm/LICENSE
vendored
Normal file
21
axhub-make/skills/third-party/anything-to-notebooklm/LICENSE
vendored
Normal file
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 Joe
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
396
axhub-make/skills/third-party/anything-to-notebooklm/README.md
vendored
Normal file
396
axhub-make/skills/third-party/anything-to-notebooklm/README.md
vendored
Normal file
@@ -0,0 +1,396 @@
|
||||
<div align="center">
|
||||
|
||||
# 🎯 多源内容 → NotebookLM 智能处理器
|
||||
|
||||
**一句话变播客、PPT、思维导图、Quiz...**
|
||||
|
||||
[](https://opensource.org/licenses/MIT)
|
||||
[](https://www.python.org/downloads/)
|
||||
[](http://makeapullrequest.com)
|
||||
[](https://github.com/joeseesun/anything-to-notebooklm/stargazers)
|
||||
[](https://github.com/joeseesun/anything-to-notebooklm/network/members)
|
||||
[](https://github.com/joeseesun/anything-to-notebooklm/issues)
|
||||
[](https://github.com/joeseesun/anything-to-notebooklm/commits/main)
|
||||
|
||||
[快速开始](#-快速开始) • [支持格式](#-支持的内容源) • [使用示例](#-使用示例) • [常见问题](#-常见问题)
|
||||
|
||||
</div>
|
||||
|
||||
---
|
||||
|
||||
## ✨ 这是什么？
|
||||
|
||||
一个 **Claude Code Skill**，让你用自然语言把**任何内容**变成**任何格式**。
|
||||
|
||||
```
|
||||
你说：把这篇微信文章生成播客
|
||||
AI ：✅ 8 分钟播客已生成 → podcast.mp3
|
||||
|
||||
你说：这本 EPUB 电子书做成思维导图
|
||||
AI ：✅ 思维导图已生成 → mindmap.json
|
||||
|
||||
你说：这个 YouTube 视频做成 PPT
|
||||
AI ：✅ 25 页 PPT 已生成 → slides.pdf
|
||||
```
|
||||
|
||||
**原理**：自动从多种来源获取内容 → 上传到 [Google NotebookLM](https://notebooklm.google.com/) → AI 生成你想要的格式
|
||||
|
||||
## 🚀 支持的内容源（15+ 种格式）
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="50%">
|
||||
|
||||
### 📱 社交媒体
|
||||
- **微信公众号**（绕过反爬虫）
|
||||
- **YouTube 视频**（自动提取字幕）
|
||||
|
||||
### 🌐 网页
|
||||
- **任意网页**（新闻、博客、文档）
|
||||
- **搜索关键词**（自动汇总结果）
|
||||
|
||||
### 📄 Office 文档
|
||||
- **Word** (.docx)
|
||||
- **PowerPoint** (.pptx)
|
||||
- **Excel** (.xlsx)
|
||||
|
||||
</td>
|
||||
<td width="50%">
|
||||
|
||||
### 📚 电子书与文档
|
||||
- **PDF**（支持扫描件 OCR）
|
||||
- **EPUB**（电子书）
|
||||
- **Markdown** (.md)
|
||||
|
||||
### 🖼️ 图片与音频
|
||||
- **图片**（JPEG/PNG/GIF，自动 OCR）
|
||||
- **音频**（WAV/MP3，自动转录）
|
||||
|
||||
### 📊 结构化数据
|
||||
- **CSV/JSON/XML**
|
||||
- **ZIP 压缩包**（批量处理）
|
||||
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
**技术支持**: [Microsoft markitdown](https://github.com/microsoft/markitdown)
|
||||
|
||||
## 🎨 可以生成什么？
|
||||
|
||||
| 输出格式 | 用途 | 生成时间 | 触发词示例 |
|
||||
|---------|------|---------|-----------|
|
||||
| 🎙️ **播客** | 通勤路上听 | 2-5 分钟 | "生成播客"、"做成音频" |
|
||||
| 📊 **PPT** | 团队分享 | 1-3 分钟 | "做成PPT"、"生成幻灯片" |
|
||||
| 🗺️ **思维导图** | 理清结构 | 1-2 分钟 | "画个思维导图"、"生成脑图" |
|
||||
| 📝 **Quiz** | 自测掌握 | 1-2 分钟 | "生成Quiz"、"出题" |
|
||||
| 🎬 **视频** | 可视化 | 3-8 分钟 | "做个视频" |
|
||||
| 📄 **报告** | 深度分析 | 2-4 分钟 | "生成报告"、"写个总结" |
|
||||
| 📈 **信息图** | 数据可视化 | 2-3 分钟 | "做个信息图" |
|
||||
| 📋 **闪卡** | 记忆巩固 | 1-2 分钟 | "做成闪卡" |
|
||||
|
||||
**完全自然语言，无需记命令！**
|
||||
|
||||
## ⚡ 快速开始
|
||||
|
||||
### 前置需求
|
||||
|
||||
- ✅ Python 3.9+
|
||||
- ✅ Git（macOS/Linux 自带）
|
||||
|
||||
**就这两样！** 其他依赖一键自动安装。
|
||||
|
||||
### 安装（3 步）
|
||||
|
||||
```bash
|
||||
# 1. 克隆到 Claude skills 目录
|
||||
cd ~/.claude/skills/
|
||||
git clone https://github.com/joeseesun/anything-to-notebooklm
|
||||
cd anything-to-notebooklm
|
||||
|
||||
# 2. 一键安装所有依赖
|
||||
./install.sh
|
||||
|
||||
# 3. 按提示配置 MCP，然后重启 Claude Code
|
||||
```
|
||||
|
||||
### 首次使用
|
||||
|
||||
```bash
|
||||
# NotebookLM 认证（只需一次）
|
||||
notebooklm login
|
||||
notebooklm list # 验证成功
|
||||
|
||||
# 环境检查（可选）
|
||||
./check_env.py
|
||||
```
|
||||
|
||||
## 💡 使用示例
|
||||
|
||||
### 场景 1：快速学习 - 文章 → 播客
|
||||
|
||||
```
|
||||
你：把这篇文章生成播客 https://mp.weixin.qq.com/s/abc123
|
||||
|
||||
AI 自动执行：
|
||||
✓ 抓取微信文章内容
|
||||
✓ 上传到 NotebookLM
|
||||
✓ 生成播客（2-5 分钟）
|
||||
|
||||
✅ 结果：/tmp/article_podcast.mp3（8 分钟，12.3 MB）
|
||||
💡 用途：通勤路上听完一篇深度文章
|
||||
```
|
||||
|
||||
### 场景 2：团队分享 - 电子书 → PPT
|
||||
|
||||
```
|
||||
你：这本书做成 PPT /Users/joe/Books/sapiens.epub
|
||||
|
||||
AI 自动执行：
|
||||
✓ 提取电子书内容（15 万字）
|
||||
✓ AI 精炼核心观点
|
||||
✓ 生成专业 PPT
|
||||
|
||||
✅ 结果：/tmp/sapiens_slides.pdf（25 页，3.8 MB）
|
||||
💡 用途：直接用于读书会分享
|
||||
```
|
||||
|
||||
### 场景 3：自测学习 - 视频 → Quiz
|
||||
|
||||
```
|
||||
你：这个 YouTube 视频生成 Quiz https://youtube.com/watch?v=abc
|
||||
|
||||
AI 自动执行：
|
||||
✓ 提取视频字幕
|
||||
✓ AI 分析关键知识点
|
||||
✓ 自动出题
|
||||
|
||||
✅ 结果：/tmp/video_quiz.md（15 道题，10 选择 + 5 简答）
|
||||
💡 用途：检验学习效果
|
||||
```
|
||||
|
||||
### 场景 4：信息整合 - 多源 → 报告
|
||||
|
||||
```
|
||||
你：把这些内容一起做成报告：
|
||||
- https://example.com/article1
|
||||
- https://youtube.com/watch?v=xyz
|
||||
- /Users/joe/research.pdf
|
||||
|
||||
AI 自动执行：
|
||||
✓ 汇总 3 个不同来源
|
||||
✓ AI 整合分析
|
||||
✓ 生成综合报告
|
||||
|
||||
✅ 结果：/tmp/multi_source_report.md（7 个章节，15.2 KB）
|
||||
💡 用途：全面的主题研究报告
|
||||
```
|
||||
|
||||
### 场景 5：文档数字化 - 扫描件 → 文字
|
||||
|
||||
```
|
||||
你：把这个扫描图片做成文档 /Users/joe/scan.jpg
|
||||
|
||||
AI 自动执行：
|
||||
✓ OCR 识别图片中的文字
|
||||
✓ 提取为纯文本
|
||||
✓ 生成结构化文档
|
||||
|
||||
✅ 结果：/tmp/scan_document.txt（识别准确率 95%+）
|
||||
💡 用途：扫描件数字化归档
|
||||
```
|
||||
|
||||
## 🎯 核心特性
|
||||
|
||||
### 🧠 智能识别
|
||||
自动判断输入类型，无需手动指定
|
||||
|
||||
```
|
||||
https://mp.weixin.qq.com/s/xxx → 微信公众号
|
||||
https://youtube.com/watch?v=xxx → YouTube 视频
|
||||
/path/to/file.epub → EPUB 电子书
|
||||
"搜索 'AI 趋势'" → 搜索查询
|
||||
```
|
||||
|
||||
### 🚀 全自动处理
|
||||
从获取到生成，一气呵成
|
||||
|
||||
```
|
||||
输入 → 获取 → 转换 → 上传 → 生成 → 下载
|
||||
︿________全自动________︿
|
||||
```
|
||||
|
||||
### 🌐 多源整合
|
||||
支持混合多种内容源
|
||||
|
||||
```
|
||||
文章 + 视频 + PDF + 搜索结果 → 综合报告
|
||||
```
|
||||
|
||||
### 🔒 本地优先
|
||||
敏感内容本地处理
|
||||
|
||||
```
|
||||
微信文章 → 本地 MCP 抓取 → 本地转换 → NotebookLM
|
||||
```
|
||||
|
||||
## 📦 技术架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────┐
|
||||
│ 用户自然语言输入 │
|
||||
│ "把这篇文章生成播客 https://..." │
|
||||
└──────────────┬──────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ Claude Code Skill │
|
||||
│ • 智能识别内容源类型 │
|
||||
│ • 自动调用对应工具 │
|
||||
└──────────────┬──────────────────────┘
|
||||
│
|
||||
┌────────┴────────┐
|
||||
│ │
|
||||
▼ ▼
|
||||
┌──────────┐ ┌─────────────┐
|
||||
│ 微信公众号 │ │ 其他格式 │
|
||||
│ MCP 抓取 │ │ markitdown │
|
||||
└─────┬────┘ └──────┬──────┘
|
||||
│ │
|
||||
└────────┬────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ NotebookLM API │
|
||||
│ • 上传内容源 │
|
||||
│ • AI 生成目标格式 │
|
||||
└──────────────┬──────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────┐
|
||||
│ 生成的文件 │
|
||||
│ .mp3 / .pdf / .json / .md │
|
||||
└─────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## 🔧 高级用法
|
||||
|
||||
### 指定已有 Notebook
|
||||
|
||||
```
|
||||
把这篇文章加到我的【AI研究】笔记本 https://example.com
|
||||
```
|
||||
|
||||
### 批量处理
|
||||
|
||||
```
|
||||
把这些文章都生成播客：
|
||||
1. https://mp.weixin.qq.com/s/abc123
|
||||
2. https://example.com/article2
|
||||
3. /Users/joe/notes.md
|
||||
```
|
||||
|
||||
### ZIP 批量转换
|
||||
|
||||
```
|
||||
把这个压缩包里的所有文档做成播客 /path/to/files.zip
|
||||
```
|
||||
|
||||
自动解压、识别、转换、合并
|
||||
|
||||
## 🐛 故障排查
|
||||
|
||||
### MCP 工具未找到
|
||||
|
||||
```bash
|
||||
# 测试 MCP 服务器
|
||||
python ~/.claude/skills/anything-to-notebooklm/wexin-read-mcp/src/server.py
|
||||
|
||||
# 重新安装依赖
|
||||
cd ~/.claude/skills/anything-to-notebooklm/wexin-read-mcp
|
||||
pip install -r requirements.txt
|
||||
playwright install chromium
|
||||
```
|
||||
|
||||
### NotebookLM 认证失败
|
||||
|
||||
```bash
|
||||
notebooklm login # 重新登录
|
||||
notebooklm list # 验证
|
||||
```
|
||||
|
||||
### 环境检查
|
||||
|
||||
```bash
|
||||
./check_env.py # 13 项全面检查
|
||||
./install.sh # 重新安装
|
||||
```
|
||||
|
||||
## 🤝 贡献
|
||||
|
||||
欢迎 PR、Issue、建议！
|
||||
|
||||
## ❓ 常见问题
|
||||
|
||||
<details>
|
||||
<summary><b>Q: 支持哪些语言？</b></summary>
|
||||
|
||||
A: NotebookLM 支持多语言，中文、英文效果最佳。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Q: 播客是谁的声音？</b></summary>
|
||||
|
||||
A: Google AI 语音合成。英文是两个 AI 主持人对话，中文是单人叙述。
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Q: 内容长度限制？</b></summary>
|
||||
|
||||
A:
|
||||
- 最短：约 500 字
|
||||
- 最长：约 50 万字
|
||||
- 推荐：1000-10000 字效果最佳
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Q: 可以商用吗？</b></summary>
|
||||
|
||||
A:
|
||||
- 本 Skill：MIT 开源，可自由使用
|
||||
- 生成内容：遵守 NotebookLM 服务条款
|
||||
- 原始内容：遵守原内容版权
|
||||
- 建议：仅用于个人学习研究
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><b>Q: 为什么需要 MCP？</b></summary>
|
||||
|
||||
A: 微信公众号有反爬虫，MCP 用浏览器模拟绕过。其他内容源（网页、YouTube、PDF）不需要 MCP。
|
||||
</details>
|
||||
|
||||
## 📄 许可证
|
||||
|
||||
[MIT License](LICENSE)
|
||||
|
||||
## 🙏 致谢
|
||||
|
||||
- [Google NotebookLM](https://notebooklm.google.com/) - AI 内容生成
|
||||
- [Microsoft markitdown](https://github.com/microsoft/markitdown) - 文件转换
|
||||
- [wexin-read-mcp](https://github.com/Bwkyd/wexin-read-mcp) - 微信抓取
|
||||
- [notebooklm-py](https://github.com/teng-lin/notebooklm-py) - NotebookLM CLI
|
||||
|
||||
## 📮 联系
|
||||
|
||||
- **Issues**: [GitHub Issues](https://github.com/joeseesun/anything-to-notebooklm/issues)
|
||||
- **Discussions**: [GitHub Discussions](https://github.com/joeseesun/anything-to-notebooklm/discussions)
|
||||
|
||||
---
|
||||
|
||||
<div align="center">
|
||||
|
||||
**如果觉得有用，请给个 ⭐ Star！**
|
||||
|
||||
Made with ❤️ by [Joe](https://github.com/joeseesun)
|
||||
|
||||
</div>
|
||||
632
axhub-make/skills/third-party/anything-to-notebooklm/SKILL.md
vendored
Normal file
632
axhub-make/skills/third-party/anything-to-notebooklm/SKILL.md
vendored
Normal file
@@ -0,0 +1,632 @@
|
||||
---
|
||||
name: anything-to-notebooklm
|
||||
description: 多源内容智能处理器：支持微信公众号、网页、YouTube、PDF、Markdown等，自动上传到NotebookLM并生成播客/PPT/思维导图等多种格式
|
||||
user-invocable: true
|
||||
homepage: https://github.com/joeseesun/anything-to-notebooklm
|
||||
---
|
||||
|
||||
# 多源内容 → NotebookLM 智能处理器
|
||||
|
||||
自动从多种来源获取内容，上传到 NotebookLM，并根据自然语言指令生成播客、PPT、思维导图等多种格式。
|
||||
|
||||
## 支持的内容源
|
||||
|
||||
### 1. 微信公众号文章
|
||||
通过 MCP 服务器自动抓取微信公众号文章内容（绕过反爬虫）
|
||||
|
||||
### 2. 任意网页链接
|
||||
支持任何公开可访问的网页（新闻、博客、文档等）
|
||||
|
||||
### 3. YouTube 视频
|
||||
自动提取 YouTube 视频的字幕和元数据
|
||||
|
||||
### 4. Office 文档
|
||||
- **Word (DOCX)** - 保留表格和格式
|
||||
- **PowerPoint (PPTX)** - 提取幻灯片和备注
|
||||
- **Excel (XLSX)** - 表格数据
|
||||
|
||||
### 5. 电子书与文档
|
||||
- **PDF** - 全文提取
|
||||
- **EPUB** - 电子书全文提取
|
||||
- **Markdown (.md)** - 原生支持
|
||||
|
||||
### 6. 图片与扫描件
|
||||
- **Images** (JPEG, PNG, GIF, WebP) - OCR 识别文字
|
||||
- 扫描的 PDF 文档 - OCR 提取文字
|
||||
|
||||
### 7. 音频文件
|
||||
- **Audio** (WAV, MP3) - 语音转文字
|
||||
|
||||
### 8. 结构化数据
|
||||
- **CSV** - 逗号分隔数据
|
||||
- **JSON** - JSON 数据
|
||||
- **XML** - XML 文档
|
||||
|
||||
### 9. 压缩包
|
||||
- **ZIP** - 自动解压并处理所有支持的文件
|
||||
|
||||
### 10. 纯文本
|
||||
直接输入或粘贴的文本内容
|
||||
|
||||
### 11. 搜索关键词
|
||||
通过 Web Search 搜索关键词，汇总多个来源的信息
|
||||
|
||||
## 前置条件
|
||||
|
||||
### 1. 安装 wexin-read-mcp
|
||||
|
||||
MCP 服务器已安装在：`~/.claude/skills/anything-to-notebooklm/wexin-read-mcp/`
|
||||
|
||||
**配置 MCP**（需要手动添加到 Claude 配置文件）：
|
||||
|
||||
**macOS**: 编辑 `~/.claude/config.json`
|
||||
|
||||
```json
|
||||
{
|
||||
"primaryApiKey": "any",
|
||||
"mcpServers": {
|
||||
"weixin-reader": {
|
||||
"command": "python",
|
||||
"args": [
|
||||
"/Users/joe/.claude/skills/anything-to-notebooklm/wexin-read-mcp/src/server.py"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**配置后需要重启 Claude Code。**
|
||||
|
||||
### 2. notebooklm 认证
|
||||
|
||||
首次使用前必须认证：
|
||||
|
||||
```bash
|
||||
notebooklm login
|
||||
notebooklm list # 验证认证成功
|
||||
```
|
||||
|
||||
## 触发方式
|
||||
|
||||
### 微信公众号文章
|
||||
- `/anything-to-notebooklm [微信文章链接]`
|
||||
- "把这篇微信文章传到NotebookLM"
|
||||
- "把这篇微信文章生成播客"
|
||||
|
||||
### 网页链接
|
||||
- "把这个网页做成播客 [URL]"
|
||||
- "这篇文章帮我做成PPT [URL]"
|
||||
- "帮我分析这个网页 [URL]"
|
||||
|
||||
### YouTube 视频
|
||||
- "把这个YouTube视频做成播客 [YouTube URL]"
|
||||
- "这个视频帮我生成思维导图 [YouTube URL]"
|
||||
|
||||
### 本地文件
|
||||
- "把这个PDF上传到NotebookLM /path/to/file.pdf"
|
||||
- "这个Markdown文件生成PPT /path/to/file.md"
|
||||
- "这个EPUB电子书生成播客 /path/to/book.epub"
|
||||
- "把这个Word文档做成思维导图 /path/to/doc.docx"
|
||||
- "这个PowerPoint生成Quiz /path/to/slides.pptx"
|
||||
- "把这个扫描PDF做成报告 /path/to/scan.pdf"（自动OCR）
|
||||
|
||||
### 搜索关键词
|
||||
- "搜索 'AI发展趋势' 并生成报告"
|
||||
- "搜索关于'量子计算'的资料做成播客"
|
||||
|
||||
### 混合使用
|
||||
- "把这篇文章、这个视频和这个PDF一起上传，生成一份报告"
|
||||
|
||||
## 自然语言 → NotebookLM 功能映射
|
||||
|
||||
| 用户说的话 | 识别意图 | NotebookLM 命令 |
|
||||
|-----------|---------|----------------|
|
||||
| "生成播客" / "做成音频" / "转成语音" | audio | `generate audio` |
|
||||
| "做成PPT" / "生成幻灯片" / "做个演示" | slide-deck | `generate slide-deck` |
|
||||
| "画个思维导图" / "生成脑图" / "做个导图" | mind-map | `generate mind-map` |
|
||||
| "生成Quiz" / "出题" / "做个测验" | quiz | `generate quiz` |
|
||||
| "做个视频" / "生成视频" | video | `generate video` |
|
||||
| "生成报告" / "写个总结" / "整理成文档" | report | `generate report` |
|
||||
| "做个信息图" / "可视化" | infographic | `generate infographic` |
|
||||
| "生成数据表" / "做个表格" | data-table | `generate data-table` |
|
||||
| "做成闪卡" / "生成记忆卡片" | flashcards | `generate flashcards` |
|
||||
|
||||
**如果没有明确指令**，默认只上传不生成任何内容，等待用户后续指令。
|
||||
|
||||
## 工作流程
|
||||
|
||||
### Step 1: 识别内容源类型
|
||||
|
||||
Claude 自动识别输入类型：
|
||||
|
||||
| 输入特征 | 识别为 | 处理方式 |
|
||||
|---------|-------|---------|
|
||||
| `https://mp.weixin.qq.com/s/` | 微信公众号 | MCP 工具抓取 |
|
||||
| `https://youtube.com/...` 或 `https://youtu.be/...` | YouTube | 直接传递给 NotebookLM |
|
||||
| `https://` 或 `http://` | 网页 | 直接传递给 NotebookLM |
|
||||
| `/path/to/file.pdf` | PDF 文件 | markitdown 转 Markdown → TXT |
|
||||
| `/path/to/file.epub` | EPUB 电子书 | markitdown 转 Markdown → TXT |
|
||||
| `/path/to/file.docx` | Word 文档 | markitdown 转 Markdown → TXT |
|
||||
| `/path/to/file.pptx` | PowerPoint | markitdown 转 Markdown → TXT |
|
||||
| `/path/to/file.xlsx` | Excel | markitdown 转 Markdown → TXT |
|
||||
| `/path/to/file.md` | Markdown | 直接上传 |
|
||||
| `/path/to/image.jpg` | 图片（OCR） | markitdown OCR → TXT |
|
||||
| `/path/to/audio.mp3` | 音频 | markitdown 转录 → TXT |
|
||||
| `/path/to/file.zip` | ZIP 压缩包 | 解压 → markitdown 批量转换 |
|
||||
| 关键词（无URL，无路径） | 搜索查询 | WebSearch → 汇总 → TXT |
|
||||
|
||||
### Step 2: 获取内容
|
||||
|
||||
**微信公众号**：
|
||||
- 使用 MCP 工具 `read_weixin_article`
|
||||
- 返回：title, author, publish_time, content
|
||||
- 保存为 TXT：`/tmp/weixin_{title}_{timestamp}.txt`
|
||||
|
||||
**网页/YouTube**：
|
||||
- 直接使用 URL 调用 `notebooklm source add [URL]`
|
||||
- NotebookLM 自动提取内容
|
||||
|
||||
**Office 文档/电子书/PDF**：
|
||||
- 使用 markitdown 转换为 Markdown
|
||||
- 命令：`markitdown /path/to/file.docx -o /tmp/converted.md`
|
||||
- 保存为 TXT：`/tmp/{filename}_converted_{timestamp}.txt`
|
||||
|
||||
**本地 Markdown**：
|
||||
- 直接上传：`notebooklm source add /path/to/file.md`
|
||||
|
||||
**图片（OCR）**：
|
||||
- markitdown 自动 OCR 识别文字
|
||||
- 提取 EXIF 元数据
|
||||
- 保存为 TXT
|
||||
|
||||
**音频文件**：
|
||||
- markitdown 自动转录语音为文字
|
||||
- 提取音频元数据
|
||||
- 保存为 TXT
|
||||
|
||||
**ZIP 压缩包**：
|
||||
- 自动解压到临时目录
|
||||
- 遍历所有支持的文件
|
||||
- 批量使用 markitdown 转换
|
||||
- 合并为单个 TXT 或多个 Source
|
||||
|
||||
**搜索关键词**：
|
||||
- 使用 WebSearch 工具搜索关键词
|
||||
- 汇总前 3-5 条结果
|
||||
- 保存为 TXT：`/tmp/search_{keyword}_{timestamp}.txt`
|
||||
|
||||
### Step 3: 上传到 NotebookLM
|
||||
|
||||
调用 `notebooklm` skill：
|
||||
|
||||
```bash
|
||||
notebooklm create "{title}" # 创建新笔记本
|
||||
notebooklm source add /tmp/weixin_xxx.txt --wait # 上传文件并等待处理完成
|
||||
```
|
||||
|
||||
**等待处理完成很重要**，否则后续生成会失败。
|
||||
|
||||
### Step 5: 根据意图生成内容（可选）
|
||||
|
||||
如果用户指定了处理意图，自动调用对应命令：
|
||||
|
||||
| 意图 | 命令 | 等待 | 下载 |
|
||||
|------|------|------|------|
|
||||
| audio | `notebooklm generate audio` | `artifact wait` | `download audio ./output.mp3` |
|
||||
| slide-deck | `notebooklm generate slide-deck` | `artifact wait` | `download slide-deck ./output.pdf` |
|
||||
| mind-map | `notebooklm generate mind-map` | `artifact wait` | `download mind-map ./map.json` |
|
||||
| quiz | `notebooklm generate quiz` | `artifact wait` | `download quiz ./quiz.md --format markdown` |
|
||||
| video | `notebooklm generate video` | `artifact wait` | `download video ./output.mp4` |
|
||||
| report | `notebooklm generate report` | `artifact wait` | `download report ./report.md` |
|
||||
| infographic | `notebooklm generate infographic` | `artifact wait` | `download infographic ./infographic.png` |
|
||||
| flashcards | `notebooklm generate flashcards` | `artifact wait` | `download flashcards ./cards.md --format markdown` |
|
||||
|
||||
**生成流程**：
|
||||
1. 发起生成请求（返回 task_id）
|
||||
2. 等待生成完成（`artifact wait <task_id>`）
|
||||
3. 下载生成的文件到本地
|
||||
4. 告知用户文件路径
|
||||
|
||||
## 完整示例
|
||||
|
||||
### 示例 1：微信公众号文章 → 播客
|
||||
|
||||
**用户输入**：
|
||||
```
|
||||
把这篇文章生成播客 https://mp.weixin.qq.com/s/abc123xyz
|
||||
```
|
||||
|
||||
**执行流程**：
|
||||
1. 识别为微信公众号链接
|
||||
2. MCP 工具抓取文章内容
|
||||
3. 创建 TXT 文件
|
||||
4. 上传到 NotebookLM
|
||||
5. 生成播客（`generate audio`）
|
||||
6. 下载播客到本地
|
||||
|
||||
**输出**：
|
||||
```
|
||||
✅ 微信文章已转换为播客！
|
||||
|
||||
📄 文章：深度学习的未来趋势
|
||||
👤 作者：张三
|
||||
📅 发布：2026-01-20
|
||||
|
||||
🎙️ 播客已生成：
|
||||
📁 文件：/tmp/weixin_深度学习的未来趋势_podcast.mp3
|
||||
⏱️ 时长：约 8 分钟
|
||||
📊 大小：12.3 MB
|
||||
```
|
||||
|
||||
### 示例 2：YouTube 视频 → 思维导图
|
||||
|
||||
**用户输入**：
|
||||
```
|
||||
这个视频帮我画个思维导图 https://www.youtube.com/watch?v=abc123
|
||||
```
|
||||
|
||||
**执行流程**：
|
||||
1. 识别为 YouTube 链接
|
||||
2. 直接传递给 NotebookLM（自动提取字幕）
|
||||
3. 生成思维导图（`generate mind-map`）
|
||||
4. 下载思维导图
|
||||
|
||||
**输出**：
|
||||
```
|
||||
✅ YouTube 视频已转换为思维导图！
|
||||
|
||||
🎬 视频：Understanding Quantum Computing
|
||||
⏱️ 时长：23 分钟
|
||||
|
||||
🗺️ 思维导图已生成：
|
||||
📁 文件：/tmp/youtube_quantum_computing_mindmap.json
|
||||
📊 节点数：45 个
|
||||
```
|
||||
|
||||
### 示例 3：搜索关键词 → 报告
|
||||
|
||||
**用户输入**：
|
||||
```
|
||||
搜索 'AI发展趋势 2026' 并生成报告
|
||||
```
|
||||
|
||||
**执行流程**：
|
||||
1. 识别为搜索查询
|
||||
2. WebSearch 搜索关键词
|
||||
3. 汇总前 5 条结果
|
||||
4. 创建 TXT 文件
|
||||
5. 上传到 NotebookLM
|
||||
6. 生成报告（`generate report`）
|
||||
|
||||
**输出**：
|
||||
```
|
||||
✅ 搜索结果已生成报告！
|
||||
|
||||
🔍 关键词：AI发展趋势 2026
|
||||
📊 来源：5 篇文章
|
||||
|
||||
📄 报告已生成：
|
||||
📁 文件：/tmp/search_AI发展趋势2026_report.md
|
||||
📝 章节：7 个
|
||||
📊 大小：15.2 KB
|
||||
```
|
||||
|
||||
### 示例 4：混合多源 → PPT
|
||||
|
||||
**用户输入**：
|
||||
```
|
||||
把这篇文章、这个视频和这个PDF一起做成PPT：
|
||||
- https://example.com/article
|
||||
- https://youtube.com/watch?v=xyz
|
||||
- /Users/joe/Documents/research.pdf
|
||||
```
|
||||
|
||||
**执行流程**：
|
||||
1. 创建新 Notebook
|
||||
2. 依次添加 3 个 Source
|
||||
3. 基于所有 Source 生成 PPT
|
||||
|
||||
**输出**：
|
||||
```
|
||||
✅ 多源内容已整合为PPT！
|
||||
|
||||
📚 内容源：
|
||||
1. 网页文章：AI in 2026
|
||||
2. YouTube：Future of AI
|
||||
3. PDF：Research Notes (12 页)
|
||||
|
||||
📊 PPT 已生成：
|
||||
📁 文件：/tmp/multi_source_slides.pdf
|
||||
📄 页数：25 页
|
||||
📦 大小：3.8 MB
|
||||
```
|
||||
|
||||
### 示例 5: EPUB 电子书 → 播客
|
||||
|
||||
**用户输入**：
|
||||
```
|
||||
把这本电子书做成播客 /Users/joe/Books/sapiens.epub
|
||||
```
|
||||
|
||||
**执行流程**：
|
||||
1. 识别为 EPUB 文件
|
||||
2. markitdown 转换为 Markdown
|
||||
3. 保存为 TXT
|
||||
4. 上传到 NotebookLM
|
||||
5. 生成播客
|
||||
|
||||
**输出**：
|
||||
```
|
||||
✅ EPUB 电子书已转换为播客！
|
||||
|
||||
📚 电子书：Sapiens: A Brief History of Humankind
|
||||
📄 页数：约 450 页
|
||||
📊 字数：约 15 万字
|
||||
|
||||
🎙️ 播客已生成：
|
||||
📁 文件：/tmp/sapiens_podcast.mp3
|
||||
⏱️ 时长：约 45 分钟（精华版）
|
||||
📊 大小：48.2 MB
|
||||
```
|
||||
|
||||
### 示例 6：Word 文档 → Quiz
|
||||
|
||||
**用户输入**：
|
||||
```
|
||||
这个Markdown生成Quiz /Users/joe/notes/machine_learning.md
|
||||
```
|
||||
|
||||
**执行流程**：
|
||||
1. 识别为本地 Markdown 文件
|
||||
2. 直接上传到 NotebookLM
|
||||
3. 生成 Quiz（`generate quiz`）
|
||||
|
||||
**输出**：
|
||||
```
|
||||
✅ Markdown 已转换为Quiz！
|
||||
|
||||
📄 文件：machine_learning.md
|
||||
📊 大小：8.5 KB
|
||||
|
||||
📝 Quiz 已生成：
|
||||
📁 文件：/tmp/machine_learning_quiz.md
|
||||
❓ 题目：15 道（10选择 + 5简答）
|
||||
```
|
||||
|
||||
## 错误处理
|
||||
|
||||
### URL 格式错误
|
||||
```
|
||||
❌ 错误：URL 格式不正确
|
||||
|
||||
必须是微信公众号文章链接：
|
||||
https://mp.weixin.qq.com/s/xxx
|
||||
|
||||
你提供的链接：https://example.com
|
||||
```
|
||||
|
||||
### 文章获取失败
|
||||
```
|
||||
❌ 错误：无法获取文章内容
|
||||
|
||||
可能原因：
|
||||
1. 文章已被删除
|
||||
2. 文章需要登录查看（暂不支持）
|
||||
3. 网络连接问题
|
||||
4. 微信反爬虫拦截（请稍后重试）
|
||||
|
||||
建议：
|
||||
- 检查链接是否正确
|
||||
- 等待 2-3 秒后重试
|
||||
- 或手动复制文章内容
|
||||
```
|
||||
|
||||
### NotebookLM 认证失败
|
||||
```
|
||||
❌ 错误：NotebookLM 认证失败
|
||||
|
||||
请运行以下命令重新登录：
|
||||
notebooklm login
|
||||
|
||||
然后验证：
|
||||
notebooklm list
|
||||
```
|
||||
|
||||
### 生成任务失败
|
||||
```
|
||||
❌ 错误：播客生成失败
|
||||
|
||||
可能原因：
|
||||
1. 文章内容太短（< 100 字）
|
||||
2. 文章内容太长（> 50万字）
|
||||
3. NotebookLM 服务异常
|
||||
|
||||
建议：
|
||||
- 检查文章长度是否适中
|
||||
- 稍后重试
|
||||
- 或尝试其他格式（如生成报告）
|
||||
```
|
||||
|
||||
## 高级功能
|
||||
|
||||
### 1. 多意图处理
|
||||
|
||||
用户可以一次性指定多个处理任务：
|
||||
|
||||
```
|
||||
这篇文章帮我生成播客和PPT https://mp.weixin.qq.com/s/abc123
|
||||
```
|
||||
|
||||
Skill 会依次执行：
|
||||
1. 生成播客
|
||||
2. 生成 PPT
|
||||
|
||||
### 2. 自定义 Notebook
|
||||
|
||||
默认每篇文章创建新 Notebook，也可以指定已有 Notebook：
|
||||
|
||||
```
|
||||
把这篇文章加到我的【AI研究】笔记本 https://mp.weixin.qq.com/s/abc123
|
||||
```
|
||||
|
||||
Skill 会：
|
||||
1. 搜索名为"AI研究"的 Notebook
|
||||
2. 将文章添加为新 Source
|
||||
3. 基于所有 Sources 生成内容
|
||||
|
||||
### 3. 自定义生成指令
|
||||
|
||||
为生成任务添加具体要求：
|
||||
|
||||
```
|
||||
这篇文章生成播客，要求：轻松幽默的风格，时长控制在5分钟
|
||||
```
|
||||
|
||||
Skill 会将要求作为 instructions 传给 NotebookLM。
|
||||
|
||||
## 注意事项
|
||||
|
||||
1. **频率限制**：
|
||||
- 每次请求间隔 > 2 秒，避免被微信封禁
|
||||
- NotebookLM 生成任务有并发限制（最多 3 个同时进行）
|
||||
|
||||
2. **内容长度**：
|
||||
- 微信文章通常 1000-5000 字，适合生成播客（3-8 分钟）
|
||||
- 超过 10000 字的长文可能需要更长生成时间
|
||||
- 少于 500 字的短文可能生成效果不佳
|
||||
|
||||
3. **版权遵守**：
|
||||
- 仅用于个人学习研究
|
||||
- 遵守微信公众号的版权规定
|
||||
- 生成的内容不得用于商业用途
|
||||
|
||||
4. **生成时间**：
|
||||
- 播客：2-5 分钟
|
||||
- 视频：3-8 分钟
|
||||
- PPT：1-3 分钟
|
||||
- 思维导图：1-2 分钟
|
||||
- Quiz/闪卡：1-2 分钟
|
||||
|
||||
5. **文件清理**：
|
||||
- TXT 源文件保存在 `/tmp/`，系统重启后自动清理
|
||||
- 生成的文件（MP3/PDF/MD 等）默认保存在 `/tmp/`
|
||||
- 可以指定自定义保存路径
|
||||
|
||||
## 相关 Skills
|
||||
|
||||
- `notebooklm` - NotebookLM 核心功能
|
||||
- `notebooklm-deep-analyzer` - 深度分析 NotebookLM 内容
|
||||
- `markitdown` - 转换其他格式文档
|
||||
|
||||
## 配置 MCP（重要）
|
||||
|
||||
⚠️ **第一次使用前必须配置**
|
||||
|
||||
编辑 `~/.claude/config.json`：
|
||||
|
||||
```json
|
||||
{
|
||||
"primaryApiKey": "any",
|
||||
"mcpServers": {
|
||||
"weixin-reader": {
|
||||
"command": "python",
|
||||
"args": [
|
||||
"/Users/joe/.claude/skills/anything-to-notebooklm/wexin-read-mcp/src/server.py"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**配置后重启 Claude Code！**
|
||||
|
||||
## 故障排查
|
||||
|
||||
### 1. MCP 工具未找到
|
||||
|
||||
```bash
|
||||
# 测试 MCP 服务器
|
||||
python ~/.claude/skills/anything-to-notebooklm/wexin-read-mcp/src/server.py
|
||||
|
||||
# 如果报错，检查依赖
|
||||
cd ~/.claude/skills/anything-to-notebooklm/wexin-read-mcp
|
||||
pip install -r requirements.txt
|
||||
playwright install chromium
|
||||
```
|
||||
|
||||
### 2. NotebookLM 命令失败
|
||||
|
||||
```bash
|
||||
# 检查认证状态
|
||||
notebooklm status
|
||||
|
||||
# 重新登录
|
||||
notebooklm login
|
||||
|
||||
# 验证
|
||||
notebooklm list
|
||||
```
|
||||
|
||||
### 3. 文件权限问题
|
||||
|
||||
```bash
|
||||
# 确保临时目录可写
|
||||
chmod 755 /tmp
|
||||
|
||||
# 测试写入
|
||||
touch /tmp/test.txt && rm /tmp/test.txt
|
||||
```
|
||||
|
||||
### 4. 生成任务卡住
|
||||
|
||||
```bash
|
||||
# 检查任务状态
|
||||
notebooklm artifact list
|
||||
|
||||
# 如果显示 "pending" 超过 10 分钟，取消重试
|
||||
# （目前 CLI 不支持取消，需要在网页端操作）
|
||||
```
|
||||
|
||||
## 典型使用场景
|
||||
|
||||
### 场景 1：快速学习
|
||||
|
||||
```
|
||||
我想学习这篇文章，帮我生成播客，上下班路上听
|
||||
链接：https://mp.weixin.qq.com/s/abc123
|
||||
```
|
||||
|
||||
→ 生成 8 分钟播客，通勤时间听完
|
||||
|
||||
### 场景 2：分享给团队
|
||||
|
||||
```
|
||||
这篇文章不错，做成PPT分享给团队
|
||||
https://mp.weixin.qq.com/s/abc123
|
||||
```
|
||||
|
||||
→ 生成 15 页 PPT，直接用于团队分享
|
||||
|
||||
### 场景 3：复习巩固
|
||||
|
||||
```
|
||||
这篇技术文章帮我出题，想测试一下掌握程度
|
||||
https://mp.weixin.qq.com/s/abc123
|
||||
```
|
||||
|
||||
→ 生成 10 道选择题 + 5 道简答题
|
||||
|
||||
### 场景 4：可视化理解
|
||||
|
||||
```
|
||||
这篇文章概念比较多，画个思维导图帮我理清结构
|
||||
https://mp.weixin.qq.com/s/abc123
|
||||
```
|
||||
|
||||
→ 生成思维导图，一目了然
|
||||
|
||||
---
|
||||
|
||||
**Skill 创建时间**：2026-01-25
|
||||
**最后更新**：2026-01-25
|
||||
**版本**：v1.0.0
|
||||
218
axhub-make/skills/third-party/anything-to-notebooklm/check_env.py
vendored
Normal file
218
axhub-make/skills/third-party/anything-to-notebooklm/check_env.py
vendored
Normal file
@@ -0,0 +1,218 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
环境检查脚本 - 验证 anything-to-notebooklm skill 所有依赖
|
||||
"""
|
||||
|
||||
import sys
|
||||
import os
|
||||
import json
|
||||
from pathlib import Path
|
||||
|
||||
# 颜色输出
|
||||
RED = '\033[0;31m'
|
||||
GREEN = '\033[0;32m'
|
||||
YELLOW = '\033[1;33m'
|
||||
BLUE = '\033[0;34m'
|
||||
NC = '\033[0m'
|
||||
|
||||
def print_status(status, message):
|
||||
"""打印状态信息"""
|
||||
if status == "ok":
|
||||
print(f"{GREEN}✅ {message}{NC}")
|
||||
elif status == "warning":
|
||||
print(f"{YELLOW}⚠️ {message}{NC}")
|
||||
elif status == "error":
|
||||
print(f"{RED}❌ {message}{NC}")
|
||||
else:
|
||||
print(f"{BLUE}ℹ️ {message}{NC}")
|
||||
|
||||
def check_python_version():
|
||||
"""检查 Python 版本"""
|
||||
version = sys.version_info
|
||||
version_str = f"{version.major}.{version.minor}.{version.micro}"
|
||||
|
||||
if version.major >= 3 and version.minor >= 9:
|
||||
print_status("ok", f"Python {version_str}")
|
||||
return True
|
||||
else:
|
||||
print_status("error", f"Python {version_str} (需要 3.9+)")
|
||||
return False
|
||||
|
||||
def check_module(module_name, import_name=None):
|
||||
"""检查 Python 模块是否已安装"""
|
||||
if import_name is None:
|
||||
import_name = module_name
|
||||
|
||||
try:
|
||||
__import__(import_name)
|
||||
print_status("ok", f"{module_name} 已安装")
|
||||
return True
|
||||
except ImportError:
|
||||
print_status("error", f"{module_name} 未安装")
|
||||
return False
|
||||
|
||||
def check_command(cmd):
|
||||
"""检查命令是否可用"""
|
||||
import shutil
|
||||
|
||||
if shutil.which(cmd):
|
||||
# 尝试获取版本
|
||||
import subprocess
|
||||
try:
|
||||
result = subprocess.run([cmd, "--version"],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=5)
|
||||
version = result.stdout.split('\n')[0] if result.stdout else "unknown"
|
||||
print_status("ok", f"{cmd} 已安装 ({version})")
|
||||
except:
|
||||
print_status("ok", f"{cmd} 已安装")
|
||||
return True
|
||||
else:
|
||||
print_status("error", f"{cmd} 未找到")
|
||||
return False
|
||||
|
||||
def check_mcp_config():
|
||||
"""检查 MCP 配置"""
|
||||
config_path = Path.home() / ".claude" / "config.json"
|
||||
|
||||
if not config_path.exists():
|
||||
print_status("error", f"未找到 Claude 配置文件: {config_path}")
|
||||
return False
|
||||
|
||||
try:
|
||||
with open(config_path, 'r') as f:
|
||||
config = json.load(f)
|
||||
|
||||
if "mcpServers" in config and "weixin-reader" in config["mcpServers"]:
|
||||
print_status("ok", "MCP 服务器已配置")
|
||||
return True
|
||||
else:
|
||||
print_status("warning", "MCP 服务器未配置（需要手动添加）")
|
||||
return False
|
||||
except Exception as e:
|
||||
print_status("error", f"无法读取配置文件: {e}")
|
||||
return False
|
||||
|
||||
def check_mcp_server():
|
||||
"""检查 MCP 服务器文件"""
|
||||
skill_dir = Path(__file__).parent
|
||||
mcp_server = skill_dir / "wexin-read-mcp" / "src" / "server.py"
|
||||
|
||||
if mcp_server.exists():
|
||||
print_status("ok", f"MCP 服务器文件存在")
|
||||
return True
|
||||
else:
|
||||
print_status("error", f"MCP 服务器文件不存在: {mcp_server}")
|
||||
return False
|
||||
|
||||
def check_notebooklm_auth():
|
||||
"""检查 NotebookLM 认证状态"""
|
||||
import subprocess
|
||||
|
||||
try:
|
||||
result = subprocess.run(["notebooklm", "list"],
|
||||
capture_output=True,
|
||||
text=True,
|
||||
timeout=10)
|
||||
|
||||
if result.returncode == 0:
|
||||
print_status("ok", "NotebookLM 已认证")
|
||||
return True
|
||||
else:
|
||||
print_status("warning", "NotebookLM 未认证（请运行 notebooklm login）")
|
||||
return False
|
||||
except subprocess.TimeoutExpired:
|
||||
print_status("warning", "NotebookLM 认证检查超时")
|
||||
return False
|
||||
except Exception as e:
|
||||
print_status("error", f"NotebookLM 认证检查失败: {e}")
|
||||
return False
|
||||
|
||||
def main():
|
||||
print(f"\n{BLUE}========================================{NC}")
|
||||
print(f"{BLUE} 环境检查 - anything-to-notebooklm{NC}")
|
||||
print(f"{BLUE}========================================{NC}\n")
|
||||
|
||||
results = []
|
||||
|
||||
# 1. Python 版本
|
||||
print(f"{YELLOW}[1/8] Python 版本{NC}")
|
||||
results.append(check_python_version())
|
||||
print()
|
||||
|
||||
# 2. 核心依赖
|
||||
print(f"{YELLOW}[2/9] 核心 Python 依赖{NC}")
|
||||
results.append(check_module("fastmcp"))
|
||||
results.append(check_module("playwright"))
|
||||
results.append(check_module("beautifulsoup4", "bs4"))
|
||||
results.append(check_module("lxml"))
|
||||
results.append(check_module("markitdown"))
|
||||
print()
|
||||
|
||||
# 3. Playwright 浏览器
|
||||
print(f"{YELLOW}[3/9] Playwright 可导入性{NC}")
|
||||
try:
|
||||
from playwright.sync_api import sync_playwright
|
||||
print_status("ok", "Playwright 可以正常导入")
|
||||
results.append(True)
|
||||
except Exception as e:
|
||||
print_status("error", f"Playwright 导入失败: {e}")
|
||||
results.append(False)
|
||||
print()
|
||||
|
||||
# 4. NotebookLM CLI
|
||||
print(f"{YELLOW}[4/9] NotebookLM CLI{NC}")
|
||||
results.append(check_command("notebooklm"))
|
||||
print()
|
||||
|
||||
# 5. markitdown CLI
|
||||
print(f"{YELLOW}[5/9] markitdown CLI{NC}")
|
||||
results.append(check_command("markitdown"))
|
||||
print()
|
||||
|
||||
# 6. Git 命令
|
||||
print(f"{YELLOW}[6/9] Git 命令{NC}")
|
||||
results.append(check_command("git"))
|
||||
print()
|
||||
|
||||
# 7. MCP 服务器文件
|
||||
print(f"{YELLOW}[7/9] MCP 服务器文件{NC}")
|
||||
results.append(check_mcp_server())
|
||||
print()
|
||||
|
||||
# 8. MCP 配置
|
||||
print(f"{YELLOW}[8/9] MCP 配置{NC}")
|
||||
results.append(check_mcp_config())
|
||||
print()
|
||||
|
||||
# 9. NotebookLM 认证
|
||||
print(f"{YELLOW}[9/9] NotebookLM 认证{NC}")
|
||||
results.append(check_notebooklm_auth())
|
||||
print()
|
||||
|
||||
# 总结
|
||||
print(f"{BLUE}========================================{NC}")
|
||||
passed = sum(results)
|
||||
total = len(results)
|
||||
|
||||
if passed == total:
|
||||
print(f"{GREEN}✅ 所有检查通过 ({passed}/{total})！环境配置完整。{NC}")
|
||||
elif passed >= total * 0.8:
|
||||
print(f"{YELLOW}⚠️ 大部分检查通过 ({passed}/{total})，但有些问题需要修复。{NC}")
|
||||
else:
|
||||
print(f"{RED}❌ 检查失败 ({passed}/{total})，请运行 install.sh 重新安装。{NC}")
|
||||
|
||||
print(f"{BLUE}========================================{NC}\n")
|
||||
|
||||
if passed < total:
|
||||
print("💡 修复建议：")
|
||||
print(" 1. 运行安装脚本：./install.sh")
|
||||
print(" 2. 配置 MCP：编辑 ~/.claude/config.json")
|
||||
print(" 3. 认证 NotebookLM：notebooklm login")
|
||||
print()
|
||||
|
||||
sys.exit(0 if passed == total else 1)
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
167
axhub-make/skills/third-party/anything-to-notebooklm/install.sh
vendored
Normal file
167
axhub-make/skills/third-party/anything-to-notebooklm/install.sh
vendored
Normal file
@@ -0,0 +1,167 @@
|
||||
#!/bin/bash
|
||||
|
||||
# anything-to-notebooklm Skill Installer
|
||||
# 自动安装所有依赖并配置环境
|
||||
|
||||
set -e # 遇到错误立即退出
|
||||
|
||||
SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
SKILL_NAME="anything-to-notebooklm"
|
||||
|
||||
# 颜色输出
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
BLUE='\033[0;34m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
echo -e "${BLUE}========================================${NC}"
|
||||
echo -e "${BLUE} 多源内容 → NotebookLM 安装程序${NC}"
|
||||
echo -e "${BLUE}========================================${NC}"
|
||||
echo ""
|
||||
|
||||
# 1. 检查 Python 版本
|
||||
echo -e "${YELLOW}[1/6] 检查 Python 环境...${NC}"
|
||||
if ! command -v python3 &> /dev/null; then
|
||||
echo -e "${RED}❌ 未找到 Python3，请先安装 Python 3.9+${NC}"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
PYTHON_VERSION=$(python3 -c 'import sys; print(".".join(map(str, sys.version_info[:2])))')
|
||||
REQUIRED_VERSION="3.9"
|
||||
|
||||
if [ "$(printf '%s\n' "$REQUIRED_VERSION" "$PYTHON_VERSION" | sort -V | head -n1)" != "$REQUIRED_VERSION" ]; then
|
||||
echo -e "${RED}❌ Python 版本过低（当前 $PYTHON_VERSION，需要 3.9+）${NC}"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo -e "${GREEN}✅ Python $PYTHON_VERSION${NC}"
|
||||
|
||||
# 2. 检查并克隆 wexin-read-mcp
|
||||
echo ""
|
||||
echo -e "${YELLOW}[2/6] 安装 MCP 服务器...${NC}"
|
||||
MCP_DIR="$SKILL_DIR/wexin-read-mcp"
|
||||
|
||||
if [ -d "$MCP_DIR" ]; then
|
||||
echo -e "${GREEN}✅ MCP 服务器已存在${NC}"
|
||||
else
|
||||
echo "正在克隆 wexin-read-mcp..."
|
||||
git clone https://github.com/Bwkyd/wexin-read-mcp.git "$MCP_DIR"
|
||||
echo -e "${GREEN}✅ MCP 服务器克隆完成${NC}"
|
||||
fi
|
||||
|
||||
# 3. 安装 Python 依赖
|
||||
echo ""
|
||||
echo -e "${YELLOW}[3/6] 安装 Python 依赖...${NC}"
|
||||
|
||||
# 安装 MCP 服务器依赖
|
||||
if [ -f "$MCP_DIR/requirements.txt" ]; then
|
||||
echo "安装 MCP 依赖..."
|
||||
pip3 install -r "$MCP_DIR/requirements.txt" -q
|
||||
echo -e "${GREEN}✅ MCP 依赖安装完成${NC}"
|
||||
fi
|
||||
|
||||
# 安装 Skill 依赖（包括 markitdown）
|
||||
if [ -f "$SKILL_DIR/requirements.txt" ]; then
|
||||
echo "安装 Skill 依赖（包括 markitdown 文件转换工具）..."
|
||||
pip3 install -r "$SKILL_DIR/requirements.txt" -q
|
||||
echo -e "${GREEN}✅ Skill 依赖安装完成${NC}"
|
||||
echo -e "${GREEN}✅ markitdown 已安装（支持 15+ 文件格式转换）${NC}"
|
||||
fi
|
||||
|
||||
# 4. 安装 Playwright 浏览器
|
||||
echo ""
|
||||
echo -e "${YELLOW}[4/6] 安装 Playwright 浏览器...${NC}"
|
||||
echo "这可能需要几分钟，请耐心等待..."
|
||||
|
||||
if python3 -c "from playwright.sync_api import sync_playwright" 2>/dev/null; then
|
||||
playwright install chromium
|
||||
echo -e "${GREEN}✅ Playwright 浏览器安装完成${NC}"
|
||||
else
|
||||
echo -e "${RED}❌ Playwright 导入失败，请检查安装${NC}"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 5. 检查并安装 notebooklm
|
||||
echo ""
|
||||
echo -e "${YELLOW}[5/6] 检查 NotebookLM CLI...${NC}"
|
||||
|
||||
if command -v notebooklm &> /dev/null; then
|
||||
NOTEBOOKLM_VERSION=$(notebooklm --version 2>/dev/null || echo "unknown")
|
||||
echo -e "${GREEN}✅ NotebookLM CLI 已安装 ($NOTEBOOKLM_VERSION)${NC}"
|
||||
else
|
||||
echo "正在安装 notebooklm-py..."
|
||||
pip3 install git+https://github.com/teng-lin/notebooklm-py.git -q
|
||||
|
||||
if command -v notebooklm &> /dev/null; then
|
||||
echo -e "${GREEN}✅ NotebookLM CLI 安装完成${NC}"
|
||||
else
|
||||
echo -e "${RED}❌ NotebookLM CLI 安装失败${NC}"
|
||||
echo "请手动安装：pip3 install git+https://github.com/teng-lin/notebooklm-py.git"
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
|
||||
# 6. 配置指导
|
||||
echo ""
|
||||
echo -e "${YELLOW}[6/6] 配置指导${NC}"
|
||||
echo ""
|
||||
|
||||
CLAUDE_CONFIG="$HOME/.claude/config.json"
|
||||
CONFIG_SNIPPET=" \"weixin-reader\": {
|
||||
\"command\": \"python\",
|
||||
\"args\": [
|
||||
\"$MCP_DIR/src/server.py\"
|
||||
]
|
||||
}"
|
||||
|
||||
echo -e "${BLUE}📝 下一步：配置 MCP 服务器${NC}"
|
||||
echo ""
|
||||
echo "请编辑 $CLAUDE_CONFIG"
|
||||
echo ""
|
||||
echo "在 \"mcpServers\" 中添加："
|
||||
echo -e "${GREEN}$CONFIG_SNIPPET${NC}"
|
||||
echo ""
|
||||
echo "完整配置示例："
|
||||
echo -e "${GREEN}{
|
||||
\"primaryApiKey\": \"any\",
|
||||
\"mcpServers\": {
|
||||
$CONFIG_SNIPPET
|
||||
}
|
||||
}${NC}"
|
||||
echo ""
|
||||
|
||||
# 检查是否已配置
|
||||
if [ -f "$CLAUDE_CONFIG" ]; then
|
||||
if grep -q "weixin-reader" "$CLAUDE_CONFIG"; then
|
||||
echo -e "${GREEN}✅ 检测到已有 weixin-reader 配置${NC}"
|
||||
else
|
||||
echo -e "${YELLOW}⚠️ 未检测到 weixin-reader 配置，请手动添加${NC}"
|
||||
fi
|
||||
else
|
||||
echo -e "${YELLOW}⚠️ 未找到 Claude 配置文件，请手动创建${NC}"
|
||||
fi
|
||||
|
||||
echo ""
|
||||
echo -e "${BLUE}🔐 NotebookLM 认证${NC}"
|
||||
echo ""
|
||||
echo "首次使用前，请运行："
|
||||
echo -e "${GREEN} notebooklm login${NC}"
|
||||
echo -e "${GREEN} notebooklm list # 验证认证成功${NC}"
|
||||
echo ""
|
||||
|
||||
# 最终检查
|
||||
echo ""
|
||||
echo -e "${BLUE}========================================${NC}"
|
||||
echo -e "${GREEN}✅ 安装完成！${NC}"
|
||||
echo -e "${BLUE}========================================${NC}"
|
||||
echo ""
|
||||
echo "📦 安装位置：$SKILL_DIR"
|
||||
echo ""
|
||||
echo "⚠️ 重要提醒："
|
||||
echo " 1. 配置 MCP 服务器后需要重启 Claude Code"
|
||||
echo " 2. 首次使用前运行 notebooklm login"
|
||||
echo ""
|
||||
echo "🚀 使用示例："
|
||||
echo " 把这篇文章生成播客 https://mp.weixin.qq.com/s/xxx"
|
||||
echo ""
|
||||
71
axhub-make/skills/third-party/anything-to-notebooklm/package.sh
vendored
Normal file
71
axhub-make/skills/third-party/anything-to-notebooklm/package.sh
vendored
Normal file
@@ -0,0 +1,71 @@
|
||||
#!/bin/bash
|
||||
|
||||
# 打包 anything-to-notebooklm skill 用于分享
|
||||
# 生成一个不包含大文件的精简版 tar.gz
|
||||
|
||||
SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
SKILL_NAME="anything-to-notebooklm"
|
||||
OUTPUT_DIR="${1:-$HOME/Desktop}"
|
||||
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
|
||||
OUTPUT_FILE="$OUTPUT_DIR/${SKILL_NAME}_${TIMESTAMP}.tar.gz"
|
||||
|
||||
# 颜色
|
||||
GREEN='\033[0;32m'
|
||||
BLUE='\033[0;34m'
|
||||
NC='\033[0m'
|
||||
|
||||
echo -e "${BLUE}========================================${NC}"
|
||||
echo -e "${BLUE} 打包 ${SKILL_NAME} Skill${NC}"
|
||||
echo -e "${BLUE}========================================${NC}"
|
||||
echo ""
|
||||
|
||||
# 要打包的文件列表
|
||||
FILES=(
|
||||
"SKILL.md"
|
||||
"README.md"
|
||||
"install.sh"
|
||||
"check_env.py"
|
||||
"requirements.txt"
|
||||
".gitignore"
|
||||
)
|
||||
|
||||
# 创建临时目录
|
||||
TEMP_DIR=$(mktemp -d)
|
||||
TEMP_SKILL="$TEMP_DIR/$SKILL_NAME"
|
||||
mkdir -p "$TEMP_SKILL"
|
||||
|
||||
echo "📦 正在打包文件..."
|
||||
|
||||
# 复制文件
|
||||
for file in "${FILES[@]}"; do
|
||||
if [ -f "$SKILL_DIR/$file" ]; then
|
||||
cp "$SKILL_DIR/$file" "$TEMP_SKILL/"
|
||||
echo " ✓ $file"
|
||||
fi
|
||||
done
|
||||
|
||||
# 创建 tar.gz
|
||||
cd "$TEMP_DIR"
|
||||
tar -czf "$OUTPUT_FILE" "$SKILL_NAME"
|
||||
|
||||
# 清理
|
||||
rm -rf "$TEMP_DIR"
|
||||
|
||||
# 显示结果
|
||||
FILE_SIZE=$(du -h "$OUTPUT_FILE" | cut -f1)
|
||||
|
||||
echo ""
|
||||
echo -e "${GREEN}✅ 打包完成！${NC}"
|
||||
echo ""
|
||||
echo "📦 文件：$OUTPUT_FILE"
|
||||
echo "📊 大小：$FILE_SIZE"
|
||||
echo ""
|
||||
echo "📤 分享说明："
|
||||
echo " 用户收到文件后，执行："
|
||||
echo " cd ~/.claude/skills/"
|
||||
echo " tar -xzf ${SKILL_NAME}_${TIMESTAMP}.tar.gz"
|
||||
echo " cd ${SKILL_NAME}"
|
||||
echo " ./install.sh"
|
||||
echo ""
|
||||
echo "💡 注意：wexin-read-mcp 会在安装时自动克隆，无需打包"
|
||||
echo ""
|
||||
11
axhub-make/skills/third-party/anything-to-notebooklm/requirements.txt
vendored
Normal file
11
axhub-make/skills/third-party/anything-to-notebooklm/requirements.txt
vendored
Normal file
@@ -0,0 +1,11 @@
|
||||
# Core MCP dependencies
|
||||
fastmcp>=0.1.0
|
||||
playwright>=1.40.0
|
||||
beautifulsoup4>=4.12.0
|
||||
lxml>=4.9.0
|
||||
|
||||
# File format conversion
|
||||
markitdown[all]>=0.0.1
|
||||
|
||||
# NotebookLM (will be installed from PyPI if available, or from git)
|
||||
# notebooklm-py
|
||||
204
axhub-make/skills/third-party/baoyu-image-gen/SKILL.md
vendored
Normal file
204
axhub-make/skills/third-party/baoyu-image-gen/SKILL.md
vendored
Normal file
@@ -0,0 +1,204 @@
|
||||
---
|
||||
name: baoyu-image-gen
|
||||
description: AI image generation with OpenAI, Google, DashScope and Replicate APIs. Supports text-to-image, reference images, aspect ratios. Sequential by default; parallel generation available on request. Use when user asks to generate, create, or draw images.
|
||||
---
|
||||
|
||||
# Image Generation (AI SDK)
|
||||
|
||||
Official API-based image generation. Supports OpenAI, Google, DashScope (阿里通义万象) and Replicate providers.
|
||||
|
||||
## Script Directory
|
||||
|
||||
**Agent Execution**:
|
||||
1. `SKILL_DIR` = this SKILL.md file's directory
|
||||
2. Script path = `${SKILL_DIR}/scripts/main.ts`
|
||||
|
||||
## Step 0: Load Preferences ⛔ BLOCKING
|
||||
|
||||
**CRITICAL**: This step MUST complete BEFORE any image generation. Do NOT skip or defer.
|
||||
|
||||
Check EXTEND.md existence (priority: project → user):
|
||||
|
||||
```bash
|
||||
test -f .baoyu-skills/baoyu-image-gen/EXTEND.md && echo "project"
|
||||
test -f "$HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md" && echo "user"
|
||||
```
|
||||
|
||||
| Result | Action |
|
||||
|--------|--------|
|
||||
| Found | Load, parse, apply settings. If `default_model.[provider]` is null → ask model only (Flow 2) |
|
||||
| Not found | ⛔ Run first-time setup ([references/config/first-time-setup.md](references/config/first-time-setup.md)) → Save EXTEND.md → Then continue |
|
||||
|
||||
**CRITICAL**: If not found, complete the full setup (provider + model + quality + save location) using AskUserQuestion BEFORE generating any images. Generation is BLOCKED until EXTEND.md is created.
|
||||
|
||||
| Path | Location |
|
||||
|------|----------|
|
||||
| `.baoyu-skills/baoyu-image-gen/EXTEND.md` | Project directory |
|
||||
| `$HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md` | User home |
|
||||
|
||||
**EXTEND.md Supports**: Default provider | Default quality | Default aspect ratio | Default image size | Default models
|
||||
|
||||
Schema: `references/config/preferences-schema.md`
|
||||
|
||||
## Usage
|
||||
|
||||
```bash
|
||||
# Basic
|
||||
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image cat.png
|
||||
|
||||
# With aspect ratio
|
||||
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A landscape" --image out.png --ar 16:9
|
||||
|
||||
# High quality
|
||||
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --quality 2k
|
||||
|
||||
# From prompt files
|
||||
npx -y bun ${SKILL_DIR}/scripts/main.ts --promptfiles system.md content.md --image out.png
|
||||
|
||||
# With reference images (Google multimodal or OpenAI edits)
|
||||
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "Make blue" --image out.png --ref source.png
|
||||
|
||||
# With reference images (explicit provider/model)
|
||||
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "Make blue" --image out.png --provider google --model gemini-3-pro-image-preview --ref source.png
|
||||
|
||||
# Specific provider
|
||||
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider openai
|
||||
|
||||
# DashScope (阿里通义万象)
|
||||
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "一只可爱的猫" --image out.png --provider dashscope
|
||||
|
||||
# Replicate (google/nano-banana-pro)
|
||||
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate
|
||||
|
||||
# Replicate with specific model
|
||||
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate --model google/nano-banana
|
||||
```
|
||||
|
||||
## Options
|
||||
|
||||
| Option | Description |
|
||||
|--------|-------------|
|
||||
| `--prompt <text>`, `-p` | Prompt text |
|
||||
| `--promptfiles <files...>` | Read prompt from files (concatenated) |
|
||||
| `--image <path>` | Output image path (required) |
|
||||
| `--provider google\|openai\|dashscope\|replicate` | Force provider (default: google) |
|
||||
| `--model <id>`, `-m` | Model ID (Google: `gemini-3-pro-image-preview`, `gemini-3.1-flash-image-preview`; OpenAI: `gpt-image-1.5`) |
|
||||
| `--ar <ratio>` | Aspect ratio (e.g., `16:9`, `1:1`, `4:3`) |
|
||||
| `--size <WxH>` | Size (e.g., `1024x1024`) |
|
||||
| `--quality normal\|2k` | Quality preset (default: 2k) |
|
||||
| `--imageSize 1K\|2K\|4K` | Image size for Google (default: from quality) |
|
||||
| `--ref <files...>` | Reference images. Supported by Google multimodal (`gemini-3-pro-image-preview`, `gemini-3-flash-preview`, `gemini-3.1-flash-image-preview`) and OpenAI edits (GPT Image models). If provider omitted: Google first, then OpenAI |
|
||||
| `--n <count>` | Number of images |
|
||||
| `--json` | JSON output |
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Description |
|
||||
|----------|-------------|
|
||||
| `OPENAI_API_KEY` | OpenAI API key |
|
||||
| `GOOGLE_API_KEY` | Google API key |
|
||||
| `DASHSCOPE_API_KEY` | DashScope API key (阿里云) |
|
||||
| `REPLICATE_API_TOKEN` | Replicate API token |
|
||||
| `OPENAI_IMAGE_MODEL` | OpenAI model override |
|
||||
| `GOOGLE_IMAGE_MODEL` | Google model override |
|
||||
| `DASHSCOPE_IMAGE_MODEL` | DashScope model override (default: z-image-turbo) |
|
||||
| `REPLICATE_IMAGE_MODEL` | Replicate model override (default: google/nano-banana-pro) |
|
||||
| `OPENAI_BASE_URL` | Custom OpenAI endpoint |
|
||||
| `GOOGLE_BASE_URL` | Custom Google endpoint |
|
||||
| `DASHSCOPE_BASE_URL` | Custom DashScope endpoint |
|
||||
| `REPLICATE_BASE_URL` | Custom Replicate endpoint |
|
||||
|
||||
**Load Priority**: CLI args > EXTEND.md > env vars > `<cwd>/.baoyu-skills/.env` > `~/.baoyu-skills/.env`
|
||||
|
||||
## Model Resolution
|
||||
|
||||
Model priority (highest → lowest), applies to all providers:
|
||||
|
||||
1. CLI flag: `--model <id>`
|
||||
2. EXTEND.md: `default_model.[provider]`
|
||||
3. Env var: `<PROVIDER>_IMAGE_MODEL` (e.g., `GOOGLE_IMAGE_MODEL`)
|
||||
4. Built-in default
|
||||
|
||||
**EXTEND.md overrides env vars**. If both EXTEND.md `default_model.google: "gemini-3-pro-image-preview"` and env var `GOOGLE_IMAGE_MODEL=gemini-3.1-flash-image-preview` exist, EXTEND.md wins.
|
||||
|
||||
**Agent MUST display model info** before each generation:
|
||||
- Show: `Using [provider] / [model]`
|
||||
- Show switch hint: `Switch model: --model <id> | EXTEND.md default_model.[provider] | env <PROVIDER>_IMAGE_MODEL`
|
||||
|
||||
### Replicate Models
|
||||
|
||||
Supported model formats:
|
||||
|
||||
- `owner/name` (recommended for official models), e.g. `google/nano-banana-pro`
|
||||
- `owner/name:version` (community models by version), e.g. `stability-ai/sdxl:<version>`
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
# Use Replicate default model
|
||||
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate
|
||||
|
||||
# Override model explicitly
|
||||
npx -y bun ${SKILL_DIR}/scripts/main.ts --prompt "A cat" --image out.png --provider replicate --model google/nano-banana
|
||||
```
|
||||
|
||||
## Provider Selection
|
||||
|
||||
1. `--ref` provided + no `--provider` → auto-select Google first, then OpenAI, then Replicate
|
||||
2. `--provider` specified → use it (if `--ref`, must be `google`, `openai`, or `replicate`)
|
||||
3. Only one API key available → use that provider
|
||||
4. Multiple available → default to Google
|
||||
|
||||
## Quality Presets
|
||||
|
||||
| Preset | Google imageSize | OpenAI Size | Use Case |
|
||||
|--------|------------------|-------------|----------|
|
||||
| `normal` | 1K | 1024px | Quick previews |
|
||||
| `2k` (default) | 2K | 2048px | Covers, illustrations, infographics |
|
||||
|
||||
**Google imageSize**: Can be overridden with `--imageSize 1K|2K|4K`
|
||||
|
||||
## Aspect Ratios
|
||||
|
||||
Supported: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2.35:1`
|
||||
|
||||
- Google multimodal: uses `imageConfig.aspectRatio`
|
||||
- Google Imagen: uses `aspectRatio` parameter
|
||||
- OpenAI: maps to closest supported size
|
||||
|
||||
## Generation Mode
|
||||
|
||||
**Default**: Sequential generation (one image at a time). This ensures stable output and easier debugging.
|
||||
|
||||
**Parallel Generation**: Only use when user explicitly requests parallel/concurrent generation.
|
||||
|
||||
| Mode | When to Use |
|
||||
|------|-------------|
|
||||
| Sequential (default) | Normal usage, single images, small batches |
|
||||
| Parallel | User explicitly requests, large batches (10+) |
|
||||
|
||||
**Parallel Settings** (when requested):
|
||||
|
||||
| Setting | Value |
|
||||
|---------|-------|
|
||||
| Recommended concurrency | 4 subagents |
|
||||
| Max concurrency | 8 subagents |
|
||||
| Use case | Large batch generation when user requests parallel |
|
||||
|
||||
**Agent Implementation** (parallel mode only):
|
||||
```
|
||||
# Launch multiple generations in parallel using Task tool
|
||||
# Each Task runs as background subagent with run_in_background=true
|
||||
# Collect results via TaskOutput when all complete
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
- Missing API key → error with setup instructions
|
||||
- Generation failure → auto-retry once
|
||||
- Invalid aspect ratio → warning, proceed with default
|
||||
- Reference images with unsupported provider/model → error with fix hint (switch to Google multimodal: `gemini-3-pro-image-preview`, `gemini-3.1-flash-image-preview`; or OpenAI GPT Image edits)
|
||||
|
||||
## Extension Support
|
||||
|
||||
Custom configurations via EXTEND.md. See **Preferences** section for paths and supported options.
|
||||
197
axhub-make/skills/third-party/baoyu-image-gen/references/config/first-time-setup.md
vendored
Normal file
197
axhub-make/skills/third-party/baoyu-image-gen/references/config/first-time-setup.md
vendored
Normal file
@@ -0,0 +1,197 @@
|
||||
---
|
||||
name: first-time-setup
|
||||
description: First-time setup and default model selection flow for baoyu-image-gen
|
||||
---
|
||||
|
||||
# First-Time Setup
|
||||
|
||||
## Overview
|
||||
|
||||
Triggered when:
|
||||
1. No EXTEND.md found → full setup (provider + model + preferences)
|
||||
2. EXTEND.md found but `default_model.[provider]` is null → model selection only
|
||||
|
||||
## Setup Flow
|
||||
|
||||
```
|
||||
No EXTEND.md found EXTEND.md found, model null
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────────┐ ┌──────────────────────┐
|
||||
│ AskUserQuestion │ │ AskUserQuestion │
|
||||
│ (full setup) │ │ (model only) │
|
||||
└─────────────────────┘ └──────────────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
┌─────────────────────┐ ┌──────────────────────┐
|
||||
│ Create EXTEND.md │ │ Update EXTEND.md │
|
||||
└─────────────────────┘ └──────────────────────┘
|
||||
│ │
|
||||
▼ ▼
|
||||
Continue Continue
|
||||
```
|
||||
|
||||
## Flow 1: No EXTEND.md (Full Setup)
|
||||
|
||||
**Language**: Use user's input language or saved language preference.
|
||||
|
||||
Use AskUserQuestion with ALL questions in ONE call:
|
||||
|
||||
### Question 1: Default Provider
|
||||
|
||||
```yaml
|
||||
header: "Provider"
|
||||
question: "Default image generation provider?"
|
||||
options:
|
||||
- label: "Google (Recommended)"
|
||||
description: "Gemini multimodal - high quality, reference images, flexible sizes"
|
||||
- label: "OpenAI"
|
||||
description: "GPT Image - consistent quality, reliable output"
|
||||
- label: "DashScope"
|
||||
description: "Alibaba Cloud - z-image-turbo, good for Chinese content"
|
||||
- label: "Replicate"
|
||||
description: "Community models - nano-banana-pro, flexible model selection"
|
||||
```
|
||||
|
||||
### Question 2: Default Google Model
|
||||
|
||||
Only show if user selected Google or auto-detect (no explicit provider).
|
||||
|
||||
```yaml
|
||||
header: "Google Model"
|
||||
question: "Default Google image generation model?"
|
||||
options:
|
||||
- label: "gemini-3-pro-image-preview (Recommended)"
|
||||
description: "Highest quality, best for production use"
|
||||
- label: "gemini-3.1-flash-image-preview"
|
||||
description: "Fast generation, good quality, lower cost"
|
||||
- label: "gemini-3-flash-preview"
|
||||
description: "Fast generation, balanced quality and speed"
|
||||
```
|
||||
|
||||
### Question 3: Default Quality
|
||||
|
||||
```yaml
|
||||
header: "Quality"
|
||||
question: "Default image quality?"
|
||||
options:
|
||||
- label: "2k (Recommended)"
|
||||
description: "2048px - covers, illustrations, infographics"
|
||||
- label: "normal"
|
||||
description: "1024px - quick previews, drafts"
|
||||
```
|
||||
|
||||
### Question 4: Save Location
|
||||
|
||||
```yaml
|
||||
header: "Save"
|
||||
question: "Where to save preferences?"
|
||||
options:
|
||||
- label: "Project (Recommended)"
|
||||
description: ".baoyu-skills/ (this project only)"
|
||||
- label: "User"
|
||||
description: "~/.baoyu-skills/ (all projects)"
|
||||
```
|
||||
|
||||
### Save Locations
|
||||
|
||||
| Choice | Path | Scope |
|
||||
|--------|------|-------|
|
||||
| Project | `.baoyu-skills/baoyu-image-gen/EXTEND.md` | Current project |
|
||||
| User | `$HOME/.baoyu-skills/baoyu-image-gen/EXTEND.md` | All projects |
|
||||
|
||||
### EXTEND.md Template
|
||||
|
||||
```yaml
|
||||
---
|
||||
version: 1
|
||||
default_provider: [selected provider or null]
|
||||
default_quality: [selected quality]
|
||||
default_aspect_ratio: null
|
||||
default_image_size: null
|
||||
default_model:
|
||||
google: [selected google model or null]
|
||||
openai: null
|
||||
dashscope: null
|
||||
replicate: null
|
||||
---
|
||||
```
|
||||
|
||||
## Flow 2: EXTEND.md Exists, Model Null
|
||||
|
||||
When EXTEND.md exists but `default_model.[current_provider]` is null, ask ONLY the model question for the current provider.
|
||||
|
||||
### Google Model Selection
|
||||
|
||||
```yaml
|
||||
header: "Google Model"
|
||||
question: "Choose a default Google image generation model?"
|
||||
options:
|
||||
- label: "gemini-3-pro-image-preview (Recommended)"
|
||||
description: "Highest quality, best for production use"
|
||||
- label: "gemini-3.1-flash-image-preview"
|
||||
description: "Fast generation, good quality, lower cost"
|
||||
- label: "gemini-3-flash-preview"
|
||||
description: "Fast generation, balanced quality and speed"
|
||||
```
|
||||
|
||||
### OpenAI Model Selection
|
||||
|
||||
```yaml
|
||||
header: "OpenAI Model"
|
||||
question: "Choose a default OpenAI image generation model?"
|
||||
options:
|
||||
- label: "gpt-image-1.5 (Recommended)"
|
||||
description: "Latest GPT Image model, high quality"
|
||||
- label: "gpt-image-1"
|
||||
description: "Previous generation GPT Image model"
|
||||
```
|
||||
|
||||
### DashScope Model Selection
|
||||
|
||||
```yaml
|
||||
header: "DashScope Model"
|
||||
question: "Choose a default DashScope image generation model?"
|
||||
options:
|
||||
- label: "z-image-turbo (Recommended)"
|
||||
description: "Fast generation, good quality"
|
||||
- label: "z-image-ultra"
|
||||
description: "Higher quality, slower generation"
|
||||
```
|
||||
|
||||
### Replicate Model Selection
|
||||
|
||||
```yaml
|
||||
header: "Replicate Model"
|
||||
question: "Choose a default Replicate image generation model?"
|
||||
options:
|
||||
- label: "google/nano-banana-pro (Recommended)"
|
||||
description: "Google's fast image model on Replicate"
|
||||
- label: "google/nano-banana"
|
||||
description: "Google's base image model on Replicate"
|
||||
```
|
||||
|
||||
### Update EXTEND.md
|
||||
|
||||
After user selects a model:
|
||||
|
||||
1. Read existing EXTEND.md
|
||||
2. If `default_model:` section exists → update the provider-specific key
|
||||
3. If `default_model:` section missing → add the full section:
|
||||
|
||||
```yaml
|
||||
default_model:
|
||||
google: [value or null]
|
||||
openai: [value or null]
|
||||
dashscope: [value or null]
|
||||
replicate: [value or null]
|
||||
```
|
||||
|
||||
Only set the selected provider's model; leave others as their current value or null.
|
||||
|
||||
## After Setup
|
||||
|
||||
1. Create directory if needed
|
||||
2. Write/update EXTEND.md with frontmatter
|
||||
3. Confirm: "Preferences saved to [path]"
|
||||
4. Continue with image generation
|
||||
69
axhub-make/skills/third-party/baoyu-image-gen/references/config/preferences-schema.md
vendored
Normal file
69
axhub-make/skills/third-party/baoyu-image-gen/references/config/preferences-schema.md
vendored
Normal file
@@ -0,0 +1,69 @@
|
||||
---
|
||||
name: preferences-schema
|
||||
description: EXTEND.md YAML schema for baoyu-image-gen user preferences
|
||||
---
|
||||
|
||||
# Preferences Schema
|
||||
|
||||
## Full Schema
|
||||
|
||||
```yaml
|
||||
---
|
||||
version: 1
|
||||
|
||||
default_provider: null # google|openai|dashscope|replicate|null (null = auto-detect)
|
||||
|
||||
default_quality: null # normal|2k|null (null = use default: 2k)
|
||||
|
||||
default_aspect_ratio: null # "16:9"|"1:1"|"4:3"|"3:4"|"2.35:1"|null
|
||||
|
||||
default_image_size: null # 1K|2K|4K|null (Google only, overrides quality)
|
||||
|
||||
default_model:
|
||||
google: null # e.g., "gemini-3-pro-image-preview", "gemini-3.1-flash-image-preview"
|
||||
openai: null # e.g., "gpt-image-1.5"
|
||||
dashscope: null # e.g., "z-image-turbo"
|
||||
replicate: null # e.g., "google/nano-banana-pro"
|
||||
---
|
||||
```
|
||||
|
||||
## Field Reference
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-------|------|---------|-------------|
|
||||
| `version` | int | 1 | Schema version |
|
||||
| `default_provider` | string\|null | null | Default provider (null = auto-detect) |
|
||||
| `default_quality` | string\|null | null | Default quality (null = 2k) |
|
||||
| `default_aspect_ratio` | string\|null | null | Default aspect ratio |
|
||||
| `default_image_size` | string\|null | null | Google image size (overrides quality) |
|
||||
| `default_model.google` | string\|null | null | Google default model |
|
||||
| `default_model.openai` | string\|null | null | OpenAI default model |
|
||||
| `default_model.dashscope` | string\|null | null | DashScope default model |
|
||||
| `default_model.replicate` | string\|null | null | Replicate default model |
|
||||
|
||||
## Examples
|
||||
|
||||
**Minimal**:
|
||||
```yaml
|
||||
---
|
||||
version: 1
|
||||
default_provider: google
|
||||
default_quality: 2k
|
||||
---
|
||||
```
|
||||
|
||||
**Full**:
|
||||
```yaml
|
||||
---
|
||||
version: 1
|
||||
default_provider: google
|
||||
default_quality: 2k
|
||||
default_aspect_ratio: "16:9"
|
||||
default_image_size: 2K
|
||||
default_model:
|
||||
google: "gemini-3-pro-image-preview"
|
||||
openai: "gpt-image-1.5"
|
||||
dashscope: "z-image-turbo"
|
||||
replicate: "google/nano-banana-pro"
|
||||
---
|
||||
```
|
||||
497
axhub-make/skills/third-party/baoyu-image-gen/scripts/main.ts
vendored
Normal file
497
axhub-make/skills/third-party/baoyu-image-gen/scripts/main.ts
vendored
Normal file
@@ -0,0 +1,497 @@
|
||||
import path from "node:path";
|
||||
import process from "node:process";
|
||||
import { homedir } from "node:os";
|
||||
import { access, mkdir, readFile, writeFile } from "node:fs/promises";
|
||||
import type { CliArgs, Provider, ExtendConfig } from "./types";
|
||||
|
||||
function printUsage(): void {
|
||||
console.log(`Usage:
|
||||
npx -y bun scripts/main.ts --prompt "A cat" --image cat.png
|
||||
npx -y bun scripts/main.ts --prompt "A landscape" --image landscape.png --ar 16:9
|
||||
npx -y bun scripts/main.ts --promptfiles system.md content.md --image out.png
|
||||
|
||||
Options:
|
||||
-p, --prompt <text> Prompt text
|
||||
--promptfiles <files...> Read prompt from files (concatenated)
|
||||
--image <path> Output image path (required)
|
||||
--provider google|openai|dashscope|replicate Force provider (auto-detect by default)
|
||||
-m, --model <id> Model ID
|
||||
--ar <ratio> Aspect ratio (e.g., 16:9, 1:1, 4:3)
|
||||
--size <WxH> Size (e.g., 1024x1024)
|
||||
--quality normal|2k Quality preset (default: 2k)
|
||||
--imageSize 1K|2K|4K Image size for Google (default: from quality)
|
||||
--ref <files...> Reference images (Google multimodal or OpenAI edits)
|
||||
--n <count> Number of images (default: 1)
|
||||
--json JSON output
|
||||
-h, --help Show help
|
||||
|
||||
Environment variables:
|
||||
OPENAI_API_KEY OpenAI API key
|
||||
GOOGLE_API_KEY Google API key
|
||||
GEMINI_API_KEY Gemini API key (alias for GOOGLE_API_KEY)
|
||||
DASHSCOPE_API_KEY DashScope API key (阿里云通义万象)
|
||||
REPLICATE_API_TOKEN Replicate API token
|
||||
OPENAI_IMAGE_MODEL Default OpenAI model (gpt-image-1.5)
|
||||
GOOGLE_IMAGE_MODEL Default Google model (gemini-3-pro-image-preview)
|
||||
DASHSCOPE_IMAGE_MODEL Default DashScope model (z-image-turbo)
|
||||
REPLICATE_IMAGE_MODEL Default Replicate model (google/nano-banana-pro)
|
||||
OPENAI_BASE_URL Custom OpenAI endpoint
|
||||
OPENAI_IMAGE_USE_CHAT Use /chat/completions instead of /images/generations (true|false)
|
||||
GOOGLE_BASE_URL Custom Google endpoint
|
||||
DASHSCOPE_BASE_URL Custom DashScope endpoint
|
||||
REPLICATE_BASE_URL Custom Replicate endpoint
|
||||
|
||||
Env file load order: CLI args > EXTEND.md > process.env > <cwd>/.baoyu-skills/.env > ~/.baoyu-skills/.env`);
|
||||
}
|
||||
|
||||
function parseArgs(argv: string[]): CliArgs {
|
||||
const out: CliArgs = {
|
||||
prompt: null,
|
||||
promptFiles: [],
|
||||
imagePath: null,
|
||||
provider: null,
|
||||
model: null,
|
||||
aspectRatio: null,
|
||||
size: null,
|
||||
quality: null,
|
||||
imageSize: null,
|
||||
referenceImages: [],
|
||||
n: 1,
|
||||
json: false,
|
||||
help: false,
|
||||
};
|
||||
|
||||
const positional: string[] = [];
|
||||
|
||||
const takeMany = (i: number): { items: string[]; next: number } => {
|
||||
const items: string[] = [];
|
||||
let j = i + 1;
|
||||
while (j < argv.length) {
|
||||
const v = argv[j]!;
|
||||
if (v.startsWith("-")) break;
|
||||
items.push(v);
|
||||
j++;
|
||||
}
|
||||
return { items, next: j - 1 };
|
||||
};
|
||||
|
||||
for (let i = 0; i < argv.length; i++) {
|
||||
const a = argv[i]!;
|
||||
|
||||
if (a === "--help" || a === "-h") {
|
||||
out.help = true;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (a === "--json") {
|
||||
out.json = true;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (a === "--prompt" || a === "-p") {
|
||||
const v = argv[++i];
|
||||
if (!v) throw new Error(`Missing value for ${a}`);
|
||||
out.prompt = v;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (a === "--promptfiles") {
|
||||
const { items, next } = takeMany(i);
|
||||
if (items.length === 0) throw new Error("Missing files for --promptfiles");
|
||||
out.promptFiles.push(...items);
|
||||
i = next;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (a === "--image") {
|
||||
const v = argv[++i];
|
||||
if (!v) throw new Error("Missing value for --image");
|
||||
out.imagePath = v;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (a === "--provider") {
|
||||
const v = argv[++i];
|
||||
if (v !== "google" && v !== "openai" && v !== "dashscope" && v !== "replicate") throw new Error(`Invalid provider: ${v}`);
|
||||
out.provider = v;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (a === "--model" || a === "-m") {
|
||||
const v = argv[++i];
|
||||
if (!v) throw new Error(`Missing value for ${a}`);
|
||||
out.model = v;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (a === "--ar") {
|
||||
const v = argv[++i];
|
||||
if (!v) throw new Error("Missing value for --ar");
|
||||
out.aspectRatio = v;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (a === "--size") {
|
||||
const v = argv[++i];
|
||||
if (!v) throw new Error("Missing value for --size");
|
||||
out.size = v;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (a === "--quality") {
|
||||
const v = argv[++i];
|
||||
if (v !== "normal" && v !== "2k") throw new Error(`Invalid quality: ${v}`);
|
||||
out.quality = v;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (a === "--imageSize") {
|
||||
const v = argv[++i]?.toUpperCase();
|
||||
if (v !== "1K" && v !== "2K" && v !== "4K") throw new Error(`Invalid imageSize: ${v}`);
|
||||
out.imageSize = v;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (a === "--ref" || a === "--reference") {
|
||||
const { items, next } = takeMany(i);
|
||||
if (items.length === 0) throw new Error(`Missing files for ${a}`);
|
||||
out.referenceImages.push(...items);
|
||||
i = next;
|
||||
continue;
|
||||
}
|
||||
|
||||
if (a === "--n") {
|
||||
const v = argv[++i];
|
||||
if (!v) throw new Error("Missing value for --n");
|
||||
out.n = parseInt(v, 10);
|
||||
if (isNaN(out.n) || out.n < 1) throw new Error(`Invalid count: ${v}`);
|
||||
continue;
|
||||
}
|
||||
|
||||
if (a.startsWith("-")) {
|
||||
throw new Error(`Unknown option: ${a}`);
|
||||
}
|
||||
|
||||
positional.push(a);
|
||||
}
|
||||
|
||||
if (!out.prompt && out.promptFiles.length === 0 && positional.length > 0) {
|
||||
out.prompt = positional.join(" ");
|
||||
}
|
||||
|
||||
return out;
|
||||
}
|
||||
|
||||
async function loadEnvFile(p: string): Promise<Record<string, string>> {
|
||||
try {
|
||||
const content = await readFile(p, "utf8");
|
||||
const env: Record<string, string> = {};
|
||||
for (const line of content.split("\n")) {
|
||||
const trimmed = line.trim();
|
||||
if (!trimmed || trimmed.startsWith("#")) continue;
|
||||
const idx = trimmed.indexOf("=");
|
||||
if (idx === -1) continue;
|
||||
const key = trimmed.slice(0, idx).trim();
|
||||
let val = trimmed.slice(idx + 1).trim();
|
||||
if ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'"))) {
|
||||
val = val.slice(1, -1);
|
||||
}
|
||||
env[key] = val;
|
||||
}
|
||||
return env;
|
||||
} catch {
|
||||
return {};
|
||||
}
|
||||
}
|
||||
|
||||
async function loadEnv(): Promise<void> {
|
||||
const home = homedir();
|
||||
const cwd = process.cwd();
|
||||
|
||||
const homeEnv = await loadEnvFile(path.join(home, ".baoyu-skills", ".env"));
|
||||
const cwdEnv = await loadEnvFile(path.join(cwd, ".baoyu-skills", ".env"));
|
||||
|
||||
for (const [k, v] of Object.entries(homeEnv)) {
|
||||
if (!process.env[k]) process.env[k] = v;
|
||||
}
|
||||
for (const [k, v] of Object.entries(cwdEnv)) {
|
||||
if (!process.env[k]) process.env[k] = v;
|
||||
}
|
||||
}
|
||||
|
||||
function extractYamlFrontMatter(content: string): string | null {
|
||||
const match = content.match(/^---\s*\n([\s\S]*?)\n---\s*$/m);
|
||||
return match ? match[1] : null;
|
||||
}
|
||||
|
||||
function parseSimpleYaml(yaml: string): Partial<ExtendConfig> {
|
||||
const config: Partial<ExtendConfig> = {};
|
||||
const lines = yaml.split("\n");
|
||||
let currentKey: string | null = null;
|
||||
|
||||
for (const line of lines) {
|
||||
const trimmed = line.trim();
|
||||
if (!trimmed || trimmed.startsWith("#")) continue;
|
||||
|
||||
if (trimmed.includes(":") && !trimmed.startsWith("-")) {
|
||||
const colonIdx = trimmed.indexOf(":");
|
||||
const key = trimmed.slice(0, colonIdx).trim();
|
||||
let value = trimmed.slice(colonIdx + 1).trim();
|
||||
|
||||
if (value === "null" || value === "") {
|
||||
value = "null";
|
||||
}
|
||||
|
||||
if (key === "version") {
|
||||
config.version = value === "null" ? 1 : parseInt(value, 10);
|
||||
} else if (key === "default_provider") {
|
||||
config.default_provider = value === "null" ? null : (value as Provider);
|
||||
} else if (key === "default_quality") {
|
||||
config.default_quality = value === "null" ? null : (value as "normal" | "2k");
|
||||
} else if (key === "default_aspect_ratio") {
|
||||
const cleaned = value.replace(/['"]/g, "");
|
||||
config.default_aspect_ratio = cleaned === "null" ? null : cleaned;
|
||||
} else if (key === "default_image_size") {
|
||||
config.default_image_size = value === "null" ? null : (value as "1K" | "2K" | "4K");
|
||||
} else if (key === "default_model") {
|
||||
config.default_model = { google: null, openai: null, dashscope: null, replicate: null };
|
||||
currentKey = "default_model";
|
||||
} else if (currentKey === "default_model" && (key === "google" || key === "openai" || key === "dashscope" || key === "replicate")) {
|
||||
const cleaned = value.replace(/['"]/g, "");
|
||||
config.default_model![key] = cleaned === "null" ? null : cleaned;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
return config;
|
||||
}
|
||||
|
||||
async function loadExtendConfig(): Promise<Partial<ExtendConfig>> {
|
||||
const home = homedir();
|
||||
const cwd = process.cwd();
|
||||
|
||||
const paths = [
|
||||
path.join(cwd, ".baoyu-skills", "baoyu-image-gen", "EXTEND.md"),
|
||||
path.join(home, ".baoyu-skills", "baoyu-image-gen", "EXTEND.md"),
|
||||
];
|
||||
|
||||
for (const p of paths) {
|
||||
try {
|
||||
const content = await readFile(p, "utf8");
|
||||
const yaml = extractYamlFrontMatter(content);
|
||||
if (!yaml) continue;
|
||||
|
||||
return parseSimpleYaml(yaml);
|
||||
} catch {
|
||||
continue;
|
||||
}
|
||||
}
|
||||
|
||||
return {};
|
||||
}
|
||||
|
||||
function mergeConfig(args: CliArgs, extend: Partial<ExtendConfig>): CliArgs {
|
||||
return {
|
||||
...args,
|
||||
provider: args.provider ?? extend.default_provider ?? null,
|
||||
quality: args.quality ?? extend.default_quality ?? null,
|
||||
aspectRatio: args.aspectRatio ?? extend.default_aspect_ratio ?? null,
|
||||
imageSize: args.imageSize ?? extend.default_image_size ?? null,
|
||||
};
|
||||
}
|
||||
|
||||
async function readPromptFromFiles(files: string[]): Promise<string> {
|
||||
const parts: string[] = [];
|
||||
for (const f of files) {
|
||||
parts.push(await readFile(f, "utf8"));
|
||||
}
|
||||
return parts.join("\n\n");
|
||||
}
|
||||
|
||||
async function readPromptFromStdin(): Promise<string | null> {
|
||||
if (process.stdin.isTTY) return null;
|
||||
try {
|
||||
const t = await Bun.stdin.text();
|
||||
const v = t.trim();
|
||||
return v.length > 0 ? v : null;
|
||||
} catch {
|
||||
return null;
|
||||
}
|
||||
}
|
||||
|
||||
function normalizeOutputImagePath(p: string): string {
|
||||
const full = path.resolve(p);
|
||||
const ext = path.extname(full);
|
||||
if (ext) return full;
|
||||
return `${full}.png`;
|
||||
}
|
||||
|
||||
function detectProvider(args: CliArgs): Provider {
|
||||
if (args.referenceImages.length > 0 && args.provider && args.provider !== "google" && args.provider !== "openai" && args.provider !== "replicate") {
|
||||
throw new Error(
|
||||
"Reference images require a ref-capable provider. Use --provider google (Gemini multimodal), --provider openai (GPT Image edits), or --provider replicate."
|
||||
);
|
||||
}
|
||||
|
||||
if (args.provider) return args.provider;
|
||||
|
||||
const hasGoogle = !!(process.env.GOOGLE_API_KEY || process.env.GEMINI_API_KEY);
|
||||
const hasOpenai = !!process.env.OPENAI_API_KEY;
|
||||
const hasDashscope = !!process.env.DASHSCOPE_API_KEY;
|
||||
const hasReplicate = !!process.env.REPLICATE_API_TOKEN;
|
||||
|
||||
if (args.referenceImages.length > 0) {
|
||||
if (hasGoogle) return "google";
|
||||
if (hasOpenai) return "openai";
|
||||
if (hasReplicate) return "replicate";
|
||||
throw new Error(
|
||||
"Reference images require Google, OpenAI or Replicate. Set GOOGLE_API_KEY/GEMINI_API_KEY, OPENAI_API_KEY, or REPLICATE_API_TOKEN, or remove --ref."
|
||||
);
|
||||
}
|
||||
|
||||
const available = [hasGoogle && "google", hasOpenai && "openai", hasDashscope && "dashscope", hasReplicate && "replicate"].filter(Boolean) as Provider[];
|
||||
|
||||
if (available.length === 1) return available[0]!;
|
||||
if (available.length > 1) return available[0]!;
|
||||
|
||||
throw new Error(
|
||||
"No API key found. Set GOOGLE_API_KEY, GEMINI_API_KEY, OPENAI_API_KEY, DASHSCOPE_API_KEY, or REPLICATE_API_TOKEN.\n" +
|
||||
"Create ~/.baoyu-skills/.env or <cwd>/.baoyu-skills/.env with your keys."
|
||||
);
|
||||
}
|
||||
|
||||
async function validateReferenceImages(referenceImages: string[]): Promise<void> {
|
||||
for (const refPath of referenceImages) {
|
||||
const fullPath = path.resolve(refPath);
|
||||
try {
|
||||
await access(fullPath);
|
||||
} catch {
|
||||
throw new Error(`Reference image not found: ${fullPath}`);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
type ProviderModule = {
|
||||
getDefaultModel: () => string;
|
||||
generateImage: (prompt: string, model: string, args: CliArgs) => Promise<Uint8Array>;
|
||||
};
|
||||
|
||||
function isRetryableGenerationError(error: unknown): boolean {
|
||||
const msg = error instanceof Error ? error.message : String(error);
|
||||
const nonRetryableMarkers = [
|
||||
"Reference image",
|
||||
"not supported",
|
||||
"only supported",
|
||||
"No API key found",
|
||||
"is required",
|
||||
];
|
||||
return !nonRetryableMarkers.some((marker) => msg.includes(marker));
|
||||
}
|
||||
|
||||
async function loadProviderModule(provider: Provider): Promise<ProviderModule> {
|
||||
if (provider === "google") {
|
||||
return (await import("./providers/google")) as ProviderModule;
|
||||
}
|
||||
if (provider === "dashscope") {
|
||||
return (await import("./providers/dashscope")) as ProviderModule;
|
||||
}
|
||||
if (provider === "replicate") {
|
||||
return (await import("./providers/replicate")) as ProviderModule;
|
||||
}
|
||||
return (await import("./providers/openai")) as ProviderModule;
|
||||
}
|
||||
|
||||
async function main(): Promise<void> {
|
||||
const args = parseArgs(process.argv.slice(2));
|
||||
|
||||
if (args.help) {
|
||||
printUsage();
|
||||
return;
|
||||
}
|
||||
|
||||
await loadEnv();
|
||||
const extendConfig = await loadExtendConfig();
|
||||
const mergedArgs = mergeConfig(args, extendConfig);
|
||||
|
||||
if (!mergedArgs.quality) mergedArgs.quality = "2k";
|
||||
|
||||
let prompt: string | null = mergedArgs.prompt;
|
||||
if (!prompt && mergedArgs.promptFiles.length > 0) prompt = await readPromptFromFiles(mergedArgs.promptFiles);
|
||||
if (!prompt) prompt = await readPromptFromStdin();
|
||||
|
||||
if (!prompt) {
|
||||
console.error("Error: Prompt is required");
|
||||
printUsage();
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
|
||||
if (!mergedArgs.imagePath) {
|
||||
console.error("Error: --image is required");
|
||||
printUsage();
|
||||
process.exitCode = 1;
|
||||
return;
|
||||
}
|
||||
|
||||
if (mergedArgs.referenceImages.length > 0) {
|
||||
await validateReferenceImages(mergedArgs.referenceImages);
|
||||
}
|
||||
|
||||
const provider = detectProvider(mergedArgs);
|
||||
const providerModule = await loadProviderModule(provider);
|
||||
|
||||
let model = mergedArgs.model;
|
||||
if (!model && extendConfig.default_model) {
|
||||
if (provider === "google") model = extendConfig.default_model.google ?? null;
|
||||
if (provider === "openai") model = extendConfig.default_model.openai ?? null;
|
||||
if (provider === "dashscope") model = extendConfig.default_model.dashscope ?? null;
|
||||
if (provider === "replicate") model = extendConfig.default_model.replicate ?? null;
|
||||
}
|
||||
model = model || providerModule.getDefaultModel();
|
||||
|
||||
const outputPath = normalizeOutputImagePath(mergedArgs.imagePath);
|
||||
|
||||
let imageData: Uint8Array;
|
||||
let retried = false;
|
||||
|
||||
while (true) {
|
||||
try {
|
||||
imageData = await providerModule.generateImage(prompt, model, mergedArgs);
|
||||
break;
|
||||
} catch (e) {
|
||||
if (!retried && isRetryableGenerationError(e)) {
|
||||
retried = true;
|
||||
console.error("Generation failed, retrying...");
|
||||
continue;
|
||||
}
|
||||
throw e;
|
||||
}
|
||||
}
|
||||
|
||||
const dir = path.dirname(outputPath);
|
||||
await mkdir(dir, { recursive: true });
|
||||
await writeFile(outputPath, imageData);
|
||||
|
||||
if (mergedArgs.json) {
|
||||
console.log(
|
||||
JSON.stringify(
|
||||
{
|
||||
savedImage: outputPath,
|
||||
provider,
|
||||
model,
|
||||
prompt: prompt.slice(0, 200),
|
||||
},
|
||||
null,
|
||||
2
|
||||
)
|
||||
);
|
||||
} else {
|
||||
console.log(outputPath);
|
||||
}
|
||||
}
|
||||
|
||||
main().catch((e) => {
|
||||
const msg = e instanceof Error ? e.message : String(e);
|
||||
console.error(msg);
|
||||
process.exit(1);
|
||||
});
|
||||
32
axhub-make/skills/third-party/baoyu-image-gen/scripts/types.ts
vendored
Normal file
32
axhub-make/skills/third-party/baoyu-image-gen/scripts/types.ts
vendored
Normal file
@@ -0,0 +1,32 @@
|
||||
export type Provider = "google" | "openai" | "dashscope" | "replicate";
|
||||
export type Quality = "normal" | "2k";
|
||||
|
||||
export type CliArgs = {
|
||||
prompt: string | null;
|
||||
promptFiles: string[];
|
||||
imagePath: string | null;
|
||||
provider: Provider | null;
|
||||
model: string | null;
|
||||
aspectRatio: string | null;
|
||||
size: string | null;
|
||||
quality: Quality | null;
|
||||
imageSize: string | null;
|
||||
referenceImages: string[];
|
||||
n: number;
|
||||
json: boolean;
|
||||
help: boolean;
|
||||
};
|
||||
|
||||
export type ExtendConfig = {
|
||||
version: number;
|
||||
default_provider: Provider | null;
|
||||
default_quality: Quality | null;
|
||||
default_aspect_ratio: string | null;
|
||||
default_image_size: "1K" | "2K" | "4K" | null;
|
||||
default_model: {
|
||||
google: string | null;
|
||||
openai: string | null;
|
||||
dashscope: string | null;
|
||||
replicate: string | null;
|
||||
};
|
||||
};
|
||||
96
axhub-make/skills/third-party/brainstorming/SKILL.md
vendored
Normal file
96
axhub-make/skills/third-party/brainstorming/SKILL.md
vendored
Normal file
@@ -0,0 +1,96 @@
|
||||
---
|
||||
name: brainstorming
|
||||
description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation."
|
||||
---
|
||||
|
||||
# Brainstorming Ideas Into Designs
|
||||
|
||||
## Overview
|
||||
|
||||
Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
|
||||
|
||||
Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
|
||||
|
||||
<HARD-GATE>
|
||||
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
|
||||
</HARD-GATE>
|
||||
|
||||
## Anti-Pattern: "This Is Too Simple To Need A Design"
|
||||
|
||||
Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
|
||||
|
||||
## Checklist
|
||||
|
||||
You MUST create a task for each of these items and complete them in order:
|
||||
|
||||
1. **Explore project context** — check files, docs, recent commits
|
||||
2. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
|
||||
3. **Propose 2-3 approaches** — with trade-offs and your recommendation
|
||||
4. **Present design** — in sections scaled to their complexity, get user approval after each section
|
||||
5. **Write design doc** — save to `docs/plans/YYYY-MM-DD-<topic>-design.md` and commit
|
||||
6. **Transition to implementation** — invoke writing-plans skill to create implementation plan
|
||||
|
||||
## Process Flow
|
||||
|
||||
```dot
|
||||
digraph brainstorming {
|
||||
"Explore project context" [shape=box];
|
||||
"Ask clarifying questions" [shape=box];
|
||||
"Propose 2-3 approaches" [shape=box];
|
||||
"Present design sections" [shape=box];
|
||||
"User approves design?" [shape=diamond];
|
||||
"Write design doc" [shape=box];
|
||||
"Invoke writing-plans skill" [shape=doublecircle];
|
||||
|
||||
"Explore project context" -> "Ask clarifying questions";
|
||||
"Ask clarifying questions" -> "Propose 2-3 approaches";
|
||||
"Propose 2-3 approaches" -> "Present design sections";
|
||||
"Present design sections" -> "User approves design?";
|
||||
"User approves design?" -> "Present design sections" [label="no, revise"];
|
||||
"User approves design?" -> "Write design doc" [label="yes"];
|
||||
"Write design doc" -> "Invoke writing-plans skill";
|
||||
}
|
||||
```
|
||||
|
||||
**The terminal state is invoking writing-plans.** Do NOT invoke frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you invoke after brainstorming is writing-plans.
|
||||
|
||||
## The Process
|
||||
|
||||
**Understanding the idea:**
|
||||
- Check out the current project state first (files, docs, recent commits)
|
||||
- Ask questions one at a time to refine the idea
|
||||
- Prefer multiple choice questions when possible, but open-ended is fine too
|
||||
- Only one question per message - if a topic needs more exploration, break it into multiple questions
|
||||
- Focus on understanding: purpose, constraints, success criteria
|
||||
|
||||
**Exploring approaches:**
|
||||
- Propose 2-3 different approaches with trade-offs
|
||||
- Present options conversationally with your recommendation and reasoning
|
||||
- Lead with your recommended option and explain why
|
||||
|
||||
**Presenting the design:**
|
||||
- Once you believe you understand what you're building, present the design
|
||||
- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
|
||||
- Ask after each section whether it looks right so far
|
||||
- Cover: architecture, components, data flow, error handling, testing
|
||||
- Be ready to go back and clarify if something doesn't make sense
|
||||
|
||||
## After the Design
|
||||
|
||||
**Documentation:**
|
||||
- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
|
||||
- Use elements-of-style:writing-clearly-and-concisely skill if available
|
||||
- Commit the design document to git
|
||||
|
||||
**Implementation:**
|
||||
- Invoke the writing-plans skill to create a detailed implementation plan
|
||||
- Do NOT invoke any other skill. writing-plans is the next step.
|
||||
|
||||
## Key Principles
|
||||
|
||||
- **One question at a time** - Don't overwhelm with multiple questions
|
||||
- **Multiple choice preferred** - Easier to answer than open-ended when possible
|
||||
- **YAGNI ruthlessly** - Remove unnecessary features from all designs
|
||||
- **Explore alternatives** - Always propose 2-3 approaches before settling
|
||||
- **Incremental validation** - Present design, get approval before moving on
|
||||
- **Be flexible** - Go back and clarify when something doesn't make sense
|
||||
30
axhub-make/skills/third-party/deep-research/.gitignore
vendored
Normal file
30
axhub-make/skills/third-party/deep-research/.gitignore
vendored
Normal file
@@ -0,0 +1,30 @@
|
||||
# Python
|
||||
__pycache__/
|
||||
*.py[cod]
|
||||
*$py.class
|
||||
*.so
|
||||
.Python
|
||||
|
||||
# Virtual environments
|
||||
venv/
|
||||
ENV/
|
||||
env/
|
||||
|
||||
# IDE
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
|
||||
# OS
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
|
||||
# Research output (kept local)
|
||||
*.json
|
||||
|
||||
# Test output
|
||||
.pytest_cache/
|
||||
.coverage
|
||||
htmlcov/
|
||||
495
axhub-make/skills/third-party/deep-research/ARCHITECTURE_REVIEW.md
vendored
Normal file
495
axhub-make/skills/third-party/deep-research/ARCHITECTURE_REVIEW.md
vendored
Normal file
@@ -0,0 +1,495 @@
|
||||
# Deep Research Skill: Architecture Review & Failure Analysis
|
||||
|
||||
**Date:** 2025-11-04
|
||||
**Purpose:** Comprehensive quality check against industry best practices and known LLM failure modes
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
**Status:** PRODUCTION-READY with 3 optimization recommendations
|
||||
|
||||
**Critical Issues:** 0
|
||||
**Optimization Opportunities:** 3
|
||||
**Strengths:** 8
|
||||
|
||||
---
|
||||
|
||||
## 1. COMPARISON TO INDUSTRY IMPLEMENTATIONS
|
||||
|
||||
### vs. AnkitClassicVision/Claude-Code-Deep-Research
|
||||
|
||||
| Feature | Their Approach | Our Approach | Winner |
|
||||
|---------|---------------|--------------|--------|
|
||||
| **Phases** | 7 (Scope→Plan→Retrieve→Triangulate→Draft→Critique→Package) | 8 (adds REFINE after Critique) | **Ours** (gap filling) |
|
||||
| **Validation** | Not documented | Automated 8-check system | **Ours** |
|
||||
| **Failure Handling** | Not documented | Explicit stop rules + error gates | **Ours** |
|
||||
| **Graph-of-Thoughts** | Yes, subagent spawning | Yes, parallel agents | **Tie** |
|
||||
| **Credibility Scoring** | Basic triangulation | 0-100 quantitative system | **Ours** |
|
||||
| **State Management** | Not documented | JSON serialization, recoverable | **Ours** |
|
||||
|
||||
**Verdict:** Our implementation is MORE ROBUST with superior validation and failure handling.
|
||||
|
||||
---
|
||||
|
||||
## 2. ALIGNMENT WITH ANTHROPIC BEST PRACTICES
|
||||
|
||||
### From Official Documentation & Community Research
|
||||
|
||||
✅ **PASS: Frontmatter Format**
|
||||
- Proper YAML with `name:` and `description:`
|
||||
- Description includes triggers and exclusions
|
||||
|
||||
✅ **PASS: Self-Contained Structure**
|
||||
- All resources in single directory
|
||||
- Progressive disclosure via references
|
||||
- No external dependencies (stdlib only)
|
||||
|
||||
⚠️ **WARNING: SKILL.md Length**
|
||||
- Current: 343 lines
|
||||
- Best practice recommendation: 100-200 lines
|
||||
- Official Anthropic: "No strict maximum" for complex skills with scripts
|
||||
- **Assessment:** ACCEPTABLE given complexity, but could optimize
|
||||
|
||||
✅ **PASS: Context Management**
|
||||
- Static-first architecture for caching (>1024 tokens)
|
||||
- Explicit cache boundary markers
|
||||
- Progressive loading (not full inline)
|
||||
- "Loss in the middle" avoidance
|
||||
|
||||
✅ **PASS: Plan-First Approach**
|
||||
- Decision tree at top of SKILL.md
|
||||
- Mode selection before execution
|
||||
- Phase-by-phase instructions
|
||||
|
||||
---
|
||||
|
||||
## 3. FAILURE MODE ANALYSIS
|
||||
|
||||
### Based on Research: "Why Do Multi-Agent LLM Systems Fail?" (arXiv:2503.13657)
|
||||
|
||||
#### 3.1 System Design Issues
|
||||
|
||||
**ISSUE: No referee for correctness validation**
|
||||
- ✅ **MITIGATED:** We have automated validator with 8 checks
|
||||
- ✅ **MITIGATED:** Human review required after 2 validation failures
|
||||
|
||||
**ISSUE: Poor termination conditions**
|
||||
- ⚠️ **PARTIAL:** Our modes define phase counts but no explicit timeout enforcement
|
||||
- **RECOMMENDATION:** Add max time limits per mode in SKILL.md
|
||||
|
||||
**ISSUE: Memory gaps (agents don't retain context)**
|
||||
- ✅ **MITIGATED:** ResearchState with JSON serialization
|
||||
- ✅ **MITIGATED:** State saved after each phase
|
||||
|
||||
#### 3.2 Inter-Agent Misalignment
|
||||
|
||||
**ISSUE: Agents work at cross-purposes**
|
||||
- ✅ **MITIGATED:** Single orchestration flow, no conflicting subagents
|
||||
- ✅ **MITIGATED:** Clear phase boundaries and handoffs
|
||||
|
||||
**ISSUE: Communication failures between agents**
|
||||
- ✅ **MITIGATED:** Centralized ResearchState, not distributed agents
|
||||
- Note: We use Task tool for parallel retrieval, not autonomous multi-agent
|
||||
|
||||
#### 3.3 Task Verification Problems
|
||||
|
||||
**ISSUE: Incomplete results go unchecked**
|
||||
- ✅ **MITIGATED:** Validator checks all required sections
|
||||
- ✅ **MITIGATED:** 3+ source triangulation enforced
|
||||
- ✅ **MITIGATED:** Credibility scoring (average must be >60/100)
|
||||
|
||||
**ISSUE: Iteration loops and cognitive deadlocks**
|
||||
- ✅ **MITIGATED:** Max 2 validation fix attempts, then escalate to user
|
||||
- ⚠️ **PARTIAL:** No explicit iteration limit for REFINE phase
|
||||
- **RECOMMENDATION:** Add max iterations to REFINE phase
|
||||
|
||||
---
|
||||
|
||||
## 4. SINGLE POINTS OF FAILURE (SPOF) ANALYSIS
|
||||
|
||||
### 4.1 CRITICAL PATH ANALYSIS
|
||||
|
||||
```
|
||||
User Query
|
||||
↓
|
||||
Decision Tree (SCOPE check) ← SPOF #1: If wrong decision, wastes resources
|
||||
↓
|
||||
Phase Execution Loop
|
||||
↓
|
||||
Validation Gate ← SPOF #2: If validator has bugs, bad reports pass
|
||||
↓
|
||||
File Write ← SPOF #3: If filesystem fails, research lost
|
||||
↓
|
||||
Delivery
|
||||
```
|
||||
|
||||
#### SPOF #1: Decision Tree Misclassification
|
||||
**Risk:** Skill invoked for simple lookups, wastes time
|
||||
**Mitigation:** ✅ Explicit "Do NOT use" in description
|
||||
**Status:** LOW RISK
|
||||
|
||||
#### SPOF #2: Validator Bugs
|
||||
**Risk:** Broken validation lets bad reports through
|
||||
**Mitigation:** ✅ Test fixtures (valid/invalid reports tested)
|
||||
**Evidence:** Test report passed ALL 8 CHECKS
|
||||
**Status:** LOW RISK (well-tested)
|
||||
|
||||
#### SPOF #3: Filesystem Failures
|
||||
**Risk:** Research completes but file write fails
|
||||
**Mitigation:** ⚠️ No retry logic for file operations
|
||||
**Recommendation:** Add try-except with retry for file writes
|
||||
**Status:** MEDIUM RISK
|
||||
|
||||
#### SPOF #4: Web Search API Unavailable
|
||||
**Risk:** Cannot retrieve sources, research fails
|
||||
**Mitigation:** ❌ No fallback mechanism
|
||||
**Recommendation:** Graceful degradation message to user
|
||||
**Status:** MEDIUM RISK (external dependency)
|
||||
|
||||
### 4.2 DEPENDENCY ANALYSIS
|
||||
|
||||
**External Dependencies:**
|
||||
1. WebSearch tool (Claude Code built-in) ← Cannot control
|
||||
2. Filesystem write access ← Usually reliable
|
||||
3. Python 3.x interpreter ← Standard
|
||||
|
||||
**Internal Dependencies:**
|
||||
1. validate_report.py ← Tested ✅
|
||||
2. source_evaluator.py ← Logic-based, no external calls ✅
|
||||
3. citation_manager.py ← String manipulation only ✅
|
||||
4. research_engine.py ← Orchestration, state management ✅
|
||||
|
||||
**Assessment:** Minimal dependency risk. Core functionality is self-contained.
|
||||
|
||||
---
|
||||
|
||||
## 5. OCCAM'S RAZOR: SIMPLIFICATION ANALYSIS
|
||||
|
||||
### Question: Is our 8-phase pipeline over-engineered?
|
||||
|
||||
#### Comparison of Approaches
|
||||
|
||||
**Minimal (3 phases):**
|
||||
Scope → Retrieve → Package
|
||||
- ❌ No verification
|
||||
- ❌ No synthesis
|
||||
- ❌ No quality control
|
||||
|
||||
**Standard (6 phases):**
|
||||
Scope → Plan → Retrieve → Triangulate → Synthesize → Package
|
||||
- ✅ Verification
|
||||
- ✅ Synthesis
|
||||
- ⚠️ No critique/refinement
|
||||
|
||||
**Our Approach (8 phases):**
|
||||
Scope → Plan → Retrieve → Triangulate → Synthesize → Critique → Refine → Package
|
||||
- ✅ Verification
|
||||
- ✅ Synthesis
|
||||
- ✅ Red-team critique
|
||||
- ✅ Gap filling
|
||||
|
||||
**Competitor (7 phases):**
|
||||
AnkitClassicVision has 7 phases (no separate REFINE)
|
||||
|
||||
#### Analysis
|
||||
|
||||
**REFINE Phase:**
|
||||
- Purpose: Address gaps identified in CRITIQUE
|
||||
- Cost: 2-5 additional minutes
|
||||
- Benefit: Completeness, addresses weaknesses before delivery
|
||||
- **Verdict:** JUSTIFIED for deep/ultradeep modes, COULD SKIP in quick/standard
|
||||
|
||||
**RECOMMENDATION:** Make REFINE phase conditional:
|
||||
- Quick mode: Skip
|
||||
- Standard mode: Skip (stay at 6 phases)
|
||||
- Deep mode: Include
|
||||
- UltraDeep mode: Include + iterate
|
||||
|
||||
**Potential Savings:**
|
||||
- Standard mode: 5-10 min → 4-8 min (faster than competitor's 7 phases)
|
||||
- Still beat OpenAI (5-30 min) and Gemini (2-5 min but lower quality)
|
||||
|
||||
---
|
||||
|
||||
## 6. WRITING STANDARDS ENFORCEMENT
|
||||
|
||||
### New Requirements (Added Today)
|
||||
|
||||
✅ **Precision:** Every word deliberately chosen
|
||||
✅ **Economy:** No fluff, eliminate fancy grammar
|
||||
✅ **Clarity:** Exact numbers, specific data
|
||||
✅ **Directness:** State findings without embellishment
|
||||
✅ **High signal-to-noise:** Dense information
|
||||
|
||||
### Implementation Locations
|
||||
|
||||
1. **SKILL.md lines 195-204:** Writing Standards section with examples
|
||||
2. **SKILL.md lines 160-165:** Report section standards
|
||||
3. **report_template.md lines 8-15:** Top-level HTML comments
|
||||
4. **report_template.md lines 59-61:** Main Analysis comments
|
||||
|
||||
### Verification Method
|
||||
|
||||
**Before:** No explicit guidance → LLM might use vague language
|
||||
**After:** 4 enforcement points with concrete examples
|
||||
|
||||
**Example transformation enforced:**
|
||||
- ❌ "significantly improved outcomes"
|
||||
- ✅ "reduced mortality 23% (p<0.01)"
|
||||
|
||||
---
|
||||
|
||||
## 7. STRESS TEST: EDGE CASES
|
||||
|
||||
### 7.1 Low Source Availability (<10 sources)
|
||||
|
||||
**Current Handling:**
|
||||
- ✅ Validator flags warning if <10 sources
|
||||
- ✅ SKILL.md says "document if fewer"
|
||||
- ⚠️ No automatic stop if 0-5 sources found
|
||||
|
||||
**RECOMMENDATION:** Add hard stop at <5 sources:
|
||||
```markdown
|
||||
**Stop immediately if:**
|
||||
- <5 sources after exhaustive search → Report limitation, ask user
|
||||
```
|
||||
**Status:** Already present in SKILL.md line 207 ✅
|
||||
|
||||
### 7.2 Contradictory Sources
|
||||
|
||||
**Current Handling:**
|
||||
- ✅ TRIANGULATE phase cross-references
|
||||
- ✅ Flag contradictions explicitly
|
||||
- ✅ Source credibility scoring helps prioritize
|
||||
|
||||
**Status:** HANDLED ✅
|
||||
|
||||
### 7.3 Time Pressure (User Wants Quick Result)
|
||||
|
||||
**Current Handling:**
|
||||
- ✅ Quick mode: 2-5 min with 3 phases
|
||||
- ✅ Mode selection at start
|
||||
|
||||
**Status:** HANDLED ✅
|
||||
|
||||
### 7.4 Technical Topic with Limited Public Sources
|
||||
|
||||
**Current Handling:**
|
||||
- ⚠️ No specialized academic database access
|
||||
- ⚠️ Relies entirely on WebSearch tool
|
||||
|
||||
**Note:** Competitor (K-Dense-AI/claude-scientific-skills) provides access to 26 scientific databases including PubMed, PubChem, AlphaFold DB.
|
||||
|
||||
**RECOMMENDATION:** Future enhancement - MCP server for academic databases
|
||||
|
||||
---
|
||||
|
||||
## 8. VALIDATION INFRASTRUCTURE ROBUSTNESS
|
||||
|
||||
### 8.1 Validator Test Coverage
|
||||
|
||||
**Test Fixtures:**
|
||||
- ✅ `valid_report.md` - passes all checks
|
||||
- ✅ `invalid_report.md` - triggers specific failures
|
||||
|
||||
**Test Execution:**
|
||||
```bash
|
||||
python scripts/validate_report.py --report tests/fixtures/valid_report.md
|
||||
# Result: ALL 8 CHECKS PASSED ✅
|
||||
```
|
||||
|
||||
**Real-World Test:**
|
||||
```bash
|
||||
python scripts/validate_report.py --report ../../research_output/senolytics_clinical_trials_test.md
|
||||
# Result: ALL 8 CHECKS PASSED ✅
|
||||
# Report: 2,356 words, 15 sources
|
||||
```
|
||||
|
||||
**Coverage:**
|
||||
1. ✅ Executive summary length (50-250 words)
|
||||
2. ✅ Required sections present
|
||||
3. ✅ Citations formatted [1], [2], [3]
|
||||
4. ✅ Bibliography matches citations
|
||||
5. ✅ No placeholder text (TBD, TODO)
|
||||
6. ✅ Word count reasonable (500-10000)
|
||||
7. ✅ Minimum 10 sources
|
||||
8. ✅ No broken internal links
|
||||
|
||||
**Status:** ROBUST ✅
|
||||
|
||||
### 8.2 Edge Case: What if Validator Itself Fails?
|
||||
|
||||
**Current Handling:**
|
||||
```python
|
||||
except Exception as e:
|
||||
print(f"❌ ERROR: Cannot read report: {e}")
|
||||
sys.exit(1)
|
||||
```
|
||||
|
||||
**Issue:** Generic exception catch, no retry logic
|
||||
**Risk:** Medium (validator crash would block delivery)
|
||||
**RECOMMENDATION:** Add validator self-test on invocation
|
||||
|
||||
---
|
||||
|
||||
## 9. PERFORMANCE BENCHMARKS
|
||||
|
||||
### Speed Comparison
|
||||
|
||||
| Implementation | Time | Phases | Quality |
|
||||
|----------------|------|--------|---------|
|
||||
| Claude Desktop | <1 min | Unknown | Low (no citations) |
|
||||
| Gemini Deep Research | 2-5 min | Unknown | Medium |
|
||||
| OpenAI Deep Research | 5-30 min | Unknown | High |
|
||||
| AnkitClassicVision | Unknown | 7 | Unknown (no validation) |
|
||||
| **Ours (Quick)** | **2-5 min** | **3** | **Medium** |
|
||||
| **Ours (Standard)** | **5-10 min** | **6** | **High** |
|
||||
| **Ours (Deep)** | **10-20 min** | **8** | **Highest** |
|
||||
| **Ours (UltraDeep)** | **20-45 min** | **8+** | **Highest** |
|
||||
|
||||
**Positioning:**
|
||||
- Quick mode: Competitive with Gemini (2-5 min)
|
||||
- Standard mode: Faster than OpenAI (5-10 vs 5-30)
|
||||
- Deep mode: Unmatched quality, reasonable time
|
||||
- UltraDeep mode: Premium tier, maximum rigor
|
||||
|
||||
---
|
||||
|
||||
## 10. RECOMMENDATIONS SUMMARY
|
||||
|
||||
### CRITICAL (0)
|
||||
None identified. System is production-ready.
|
||||
|
||||
### HIGH PRIORITY (2)
|
||||
|
||||
**1. Add Filesystem Retry Logic**
|
||||
```python
|
||||
# In report writing
|
||||
max_retries = 3
|
||||
for attempt in range(max_retries):
|
||||
try:
|
||||
output_path.write_text(report)
|
||||
break
|
||||
except IOError as e:
|
||||
if attempt == max_retries - 1:
|
||||
raise
|
||||
time.sleep(1)
|
||||
```
|
||||
|
||||
**2. Conditional REFINE Phase**
|
||||
Update SKILL.md and research_engine.py:
|
||||
```python
|
||||
def get_phases_for_mode(mode: ResearchMode) -> List[ResearchPhase]:
|
||||
if mode == ResearchMode.QUICK:
|
||||
return [SCOPE, RETRIEVE, PACKAGE]
|
||||
elif mode == ResearchMode.STANDARD:
|
||||
return [SCOPE, PLAN, RETRIEVE, TRIANGULATE, SYNTHESIZE, PACKAGE] # Skip REFINE
|
||||
elif mode == ResearchMode.DEEP:
|
||||
return [SCOPE, PLAN, RETRIEVE, TRIANGULATE, SYNTHESIZE, CRITIQUE, REFINE, PACKAGE]
|
||||
# ...
|
||||
```
|
||||
|
||||
### MEDIUM PRIORITY (3)
|
||||
|
||||
**3. Add Explicit Timeout Enforcement**
|
||||
```markdown
|
||||
**Time Limits:**
|
||||
- Quick mode: 5 min max
|
||||
- Standard mode: 12 min max
|
||||
- Deep mode: 25 min max
|
||||
- UltraDeep mode: 50 min max
|
||||
```
|
||||
|
||||
**4. Add WebSearch Failure Graceful Degradation**
|
||||
```markdown
|
||||
**If WebSearch unavailable:**
|
||||
- Notify user immediately
|
||||
- Ask if they want to proceed with limited sources
|
||||
- Document limitation prominently in report
|
||||
```
|
||||
|
||||
**5. Add REFINE Phase Iteration Limit**
|
||||
```markdown
|
||||
**REFINE Phase:**
|
||||
- Max 2 iterations
|
||||
- If gaps remain after 2 iterations, document in limitations section
|
||||
```
|
||||
|
||||
### LOW PRIORITY (1)
|
||||
|
||||
**6. Future Enhancement: Academic Database Access**
|
||||
- Consider MCP server for PubMed, PubChem, ArXiv
|
||||
- Would match K-Dense-AI/claude-scientific-skills capability
|
||||
- Not blocking for current use cases
|
||||
|
||||
---
|
||||
|
||||
## 11. FINAL VERDICT
|
||||
|
||||
### Architecture Soundness: ✅ EXCELLENT
|
||||
|
||||
**Strengths:**
|
||||
1. Superior validation infrastructure vs competitors
|
||||
2. Robust state management with recovery
|
||||
3. Well-tested with fixtures and real-world data
|
||||
4. Context-optimized (85% latency reduction potential)
|
||||
5. Writing standards enforce precision and clarity
|
||||
6. Graceful degradation paths
|
||||
7. Minimal external dependencies
|
||||
8. Progressive disclosure for efficiency
|
||||
|
||||
**Weaknesses:**
|
||||
1. No filesystem retry logic (easy fix)
|
||||
2. REFINE phase not conditional by mode (optimization opportunity)
|
||||
3. No explicit timeout enforcement (nice-to-have)
|
||||
|
||||
### Occam's Razor Assessment: ✅ APPROPRIATELY COMPLEX
|
||||
|
||||
The 8-phase pipeline is justified for deep research. Making REFINE conditional would optimize standard mode without sacrificing quality.
|
||||
|
||||
### Production Readiness: ✅ READY
|
||||
|
||||
The system is production-ready with minor optimizations available. Zero critical blockers identified.
|
||||
|
||||
---
|
||||
|
||||
## 12. COMPARISON TO ORIGINAL REQUIREMENTS
|
||||
|
||||
### User's Request:
|
||||
> "Can you create a skill that does a high level if not better version of that [Claude Desktop deep research] -- it can use python scrips and libraries, don't hesitate to inspire yourself with github repo. Once done deploy globally so i can use in any instance of claude code."
|
||||
|
||||
### Delivered:
|
||||
|
||||
✅ **High-level or better:** Beats Claude Desktop, OpenAI, Gemini in quality
|
||||
✅ **Python scripts:** 4 scripts (research_engine, validator, source_evaluator, citation_manager)
|
||||
✅ **GitHub inspiration:** Analyzed AnkitClassicVision, Anthropic official, community repos
|
||||
✅ **Globally deployed:** Located in `~/.claude/skills/deep-research/`
|
||||
✅ **Works in any instance:** Self-contained, no external dependencies
|
||||
|
||||
### Additional Deliverables (Beyond Request):
|
||||
|
||||
✅ Automated validation (8 checks)
|
||||
✅ Source credibility scoring (0-100)
|
||||
✅ 4 depth modes (quick/standard/deep/ultradeep)
|
||||
✅ Context optimization (2025 best practices)
|
||||
✅ Writing standards enforcement (precision, economy)
|
||||
✅ Comprehensive documentation (6 supporting files)
|
||||
✅ Test fixtures and real-world validation
|
||||
✅ Competitive analysis vs market leaders
|
||||
|
||||
---
|
||||
|
||||
## CONCLUSION
|
||||
|
||||
The deep research skill is **production-ready** with **zero critical issues** and outperforms competing implementations in validation, failure handling, and quality control.
|
||||
|
||||
The 2 high-priority optimizations (filesystem retry, conditional REFINE) would enhance robustness and efficiency but are not blocking.
|
||||
|
||||
**Overall Grade: A (95/100)**
|
||||
|
||||
*Deductions:*
|
||||
- -3 for missing filesystem retry logic
|
||||
- -2 for non-conditional REFINE phase
|
||||
|
||||
**Recommendation:** Deploy as-is, implement optimizations in v1.1 based on real-world usage patterns.
|
||||
420
axhub-make/skills/third-party/deep-research/AUTONOMY_VERIFICATION.md
vendored
Normal file
420
axhub-make/skills/third-party/deep-research/AUTONOMY_VERIFICATION.md
vendored
Normal file
@@ -0,0 +1,420 @@
|
||||
# Autonomy Verification: Claude Code Skill Independence
|
||||
|
||||
**Date:** 2025-11-04
|
||||
**Purpose:** Verify deep-research skill operates autonomously without blocking user interaction
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
✅ **VERIFIED: Skill operates autonomously by default**
|
||||
|
||||
- **Discovery**: Properly configured with valid YAML frontmatter
|
||||
- **Autonomy**: Optimized for independent operation
|
||||
- **Blocking**: Only stops for critical errors (by design)
|
||||
- **Scripts**: No interactive prompts
|
||||
- **Default behavior**: Proceed → Execute → Deliver
|
||||
|
||||
---
|
||||
|
||||
## 1. SKILL DISCOVERY VERIFICATION
|
||||
|
||||
### Location Check
|
||||
```
|
||||
~/.claude/skills/deep-research/
|
||||
└── SKILL.md (with valid YAML frontmatter)
|
||||
```
|
||||
|
||||
**Status:** ✅ DISCOVERED
|
||||
|
||||
### Frontmatter Validation
|
||||
```yaml
|
||||
---
|
||||
name: deep-research
|
||||
description: Conduct enterprise-grade research with multi-source synthesis, citation tracking, and verification. Use when user needs comprehensive analysis requiring 10+ sources, verified claims, or comparison of approaches. Triggers include "deep research", "comprehensive analysis", "research report", "compare X vs Y", or "analyze trends". Do NOT use for simple lookups, debugging, or questions answerable with 1-2 searches.
|
||||
---
|
||||
```
|
||||
|
||||
**Python YAML Parser:** ✅ VALID
|
||||
**Description Length:** 414 characters
|
||||
**Trigger Keywords:** "deep research", "comprehensive analysis", "research report", "compare X vs Y", "analyze trends"
|
||||
**Exclusions:** "simple lookups", "debugging", "1-2 searches"
|
||||
|
||||
---
|
||||
|
||||
## 2. AUTONOMY OPTIMIZATION
|
||||
|
||||
### Before Optimization (Issues Identified)
|
||||
|
||||
**ISSUE #1: Clarify Section Too Aggressive**
|
||||
```markdown
|
||||
**When to ask:**
|
||||
- Question ambiguous or vague
|
||||
- Scope unclear (too broad/narrow)
|
||||
- Mode unspecified for complex topics
|
||||
- Time constraints critical
|
||||
```
|
||||
**Problem:** Could cause Claude to stop and ask questions too frequently, breaking autonomous flow.
|
||||
|
||||
**ISSUE #2: Preview Section Ambiguous**
|
||||
```markdown
|
||||
**Preview scope if:**
|
||||
- Mode is deep/ultradeep
|
||||
- Topic highly specialized
|
||||
- User requests preview
|
||||
```
|
||||
**Problem:** Unclear if this means "wait for approval" or just "announce plan and proceed".
|
||||
|
||||
### After Optimization (Fixed)
|
||||
|
||||
**FIX #1: Autonomy-First Clarify**
|
||||
```markdown
|
||||
### 1. Clarify (Rarely Needed - Prefer Autonomy)
|
||||
|
||||
**DEFAULT: Proceed autonomously. Make reasonable assumptions based on query context.**
|
||||
|
||||
**ONLY ask if CRITICALLY ambiguous:**
|
||||
- Query is genuinely incomprehensible (e.g., "research the thing")
|
||||
- Contradictory requirements (e.g., "quick 50-source ultradeep analysis")
|
||||
|
||||
**When in doubt: PROCEED with standard mode. User can redirect if needed.**
|
||||
|
||||
**Good autonomous assumptions:**
|
||||
- Technical query → Assume technical audience
|
||||
- Comparison query → Assume balanced perspective needed
|
||||
- Trend query → Assume recent 1-2 years unless specified
|
||||
- Standard mode is default for most queries
|
||||
```
|
||||
|
||||
**FIX #2: Clear Announcement (No Blocking)**
|
||||
```markdown
|
||||
**Announce plan (then proceed immediately):**
|
||||
- Briefly state: selected mode, estimated time, number of sources
|
||||
- Example: "Starting standard mode research (5-10 min, 15-30 sources)"
|
||||
- NO need to wait for approval - proceed directly to execution
|
||||
```
|
||||
|
||||
**FIX #3: Explicit Autonomy Principle**
|
||||
```markdown
|
||||
**AUTONOMY PRINCIPLE:** This skill operates independently. Proceed with reasonable assumptions. Only stop for critical errors or genuinely incomprehensible queries.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. AUTONOMOUS OPERATION FLOW
|
||||
|
||||
### Happy Path (No User Interaction)
|
||||
|
||||
```
|
||||
User Input: "deep research on quantum computing 2025"
|
||||
↓
|
||||
Skill Activates (triggers: "deep research")
|
||||
↓
|
||||
Plan: Standard mode (5-10 min, 15-30 sources)
|
||||
Announce: "Starting standard mode research..."
|
||||
↓
|
||||
Phase 1: SCOPE
|
||||
- Define research boundaries
|
||||
- No user input needed ✅
|
||||
↓
|
||||
Phase 2: PLAN
|
||||
- Strategy formulation
|
||||
- No user input needed ✅
|
||||
↓
|
||||
Phase 3: RETRIEVE
|
||||
- Web searches (15-30 sources)
|
||||
- Parallel agent spawning
|
||||
- No user input needed ✅
|
||||
↓
|
||||
Phase 4: TRIANGULATE
|
||||
- Cross-verify 3+ sources per claim
|
||||
- No user input needed ✅
|
||||
↓
|
||||
Phase 5: SYNTHESIZE
|
||||
- Generate insights
|
||||
- No user input needed ✅
|
||||
↓
|
||||
Phase 6: PACKAGE
|
||||
- Generate markdown report
|
||||
- Save to ~/.claude/research_output/
|
||||
- No user input needed ✅
|
||||
↓
|
||||
Phase 7: VALIDATE
|
||||
- Run 8 automated checks
|
||||
- No user input needed ✅
|
||||
↓
|
||||
Deliver:
|
||||
- Executive summary (inline)
|
||||
- File path confirmation
|
||||
- Source quality summary
|
||||
↓
|
||||
DONE (Total user interactions: 0 ✅)
|
||||
```
|
||||
|
||||
### Error Path (Intentional Stops)
|
||||
|
||||
**These are INTENTIONAL blocking points (by design):**
|
||||
|
||||
1. **Validation Failure (2 attempts)**
|
||||
- Condition: Report fails validation twice
|
||||
- Action: Stop, report issues, ask user
|
||||
- Justification: Don't deliver broken reports
|
||||
|
||||
2. **Insufficient Sources (<5)**
|
||||
- Condition: Exhaustive search finds <5 sources
|
||||
- Action: Report limitation, ask to proceed
|
||||
- Justification: User should know about data scarcity
|
||||
|
||||
3. **Critically Ambiguous Query**
|
||||
- Condition: Query is genuinely incomprehensible
|
||||
- Action: Ask for clarification
|
||||
- Justification: Can't proceed without basic understanding
|
||||
|
||||
**These stops are CORRECT behavior - quality over blind automation.**
|
||||
|
||||
---
|
||||
|
||||
## 4. PYTHON SCRIPT VERIFICATION
|
||||
|
||||
### Interactive Prompt Check
|
||||
|
||||
**Command:** `grep -r "input(" scripts/`
|
||||
**Result:** ✅ No input() calls found
|
||||
|
||||
**Scripts Verified:**
|
||||
- ✅ `research_engine.py` (578 lines) - No interactive prompts
|
||||
- ✅ `validate_report.py` (293 lines) - No interactive prompts
|
||||
- ✅ `source_evaluator.py` (292 lines) - No interactive prompts
|
||||
- ✅ `citation_manager.py` (177 lines) - No interactive prompts
|
||||
|
||||
### Syntax Validation
|
||||
|
||||
**Command:** `python -m py_compile scripts/*.py`
|
||||
**Result:** ✅ All scripts compile without errors
|
||||
|
||||
**Dependencies:** Python stdlib only (no external packages requiring user setup)
|
||||
|
||||
---
|
||||
|
||||
## 5. AUTONOMOUS MODE SELECTION
|
||||
|
||||
### Default Behavior Matrix
|
||||
|
||||
| User Query | Auto-Selected Mode | Time | Sources | User Input Needed? |
|
||||
|------------|-------------------|------|---------|-------------------|
|
||||
| "deep research X" | Standard | 5-10 min | 15-30 | ❌ No |
|
||||
| "quick overview of X" | Quick | 2-5 min | 10-15 | ❌ No |
|
||||
| "comprehensive analysis X" | Standard | 5-10 min | 15-30 | ❌ No |
|
||||
| "compare X vs Y" | Standard | 5-10 min | 15-30 | ❌ No |
|
||||
| "research the thing" (ambiguous) | Ask clarification | N/A | N/A | ✅ Yes (justified) |
|
||||
|
||||
**Autonomous Decision Logic:**
|
||||
- Clear query → Standard mode (DEFAULT)
|
||||
- "quick" keyword → Quick mode
|
||||
- "comprehensive" keyword → Standard mode
|
||||
- "deep" or "thorough" → Deep mode
|
||||
- Ambiguous → Standard mode (when in doubt, proceed)
|
||||
- Incomprehensible → Ask (rare edge case)
|
||||
|
||||
---
|
||||
|
||||
## 6. FILE STRUCTURE VERIFICATION
|
||||
|
||||
### Required Files (Claude Code Skill)
|
||||
|
||||
```
|
||||
~/.claude/skills/deep-research/
|
||||
├── SKILL.md ✅ (with valid frontmatter)
|
||||
├── scripts/ ✅ (all executable, no interactive prompts)
|
||||
│ ├── research_engine.py
|
||||
│ ├── validate_report.py
|
||||
│ ├── source_evaluator.py
|
||||
│ └── citation_manager.py
|
||||
├── templates/ ✅
|
||||
│ └── report_template.md
|
||||
├── reference/ ✅
|
||||
│ └── methodology.md
|
||||
└── tests/ ✅
|
||||
└── fixtures/
|
||||
├── valid_report.md
|
||||
└── invalid_report.md
|
||||
```
|
||||
|
||||
**Status:** ✅ All files present and properly structured
|
||||
|
||||
---
|
||||
|
||||
## 7. TRIGGER KEYWORDS (Automatic Invocation)
|
||||
|
||||
The skill automatically activates when user says:
|
||||
|
||||
✅ "deep research"
|
||||
✅ "comprehensive analysis"
|
||||
✅ "research report"
|
||||
✅ "compare X vs Y"
|
||||
✅ "analyze trends"
|
||||
|
||||
**Exclusions (skill does NOT activate for):**
|
||||
|
||||
❌ Simple lookups (use WebSearch instead)
|
||||
❌ Debugging (use standard tools)
|
||||
❌ Questions answerable with 1-2 searches
|
||||
|
||||
---
|
||||
|
||||
## 8. CONTEXT OPTIMIZATION (Independent Operation)
|
||||
|
||||
### Static vs Dynamic Content
|
||||
|
||||
**Static Content (Cached after first use):**
|
||||
- Core system instructions
|
||||
- Decision trees
|
||||
- Workflow definitions
|
||||
- Output contracts
|
||||
- Quality standards
|
||||
- Error handling
|
||||
|
||||
**Dynamic Content (Runtime only):**
|
||||
- User query
|
||||
- Retrieved sources
|
||||
- Generated analysis
|
||||
|
||||
**Benefit for Autonomy:**
|
||||
- First invocation: Full processing
|
||||
- Subsequent invocations: 85% faster (cached static content)
|
||||
- No external dependencies
|
||||
- No user configuration needed
|
||||
|
||||
---
|
||||
|
||||
## 9. INDEPENDENCE CHECKLIST
|
||||
|
||||
| Requirement | Status | Evidence |
|
||||
|-------------|--------|----------|
|
||||
| **Valid YAML frontmatter** | ✅ Pass | Python YAML parser validates |
|
||||
| **Skill discoverable by Claude Code** | ✅ Pass | Located in `~/.claude/skills/` |
|
||||
| **Clear trigger keywords** | ✅ Pass | 5+ triggers in description |
|
||||
| **Clear exclusion criteria** | ✅ Pass | "Do NOT use for..." specified |
|
||||
| **Autonomy principle stated** | ✅ Pass | "Operates independently" explicit |
|
||||
| **Default behavior: proceed** | ✅ Pass | "When in doubt: PROCEED" |
|
||||
| **No unnecessary clarification** | ✅ Pass | "Rarely Needed - Prefer Autonomy" |
|
||||
| **No approval waiting** | ✅ Pass | "NO need to wait for approval" |
|
||||
| **No interactive prompts in scripts** | ✅ Pass | `grep` confirms no input() |
|
||||
| **Python stdlib only (no setup)** | ✅ Pass | requirements.txt empty |
|
||||
| **All scripts compile** | ✅ Pass | `py_compile` succeeds |
|
||||
| **Error handling graceful** | ✅ Pass | Retry logic, clear error messages |
|
||||
| **Output path predetermined** | ✅ Pass | `~/.claude/research_output/` |
|
||||
| **Validation automated** | ✅ Pass | 8 checks, no manual review |
|
||||
| **Mode selection autonomous** | ✅ Pass | Standard as default |
|
||||
|
||||
**Total:** 15/15 checks passed ✅
|
||||
|
||||
---
|
||||
|
||||
## 10. COMPARISON: Before vs After Optimization
|
||||
|
||||
| Aspect | Before | After | Improvement |
|
||||
|--------|--------|-------|-------------|
|
||||
| **Clarify frequency** | "When to ask" (ambiguous conditions) | "Rarely needed" (explicit autonomy) | ✅ 90% fewer stops |
|
||||
| **Preview behavior** | "Preview scope if..." (unclear) | "Announce and proceed" (clear) | ✅ No blocking |
|
||||
| **Autonomy principle** | Implicit | Explicit ("operates independently") | ✅ Clear guidance |
|
||||
| **Default action** | Unclear | "PROCEED with standard mode" | ✅ Removes ambiguity |
|
||||
| **User interaction** | 2-3 stops possible | 0-1 stops (errors only) | ✅ 90% reduction |
|
||||
|
||||
---
|
||||
|
||||
## 11. EDGE CASE HANDLING
|
||||
|
||||
### Truly Ambiguous Query
|
||||
|
||||
**User:** "research the thing"
|
||||
|
||||
**Behavior:**
|
||||
1. Skill recognizes query is incomprehensible
|
||||
2. Asks: "What topic should I research?"
|
||||
3. User clarifies: "quantum computing"
|
||||
4. Proceeds autonomously
|
||||
|
||||
**Verdict:** ✅ Correct behavior (can't proceed without basic information)
|
||||
|
||||
### Borderline Ambiguous Query
|
||||
|
||||
**User:** "research recent developments"
|
||||
|
||||
**Old Behavior:** Might ask "Recent developments in what?"
|
||||
**New Behavior:** Makes reasonable assumption (tech/science), proceeds
|
||||
**Verdict:** ✅ Improved autonomy
|
||||
|
||||
### Clear Query
|
||||
|
||||
**User:** "deep research on CRISPR gene editing 2024-2025"
|
||||
|
||||
**Behavior:**
|
||||
1. Skill activates
|
||||
2. Announces: "Starting standard mode research (5-10 min, 15-30 sources)"
|
||||
3. Executes all 6 phases
|
||||
4. Generates 2,000-5,000 word report
|
||||
5. Delivers report
|
||||
|
||||
**User interactions:** 0 ✅
|
||||
|
||||
---
|
||||
|
||||
## 12. FINAL VERIFICATION
|
||||
|
||||
### Manual Test Simulation
|
||||
|
||||
**Test Query:** "comprehensive analysis of senolytics clinical trials"
|
||||
|
||||
**Expected Behavior:**
|
||||
1. ✅ Skill activates (trigger: "comprehensive analysis")
|
||||
2. ✅ Announces plan without waiting
|
||||
3. ✅ Executes standard mode (6 phases)
|
||||
4. ✅ Gathers 15-30 sources
|
||||
5. ✅ Triangulates 3+ sources per claim
|
||||
6. ✅ Generates report (2,000-5,000 words)
|
||||
7. ✅ Validates automatically (8 checks)
|
||||
8. ✅ Saves to ~/.claude/research_output/
|
||||
9. ✅ Delivers executive summary
|
||||
|
||||
**Actual Result (from previous test):**
|
||||
- Report: 2,356 words ✅
|
||||
- Sources: 15 citations ✅
|
||||
- Validation: ALL 8 CHECKS PASSED ✅
|
||||
- User interactions: 0 ✅
|
||||
|
||||
**Verdict:** ✅ OPERATES AUTONOMOUSLY AS DESIGNED
|
||||
|
||||
---
|
||||
|
||||
## 13. GITHUB REPOSITORY SYNC
|
||||
|
||||
**Repository:** https://github.com/199-biotechnologies/claude-deep-research-skill
|
||||
**Visibility:** PRIVATE
|
||||
**Commit:** e4cd081
|
||||
|
||||
**Next Steps:**
|
||||
- Commit autonomy optimizations
|
||||
- Push to GitHub
|
||||
- Verify consistency
|
||||
|
||||
---
|
||||
|
||||
## CONCLUSION
|
||||
|
||||
### Autonomy Status: ✅ VERIFIED
|
||||
|
||||
The deep-research skill is properly configured as a Claude Code skill and optimized for autonomous operation:
|
||||
|
||||
1. **Discovery:** ✅ Valid frontmatter, correct location
|
||||
2. **Triggers:** ✅ Clear activation keywords
|
||||
3. **Autonomy:** ✅ Explicit "proceed independently" principle
|
||||
4. **Default:** ✅ "When in doubt, proceed" with reasonable assumptions
|
||||
5. **Scripts:** ✅ No interactive prompts, stdlib only
|
||||
6. **Blocking:** ✅ Only stops for critical errors (by design)
|
||||
7. **Flow:** ✅ 0 user interactions in happy path
|
||||
8. **Testing:** ✅ Real-world validation successful
|
||||
|
||||
**Independence Score:** 15/15 checks passed (100%)
|
||||
|
||||
**Ready for autonomous deployment and use.**
|
||||
179
axhub-make/skills/third-party/deep-research/COMPETITIVE_ANALYSIS.md
vendored
Normal file
179
axhub-make/skills/third-party/deep-research/COMPETITIVE_ANALYSIS.md
vendored
Normal file
@@ -0,0 +1,179 @@
|
||||
# Competitive Analysis: Deep Research Skill vs Market Leaders
|
||||
|
||||
## Competitive Landscape (2025)
|
||||
|
||||
### OpenAI Deep Research (o3-based)
|
||||
- **Time**: 5-30 minutes
|
||||
- **Sources**: Multi-step, unspecified count
|
||||
- **Model**: o3 reasoning
|
||||
- **Benchmark**: 26.6% on "Humanity's Last Exam"
|
||||
- **Strengths**: Visual browser, transparency sidebar, reasoning capability
|
||||
- **Weaknesses**: Slow, occasional hallucinations, may reference rumors
|
||||
|
||||
### Google Gemini Deep Research (2.5)
|
||||
- **Time**: "A few minutes"
|
||||
- **Sources**: "Hundreds of websites"
|
||||
- **Model**: Gemini 2.5 Flash Thinking
|
||||
- **Strengths**: PDF/image upload, Google Drive integration, interactive reports
|
||||
- **Process**: Creates plan for approval before executing
|
||||
- **Weaknesses**: Limited quality control
|
||||
|
||||
### Claude Desktop Research
|
||||
- **Time**: "Less than a minute" (claimed)
|
||||
- **Sources**: 427 sources in example (breadth over depth)
|
||||
- **Strengths**: Speed, Google Workspace integration
|
||||
- **Weaknesses**:
|
||||
- Often lacks cited sources for verification
|
||||
- Doesn't ask clarifying questions
|
||||
- Quality inconsistent
|
||||
- US/Japan/Brazil only, expensive ($100/mo Max plan)
|
||||
|
||||
---
|
||||
|
||||
## Our Deep Research Skill Advantages
|
||||
|
||||
### Speed Competitive
|
||||
- **Standard Mode**: 5-10 minutes (faster than OpenAI, comparable to Gemini)
|
||||
- **Quick Mode**: 2-5 minutes (approaches Claude Desktop speed)
|
||||
- **Parallel Agents**: Simultaneous source retrieval for efficiency
|
||||
|
||||
### Superior Quality Control
|
||||
| Feature | OpenAI | Gemini | Claude Desktop | **Our Skill** |
|
||||
|---------|--------|--------|---------------|---------------|
|
||||
| Source credibility scoring | ❌ | ❌ | ❌ | ✅ (0-100) |
|
||||
| 3+ source triangulation | Partial | ❌ | ❌ | ✅ (enforced) |
|
||||
| Built-in validation | ❌ | ❌ | ❌ | ✅ (automated) |
|
||||
| Critique phase | ❌ | ❌ | ❌ | ✅ (red-team) |
|
||||
| Refine phase | ❌ | ❌ | ❌ | ✅ (gap filling) |
|
||||
| Citation quality | Good | Good | Poor | ✅ Excellent |
|
||||
|
||||
### Better Methodology
|
||||
- **8-Phase Pipeline**: More thorough than competitors' ad-hoc approaches
|
||||
- **Graph-of-Thoughts**: Non-linear reasoning with branching paths
|
||||
- **Multiple Modes**: 4 depth levels (quick/standard/deep/ultradeep)
|
||||
- **Decision Trees**: Clear logic for mode and tool selection
|
||||
- **Stop Rules**: Prevents runaway research or low-quality loops
|
||||
|
||||
### Unique Differentiators
|
||||
|
||||
1. **Source Credibility Assessment**
|
||||
- Every source scored 0-100
|
||||
- Evaluates domain authority, recency, expertise, bias
|
||||
- Filters low-quality sources automatically
|
||||
|
||||
2. **Triangulation Phase**
|
||||
- Minimum 3 sources for major claims
|
||||
- Cross-reference verification
|
||||
- Flags contradictions explicitly
|
||||
|
||||
3. **Critique + Refine Cycle**
|
||||
- Red-team analysis before delivery
|
||||
- Identifies gaps and weaknesses
|
||||
- Iteratively improves before finalization
|
||||
|
||||
4. **Validation Infrastructure**
|
||||
- Automated quality checks
|
||||
- Catches placeholders, broken citations
|
||||
- Enforces quality standards
|
||||
|
||||
5. **Progressive Disclosure**
|
||||
- Tight SKILL.md (237 lines)
|
||||
- Detailed methodology in references
|
||||
- Efficient context management
|
||||
|
||||
### Performance Comparison
|
||||
|
||||
| Metric | OpenAI | Gemini | Claude Desktop | **Our Skill** |
|
||||
|--------|--------|--------|----------------|---------------|
|
||||
| **Speed** | 5-30 min | 2-5 min | <1 min | 2-10 min |
|
||||
| **Source Count** | Unspecified | Hundreds | 427 | 15-50 |
|
||||
| **Citation Quality** | Excellent | Good | Poor | Excellent |
|
||||
| **Verification** | Partial | Minimal | None | Rigorous (3+) |
|
||||
| **Customization** | None | Minimal | None | 4 modes |
|
||||
| **Validation** | None | None | None | Automated |
|
||||
| **Credibility Scoring** | No | No | No | Yes (0-100) |
|
||||
| **Cost** | $20/mo+ | $20/mo+ | $100/mo | Free (Claude Code) |
|
||||
|
||||
---
|
||||
|
||||
## Competitive Positioning
|
||||
|
||||
### When to Use Our Skill vs Competitors
|
||||
|
||||
**Use Our Skill When:**
|
||||
- Quality and verification are critical
|
||||
- Need source credibility assessment
|
||||
- Want multiple depth modes
|
||||
- Require local deployment/privacy
|
||||
- Need validation before delivery
|
||||
- Want reproducible methodology
|
||||
|
||||
**Use OpenAI When:**
|
||||
- Maximum reasoning depth needed
|
||||
- Visual content analysis required
|
||||
- Can afford 30+ minutes
|
||||
- Need visual browser capabilities
|
||||
|
||||
**Use Gemini When:**
|
||||
- PDF/image upload needed
|
||||
- Google Workspace integration required
|
||||
- Interactive reports desired
|
||||
- Fast turnaround acceptable with less rigor
|
||||
|
||||
**Use Claude Desktop When:**
|
||||
- Speed is absolute priority (< 1 min)
|
||||
- Breadth over depth preferred
|
||||
- Basic research acceptable
|
||||
- Can afford $100/mo
|
||||
|
||||
---
|
||||
|
||||
## Technical Advantages
|
||||
|
||||
### Architecture
|
||||
- **File-based skills system**: Portable, version-controlled
|
||||
- **No external dependencies**: Pure Python stdlib
|
||||
- **Offline-capable**: No API calls required
|
||||
- **Modular design**: Easy to customize and extend
|
||||
|
||||
### Quality Engineering
|
||||
- **Automated validation**: Catches 8+ error types
|
||||
- **Test fixtures**: Reproducible quality checks
|
||||
- **Error handling**: Clear stop rules and escalation
|
||||
- **Graceful degradation**: Handles limited sources
|
||||
|
||||
### Developer Experience
|
||||
- **Clear documentation**: SKILL.md, methodology, templates
|
||||
- **Testing infrastructure**: Valid/invalid fixtures
|
||||
- **Progressive disclosure**: Efficient context management
|
||||
- **Decision trees**: Explicit logic paths
|
||||
|
||||
---
|
||||
|
||||
## Benchmark Summary
|
||||
|
||||
| Capability | Score | Notes |
|
||||
|-----------|-------|-------|
|
||||
| **Speed** | 8/10 | Faster than OpenAI, comparable to Gemini |
|
||||
| **Quality** | 10/10 | Superior validation and verification |
|
||||
| **Depth** | 9/10 | 8-phase pipeline, critique + refine |
|
||||
| **Citations** | 10/10 | Automatic tracking, validation |
|
||||
| **Credibility** | 10/10 | Unique 0-100 scoring system |
|
||||
| **Flexibility** | 10/10 | 4 modes, customizable |
|
||||
| **Cost** | 10/10 | Free with Claude Code |
|
||||
| **Privacy** | 10/10 | Local execution, no external APIs |
|
||||
|
||||
**Overall**: 77/80 (96%)
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
Our Deep Research Skill delivers:
|
||||
- ✅ **Speed**: 5-10 min standard (competitive with Gemini, faster than OpenAI)
|
||||
- ✅ **Quality**: Superior through triangulation, critique, and validation
|
||||
- ✅ **Depth**: 8-phase methodology exceeds competitors
|
||||
- ✅ **Innovation**: Unique credibility scoring and validation
|
||||
- ✅ **Value**: Free, local, portable
|
||||
|
||||
**Best in class** for quality-critical research where verification and credibility matter.
|
||||
293
axhub-make/skills/third-party/deep-research/CONTEXT_OPTIMIZATION.md
vendored
Normal file
293
axhub-make/skills/third-party/deep-research/CONTEXT_OPTIMIZATION.md
vendored
Normal file
@@ -0,0 +1,293 @@
|
||||
# Context Optimization: 2025 Engineering Best Practices
|
||||
|
||||
## Applied Optimizations
|
||||
|
||||
This skill implements cutting-edge context engineering research from 2025 to achieve **85% latency reduction** and **90% cost reduction** through intelligent context management.
|
||||
|
||||
---
|
||||
|
||||
## 1. Prompt Caching Architecture
|
||||
|
||||
### Static-First Structure
|
||||
|
||||
**SKILL.md organized as:**
|
||||
```
|
||||
[STATIC BLOCK - Cached, >1024 tokens]
|
||||
├─ Frontmatter
|
||||
├─ Core system instructions
|
||||
├─ Decision trees
|
||||
├─ Workflow definitions
|
||||
├─ Output contracts
|
||||
├─ Quality standards
|
||||
└─ Error handling
|
||||
|
||||
[DYNAMIC BLOCK - Runtime only]
|
||||
├─ User query
|
||||
├─ Retrieved sources
|
||||
└─ Generated analysis
|
||||
```
|
||||
|
||||
**Result:** After first invocation, static instructions are cached, reducing latency by up to 85% and costs by up to 90% on subsequent calls.
|
||||
|
||||
### Format Consistency
|
||||
|
||||
- Exact whitespace, line breaks, and capitalization maintained
|
||||
- Consistent markdown formatting throughout
|
||||
- Clear delimiters (HTML comments, horizontal rules)
|
||||
|
||||
**Why it matters:** Cache hits require exact matching. Consistent formatting ensures maximum cache efficiency.
|
||||
|
||||
---
|
||||
|
||||
## 2. Progressive Disclosure
|
||||
|
||||
### On-Demand Loading
|
||||
|
||||
Rather than inlining all content, we reference external files:
|
||||
|
||||
```markdown
|
||||
# Load only when needed
|
||||
- [methodology.md](./reference/methodology.md) - Loaded per-phase
|
||||
- [report_template.md](./templates/report_template.md) - Loaded for Phase 8 only
|
||||
```
|
||||
|
||||
**Benefit:** Reduces token usage by 60-75% compared to full inline approach. Context stays focused on current phase.
|
||||
|
||||
### Reference Strategy
|
||||
|
||||
- **Heavy content**: External files (methodology, templates)
|
||||
- **Critical instructions**: Inline (decision trees, quality gates)
|
||||
- **Examples**: External (test fixtures)
|
||||
|
||||
---
|
||||
|
||||
## 3. Avoiding "Loss in the Middle"
|
||||
|
||||
### The Problem
|
||||
|
||||
Research shows LLMs struggle with information buried in middle of long contexts. Recall drops significantly for middle sections.
|
||||
|
||||
### Our Solution
|
||||
|
||||
**Explicit guidance in SKILL.md:**
|
||||
```
|
||||
Critical: Avoid "Loss in the Middle"
|
||||
- Place key findings at START and END of sections, not buried
|
||||
- Use explicit headers and markers
|
||||
- Structure: Summary → Details → Conclusion
|
||||
```
|
||||
|
||||
**Report structure enforced:**
|
||||
- Executive Summary (START)
|
||||
- Main content (MIDDLE)
|
||||
- Synthesis & Insights (END)
|
||||
- Recommendations (END)
|
||||
|
||||
**Result:** Critical information positioned where models have highest recall.
|
||||
|
||||
---
|
||||
|
||||
## 4. Explicit Section Markers
|
||||
|
||||
### HTML Comments for Navigation
|
||||
|
||||
```html
|
||||
<!-- STATIC CONTEXT BLOCK START - Optimized for prompt caching -->
|
||||
...
|
||||
<!-- STATIC CONTEXT BLOCK END -->
|
||||
|
||||
<!-- 📝 Dynamic content begins here -->
|
||||
```
|
||||
|
||||
**Purpose:** Helps model understand context boundaries and efficiently navigate long documents.
|
||||
|
||||
### Hierarchical Structure
|
||||
|
||||
- Clear markdown hierarchy (##, ###)
|
||||
- Numbered sections
|
||||
- ASCII tree diagrams for decision flows
|
||||
|
||||
---
|
||||
|
||||
## 5. Context Pruning Strategies
|
||||
|
||||
### Selective Loading
|
||||
|
||||
**Phase 1 (SCOPE):**
|
||||
```python
|
||||
# Only load scope instructions
|
||||
load("./reference/methodology.md#phase-1-scope")
|
||||
# Do not load phases 2-8 yet
|
||||
```
|
||||
|
||||
**Phase 8 (PACKAGE):**
|
||||
```python
|
||||
# Only load template when needed
|
||||
load("./templates/report_template.md")
|
||||
```
|
||||
|
||||
### Benefits
|
||||
|
||||
| Approach | Token Usage | Latency | Cost |
|
||||
|----------|-------------|---------|------|
|
||||
| Inline all | ~15,000 | High | High |
|
||||
| Progressive (ours) | ~4,000-6,000 | 85% lower | 90% lower |
|
||||
|
||||
---
|
||||
|
||||
## 6. Agent Communication Protocol
|
||||
|
||||
### Multi-Agent Context Sharing
|
||||
|
||||
When spawning parallel agents for retrieval:
|
||||
|
||||
```python
|
||||
# Each agent gets minimal context
|
||||
agent.context = {
|
||||
"query": user_query,
|
||||
"phase": "RETRIEVE",
|
||||
"instructions": load("./reference/methodology.md#phase-3-retrieve"),
|
||||
"sources": assigned_sources # Only their subset
|
||||
}
|
||||
```
|
||||
|
||||
**Avoid:** Sending full skill context to every agent
|
||||
**Benefit:** 3-5x faster parallel execution
|
||||
|
||||
---
|
||||
|
||||
## 7. KV Cache Efficiency
|
||||
|
||||
### Consistent Prefixes
|
||||
|
||||
The static block acts as consistent prefix across all invocations:
|
||||
|
||||
**First call:**
|
||||
```
|
||||
[Static Block 2000 tokens] + [Query 100 tokens] = 2100 tokens processed
|
||||
```
|
||||
|
||||
**Subsequent calls (cached):**
|
||||
```
|
||||
[Cached] + [Query 100 tokens] = 100 tokens processed
|
||||
```
|
||||
|
||||
**Speedup:** 20x for static portion
|
||||
|
||||
### Implications
|
||||
|
||||
- First research query: 5-10 minutes
|
||||
- Subsequent queries: 2-5 minutes (cache hit)
|
||||
- Enterprise use: Massive cost savings with repeated research
|
||||
|
||||
---
|
||||
|
||||
## 8. Validation Layer
|
||||
|
||||
### Context-Aware Validation
|
||||
|
||||
Validator checks for context bloat:
|
||||
|
||||
```python
|
||||
def check_word_count(self):
|
||||
word_count = len(self.content.split())
|
||||
if word_count > 10000:
|
||||
self.warnings.append(
|
||||
f"Report very long: {word_count} words (consider condensing)"
|
||||
)
|
||||
```
|
||||
|
||||
**Purpose:** Keeps outputs concise, preventing downstream context issues.
|
||||
|
||||
---
|
||||
|
||||
## Benchmark: Before vs After
|
||||
|
||||
### Old Approach (Pre-2025)
|
||||
|
||||
```
|
||||
SKILL.md: 413 lines, all inline
|
||||
├─ Full methodology embedded (long)
|
||||
├─ Templates inlined
|
||||
├─ No caching markers
|
||||
└─ No progressive loading
|
||||
|
||||
Result: ~18,000 tokens per invocation, no caching benefit
|
||||
```
|
||||
|
||||
### New Approach (2025 Optimized)
|
||||
|
||||
```
|
||||
SKILL.md: 300 lines, strategic structure
|
||||
├─ Static block (cached after first use)
|
||||
├─ Progressive references
|
||||
├─ Explicit markers
|
||||
└─ Dynamic zone clearly separated
|
||||
|
||||
Result: ~2,000 tokens cached, ~4,000 dynamic = 6,000 total
|
||||
Cache hit: 2,000 tokens reused, only 4,000 new tokens processed
|
||||
```
|
||||
|
||||
### Performance Gains
|
||||
|
||||
| Metric | Old | New | Improvement |
|
||||
|--------|-----|-----|-------------|
|
||||
| **First call latency** | 10 min | 10 min | 0% (same) |
|
||||
| **Cached call latency** | 10 min | 1.5 min | **85%** |
|
||||
| **Token cost (cached)** | 18K | 4K | **78%** |
|
||||
| **Context efficiency** | Low | High | **3-4x** |
|
||||
|
||||
---
|
||||
|
||||
## Research Sources
|
||||
|
||||
These optimizations based on:
|
||||
|
||||
1. **"A Survey of Context Engineering for Large Language Models"** (arXiv:2507.13334, 2025) by Lingrui Mei et al.
|
||||
2. **Anthropic Prompt Caching Documentation** (2025) - 90% cost reduction, 85% latency reduction
|
||||
3. **"Context Windows Get Huge"** - IEEE Spectrum (2025) - Long context best practices
|
||||
4. **WebWeaver Framework** (2025) - Avoiding "loss in the middle" in research pipelines
|
||||
5. **Kimi Linear Model** (2025) - 75% KV cache reduction techniques
|
||||
|
||||
---
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
When creating new research skills, ensure:
|
||||
|
||||
- [ ] Static content first (>1024 tokens for caching)
|
||||
- [ ] Dynamic content last
|
||||
- [ ] Explicit cache boundary markers
|
||||
- [ ] Progressive reference loading (not inline)
|
||||
- [ ] "Loss in the middle" avoidance (key info at start/end)
|
||||
- [ ] Clear section navigation markers
|
||||
- [ ] Format consistency maintained
|
||||
- [ ] Context pruning per phase
|
||||
- [ ] Validation for output size
|
||||
- [ ] Multi-agent minimal context protocol
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Potential 2026 optimizations:
|
||||
|
||||
1. **Adaptive context windows** - Adjust based on query complexity
|
||||
2. **Semantic caching** - Cache similar (not identical) contexts
|
||||
3. **Context compression** - Auto-summarize retrieved sources
|
||||
4. **Hierarchical agents** - Deeper context partitioning
|
||||
5. **Real-time cache metrics** - Monitor hit rates, optimize
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
By applying 2025 context engineering research, this skill achieves:
|
||||
|
||||
✅ **85% latency reduction** (cached calls)
|
||||
✅ **90% cost reduction** (token savings)
|
||||
✅ **3-4x context efficiency** (progressive loading)
|
||||
✅ **No "loss in the middle"** (strategic positioning)
|
||||
✅ **Production-ready architecture** (scalable, maintainable)
|
||||
|
||||
These optimizations make deep research practical for high-frequency use cases while maintaining superior quality vs competitors.
|
||||
167
axhub-make/skills/third-party/deep-research/QUICK_START.md
vendored
Normal file
167
axhub-make/skills/third-party/deep-research/QUICK_START.md
vendored
Normal file
@@ -0,0 +1,167 @@
|
||||
# Deep Research Skill - Quick Start Guide
|
||||
|
||||
## What is This?
|
||||
|
||||
A comprehensive research engine for Claude Code that **matches and exceeds** Claude Desktop's "Advanced Research" feature. It conducts enterprise-grade deep research with extended reasoning, multi-source synthesis, and citation-backed reports.
|
||||
|
||||
## How to Use
|
||||
|
||||
### Simple Invocation (Recommended)
|
||||
|
||||
Just ask Claude Code to use deep research:
|
||||
|
||||
```
|
||||
Use deep research to analyze the current state of AI agent frameworks in 2025
|
||||
```
|
||||
|
||||
```
|
||||
Deep research: Should we migrate from PostgreSQL to Supabase?
|
||||
```
|
||||
|
||||
```
|
||||
Use deep research in ultradeep mode to review recent advances in longevity science
|
||||
```
|
||||
|
||||
### Direct CLI Usage
|
||||
|
||||
```bash
|
||||
# Standard research (6 phases, ~5-10 minutes)
|
||||
python3 ~/.claude/skills/deep-research/research_engine.py \
|
||||
--query "Your research question" \
|
||||
--mode standard
|
||||
|
||||
# Deep research (8 phases, ~10-20 minutes)
|
||||
python3 ~/.claude/skills/deep-research/research_engine.py \
|
||||
--query "Your research question" \
|
||||
--mode deep
|
||||
|
||||
# Quick research (3 phases, ~2-5 minutes)
|
||||
python3 ~/.claude/skills/deep-research/research_engine.py \
|
||||
--query "Your research question" \
|
||||
--mode quick
|
||||
|
||||
# Ultra-deep research (8+ phases, ~20-45 minutes)
|
||||
python3 ~/.claude/skills/deep-research/research_engine.py \
|
||||
--query "Your research question" \
|
||||
--mode ultradeep
|
||||
```
|
||||
|
||||
## Research Modes Explained
|
||||
|
||||
| Mode | Phases | Time | Use When |
|
||||
|------|--------|------|----------|
|
||||
| **Quick** | 3 | 2-5 min | Initial exploration, simple questions |
|
||||
| **Standard** | 6 | 5-10 min | Most research needs (default) |
|
||||
| **Deep** | 8 | 10-20 min | Complex topics, important decisions |
|
||||
| **UltraDeep** | 8+ | 20-45 min | Critical analysis, comprehensive reports |
|
||||
|
||||
## What You Get
|
||||
|
||||
Every research report includes:
|
||||
|
||||
- **Executive Summary** - Key findings in 3-5 bullets
|
||||
- **Detailed Analysis** - With full citations [1], [2], [3]
|
||||
- **Synthesis & Insights** - Novel insights beyond sources
|
||||
- **Limitations & Caveats** - What's uncertain or missing
|
||||
- **Recommendations** - Actionable next steps
|
||||
- **Full Bibliography** - All sources with credibility scores
|
||||
- **Methodology Appendix** - How research was conducted
|
||||
|
||||
## Output Location
|
||||
|
||||
All research is saved to:
|
||||
```
|
||||
~/.claude/research_output/
|
||||
```
|
||||
|
||||
Format: `research_report_YYYYMMDD_HHMMSS.md`
|
||||
|
||||
## Features That Beat Claude Desktop Research
|
||||
|
||||
✅ **8-Phase Pipeline** - More thorough than Claude Desktop's approach
|
||||
✅ **Multiple Research Modes** - Choose depth vs speed
|
||||
✅ **Source Credibility Scoring** - Evaluates each source (0-100 score)
|
||||
✅ **Graph-of-Thoughts** - Non-linear exploration with branching reasoning
|
||||
✅ **Citation Management** - Automatic tracking and bibliography generation
|
||||
✅ **Critique Phase** - Built-in red-team analysis of findings
|
||||
✅ **Refine Phase** - Addresses gaps before finalizing
|
||||
✅ **Local File Integration** - Can search your codebase/docs
|
||||
✅ **Code Execution** - Can run analyses and validations
|
||||
|
||||
## Example Use Cases
|
||||
|
||||
### Technology Evaluation
|
||||
```
|
||||
Use deep research to compare Next.js 15 vs Remix vs Astro for my project
|
||||
```
|
||||
|
||||
### Market Analysis
|
||||
```
|
||||
Deep research: What are the key trends in longevity biotech funding 2023-2025?
|
||||
```
|
||||
|
||||
### Technical Decision
|
||||
```
|
||||
Use deep research to help me choose between Auth0, Clerk, and Supabase Auth
|
||||
```
|
||||
|
||||
### Scientific Review
|
||||
```
|
||||
Use deep research in ultradeep mode to summarize senolytics research progress
|
||||
```
|
||||
|
||||
### Competitive Intelligence
|
||||
```
|
||||
Deep research: Who are the top 5 competitors in the AI code assistant space?
|
||||
```
|
||||
|
||||
## Quality Standards
|
||||
|
||||
Every report guarantees:
|
||||
- ✅ 10+ distinct sources (unless highly specialized topic)
|
||||
- ✅ 3+ source verification for major claims
|
||||
- ✅ Full citation tracking
|
||||
- ✅ Credibility assessment for each source
|
||||
- ✅ Limitations documented
|
||||
- ✅ Methodology explained
|
||||
|
||||
## Tips for Best Results
|
||||
|
||||
1. **Be Specific** - "Compare X vs Y for use case Z" is better than "Tell me about X"
|
||||
2. **State Your Goal** - "Help me decide..." vs "Give me an overview..."
|
||||
3. **Choose Right Mode** - Use Quick for exploration, Deep for decisions
|
||||
4. **Check Scope First** - Review Phase 1 output to ensure on track
|
||||
5. **Use Citations** - Drill deeper by asking about specific sources [1], [2], etc.
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
deep-research/
|
||||
├── SKILL.md # Main skill definition (11KB)
|
||||
├── research_engine.py # Core engine (16KB)
|
||||
├── utils/
|
||||
│ ├── citation_manager.py # Citation tracking (6KB)
|
||||
│ └── source_evaluator.py # Credibility scoring (8KB)
|
||||
├── README.md # Full documentation
|
||||
├── QUICK_START.md # This guide
|
||||
└── requirements.txt # No external deps needed!
|
||||
```
|
||||
|
||||
## No Dependencies Required!
|
||||
|
||||
The skill uses only Python standard library - no pip install needed for basic usage.
|
||||
|
||||
## Version
|
||||
|
||||
**v1.0** - Released 2025-11-04
|
||||
|
||||
Built to match and exceed Claude Desktop's Advanced Research feature.
|
||||
|
||||
---
|
||||
|
||||
**Ready to use?** Just type:
|
||||
```
|
||||
Use deep research to [your question here]
|
||||
```
|
||||
|
||||
Claude Code will automatically load this skill and execute the research pipeline!
|
||||
259
axhub-make/skills/third-party/deep-research/README.md
vendored
Normal file
259
axhub-make/skills/third-party/deep-research/README.md
vendored
Normal file
@@ -0,0 +1,259 @@
|
||||
# Deep Research Skill for Claude Code
|
||||
|
||||
A comprehensive research engine that brings Claude Desktop's Advanced Research capabilities (and more) to Claude Code terminal.
|
||||
|
||||
## Features
|
||||
|
||||
### Core Research Pipeline
|
||||
- **8.5-Phase Research Pipeline**: Scope → Plan → Retrieve (Parallel) → Triangulate → **Outline Refinement** → Synthesize → Critique → Refine → Package
|
||||
- **Multiple Research Modes**: Quick, Standard, Deep, and UltraDeep
|
||||
- **Graph-of-Thoughts Reasoning**: Non-linear exploration with branching thought paths
|
||||
|
||||
### 2025 Enhancements (Latest - v2.2)
|
||||
- **🔄 Auto-Continuation System (NEW)**: **TRUE UNLIMITED length** (50K, 100K+ words) via recursive agent spawning with context preservation
|
||||
- **📄 Progressive File Assembly**: Section-by-section generation with quality safeguards
|
||||
- **⚡ Parallel Search Execution**: 5-10 concurrent searches + parallel agents (3-5x faster Phase 3)
|
||||
- **🎯 First Finish Search (FFS) Pattern**: Adaptive completion based on quality thresholds
|
||||
- **🔍 Enhanced Citation Validation (CiteGuard)**: Hallucination detection, URL verification, multi-source cross-checking
|
||||
- **📋 Dynamic Outline Evolution (WebWeaver)**: Adapt structure after Phase 4 based on evidence
|
||||
- **🔗 Attribution Gradients UI**: Interactive citation tooltips showing evidence chains in HTML reports
|
||||
- **🛡️ Anti-Fatigue Enforcement**: Prose-first quality checks prevent bullet-point degradation
|
||||
|
||||
### Traditional Strengths
|
||||
- **Citation Management**: Automatic source tracking and bibliography generation
|
||||
- **Source Credibility Assessment**: Evaluates source quality and potential biases
|
||||
- **Structured Reports**: Professional markdown, HTML (McKinsey-style), and PDF outputs
|
||||
- **Verification & Triangulation**: Cross-references claims across multiple sources
|
||||
|
||||
## Installation
|
||||
|
||||
The skill is already installed globally in `~/.claude/skills/deep-research/`
|
||||
|
||||
No additional dependencies required for basic usage.
|
||||
|
||||
## Usage
|
||||
|
||||
### In Claude Code
|
||||
|
||||
Simply invoke the skill:
|
||||
|
||||
```
|
||||
Use deep research to analyze the state of quantum computing in 2025
|
||||
```
|
||||
|
||||
Or specify a mode:
|
||||
|
||||
```
|
||||
Use deep research in ultradeep mode to compare PostgreSQL vs Supabase
|
||||
```
|
||||
|
||||
### Direct CLI Usage
|
||||
|
||||
```bash
|
||||
# Standard research
|
||||
python ~/.claude/skills/deep-research/research_engine.py --query "Your research question" --mode standard
|
||||
|
||||
# Deep research (all 8 phases)
|
||||
python ~/.claude/skills/deep-research/research_engine.py --query "Your research question" --mode deep
|
||||
|
||||
# Quick research (3 phases only)
|
||||
python ~/.claude/skills/deep-research/research_engine.py --query "Your research question" --mode quick
|
||||
|
||||
# Ultra-deep research (extended iterations)
|
||||
python ~/.claude/skills/deep-research/research_engine.py --query "Your research question" --mode ultradeep
|
||||
```
|
||||
|
||||
## Research Modes
|
||||
|
||||
| Mode | Phases | Duration | Best For |
|
||||
|------|--------|----------|----------|
|
||||
| **Quick** | 3 phases | 2-5 min | Simple topics, initial exploration |
|
||||
| **Standard** | 6 phases | 5-10 min | Most research questions |
|
||||
| **Deep** | 8 phases | 10-20 min | Complex topics requiring thorough analysis |
|
||||
| **UltraDeep** | 8+ phases | 20-45 min | Critical decisions, comprehensive reports |
|
||||
|
||||
## Output
|
||||
|
||||
Research reports are saved to organized folders in `~/Documents/[Topic]_Research_[Date]/`
|
||||
|
||||
Each report includes:
|
||||
- Executive Summary
|
||||
- Detailed Analysis with Citations
|
||||
- Synthesis & Insights
|
||||
- Limitations & Caveats
|
||||
- Recommendations
|
||||
- Full Bibliography
|
||||
- Methodology Appendix
|
||||
|
||||
### Unlimited Report Generation (2025 Auto-Continuation System)
|
||||
|
||||
Reports use **progressive file assembly with auto-continuation** - achieving truly unlimited length through recursive agent spawning:
|
||||
|
||||
**How It Works:**
|
||||
|
||||
1. **Initial Generation (18K words)**
|
||||
- Generate sections 1-10 progressively
|
||||
- Each section written to file immediately (stays under 32K limit per agent)
|
||||
- Save continuation state with research context
|
||||
|
||||
2. **Auto-Continuation (if needed)**
|
||||
- Automatically spawns continuation agent via Task tool
|
||||
- Continuation agent loads state: themes, narrative arc, citations, quality metrics
|
||||
- Generates next batch of sections (another 18K words)
|
||||
- Updates state and spawns next agent if more sections remain
|
||||
|
||||
3. **Recursive Chaining**
|
||||
- Each agent stays under 32K output token limit
|
||||
- Chain continues until all sections complete
|
||||
- Final agent generates bibliography and validates report
|
||||
|
||||
**Realistic Report Sizes:**
|
||||
- **Quick mode**: 2,000-4,000 words (single run) ✅
|
||||
- **Standard mode**: 4,000-8,000 words (single run) ✅
|
||||
- **Deep mode**: 8,000-15,000 words (single run) ✅
|
||||
- **UltraDeep mode**: 20,000-100,000+ words (auto-continuation) ✅
|
||||
|
||||
**Example: 50,000 word report:**
|
||||
- Agent 1: Sections 1-10 (18K words) → Spawns Agent 2
|
||||
- Agent 2: Sections 11-20 (18K words) → Spawns Agent 3
|
||||
- Agent 3: Sections 21-25 + Bibliography (14K words) → Complete!
|
||||
- Total: 50K words across 3 agents, each under 32K limit
|
||||
|
||||
**Context Preservation (Quality Safeguards):**
|
||||
|
||||
Continuation state includes:
|
||||
- ✅ Research question and key themes
|
||||
- ✅ Main findings summaries (100 words each)
|
||||
- ✅ Narrative arc position (beginning/middle/end)
|
||||
- ✅ Quality metrics (avg words, citation density, prose ratio)
|
||||
- ✅ All citations used + bibliography entries
|
||||
- ✅ Writing style characteristics
|
||||
|
||||
Each continuation agent:
|
||||
- Reads last 3 sections to understand flow
|
||||
- Maintains established themes and style
|
||||
- Continues citation numbering correctly
|
||||
- Matches quality metrics (±20% tolerance)
|
||||
- Verifies coherence before each section
|
||||
|
||||
**Quality Gates (Per Section):**
|
||||
- [ ] Word count: Within ±20% of average
|
||||
- [ ] Citation density: Matches established rate
|
||||
- [ ] Prose ratio: ≥80% prose (not bullets)
|
||||
- [ ] Theme alignment: Ties to key themes
|
||||
- [ ] Style consistency: Matches established patterns
|
||||
|
||||
**Benefits:**
|
||||
- ✅ TRUE unlimited length (50K, 100K+ words achievable)
|
||||
- ✅ Fully automatic (no manual intervention)
|
||||
- ✅ Context preserved across continuations
|
||||
- ✅ Quality maintained throughout
|
||||
- ✅ Each agent stays under 32K token limit
|
||||
- ✅ Progressive assembly prevents truncation
|
||||
|
||||
## Examples
|
||||
|
||||
### Technology Analysis
|
||||
```
|
||||
Use deep research to evaluate whether we should adopt Next.js 15 for our project
|
||||
```
|
||||
|
||||
### Market Research
|
||||
```
|
||||
Use deep research to analyze longevity biotech funding trends 2023-2025
|
||||
```
|
||||
|
||||
### Technical Decision
|
||||
```
|
||||
Use deep research to compare authentication solutions: Auth0 vs Clerk vs Supabase Auth
|
||||
```
|
||||
|
||||
### Scientific Review
|
||||
```
|
||||
Use deep research in ultradeep mode to summarize recent advances in senolytic therapies
|
||||
```
|
||||
|
||||
## Quality Standards
|
||||
|
||||
Every research output:
|
||||
- ✅ Minimum 10+ distinct sources
|
||||
- ✅ Citations for all major claims
|
||||
- ✅ Cross-verified facts (3+ sources)
|
||||
- ✅ Executive summary under 250 words
|
||||
- ✅ Limitations section
|
||||
- ✅ Full bibliography
|
||||
- ✅ Methodology documentation
|
||||
|
||||
## Architecture
|
||||
|
||||
```
|
||||
deep-research/
|
||||
├── SKILL.md # Main skill definition
|
||||
├── research_engine.py # Core orchestration engine
|
||||
├── utils/
|
||||
│ ├── citation_manager.py # Citation tracking & bibliography
|
||||
│ └── source_evaluator.py # Source credibility assessment
|
||||
├── requirements.txt
|
||||
└── README.md
|
||||
```
|
||||
|
||||
## Tips for Best Results
|
||||
|
||||
1. **Be Specific**: Frame questions clearly with context
|
||||
2. **Set Expectations**: Specify if you need comparisons, recommendations, or pure analysis
|
||||
3. **Choose Appropriate Mode**: Use Quick for exploration, Deep for decisions
|
||||
4. **Review Scope**: Check Phase 1 output to ensure research is on track
|
||||
5. **Leverage Citations**: Use citation numbers to drill deeper into specific sources
|
||||
|
||||
## Comparison with Claude Desktop Research
|
||||
|
||||
| Feature | Claude Desktop | Deep Research Skill |
|
||||
|---------|---------------|---------------------|
|
||||
| Multi-source synthesis | ✅ | ✅ |
|
||||
| Citation tracking | ✅ | ✅ |
|
||||
| Iterative refinement | ✅ | ✅ |
|
||||
| Source verification | ✅ | ✅ Enhanced |
|
||||
| Credibility scoring | ❌ | ✅ |
|
||||
| 8-phase methodology | ❌ | ✅ |
|
||||
| Graph-of-Thoughts | ❌ | ✅ |
|
||||
| Multiple modes | ❌ | ✅ |
|
||||
| Local file integration | ❌ | ✅ |
|
||||
| Code execution | ❌ | ✅ |
|
||||
|
||||
## 2025 Research Papers Implemented
|
||||
|
||||
This skill now incorporates cutting-edge techniques from 2025 academic research:
|
||||
|
||||
1. **Parallel Execution** (GAP, Flash-Searcher, TPS-Bench)
|
||||
- DAG-based parallel tool use for independent subtasks
|
||||
- 3-5x faster retrieval phase
|
||||
- Concurrent search strategies
|
||||
|
||||
2. **First Finish Search** (arXiv 2505.18149)
|
||||
- Quality threshold gates by mode
|
||||
- Continue background searches for depth
|
||||
- Optimal latency-accuracy tradeoff
|
||||
|
||||
3. **Citation Validation** (CiteGuard, arXiv 2510.17853)
|
||||
- Hallucination pattern detection
|
||||
- Multi-source verification (DOI + URL)
|
||||
- Strict mode for critical reports
|
||||
|
||||
4. **Dynamic Outlines** (WebWeaver, arXiv 2509.13312)
|
||||
- Evidence-driven structure adaptation
|
||||
- Phase 4.5 refinement step
|
||||
- Prevents locked-in research paths
|
||||
|
||||
5. **Attribution Gradients** (arXiv 2510.00361)
|
||||
- Interactive evidence chains
|
||||
- Hover tooltips in HTML reports
|
||||
- Improved auditability
|
||||
|
||||
## Version
|
||||
|
||||
2.0 (2025-11-05) - Major update with 2025 research enhancements
|
||||
1.0 (2025-11-04) - Initial release
|
||||
|
||||
## License
|
||||
|
||||
User skill - modify as needed for your workflow
|
||||
856
axhub-make/skills/third-party/deep-research/SKILL.md
vendored
Normal file
856
axhub-make/skills/third-party/deep-research/SKILL.md
vendored
Normal file
@@ -0,0 +1,856 @@
|
||||
---
|
||||
name: deep-research
|
||||
description: Conduct enterprise-grade research with multi-source synthesis, citation tracking, and verification. Use when user needs comprehensive analysis requiring 10+ sources, verified claims, or comparison of approaches. Triggers include "deep research", "comprehensive analysis", "research report", "compare X vs Y", or "analyze trends". Do NOT use for simple lookups, debugging, or questions answerable with 1-2 searches.
|
||||
---
|
||||
|
||||
# Deep Research
|
||||
|
||||
<!-- STATIC CONTEXT BLOCK START - Optimized for prompt caching -->
|
||||
<!-- All static instructions, methodology, and templates below this line -->
|
||||
<!-- Dynamic content (user queries, results) added after this block -->
|
||||
|
||||
## Core System Instructions
|
||||
|
||||
**Purpose:** Deliver citation-backed, verified research reports through 8-phase pipeline (Scope → Plan → Retrieve → Triangulate → Synthesize → Critique → Refine → Package) with source credibility scoring and progressive context management.
|
||||
|
||||
**Context Strategy:** This skill uses 2025 context engineering best practices:
|
||||
- Static instructions cached (this section)
|
||||
- Progressive disclosure (load references only when needed)
|
||||
- Avoid "loss in the middle" (critical info at start/end, not buried)
|
||||
- Explicit section markers for context navigation
|
||||
|
||||
---
|
||||
|
||||
## Decision Tree (Execute First)
|
||||
|
||||
```
|
||||
Request Analysis
|
||||
├─ Simple lookup? → STOP: Use WebSearch, not this skill
|
||||
├─ Debugging? → STOP: Use standard tools, not this skill
|
||||
└─ Complex analysis needed? → CONTINUE
|
||||
|
||||
Mode Selection
|
||||
├─ Initial exploration? → quick (3 phases, 2-5 min)
|
||||
├─ Standard research? → standard (6 phases, 5-10 min) [DEFAULT]
|
||||
├─ Critical decision? → deep (8 phases, 10-20 min)
|
||||
└─ Comprehensive review? → ultradeep (8+ phases, 20-45 min)
|
||||
|
||||
Execution Loop (per phase)
|
||||
├─ Load phase instructions from [methodology](./reference/methodology.md#phase-N)
|
||||
├─ Execute phase tasks
|
||||
├─ Spawn parallel agents if applicable
|
||||
└─ Update progress
|
||||
|
||||
Validation Gate
|
||||
├─ Run `python scripts/validate_report.py --report [path]`
|
||||
├─ Pass? → Deliver
|
||||
└─ Fail? → Fix (max 2 attempts) → Still fails? → Escalate
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Workflow (Clarify → Plan → Act → Verify → Report)
|
||||
|
||||
**AUTONOMY PRINCIPLE:** This skill operates independently. Infer assumptions from query context. Only stop for critical errors or incomprehensible queries.
|
||||
|
||||
### 1. Clarify (Rarely Needed - Prefer Autonomy)
|
||||
|
||||
**DEFAULT: Proceed autonomously. Derive assumptions from query signals.**
|
||||
|
||||
**ONLY ask if CRITICALLY ambiguous:**
|
||||
- Query is incomprehensible (e.g., "research the thing")
|
||||
- Contradictory requirements (e.g., "quick 50-source ultradeep analysis")
|
||||
|
||||
**When in doubt: PROCEED with standard mode. User will redirect if incorrect.**
|
||||
|
||||
**Default assumptions:**
|
||||
- Technical query → Assume technical audience
|
||||
- Comparison query → Assume balanced perspective needed
|
||||
- Trend query → Assume recent 1-2 years unless specified
|
||||
- Standard mode is default for most queries
|
||||
|
||||
---
|
||||
|
||||
### 2. Plan
|
||||
|
||||
**Mode selection criteria:**
|
||||
- **Quick** (2-5 min): Exploration, broad overview, time-sensitive
|
||||
- **Standard** (5-10 min): Most use cases, balanced depth/speed [DEFAULT]
|
||||
- **Deep** (10-20 min): Important decisions, need thorough verification
|
||||
- **UltraDeep** (20-45 min): Critical analysis, maximum rigor
|
||||
|
||||
**Announce plan and execute:**
|
||||
- Briefly state: selected mode, estimated time, number of sources
|
||||
- Example: "Starting standard mode research (5-10 min, 15-30 sources)"
|
||||
- Proceed without waiting for approval
|
||||
|
||||
---
|
||||
|
||||
### 3. Act (Phase Execution)
|
||||
|
||||
**All modes execute:**
|
||||
- Phase 1: SCOPE - Define boundaries ([method](./reference/methodology.md#phase-1-scope))
|
||||
- Phase 3: RETRIEVE - Parallel search execution (5-10 concurrent searches + agents) ([method](./reference/methodology.md#phase-3-retrieve---parallel-information-gathering))
|
||||
- Phase 8: PACKAGE - Generate report using [template](./templates/report_template.md)
|
||||
|
||||
**Standard/Deep/UltraDeep execute:**
|
||||
- Phase 2: PLAN - Strategy formulation
|
||||
- Phase 4: TRIANGULATE - Verify 3+ sources per claim
|
||||
- Phase 4.5: OUTLINE REFINEMENT - Adapt structure based on evidence (WebWeaver 2025) ([method](./reference/methodology.md#phase-45-outline-refinement---dynamic-evolution-webweaver-2025))
|
||||
- Phase 5: SYNTHESIZE - Generate novel insights
|
||||
|
||||
**Deep/UltraDeep execute:**
|
||||
- Phase 6: CRITIQUE - Red-team analysis
|
||||
- Phase 7: REFINE - Address gaps
|
||||
|
||||
**Critical: Avoid "Loss in the Middle"**
|
||||
- Place key findings at START and END of sections, not buried
|
||||
- Use explicit headers and markers
|
||||
- Structure: Summary → Details → Conclusion (not Details sandwiched)
|
||||
|
||||
**Progressive Context Loading:**
|
||||
- Load [methodology](./reference/methodology.md) sections on-demand
|
||||
- Load [template](./templates/report_template.md) only for Phase 8
|
||||
- Do not inline everything - reference external files
|
||||
|
||||
**Anti-Hallucination Protocol (CRITICAL):**
|
||||
- **Source grounding**: Every factual claim MUST cite a specific source immediately [N]
|
||||
- **Clear boundaries**: Distinguish between FACTS (from sources) and SYNTHESIS (your analysis)
|
||||
- **Explicit markers**: Use "According to [1]..." or "[1] reports..." for source-grounded statements
|
||||
- **No speculation without labeling**: Mark inferences as "This suggests..." not "Research shows..."
|
||||
- **Verify before citing**: If unsure whether source actually says X, do NOT fabricate citation
|
||||
- **When uncertain**: Say "No sources found for X" rather than inventing references
|
||||
|
||||
**Parallel Execution Requirements (CRITICAL for Speed):**
|
||||
|
||||
**Phase 3 RETRIEVE - Mandatory Parallel Search:**
|
||||
1. **Decompose query** into 5-10 independent search angles before ANY searches
|
||||
2. **Launch ALL searches in single message** with multiple tool calls (NOT sequential)
|
||||
3. **Quality threshold monitoring** for FFS pattern:
|
||||
- Track source count and avg credibility score
|
||||
- Proceed when threshold reached (mode-specific, see methodology)
|
||||
- Continue background searches for additional depth
|
||||
4. **Spawn 3-5 parallel agents** using Task tool for deep-dive investigations
|
||||
|
||||
**Example correct execution:**
|
||||
```
|
||||
[Single message with 8+ parallel tool calls]
|
||||
WebSearch #1: Core topic semantic
|
||||
WebSearch #2: Technical keywords
|
||||
WebSearch #3: Recent 2024-2025 filtered
|
||||
WebSearch #4: Academic domains
|
||||
WebSearch #5: Critical analysis
|
||||
WebSearch #6: Industry trends
|
||||
Task agent #1: Academic paper analysis
|
||||
Task agent #2: Technical documentation deep dive
|
||||
```
|
||||
|
||||
**❌ WRONG (sequential execution):**
|
||||
```
|
||||
WebSearch #1 → wait for results → WebSearch #2 → wait → WebSearch #3...
|
||||
```
|
||||
|
||||
**✅ RIGHT (parallel execution):**
|
||||
```
|
||||
All searches + agents launched simultaneously in one message
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 4. Verify (Always Execute)
|
||||
|
||||
**Step 1: Citation Verification (Catches Fabricated Sources)**
|
||||
|
||||
```bash
|
||||
python scripts/verify_citations.py --report [path]
|
||||
```
|
||||
|
||||
**Checks:**
|
||||
- DOI resolution (verifies citation actually exists)
|
||||
- Title/year matching (detects mismatched metadata)
|
||||
- Flags suspicious entries (2024+ without DOI, no URL, failed verification)
|
||||
|
||||
**If suspicious citations found:**
|
||||
- Review flagged entries manually
|
||||
- Remove or replace fabricated sources
|
||||
- Re-run until clean
|
||||
|
||||
**Step 2: Structure & Quality Validation**
|
||||
|
||||
```bash
|
||||
python scripts/validate_report.py --report [path]
|
||||
```
|
||||
|
||||
**8 automated checks:**
|
||||
1. Executive summary length (50-250 words)
|
||||
2. Required sections present (+ recommended: Claims table, Counterevidence)
|
||||
3. Citations formatted [1], [2], [3]
|
||||
4. Bibliography matches citations
|
||||
5. No placeholder text (TBD, TODO)
|
||||
6. Word count reasonable (500-10000)
|
||||
7. Minimum 10 sources
|
||||
8. No broken internal links
|
||||
|
||||
**If fails:**
|
||||
- Attempt 1: Auto-fix formatting/links
|
||||
- Attempt 2: Manual review + correction
|
||||
- After 2 failures: **STOP** → Report issues → Ask user
|
||||
|
||||
---
|
||||
|
||||
### 5. Report
|
||||
|
||||
**CRITICAL: Generate COMPREHENSIVE, DETAILED markdown reports**
|
||||
|
||||
**File Organization (CRITICAL - Clean Accessibility):**
|
||||
|
||||
**1. Create Organized Folder in Documents:**
|
||||
- ALWAYS create dedicated folder: `~/Documents/[TopicName]_Research_[YYYYMMDD]/`
|
||||
- Extract clean topic name from research question (remove special chars, use underscores/CamelCase)
|
||||
- Examples:
|
||||
- "psilocybin research 2025" → `~/Documents/Psilocybin_Research_20251104/`
|
||||
- "compare React vs Vue" → `~/Documents/React_vs_Vue_Research_20251104/`
|
||||
- "AI safety trends" → `~/Documents/AI_Safety_Trends_Research_20251104/`
|
||||
- If folder exists, use it; if not, create it
|
||||
- This ensures clean organization and easy accessibility
|
||||
|
||||
**2. Save All Formats to Same Folder:**
|
||||
|
||||
**Markdown (Primary Source):**
|
||||
- Save to: `[Documents folder]/research_report_[YYYYMMDD]_[topic_slug].md`
|
||||
- Also save copy to: `~/.claude/research_output/` (internal tracking)
|
||||
- Full detailed report with all findings
|
||||
|
||||
**HTML (McKinsey Style - ALWAYS GENERATE):**
|
||||
- Save to: `[Documents folder]/research_report_[YYYYMMDD]_[topic_slug].html`
|
||||
- Use McKinsey template: [mckinsey_template](./templates/mckinsey_report_template.html)
|
||||
- Design principles: Sharp corners (NO border-radius), muted corporate colors (navy #003d5c, gray #f8f9fa), ultra-compact layout, info-first structure
|
||||
- Place critical metrics dashboard at top (extract 3-4 key quantitative findings)
|
||||
- Use data tables for dense information presentation
|
||||
- 14px base font, compact spacing, no decorative gradients or colors
|
||||
- **Attribution Gradients (2025):** Wrap each citation [N] in `<span class="citation">` with nested tooltip div showing source details
|
||||
- OPEN in browser automatically after generation
|
||||
|
||||
**PDF (Professional Print - ALWAYS GENERATE):**
|
||||
- Save to: `[Documents folder]/research_report_[YYYYMMDD]_[topic_slug].pdf`
|
||||
- Use generating-pdf skill (via Task tool with general-purpose agent)
|
||||
- Professional formatting with headers, page numbers
|
||||
- OPEN in default PDF viewer after generation
|
||||
|
||||
**3. File Naming Convention:**
|
||||
All files use same base name for easy matching:
|
||||
- `research_report_20251104_psilocybin_2025.md`
|
||||
- `research_report_20251104_psilocybin_2025.html`
|
||||
- `research_report_20251104_psilocybin_2025.pdf`
|
||||
|
||||
**Length Requirements (UNLIMITED with Progressive Assembly):**
|
||||
- Quick mode: 2,000+ words (baseline quality threshold)
|
||||
- Standard mode: 4,000+ words (comprehensive analysis)
|
||||
- Deep mode: 6,000+ words (thorough investigation)
|
||||
- UltraDeep mode: 10,000-50,000+ words (NO UPPER LIMIT - as comprehensive as evidence warrants)
|
||||
|
||||
**How Unlimited Length Works:**
|
||||
Progressive file assembly allows ANY report length by generating section-by-section.
|
||||
Each section is written to file immediately (avoiding output token limits).
|
||||
Complex topics with many findings? Generate 20, 30, 50+ findings - no constraint!
|
||||
|
||||
**Content Requirements:**
|
||||
- Use [template](./templates/report_template.md) as exact structure
|
||||
- Generate each section to APPROPRIATE depth (determined by evidence, not word targets)
|
||||
- Include specific data, statistics, dates, numbers (not vague statements)
|
||||
- Multiple paragraphs per finding with evidence (as many as needed)
|
||||
- Each section gets focused generation attention
|
||||
- DO NOT write summaries - write FULL analysis
|
||||
|
||||
**Writing Standards:**
|
||||
- **Narrative-driven**: Write in flowing prose. Each finding tells a story with beginning (context), middle (evidence), end (implications)
|
||||
- **Precision**: Every word deliberately chosen, carries intention
|
||||
- **Economy**: No fluff, eliminate fancy grammar, unnecessary modifiers
|
||||
- **Clarity**: Exact numbers embedded in sentences ("The study demonstrated a 23% reduction in mortality"), not isolated in bullets
|
||||
- **Directness**: State findings without embellishment
|
||||
- **High signal-to-noise**: Dense information, respect reader's time
|
||||
|
||||
**Bullet Point Policy (Anti-Fatigue Enforcement):**
|
||||
- Use bullets SPARINGLY: Only for distinct lists (product names, company roster, enumerated steps)
|
||||
- NEVER use bullets as primary content delivery - they fragment thinking
|
||||
- Each findings section requires substantive prose paragraphs (3-5+ paragraphs minimum)
|
||||
- Example: Instead of "• Market size: $2.4B" write "The global market reached $2.4 billion in 2023, driven by increasing consumer demand and regulatory tailwinds [1]."
|
||||
|
||||
**Anti-Fatigue Quality Check (Apply to EVERY Section):**
|
||||
Before considering a section complete, verify:
|
||||
- [ ] **Paragraph count**: ≥3 paragraphs for major sections (## headings)
|
||||
- [ ] **Prose-first**: <20% of content is bullet points (≥80% must be flowing prose)
|
||||
- [ ] **No placeholders**: Zero instances of "Content continues", "Due to length", "[Sections X-Y]"
|
||||
- [ ] **Evidence-rich**: Specific data points, statistics, quotes (not vague statements)
|
||||
- [ ] **Citation density**: Major claims cited within same sentence
|
||||
|
||||
**If ANY check fails:** Regenerate the section before moving to next.
|
||||
|
||||
**Source Attribution Standards (Critical for Preventing Fabrication):**
|
||||
- **Immediate citation**: Every factual claim followed by [N] citation in same sentence
|
||||
- **Quote sources directly**: Use "According to [1]..." or "[1] reports..." for factual statements
|
||||
- **Distinguish fact from synthesis**:
|
||||
- ✅ GOOD: "Mortality decreased 23% (p<0.01) in the treatment group [1]."
|
||||
- ❌ BAD: "Studies show mortality improved significantly."
|
||||
- **No vague attributions**:
|
||||
- ❌ NEVER: "Research suggests...", "Studies show...", "Experts believe..."
|
||||
- ✅ ALWAYS: "Smith et al. (2024) found..." [1], "According to FDA data..." [2]
|
||||
- **Label speculation explicitly**:
|
||||
- ✅ GOOD: "This suggests a potential mechanism..." (analysis, not fact)
|
||||
- ❌ BAD: "The mechanism is..." (presented as fact without citation)
|
||||
- **Admit uncertainty**:
|
||||
- ✅ GOOD: "No sources found addressing X directly."
|
||||
- ❌ BAD: Fabricating a citation to fill the gap
|
||||
- **Template pattern**: "[Specific claim with numbers/data] [Citation]. [Analysis/implication]."
|
||||
|
||||
**Deliver to user:**
|
||||
1. Executive summary (inline in chat)
|
||||
2. Organized folder path (e.g., "All files saved to: ~/Documents/Psilocybin_Research_20251104/")
|
||||
3. Confirmation of all three formats generated:
|
||||
- Markdown (source)
|
||||
- HTML (McKinsey-style, opened in browser)
|
||||
- PDF (professional print, opened in viewer)
|
||||
4. Source quality assessment summary (source count)
|
||||
5. Next steps (if relevant)
|
||||
|
||||
**Generation Workflow: Progressive File Assembly (Unlimited Length)**
|
||||
|
||||
**Phase 8.1: Setup**
|
||||
```bash
|
||||
# Extract topic slug from research question
|
||||
# Create folder: ~/Documents/[TopicName]_Research_[YYYYMMDD]/
|
||||
mkdir -p ~/Documents/[folder_name]
|
||||
|
||||
# Create initial markdown file with frontmatter
|
||||
# File path: [folder]/research_report_[YYYYMMDD]_[slug].md
|
||||
```
|
||||
|
||||
**Phase 8.2: Progressive Section Generation**
|
||||
|
||||
**CRITICAL STRATEGY:** Generate and write each section individually to file using Write/Edit tools.
|
||||
This allows unlimited report length while keeping each generation manageable.
|
||||
|
||||
**OUTPUT TOKEN LIMIT SAFEGUARD (CRITICAL - Claude Code Default: 32K):**
|
||||
|
||||
Claude Code default limit: 32,000 output tokens (≈24,000 words total per skill execution)
|
||||
This is a HARD LIMIT and cannot be changed within the skill.
|
||||
|
||||
**What this means:**
|
||||
- Total output (your text + all tool call content) must be <32,000 tokens
|
||||
- 32,000 tokens ≈ 24,000 words max
|
||||
- Leave safety margin: Target ≤20,000 words total output
|
||||
|
||||
**Realistic report sizes per mode:**
|
||||
- Quick mode: 2,000-4,000 words ✅ (well under limit)
|
||||
- Standard mode: 4,000-8,000 words ✅ (comfortably under limit)
|
||||
- Deep mode: 8,000-15,000 words ✅ (achievable with care)
|
||||
- UltraDeep mode: 15,000-20,000 words ⚠️ (at limit, monitor closely)
|
||||
|
||||
**For reports >20,000 words:**
|
||||
User must run skill multiple times:
|
||||
- Run 1: "Generate Part 1 (sections 1-6)" → saves to part1.md
|
||||
- Run 2: "Generate Part 2 (sections 7-12)" → saves to part2.md
|
||||
- User manually combines or asks Claude to merge files
|
||||
|
||||
**Auto-Continuation Strategy (TRUE Unlimited Length):**
|
||||
|
||||
When report exceeds 18,000 words in single run:
|
||||
1. Generate sections 1-10 (stay under 18K words)
|
||||
2. Save continuation state file with context preservation
|
||||
3. Spawn continuation agent via Task tool
|
||||
4. Continuation agent: Reads state → Generates next batch → Spawns next agent if needed
|
||||
5. Chain continues recursively until complete
|
||||
|
||||
This achieves UNLIMITED length while respecting 32K limit per agent
|
||||
|
||||
**Initialize Citation Tracking:**
|
||||
```
|
||||
citations_used = [] # Maintain this list in working memory throughout
|
||||
```
|
||||
|
||||
**Section Generation Loop:**
|
||||
|
||||
**Pattern:** Generate section content → Use Write/Edit tool with that content → Move to next section
|
||||
Each Write/Edit call contains ONE section (≤2,000 words per call)
|
||||
|
||||
1. **Executive Summary** (200-400 words)
|
||||
- Generate section content
|
||||
- Tool: Write(file, content=frontmatter + Executive Summary)
|
||||
- Track citations used
|
||||
- Progress: "✓ Executive Summary"
|
||||
|
||||
2. **Introduction** (400-800 words)
|
||||
- Generate section content
|
||||
- Tool: Edit(file, old=last_line, new=old + Introduction section)
|
||||
- Track citations used
|
||||
- Progress: "✓ Introduction"
|
||||
|
||||
3. **Finding 1** (600-2,000 words)
|
||||
- Generate complete finding
|
||||
- Tool: Edit(file, append Finding 1)
|
||||
- Track citations used
|
||||
- Progress: "✓ Finding 1"
|
||||
|
||||
4. **Finding 2** (600-2,000 words)
|
||||
- Generate complete finding
|
||||
- Tool: Edit(file, append Finding 2)
|
||||
- Track citations used
|
||||
- Progress: "✓ Finding 2"
|
||||
|
||||
... Continue for ALL findings (each finding = one Edit tool call, ≤2,000 words)
|
||||
|
||||
**CRITICAL:** If you have 10 findings × 1,500 words each = 15,000 words of findings
|
||||
This is OKAY because each Edit call is only 1,500 words (under 2,000 word limit per tool call)
|
||||
The FILE grows to 15,000 words, but no single tool call exceeds limits
|
||||
|
||||
4. **Synthesis & Insights**
|
||||
- Generate: Novel insights beyond source statements (as long as needed for synthesis)
|
||||
- Tool: Edit (append to file)
|
||||
- Track: Extract citations, append to citations_used
|
||||
- Progress: "Generated Synthesis ✓"
|
||||
|
||||
5. **Limitations & Caveats**
|
||||
- Generate: Counterevidence, gaps, uncertainties (appropriate depth)
|
||||
- Tool: Edit (append to file)
|
||||
- Track: Extract citations, append to citations_used
|
||||
- Progress: "Generated Limitations ✓"
|
||||
|
||||
6. **Recommendations**
|
||||
- Generate: Immediate actions, next steps, research needs (appropriate depth)
|
||||
- Tool: Edit (append to file)
|
||||
- Track: Extract citations, append to citations_used
|
||||
- Progress: "Generated Recommendations ✓"
|
||||
|
||||
7. **Bibliography (CRITICAL - ALL Citations)**
|
||||
- Generate: COMPLETE bibliography with EVERY citation from citations_used list
|
||||
- Format: [1], [2], [3]... [N] - each citation gets full entry
|
||||
- Verification: Check citations_used list - if list contains [1] through [73], generate all 73 entries
|
||||
- NO ranges ([1-50]), NO placeholders ("Additional citations"), NO truncation
|
||||
- Tool: Edit (append to file)
|
||||
- Progress: "Generated Bibliography ✓ (N citations)"
|
||||
|
||||
8. **Methodology Appendix**
|
||||
- Generate: Research process, verification approach (appropriate depth)
|
||||
- Tool: Edit (append to file)
|
||||
- Progress: "Generated Methodology ✓"
|
||||
|
||||
**Phase 8.3: Auto-Continuation Decision Point**
|
||||
|
||||
After generating sections, check word count:
|
||||
|
||||
**If total output ≤18,000 words:** Complete normally
|
||||
- Generate Bibliography (all citations)
|
||||
- Generate Methodology
|
||||
- Verify complete report
|
||||
- Save copy to ~/.claude/research_output/
|
||||
- Done! ✓
|
||||
|
||||
**If total output will exceed 18,000 words:** Auto-Continuation Protocol
|
||||
|
||||
**Step 1: Save Continuation State**
|
||||
Create file: `~/.claude/research_output/continuation_state_[report_id].json`
|
||||
|
||||
```json
|
||||
{
|
||||
"version": "2.1.1",
|
||||
"report_id": "[unique_id]",
|
||||
"file_path": "[absolute_path_to_report.md]",
|
||||
"mode": "[quick|standard|deep|ultradeep]",
|
||||
|
||||
"progress": {
|
||||
"sections_completed": [list of section IDs done],
|
||||
"total_planned_sections": [total count],
|
||||
"word_count_so_far": [current word count],
|
||||
"continuation_count": [which continuation this is, starts at 1]
|
||||
},
|
||||
|
||||
"citations": {
|
||||
"used": [1, 2, 3, ..., N],
|
||||
"next_number": [N+1],
|
||||
"bibliography_entries": [
|
||||
"[1] Full citation entry",
|
||||
"[2] Full citation entry",
|
||||
...
|
||||
]
|
||||
},
|
||||
|
||||
"research_context": {
|
||||
"research_question": "[original question]",
|
||||
"key_themes": ["theme1", "theme2", "theme3"],
|
||||
"main_findings_summary": [
|
||||
"Finding 1: [100-word summary]",
|
||||
"Finding 2: [100-word summary]",
|
||||
...
|
||||
],
|
||||
"narrative_arc": "[Current position in story: beginning/middle/conclusion]"
|
||||
},
|
||||
|
||||
"quality_metrics": {
|
||||
"avg_words_per_finding": [calculated average],
|
||||
"citation_density": [citations per 1000 words],
|
||||
"prose_vs_bullets_ratio": [e.g., "85% prose"],
|
||||
"writing_style": "technical-precise-data-driven"
|
||||
},
|
||||
|
||||
"next_sections": [
|
||||
{"id": N, "type": "finding", "title": "Finding X", "target_words": 1500},
|
||||
{"id": N+1, "type": "synthesis", "title": "Synthesis", "target_words": 1000},
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Step 2: Spawn Continuation Agent**
|
||||
|
||||
Use Task tool with general-purpose agent:
|
||||
|
||||
```
|
||||
Task(
|
||||
subagent_type="general-purpose",
|
||||
description="Continue deep-research report generation",
|
||||
prompt="""
|
||||
CONTINUATION TASK: You are continuing an existing deep-research report.
|
||||
|
||||
CRITICAL INSTRUCTIONS:
|
||||
1. Read continuation state file: ~/.claude/research_output/continuation_state_[report_id].json
|
||||
2. Read existing report to understand context: [file_path from state]
|
||||
3. Read LAST 3 completed sections to understand flow and style
|
||||
4. Load research context: themes, narrative arc, writing style from state
|
||||
5. Continue citation numbering from state.citations.next_number
|
||||
6. Maintain quality metrics from state (avg words, citation density, prose ratio)
|
||||
|
||||
CONTEXT PRESERVATION:
|
||||
- Research question: [from state]
|
||||
- Key themes established: [from state]
|
||||
- Findings so far: [summaries from state]
|
||||
- Narrative position: [from state]
|
||||
- Writing style: [from state]
|
||||
|
||||
YOUR TASK:
|
||||
Generate next batch of sections (stay under 18,000 words):
|
||||
[List next_sections from state]
|
||||
|
||||
Use Write/Edit tools to append to existing file: [file_path]
|
||||
|
||||
QUALITY GATES (verify before each section):
|
||||
- Words per section: Within ±20% of [avg_words_per_finding]
|
||||
- Citation density: Match [citation_density] ±0.5 per 1K words
|
||||
- Prose ratio: Maintain ≥80% prose (not bullets)
|
||||
- Theme alignment: Section ties to key_themes
|
||||
- Style consistency: Match [writing_style]
|
||||
|
||||
After generating sections:
|
||||
- If more sections remain: Update state, spawn next continuation agent
|
||||
- If final sections: Generate complete bibliography, verify report, cleanup state file
|
||||
|
||||
HANDOFF PROTOCOL (if spawning next agent):
|
||||
1. Update continuation_state.json with new progress
|
||||
2. Add new citations to state
|
||||
3. Add summaries of new findings to state
|
||||
4. Update quality metrics
|
||||
5. Spawn next agent with same instructions
|
||||
"""
|
||||
)
|
||||
```
|
||||
|
||||
**Step 3: Report Continuation Status**
|
||||
Tell user:
|
||||
```
|
||||
📊 Report Generation: Part 1 Complete (N sections, X words)
|
||||
🔄 Auto-continuing via spawned agent...
|
||||
Next batch: [section list]
|
||||
Progress: [X%] complete
|
||||
```
|
||||
|
||||
**Phase 8.4: Continuation Agent Quality Protocol**
|
||||
|
||||
When continuation agent starts:
|
||||
|
||||
**Context Loading (CRITICAL):**
|
||||
1. Read continuation_state.json → Load ALL context
|
||||
2. Read existing report file → Review last 3 sections
|
||||
3. Extract patterns:
|
||||
- Sentence structure complexity
|
||||
- Technical terminology used
|
||||
- Citation placement patterns
|
||||
- Paragraph transition style
|
||||
|
||||
**Pre-Generation Checklist:**
|
||||
- [ ] Loaded research context (themes, question, narrative arc)
|
||||
- [ ] Reviewed previous sections for flow
|
||||
- [ ] Loaded citation numbering (start from N+1)
|
||||
- [ ] Loaded quality targets (words, density, style)
|
||||
- [ ] Understand where in narrative arc (beginning/middle/end)
|
||||
|
||||
**Per-Section Generation:**
|
||||
1. Generate section content
|
||||
2. Quality checks:
|
||||
- Word count: Within target ±20%
|
||||
- Citation density: Matches established rate
|
||||
- Prose ratio: ≥80% prose
|
||||
- Theme connection: Ties to key_themes
|
||||
- Style match: Consistent with quality_metrics.writing_style
|
||||
3. If ANY check fails: Regenerate section
|
||||
4. If passes: Write to file, update state
|
||||
|
||||
**Handoff Decision:**
|
||||
- Calculate: Current word count + remaining sections × avg_words_per_section
|
||||
- If total < 18K: Generate all remaining sections + finish
|
||||
- If total > 18K: Generate partial batch, update state, spawn next agent
|
||||
|
||||
**Final Agent Responsibilities:**
|
||||
- Generate final content sections
|
||||
- Generate COMPLETE bibliography using ALL citations from state.citations.bibliography_entries
|
||||
- Read entire assembled report
|
||||
- Run validation: python scripts/validate_report.py --report [path]
|
||||
- Delete continuation_state.json (cleanup)
|
||||
- Report complete to user with metrics
|
||||
|
||||
**Anti-Fatigue Built-In:**
|
||||
Each agent generates manageable chunks (≤18K words), maintaining quality.
|
||||
Context preservation ensures coherence across continuation boundaries.
|
||||
|
||||
**Generate HTML (McKinsey Style)**
|
||||
1. Read McKinsey template from `./templates/mckinsey_report_template.html`
|
||||
2. Extract 3-4 key quantitative metrics from findings for dashboard
|
||||
3. **Use Python script for MD to HTML conversion:**
|
||||
|
||||
```bash
|
||||
cd ~/.claude/skills/deep-research
|
||||
python scripts/md_to_html.py [markdown_report_path]
|
||||
```
|
||||
|
||||
The script returns two parts:
|
||||
- **Part A ({{CONTENT}}):** All sections except Bibliography, properly converted to HTML
|
||||
- **Part B ({{BIBLIOGRAPHY}}):** Bibliography section only, formatted as HTML
|
||||
|
||||
**CRITICAL:** The script handles ALL conversion automatically:
|
||||
- Headers: ## → `<div class="section"><h2 class="section-title">`, ### → `<h3 class="subsection-title">`
|
||||
- Lists: Markdown bullets → `<ul><li>` with proper nesting
|
||||
- Tables: Markdown tables → `<table>` with thead/tbody
|
||||
- Paragraphs: Text wrapped in `<p>` tags
|
||||
- Bold/italic: **text** → `<strong>`, *text* → `<em>`
|
||||
- Citations: [N] preserved for tooltip conversion in step 4
|
||||
|
||||
4. **Add Citation Tooltips (Attribution Gradients):**
|
||||
For each [N] citation in {{CONTENT}} (not bibliography), optionally add interactive tooltips:
|
||||
```html
|
||||
<span class="citation">[N]
|
||||
<span class="citation-tooltip">
|
||||
<div class="tooltip-title">[Source Title]</div>
|
||||
<div class="tooltip-source">[Author/Publisher]</div>
|
||||
<div class="tooltip-claim">
|
||||
<div class="tooltip-claim-label">Supports Claim:</div>
|
||||
[Extract sentence with this citation]
|
||||
</div>
|
||||
</span>
|
||||
</span>
|
||||
```
|
||||
NOTE: This step is optional for speed. Basic [N] citations are sufficient.
|
||||
|
||||
5. Replace placeholders in template:
|
||||
- {{TITLE}} - Report title (extract from first ## heading in MD)
|
||||
- {{DATE}} - Generation date (YYYY-MM-DD format)
|
||||
- {{SOURCE_COUNT}} - Number of unique sources
|
||||
- {{METRICS_DASHBOARD}} - Metrics HTML from step 2
|
||||
- {{CONTENT}} - HTML from Part A (script output)
|
||||
- {{BIBLIOGRAPHY}} - HTML from Part B (script output)
|
||||
|
||||
6. **CRITICAL: NO EMOJIS** - Remove any emoji characters from final HTML
|
||||
|
||||
7. Save to: `[folder]/research_report_[YYYYMMDD]_[slug].html`
|
||||
|
||||
8. **Verify HTML (MANDATORY):**
|
||||
```bash
|
||||
python scripts/verify_html.py --html [html_path] --md [md_path]
|
||||
```
|
||||
- Check passes: Proceed to step 9
|
||||
- Check fails: Fix errors and re-run verification
|
||||
|
||||
9. Open in browser: `open [html_path]`
|
||||
|
||||
**Generate PDF**
|
||||
1. Use Task tool with general-purpose agent
|
||||
2. Invoke generating-pdf skill with markdown as input
|
||||
3. Save to: `[folder]/research_report_[YYYYMMDD]_[slug].pdf`
|
||||
4. PDF will auto-open when complete
|
||||
|
||||
---
|
||||
|
||||
## Output Contract
|
||||
|
||||
**Format:** Comprehensive markdown report following [template](./templates/report_template.md) EXACTLY
|
||||
|
||||
**Required sections (all must be detailed):**
|
||||
- Executive Summary (2-3 concise paragraphs, 50-250 words)
|
||||
- Introduction (2-3 paragraphs: question, scope, methodology, assumptions)
|
||||
- Main Analysis (4-8 findings, each 300-500 words with citations [1], [2], [3])
|
||||
- Synthesis & Insights (500-1000 words: patterns, novel insights, implications)
|
||||
- Limitations & Caveats (2-3 paragraphs: gaps, assumptions, uncertainties)
|
||||
- Recommendations (3-5 immediate actions, 3-5 next steps, 3-5 further research)
|
||||
- **Bibliography (CRITICAL - see rules below)**
|
||||
- Methodology Appendix (2-3 paragraphs: process, sources, verification)
|
||||
|
||||
**Bibliography Requirements (ZERO TOLERANCE - Report is UNUSABLE without complete bibliography):**
|
||||
- ✅ MUST include EVERY citation [N] used in report body (if report has [1]-[50], write all 50 entries)
|
||||
- ✅ Format: [N] Author/Org (Year). "Title". Publication. URL (Retrieved: Date)
|
||||
- ✅ Each entry on its own line, complete with all metadata
|
||||
- ❌ NO placeholders: NEVER use "[8-75] Additional citations", "...continue...", "etc.", "[Continue with sources...]"
|
||||
- ❌ NO ranges: Write [3], [4], [5]... individually, NOT "[3-50]"
|
||||
- ❌ NO truncation: If 30 sources cited, write all 30 entries in full
|
||||
- ⚠️ Validation WILL FAIL if bibliography contains placeholders or missing citations
|
||||
- ⚠️ Report is GARBAGE without complete bibliography - no way to verify claims
|
||||
|
||||
**Strictly Prohibited:**
|
||||
- Placeholder text (TBD, TODO, [citation needed])
|
||||
- Uncited major claims
|
||||
- Broken links
|
||||
- Missing required sections
|
||||
- **Short summaries instead of detailed analysis**
|
||||
- **Vague statements without specific evidence**
|
||||
|
||||
**Writing Standards (Critical):**
|
||||
- **Narrative-driven**: Write in flowing prose with complete sentences that build understanding progressively
|
||||
- **Precision**: Choose each word deliberately - every word must carry intention
|
||||
- **Economy**: Eliminate fluff, unnecessary adjectives, fancy grammar
|
||||
- **Clarity**: Use precise technical terms, avoid ambiguity. Embed exact numbers in sentences, not bullets
|
||||
- **Directness**: State findings clearly without embellishment
|
||||
- **Signal-to-noise**: High information density, respect reader's time
|
||||
- **Bullet discipline**: Use bullets only for distinct lists (products, companies, steps). Default to prose paragraphs
|
||||
- **Examples of precision**:
|
||||
- Bad: "significantly improved outcomes" → Good: "reduced mortality 23% (p<0.01)"
|
||||
- Bad: "several studies suggest" → Good: "5 RCTs (n=1,847) show"
|
||||
- Bad: "potentially beneficial" → Good: "increased biomarker X by 15%"
|
||||
- Bad: "• Market: $2.4B" → Good: "The market reached $2.4 billion in 2023, driven by consumer demand [1]."
|
||||
|
||||
**Quality gates (enforced by validator):**
|
||||
- Minimum 2,000 words (standard mode)
|
||||
- Average credibility score >60/100
|
||||
- 3+ sources per major claim
|
||||
- Clear facts vs. analysis distinction
|
||||
- All sections present and detailed
|
||||
|
||||
---
|
||||
|
||||
## Error Handling & Stop Rules
|
||||
|
||||
**Stop immediately if:**
|
||||
- 2 validation failures on same error → Pause, report, ask user
|
||||
- <5 sources after exhaustive search → Report limitation, request direction
|
||||
- User interrupts/changes scope → Confirm new direction
|
||||
|
||||
**Graceful degradation:**
|
||||
- 5-10 sources → Note in limitations, proceed with extra verification
|
||||
- Time constraint reached → Package partial results, document gaps
|
||||
- High-priority critique issue → Address immediately
|
||||
|
||||
**Error format:**
|
||||
```
|
||||
⚠️ Issue: [Description]
|
||||
📊 Context: [What was attempted]
|
||||
🔍 Tried: [Resolution attempts]
|
||||
💡 Options:
|
||||
1. [Option 1]
|
||||
2. [Option 2]
|
||||
3. [Option 3]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Quality Standards (Always Enforce)
|
||||
|
||||
Every report must:
|
||||
- 10+ sources (document if fewer)
|
||||
- 3+ sources per major claim
|
||||
- Executive summary <250 words
|
||||
- Full citations with URLs
|
||||
- Credibility assessment
|
||||
- Limitations section
|
||||
- Methodology documented
|
||||
- No placeholders
|
||||
|
||||
**Priority:** Thoroughness over speed. Quality > speed.
|
||||
|
||||
---
|
||||
|
||||
## Inputs & Assumptions
|
||||
|
||||
**Required:**
|
||||
- Research question (string)
|
||||
|
||||
**Optional:**
|
||||
- Mode (quick/standard/deep/ultradeep)
|
||||
- Time constraints
|
||||
- Required perspectives/sources
|
||||
- Output format
|
||||
|
||||
**Assumptions:**
|
||||
- User requires verified, citation-backed information
|
||||
- 10-50 sources available on topic
|
||||
- Time investment: 5-45 minutes
|
||||
|
||||
---
|
||||
|
||||
## When to Use / NOT Use
|
||||
|
||||
**Use when:**
|
||||
- Comprehensive analysis (10+ sources needed)
|
||||
- Comparing technologies/approaches/strategies
|
||||
- State-of-the-art reviews
|
||||
- Multi-perspective investigation
|
||||
- Technical decisions
|
||||
- Market/trend analysis
|
||||
|
||||
**Do NOT use:**
|
||||
- Simple lookups (use WebSearch)
|
||||
- Debugging (use standard tools)
|
||||
- 1-2 search answers
|
||||
- Time-sensitive quick answers
|
||||
|
||||
---
|
||||
|
||||
## Scripts (Offline, Python stdlib only)
|
||||
|
||||
**Location:** `./scripts/`
|
||||
|
||||
- **research_engine.py** - Orchestration engine
|
||||
- **validate_report.py** - Quality validation (8 checks)
|
||||
- **citation_manager.py** - Citation tracking
|
||||
- **source_evaluator.py** - Credibility scoring (0-100)
|
||||
|
||||
**No external dependencies required.**
|
||||
|
||||
---
|
||||
|
||||
## Progressive References (Load On-Demand)
|
||||
|
||||
**Do not inline these - reference only:**
|
||||
- [Complete Methodology](./reference/methodology.md) - 8-phase details
|
||||
- [Report Template](./templates/report_template.md) - Output structure
|
||||
- [README](./README.md) - Usage docs
|
||||
- [Quick Start](./QUICK_START.md) - Fast reference
|
||||
- [Competitive Analysis](./COMPETITIVE_ANALYSIS.md) - vs OpenAI/Gemini
|
||||
|
||||
**Context Management:** Load files on-demand for current phase only. Do not preload all content.
|
||||
|
||||
---
|
||||
|
||||
<!-- STATIC CONTEXT BLOCK END -->
|
||||
<!-- ⚡ Above content is cacheable (>1024 tokens, static) -->
|
||||
<!-- 📝 Below: Dynamic content (user queries, retrieved data, generated reports) -->
|
||||
<!-- This structure enables 85% latency reduction via prompt caching -->
|
||||
|
||||
---
|
||||
|
||||
## Dynamic Execution Zone
|
||||
|
||||
**User Query Processing:**
|
||||
[User research question will be inserted here during execution]
|
||||
|
||||
**Retrieved Information:**
|
||||
[Search results and sources will be accumulated here]
|
||||
|
||||
**Generated Analysis:**
|
||||
[Findings, synthesis, and report content generated here]
|
||||
|
||||
**Note:** This section remains empty in the skill definition. Content populated during runtime only.
|
||||
476
axhub-make/skills/third-party/deep-research/WORD_PRECISION_AUDIT.md
vendored
Normal file
476
axhub-make/skills/third-party/deep-research/WORD_PRECISION_AUDIT.md
vendored
Normal file
@@ -0,0 +1,476 @@
|
||||
# Word Precision Audit: Deep Research Skill
|
||||
|
||||
**Date:** 2025-11-04
|
||||
**Purpose:** Systematic review of every word in SKILL.md for precision, intention, and clarity
|
||||
|
||||
---
|
||||
|
||||
## Audit Methodology
|
||||
|
||||
**Criteria for precision:**
|
||||
1. **No hedge words** ("reasonably", "generally", "basically", "essentially")
|
||||
2. **No weak verbs** ("can", "may", "might", "should" → use "must", "will", "do")
|
||||
3. **No vague adjectives** ("good", "nice", "reasonable" → use specific criteria)
|
||||
4. **No passive voice** where active is stronger
|
||||
5. **No colloquialisms** in formal directives
|
||||
6. **No double negatives** ("no need to" → "proceed without")
|
||||
7. **No redundancy** (say once, clearly)
|
||||
8. **No ambiguous pronouns** without clear referents
|
||||
|
||||
---
|
||||
|
||||
## Issues Found (14 total)
|
||||
|
||||
### HIGH PRIORITY (8 issues)
|
||||
|
||||
#### Issue #1: "reasonable assumptions" (Lines 54, 58)
|
||||
**Current:**
|
||||
```markdown
|
||||
Proceed with reasonable assumptions.
|
||||
Make reasonable assumptions based on query context.
|
||||
```
|
||||
|
||||
**Problem:** "reasonable" is subjective, vague, creates uncertainty about what's acceptable
|
||||
|
||||
**Fix:**
|
||||
```markdown
|
||||
Infer assumptions from query context.
|
||||
Derive assumptions from query signals.
|
||||
```
|
||||
|
||||
**Intention carried:** "reasonable" → permission-seeking, cautious | "infer/derive" → direct action, confident
|
||||
|
||||
---
|
||||
|
||||
#### Issue #2: "genuinely incomprehensible" (Line 61)
|
||||
**Current:**
|
||||
```markdown
|
||||
Query is genuinely incomprehensible
|
||||
```
|
||||
|
||||
**Problem:** "genuinely" is hedge word, weakens the criterion
|
||||
|
||||
**Fix:**
|
||||
```markdown
|
||||
Query is incomprehensible
|
||||
```
|
||||
|
||||
**Intention carried:** "genuinely" → doubting, qualifying | removed → clear, definitive
|
||||
|
||||
---
|
||||
|
||||
#### Issue #3: "User can redirect if needed" (Line 64)
|
||||
**Current:**
|
||||
```markdown
|
||||
PROCEED with standard mode. User can redirect if needed.
|
||||
```
|
||||
|
||||
**Problem:** "can" is weak permission, "if needed" is uncertain, both undermine autonomy
|
||||
|
||||
**Fix:**
|
||||
```markdown
|
||||
PROCEED with standard mode. User will redirect if incorrect.
|
||||
```
|
||||
|
||||
**Intention carried:** "can...if needed" → uncertain, permission-seeking | "will...if incorrect" → confident, definitive
|
||||
|
||||
---
|
||||
|
||||
#### Issue #4: "NO need to wait" - double negative (Line 85)
|
||||
**Current:**
|
||||
```markdown
|
||||
NO need to wait for approval - proceed directly to execution
|
||||
```
|
||||
|
||||
**Problem:** Double negative ("NO need") is weaker than direct command, "proceed directly to execution" is wordy
|
||||
|
||||
**Fix:**
|
||||
```markdown
|
||||
Proceed without waiting for approval
|
||||
```
|
||||
|
||||
**Intention carried:** "NO need to" → permissive, passive | "Proceed without" → imperative, active
|
||||
|
||||
---
|
||||
|
||||
#### Issue #5: Contraction "Don't" (Line 113)
|
||||
**Current:**
|
||||
```markdown
|
||||
Don't inline everything - use references
|
||||
```
|
||||
|
||||
**Problem:** Contraction in formal directive, less authoritative
|
||||
|
||||
**Fix:**
|
||||
```markdown
|
||||
Do not inline everything - reference external files
|
||||
```
|
||||
|
||||
**Intention carried:** "Don't" → casual | "Do not" → formal, authoritative
|
||||
|
||||
---
|
||||
|
||||
#### Issue #6: "ask to proceed" - weak request (Line 229)
|
||||
**Current:**
|
||||
```markdown
|
||||
<5 sources after exhaustive search → Report limitation, ask to proceed
|
||||
```
|
||||
|
||||
**Problem:** "ask to proceed" is weak, implies uncertainty about whether to continue
|
||||
|
||||
**Fix:**
|
||||
```markdown
|
||||
<5 sources after exhaustive search → Report limitation, request direction
|
||||
```
|
||||
|
||||
**Intention carried:** "ask to proceed" → tentative | "request direction" → professional, clear need
|
||||
|
||||
---
|
||||
|
||||
#### Issue #7: "When uncertain" contradicts autonomy (Line 262)
|
||||
**Current:**
|
||||
```markdown
|
||||
**When uncertain:** Be thorough, not fast. Quality > speed.
|
||||
```
|
||||
|
||||
**Problem:** "When uncertain" directly contradicts autonomy principle (line 54 says operate independently), creates confusion about when to be uncertain
|
||||
|
||||
**Fix:**
|
||||
```markdown
|
||||
**Priority:** Thoroughness over speed. Quality > speed.
|
||||
```
|
||||
|
||||
**Intention carried:** "When uncertain" → hesitation, doubt | "Priority" → clear directive, no uncertainty
|
||||
|
||||
---
|
||||
|
||||
#### Issue #8: "acceptable" is passive (Line 280)
|
||||
**Current:**
|
||||
```markdown
|
||||
Extended reasoning acceptable (5-45 min)
|
||||
```
|
||||
|
||||
**Problem:** "acceptable" is passive, permission-seeking, weak
|
||||
|
||||
**Fix:**
|
||||
```markdown
|
||||
Time investment: 5-45 minutes
|
||||
```
|
||||
|
||||
**Intention carried:** "acceptable" → asking permission | "investment" → stating fact
|
||||
|
||||
---
|
||||
|
||||
### MEDIUM PRIORITY (6 issues)
|
||||
|
||||
#### Issue #9: "Good autonomous assumptions" - vague judgment (Line 66)
|
||||
**Current:**
|
||||
```markdown
|
||||
**Good autonomous assumptions:**
|
||||
```
|
||||
|
||||
**Problem:** "Good" is vague value judgment without criteria
|
||||
|
||||
**Fix:**
|
||||
```markdown
|
||||
**Default assumptions:**
|
||||
```
|
||||
|
||||
**Intention carried:** "Good" → subjective approval-seeking | "Default" → objective, standard procedure
|
||||
|
||||
---
|
||||
|
||||
#### Issue #10: "Standard+" unclear notation (Lines 96, 101)
|
||||
**Current:**
|
||||
```markdown
|
||||
**Standard+ adds:**
|
||||
**Deep+ adds:**
|
||||
```
|
||||
|
||||
**Problem:** "+" notation is programming jargon, unclear if it means "and above" or "additional to"
|
||||
|
||||
**Fix:**
|
||||
```markdown
|
||||
**Standard/Deep/UltraDeep execute:**
|
||||
**Deep/UltraDeep execute:**
|
||||
```
|
||||
|
||||
**Intention carried:** "+" → ambiguous scope | explicit listing → clear scope
|
||||
|
||||
---
|
||||
|
||||
#### Issue #11: "(optional)" weakens directive (Line 174)
|
||||
**Current:**
|
||||
```markdown
|
||||
4. Next steps (optional)
|
||||
```
|
||||
|
||||
**Problem:** "(optional)" signals uncertainty, weakens the delivery item
|
||||
|
||||
**Fix:**
|
||||
```markdown
|
||||
4. Next steps (if relevant)
|
||||
```
|
||||
OR remove entirely since it's in "Deliver to user" section
|
||||
|
||||
**Intention carried:** "(optional)" → uncertain, dismissible | "(if relevant)" → conditional, purposeful | removed → expected
|
||||
|
||||
---
|
||||
|
||||
#### Issue #12: "Offer:" implies asking permission (Lines 176-179)
|
||||
**Current:**
|
||||
```markdown
|
||||
**Offer:**
|
||||
- Deep-dive any section
|
||||
- Follow-up questions
|
||||
- Alternative formats
|
||||
```
|
||||
|
||||
**Problem:** "Offer" implies asking permission, waiting for response, breaks autonomous flow
|
||||
|
||||
**Fix:**
|
||||
```markdown
|
||||
**Available on request:**
|
||||
- Section deep-dives
|
||||
- Follow-up analysis
|
||||
- Alternative formats
|
||||
```
|
||||
OR remove entirely (user will ask if interested)
|
||||
|
||||
**Intention carried:** "Offer" → salesperson, permission-seeking | "Available on request" → service menu, user-initiated | removed → autonomous
|
||||
|
||||
---
|
||||
|
||||
#### Issue #13: "hit" colloquial (Line 234)
|
||||
**Current:**
|
||||
```markdown
|
||||
Time constraint hit → Package partial results, document gaps
|
||||
```
|
||||
|
||||
**Problem:** "hit" is colloquial, imprecise for technical directive
|
||||
|
||||
**Fix:**
|
||||
```markdown
|
||||
Time constraint reached → Package partial results, document gaps
|
||||
```
|
||||
|
||||
**Intention carried:** "hit" → casual, imprecise | "reached" → formal, precise
|
||||
|
||||
---
|
||||
|
||||
#### Issue #14: "explicitly needed" redundant (Line 324)
|
||||
**Current:**
|
||||
```markdown
|
||||
Load these files only when explicitly needed for current phase.
|
||||
```
|
||||
|
||||
**Problem:** "explicitly needed" is redundant - either needed or not, "explicitly" adds no precision
|
||||
|
||||
**Fix:**
|
||||
```markdown
|
||||
Load files on-demand for current phase only.
|
||||
```
|
||||
|
||||
**Intention carried:** "explicitly needed" → overthinking, redundant | "on-demand" → clear technical term
|
||||
|
||||
---
|
||||
|
||||
## Impact Analysis
|
||||
|
||||
### Before Fixes (Current State)
|
||||
|
||||
**Hedge words count:** 4 ("reasonable" ×2, "genuinely", "acceptable")
|
||||
**Weak modal verbs:** 2 ("can redirect", "may")
|
||||
**Passive constructions:** 3 ("can", "acceptable", "optional")
|
||||
**Vague adjectives:** 2 ("good", "reasonable")
|
||||
**Colloquialisms:** 1 ("hit")
|
||||
**Redundancies:** 2 ("explicitly needed", "NO need to")
|
||||
|
||||
**Total weakness indicators:** 14
|
||||
|
||||
### After Fixes (Proposed State)
|
||||
|
||||
**Hedge words count:** 0
|
||||
**Weak modal verbs:** 0
|
||||
**Passive constructions:** 0
|
||||
**Vague adjectives:** 0
|
||||
**Colloquialisms:** 0
|
||||
**Redundancies:** 0
|
||||
|
||||
**Total weakness indicators:** 0
|
||||
|
||||
---
|
||||
|
||||
## Word Intention Analysis
|
||||
|
||||
### Critical Word Replacements
|
||||
|
||||
| Current Word | Unintended Intention | Replacement | Intended Intention |
|
||||
|--------------|---------------------|-------------|-------------------|
|
||||
| reasonable | subjective, cautious | infer/derive | objective, confident |
|
||||
| genuinely | doubting, qualifying | [remove] | certain, definitive |
|
||||
| can | permission-seeking | will | confident expectation |
|
||||
| if needed | uncertain | if incorrect | conditional, clear |
|
||||
| NO need to | passive, permissive | Proceed without | active, imperative |
|
||||
| Don't | casual, conversational | Do not | formal, authoritative |
|
||||
| ask to | tentative, weak | request | professional, clear |
|
||||
| When uncertain | hesitant, contradictory | Priority | directive, unambiguous |
|
||||
| acceptable | permission-seeking | investment | factual, confident |
|
||||
| Good | subjective approval | Default | objective standard |
|
||||
| + | ambiguous, jargon | explicit list | clear, precise |
|
||||
| optional | dismissible, weak | [remove or "if relevant"] | purposeful or expected |
|
||||
| Offer | salesperson, passive | [remove] | autonomous |
|
||||
| hit | casual, imprecise | reached | formal, precise |
|
||||
| explicitly needed | redundant, overthinking | on-demand | technical, concise |
|
||||
|
||||
---
|
||||
|
||||
## Linguistic Precision Principles Applied
|
||||
|
||||
### 1. Imperative Voice for Commands
|
||||
**Before:** "NO need to wait for approval"
|
||||
**After:** "Proceed without waiting for approval"
|
||||
**Principle:** Direct commands > passive permissions
|
||||
|
||||
### 2. Remove Hedge Words
|
||||
**Before:** "genuinely incomprehensible"
|
||||
**After:** "incomprehensible"
|
||||
**Principle:** Qualifiers weaken, removal strengthens
|
||||
|
||||
### 3. Eliminate Subjective Judgments
|
||||
**Before:** "Good autonomous assumptions"
|
||||
**After:** "Default assumptions"
|
||||
**Principle:** Objective standards > vague judgments
|
||||
|
||||
### 4. Active Voice Over Passive
|
||||
**Before:** "Extended reasoning acceptable"
|
||||
**After:** "Time investment: 5-45 minutes"
|
||||
**Principle:** Active assertions > passive permissions
|
||||
|
||||
### 5. Precise Technical Terms
|
||||
**Before:** "Time constraint hit"
|
||||
**After:** "Time constraint reached"
|
||||
**Principle:** Formal precision > colloquial approximation
|
||||
|
||||
### 6. Remove Redundancy
|
||||
**Before:** "explicitly needed"
|
||||
**After:** "on-demand"
|
||||
**Principle:** Say once clearly > repeat with qualifiers
|
||||
|
||||
### 7. Strong Modals
|
||||
**Before:** "User can redirect if needed"
|
||||
**After:** "User will redirect if incorrect"
|
||||
**Principle:** "will" (expectation) > "can" (possibility)
|
||||
|
||||
---
|
||||
|
||||
## Autonomy Language Analysis
|
||||
|
||||
### Contradiction Resolution
|
||||
|
||||
**Problem:** Line 262 "When uncertain" contradicts Line 54 "operates independently"
|
||||
|
||||
**Analysis:**
|
||||
- Line 54 establishes autonomy principle: proceed independently
|
||||
- Line 262 suggests there are times of uncertainty
|
||||
- These create cognitive dissonance: am I uncertain or autonomous?
|
||||
|
||||
**Resolution:**
|
||||
- Replace "When uncertain" with "Priority"
|
||||
- Frame as quality standard, not uncertainty condition
|
||||
- Maintains autonomy while setting quality expectations
|
||||
|
||||
**Result:** No contradiction, clear hierarchy (autonomy + quality priority)
|
||||
|
||||
---
|
||||
|
||||
## Permission-Seeking Language Removal
|
||||
|
||||
### Identified Permission-Seeking Patterns
|
||||
|
||||
1. "reasonable assumptions" → seeking approval for assumption quality
|
||||
2. "can redirect if needed" → seeking permission to proceed
|
||||
3. "NO need to wait" → asking if it's okay to proceed
|
||||
4. "acceptable" → asking if time investment is okay
|
||||
5. "Offer" → asking permission to provide options
|
||||
|
||||
### Replacement Strategy
|
||||
|
||||
Replace all permission-seeking with:
|
||||
- **Assertions:** State facts confidently
|
||||
- **Imperatives:** Give direct commands
|
||||
- **Expectations:** Describe what will happen
|
||||
- **Standards:** Define objective criteria
|
||||
|
||||
---
|
||||
|
||||
## Testing Precision Improvements
|
||||
|
||||
### Scenario 1: Ambiguous Query
|
||||
|
||||
**Before (with weak language):**
|
||||
> "Make reasonable assumptions based on query context. User can redirect if needed."
|
||||
|
||||
**Interpretation:** Unclear what "reasonable" means, "can" suggests permission, "if needed" is vague
|
||||
|
||||
**After (precise language):**
|
||||
> "Infer assumptions from query context. User will redirect if incorrect."
|
||||
|
||||
**Interpretation:** Clear action (infer), confident expectation (will), definite condition (incorrect)
|
||||
|
||||
### Scenario 2: Time Investment
|
||||
|
||||
**Before (passive):**
|
||||
> "Extended reasoning acceptable (5-45 min)"
|
||||
|
||||
**Interpretation:** Sounds like asking permission for time
|
||||
|
||||
**After (assertive):**
|
||||
> "Time investment: 5-45 minutes"
|
||||
|
||||
**Interpretation:** States fact, no permission sought
|
||||
|
||||
---
|
||||
|
||||
## Implementation Priority
|
||||
|
||||
### Phase 1: HIGH PRIORITY (Autonomy-Critical)
|
||||
Fix Issues #1-8 immediately - these directly impact autonomous operation
|
||||
|
||||
### Phase 2: MEDIUM PRIORITY (Clarity Improvements)
|
||||
Fix Issues #9-14 after Phase 1 - these improve clarity but don't block autonomy
|
||||
|
||||
---
|
||||
|
||||
## Verification Checklist
|
||||
|
||||
After fixes applied:
|
||||
|
||||
- [ ] No hedge words ("basically", "essentially", "generally", "reasonably")
|
||||
- [ ] No weak modals ("can", "may", "might", "could" where "will", "must" fit)
|
||||
- [ ] No passive voice where active is stronger
|
||||
- [ ] No subjective judgments ("good", "nice", "reasonable")
|
||||
- [ ] No colloquialisms in formal directives
|
||||
- [ ] No double negatives ("NO need to")
|
||||
- [ ] No redundancies ("explicitly needed")
|
||||
- [ ] No permission-seeking language
|
||||
- [ ] All commands use imperative voice
|
||||
- [ ] All conditions state clear criteria
|
||||
|
||||
---
|
||||
|
||||
## Conclusion
|
||||
|
||||
**Total issues found:** 14
|
||||
**High priority:** 8 (autonomy-impacting)
|
||||
**Medium priority:** 6 (clarity improvements)
|
||||
|
||||
**Primary problem:** Permission-seeking and hedge language that undermines autonomous operation principle
|
||||
|
||||
**Primary fix:** Replace all permission-seeking with assertions, imperatives, and expectations
|
||||
|
||||
**Expected impact:**
|
||||
- Clearer autonomous behavior (no uncertainty about when to proceed)
|
||||
- Stronger directives (commands not suggestions)
|
||||
- Precise language (every word carries specific intention)
|
||||
- Zero ambiguity about autonomy expectations
|
||||
384
axhub-make/skills/third-party/deep-research/reference/methodology.md
vendored
Normal file
384
axhub-make/skills/third-party/deep-research/reference/methodology.md
vendored
Normal file
@@ -0,0 +1,384 @@
|
||||
# Deep Research Methodology: 8-Phase Pipeline
|
||||
|
||||
## Overview
|
||||
|
||||
This document contains the detailed methodology for conducting deep research. The 8 phases represent a comprehensive approach to gathering, verifying, and synthesizing information from multiple sources.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: SCOPE - Research Framing
|
||||
|
||||
**Objective:** Define research boundaries and success criteria
|
||||
|
||||
**Activities:**
|
||||
1. Decompose the question into core components
|
||||
2. Identify stakeholder perspectives
|
||||
3. Define scope boundaries (what's in/out)
|
||||
4. Establish success criteria
|
||||
5. List key assumptions to validate
|
||||
|
||||
**Ultrathink Application:** Use extended reasoning to explore multiple framings of the question before committing to scope.
|
||||
|
||||
**Output:** Structured scope document with research boundaries
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: PLAN - Strategy Formulation
|
||||
|
||||
**Objective:** Create an intelligent research roadmap
|
||||
|
||||
**Activities:**
|
||||
1. Identify primary and secondary sources
|
||||
2. Map knowledge dependencies (what must be understood first)
|
||||
3. Create search query strategy with variants
|
||||
4. Plan triangulation approach
|
||||
5. Estimate time/effort per phase
|
||||
6. Define quality gates
|
||||
|
||||
**Graph-of-Thoughts:** Branch into multiple potential research paths, then converge on optimal strategy.
|
||||
|
||||
**Output:** Research plan with prioritized investigation paths
|
||||
|
||||
---
|
||||
|
||||
## Phase 3: RETRIEVE - Parallel Information Gathering
|
||||
|
||||
**Objective:** Systematically collect information from multiple sources using parallel execution for maximum speed
|
||||
|
||||
**CRITICAL: Execute ALL searches in parallel using a single message with multiple tool calls**
|
||||
|
||||
### Query Decomposition Strategy
|
||||
|
||||
Before launching searches, decompose the research question into 5-10 independent search angles:
|
||||
|
||||
1. **Core topic (semantic search)** - Meaning-based exploration of main concept
|
||||
2. **Technical details (keyword search)** - Specific terms, APIs, implementations
|
||||
3. **Recent developments (date-filtered)** - What's new in 2024-2025
|
||||
4. **Academic sources (domain-specific)** - Papers, research, formal analysis
|
||||
5. **Alternative perspectives (comparison)** - Competing approaches, criticisms
|
||||
6. **Statistical/data sources** - Quantitative evidence, metrics, benchmarks
|
||||
7. **Industry analysis** - Commercial applications, market trends
|
||||
8. **Critical analysis/limitations** - Known problems, failure modes, edge cases
|
||||
|
||||
### Parallel Execution Protocol
|
||||
|
||||
**Step 1: Launch ALL searches concurrently (single message)**
|
||||
|
||||
**CRITICAL: Use correct tool and parameters to avoid errors**
|
||||
|
||||
Choose ONE search approach per research session:
|
||||
|
||||
**Option A: Use WebSearch (built-in, no MCP required)**
|
||||
- Standard web search with simple query string
|
||||
- Parameters: `query` (required)
|
||||
- Optional: `allowed_domains`, `blocked_domains`
|
||||
- Example: `WebSearch(query="quantum computing 2025")`
|
||||
|
||||
**Option B: Use Exa MCP (if available, more powerful)**
|
||||
- Advanced semantic + keyword search
|
||||
- Tool name: `mcp__Exa__exa_search`
|
||||
- Parameters: `query` (required), `type` (auto/neural/keyword), `num_results`, `start_published_date`, `include_domains`
|
||||
- Example: `mcp__Exa__exa_search(query="quantum computing", type="neural", num_results=10)`
|
||||
|
||||
**NEVER mix parameter styles** - this causes "Invalid tool parameters" errors.
|
||||
|
||||
**Step 2: Spawn parallel deep-dive agents**
|
||||
|
||||
Use Task tool with general-purpose agents (3-5 agents) for:
|
||||
- Academic paper analysis (PDFs, detailed extraction)
|
||||
- Documentation deep dives (technical specs, API docs)
|
||||
- Repository analysis (code examples, implementations)
|
||||
- Specialized domain research (requires multi-step investigation)
|
||||
|
||||
**Example parallel execution (using WebSearch):**
|
||||
```
|
||||
[Single message with multiple tool calls]
|
||||
- WebSearch(query="quantum computing 2025 state of the art")
|
||||
- WebSearch(query="quantum computing limitations challenges")
|
||||
- WebSearch(query="quantum computing commercial applications 2024-2025")
|
||||
- WebSearch(query="quantum computing vs classical comparison")
|
||||
- WebSearch(query="quantum error correction research", allowed_domains=["arxiv.org", "scholar.google.com"])
|
||||
- Task(subagent_type="general-purpose", description="Analyze quantum computing papers", prompt="Deep dive into quantum computing academic papers from 2024-2025, extract key findings and methodologies")
|
||||
- Task(subagent_type="general-purpose", description="Industry analysis", prompt="Analyze quantum computing industry reports and market data, identify commercial applications")
|
||||
- Task(subagent_type="general-purpose", description="Technical challenges", prompt="Extract technical limitations and challenges from quantum computing research")
|
||||
```
|
||||
|
||||
**Example parallel execution (using Exa MCP - if available):**
|
||||
```
|
||||
[Single message with multiple tool calls]
|
||||
- mcp__Exa__exa_search(query="quantum computing state of the art", type="neural", num_results=10, start_published_date="2024-01-01")
|
||||
- mcp__Exa__exa_search(query="quantum computing limitations", type="keyword", num_results=10)
|
||||
- mcp__Exa__exa_search(query="quantum computing commercial", type="auto", num_results=10, start_published_date="2024-01-01")
|
||||
- mcp__Exa__exa_search(query="quantum error correction", type="neural", num_results=10, include_domains=["arxiv.org"])
|
||||
- Task(subagent_type="general-purpose", description="Academic analysis", prompt="Analyze quantum computing academic papers")
|
||||
```
|
||||
|
||||
**Step 3: Collect and organize results**
|
||||
|
||||
As results arrive:
|
||||
1. Extract key passages with source metadata (title, URL, date, credibility)
|
||||
2. Track information gaps that emerge
|
||||
3. Follow promising tangents with additional targeted searches
|
||||
4. Maintain source diversity (mix academic, industry, news, technical docs)
|
||||
5. Monitor for quality threshold (see FFS pattern below)
|
||||
|
||||
### First Finish Search (FFS) Pattern
|
||||
|
||||
**Adaptive completion based on quality threshold:**
|
||||
|
||||
**Quality gate:** Proceed to Phase 4 when FIRST threshold reached:
|
||||
- **Quick mode:** 10+ sources with avg credibility >60/100 OR 2 minutes elapsed
|
||||
- **Standard mode:** 15+ sources with avg credibility >60/100 OR 5 minutes elapsed
|
||||
- **Deep mode:** 25+ sources with avg credibility >70/100 OR 10 minutes elapsed
|
||||
- **UltraDeep mode:** 30+ sources with avg credibility >75/100 OR 15 minutes elapsed
|
||||
|
||||
**Continue background searches:**
|
||||
- If threshold reached early, continue remaining parallel searches in background
|
||||
- Additional sources used in Phase 5 (SYNTHESIZE) for depth and diversity
|
||||
- Allows fast progression without sacrificing thoroughness
|
||||
|
||||
### Quality Standards
|
||||
|
||||
**Source diversity requirements:**
|
||||
- Minimum 3 source types (academic, industry, news, technical docs)
|
||||
- Temporal diversity (mix of recent 2024-2025 + foundational older sources)
|
||||
- Perspective diversity (proponents + critics + neutral analysis)
|
||||
- Geographic diversity (not just US sources)
|
||||
|
||||
**Credibility tracking:**
|
||||
- Score each source 0-100 using source_evaluator.py
|
||||
- Flag low-credibility sources (<40) for additional verification
|
||||
- Prioritize high-credibility sources (>80) for core claims
|
||||
|
||||
**Techniques:**
|
||||
- Use WebSearch for current information (primary tool)
|
||||
- Use WebFetch for deep dives into specific sources (secondary)
|
||||
- Use Exa search (via WebSearch with type="neural") for semantic exploration
|
||||
- Use Grep/Read for local documentation
|
||||
- Execute code for computational analysis (when needed)
|
||||
- Use Task tool to spawn parallel retrieval agents (3-5 agents)
|
||||
|
||||
**Output:** Organized information repository with source tracking, credibility scores, and coverage map
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: TRIANGULATE - Cross-Reference Verification
|
||||
|
||||
**Objective:** Validate information across multiple independent sources
|
||||
|
||||
**Activities:**
|
||||
1. Identify claims requiring verification
|
||||
2. Cross-reference facts across 3+ sources
|
||||
3. Flag contradictions or uncertainties
|
||||
4. Assess source credibility
|
||||
5. Note consensus vs. debate areas
|
||||
6. Document verification status per claim
|
||||
|
||||
**Quality Standards:**
|
||||
- Core claims must have 3+ independent sources
|
||||
- Flag any single-source information
|
||||
- Note recency of information
|
||||
- Identify potential biases
|
||||
|
||||
**Output:** Verified fact base with confidence levels
|
||||
|
||||
---
|
||||
|
||||
## Phase 4.5: OUTLINE REFINEMENT - Dynamic Evolution (WebWeaver 2025)
|
||||
|
||||
**Objective:** Adapt research direction based on evidence discovered
|
||||
|
||||
**Problem Solved:** Prevents "locked-in" research when evidence points to different conclusions or uncovers more important angles than initially planned.
|
||||
|
||||
**When to Execute:**
|
||||
- **Standard/Deep/UltraDeep modes only** (Quick mode skips this)
|
||||
- After Phase 4 (TRIANGULATE) completes
|
||||
- Before Phase 5 (SYNTHESIZE)
|
||||
|
||||
**Activities:**
|
||||
|
||||
1. **Review Initial Scope vs. Actual Findings**
|
||||
- Compare Phase 1 scope with Phase 3-4 discoveries
|
||||
- Identify unexpected patterns or contradictions
|
||||
- Note underexplored angles that emerged as critical
|
||||
- Flag overexplored areas that proved less important
|
||||
|
||||
2. **Evaluate Outline Adaptation Need**
|
||||
|
||||
**Signals for adaptation (ANY triggers refinement):**
|
||||
- Major findings contradict initial assumptions
|
||||
- Evidence reveals more important angle than originally scoped
|
||||
- Critical subtopic emerged that wasn't in original plan
|
||||
- Original research question was too broad/narrow based on evidence
|
||||
- Sources consistently discuss aspects not in initial outline
|
||||
|
||||
**Signals to keep current outline:**
|
||||
- Evidence aligns with initial scope
|
||||
- All key angles adequately covered
|
||||
- No major gaps or surprises
|
||||
|
||||
3. **Refine Outline (if needed)**
|
||||
|
||||
**Update structure to reflect evidence:**
|
||||
- Add sections for unexpected but important findings
|
||||
- Demote/remove sections with insufficient evidence
|
||||
- Reorder sections based on evidence strength and importance
|
||||
- Adjust scope boundaries based on what's actually discoverable
|
||||
|
||||
**Example adaptation:**
|
||||
```
|
||||
Original outline:
|
||||
1. Introduction
|
||||
2. Technical Architecture
|
||||
3. Performance Benchmarks
|
||||
4. Conclusion
|
||||
|
||||
Refined after Phase 4 (evidence revealed security as critical):
|
||||
1. Introduction
|
||||
2. Technical Architecture
|
||||
3. **Security Vulnerabilities (NEW - major finding)**
|
||||
4. Performance Benchmarks (demoted - less critical than expected)
|
||||
5. **Real-World Failure Modes (NEW - pattern emerged)**
|
||||
6. Synthesis & Recommendations
|
||||
```
|
||||
|
||||
4. **Targeted Gap Filling (if major gaps found)**
|
||||
|
||||
If outline refinement reveals critical knowledge gaps:
|
||||
- Launch 2-3 targeted searches for newly identified angles
|
||||
- Quick retrieval only (don't restart full Phase 3)
|
||||
- Time-box to 2-5 minutes
|
||||
- Update triangulation for new evidence only
|
||||
|
||||
5. **Document Adaptation Rationale**
|
||||
|
||||
Record in methodology appendix:
|
||||
- What changed in outline
|
||||
- Why it changed (evidence-driven reasons)
|
||||
- What additional research was conducted (if any)
|
||||
|
||||
**Quality Standards:**
|
||||
- Adaptation must be evidence-driven (cite specific sources that prompted change)
|
||||
- No more than 50% outline restructuring (if more needed, scope was severely mis scoped)
|
||||
- Retain original research question core (don't drift into different topic entirely)
|
||||
- New sections must have supporting evidence already gathered
|
||||
|
||||
**Output:** Refined outline that accurately reflects evidence landscape, ready for synthesis
|
||||
|
||||
**Anti-Pattern Warning:**
|
||||
- ❌ DON'T adapt outline based on speculation or "what would be interesting"
|
||||
- ❌ DON'T add sections without supporting evidence already in hand
|
||||
- ❌ DON'T completely abandon original research question
|
||||
- ✅ DO adapt when evidence clearly indicates better structure
|
||||
- ✅ DO document rationale for changes
|
||||
- ✅ DO stay within original topic scope
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: SYNTHESIZE - Deep Analysis
|
||||
|
||||
**Objective:** Connect insights and generate novel understanding
|
||||
|
||||
**Activities:**
|
||||
1. Identify patterns across sources
|
||||
2. Map relationships between concepts
|
||||
3. Generate insights beyond source material
|
||||
4. Create conceptual frameworks
|
||||
5. Build argument structures
|
||||
6. Develop evidence hierarchies
|
||||
|
||||
**Ultrathink Integration:** Use extended reasoning to explore non-obvious connections and second-order implications.
|
||||
|
||||
**Output:** Synthesized understanding with insight generation
|
||||
|
||||
---
|
||||
|
||||
## Phase 6: CRITIQUE - Quality Assurance
|
||||
|
||||
**Objective:** Rigorously evaluate research quality
|
||||
|
||||
**Activities:**
|
||||
1. Review for logical consistency
|
||||
2. Check citation completeness
|
||||
3. Identify gaps or weaknesses
|
||||
4. Assess balance and objectivity
|
||||
5. Verify claims against sources
|
||||
6. Test alternative interpretations
|
||||
|
||||
**Red Team Questions:**
|
||||
- What's missing?
|
||||
- What could be wrong?
|
||||
- What alternative explanations exist?
|
||||
- What biases might be present?
|
||||
- What counterfactuals should be considered?
|
||||
|
||||
**Output:** Critique report with improvement recommendations
|
||||
|
||||
---
|
||||
|
||||
## Phase 7: REFINE - Iterative Improvement
|
||||
|
||||
**Objective:** Address gaps and strengthen weak areas
|
||||
|
||||
**Activities:**
|
||||
1. Conduct additional research for gaps
|
||||
2. Strengthen weak arguments
|
||||
3. Add missing perspectives
|
||||
4. Resolve contradictions
|
||||
5. Enhance clarity
|
||||
6. Verify revised content
|
||||
|
||||
**Output:** Strengthened research with addressed deficiencies
|
||||
|
||||
---
|
||||
|
||||
## Phase 8: PACKAGE - Report Generation
|
||||
|
||||
**Objective:** Deliver professional, actionable research
|
||||
|
||||
**Activities:**
|
||||
1. Structure report with clear hierarchy
|
||||
2. Write executive summary
|
||||
3. Develop detailed sections
|
||||
4. Create visualizations (tables, diagrams)
|
||||
5. Compile full bibliography
|
||||
6. Add methodology appendix
|
||||
|
||||
**Output:** Complete research report ready for use
|
||||
|
||||
---
|
||||
|
||||
## Advanced Features
|
||||
|
||||
### Graph-of-Thoughts Reasoning
|
||||
|
||||
Rather than linear thinking, branch into multiple reasoning paths:
|
||||
- Explore alternative framings in parallel
|
||||
- Pursue tangential leads that might be relevant
|
||||
- Merge insights from different branches
|
||||
- Backtrack and revise as new information emerges
|
||||
|
||||
### Parallel Agent Deployment
|
||||
|
||||
Use Task tool to spawn sub-agents for:
|
||||
- Parallel source retrieval
|
||||
- Independent verification paths
|
||||
- Competing hypothesis evaluation
|
||||
- Specialized domain analysis
|
||||
|
||||
### Adaptive Depth Control
|
||||
|
||||
Automatically adjust research depth based on:
|
||||
- Information complexity
|
||||
- Source availability
|
||||
- Time constraints
|
||||
- Confidence levels
|
||||
|
||||
### Citation Intelligence
|
||||
|
||||
Smart citation management:
|
||||
- Track provenance of every claim
|
||||
- Link to original sources
|
||||
- Assess source credibility
|
||||
- Handle conflicting sources
|
||||
- Generate proper bibliographies
|
||||
10
axhub-make/skills/third-party/deep-research/requirements.txt
vendored
Normal file
10
axhub-make/skills/third-party/deep-research/requirements.txt
vendored
Normal file
@@ -0,0 +1,10 @@
|
||||
# Deep Research Skill Dependencies
|
||||
# These are standard library modules, no external dependencies needed for core functionality
|
||||
|
||||
# Optional: For enhanced features, uncomment if needed
|
||||
# requests>=2.31.0 # For web fetching
|
||||
# beautifulsoup4>=4.12.0 # For HTML parsing
|
||||
# markdownify>=0.11.6 # For HTML to markdown conversion
|
||||
# numpy>=1.24.0 # For statistical analysis
|
||||
# pandas>=2.0.0 # For data analysis
|
||||
# networkx>=3.1 # For knowledge graph analysis
|
||||
177
axhub-make/skills/third-party/deep-research/scripts/citation_manager.py
vendored
Normal file
177
axhub-make/skills/third-party/deep-research/scripts/citation_manager.py
vendored
Normal file
@@ -0,0 +1,177 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Citation Management System
|
||||
Tracks sources, generates citations, and maintains bibliography
|
||||
"""
|
||||
|
||||
from dataclasses import dataclass, field
|
||||
from typing import List, Dict, Optional
|
||||
from datetime import datetime
|
||||
from urllib.parse import urlparse
|
||||
import hashlib
|
||||
|
||||
|
||||
@dataclass
|
||||
class Citation:
|
||||
"""Represents a single citation"""
|
||||
id: str
|
||||
title: str
|
||||
url: str
|
||||
authors: Optional[List[str]] = None
|
||||
publication_date: Optional[str] = None
|
||||
retrieved_date: str = field(default_factory=lambda: datetime.now().strftime('%Y-%m-%d'))
|
||||
source_type: str = "web" # web, academic, documentation, book, paper
|
||||
doi: Optional[str] = None
|
||||
citation_count: int = 0
|
||||
|
||||
def to_apa(self, index: int) -> str:
|
||||
"""Generate APA format citation"""
|
||||
author_str = ""
|
||||
if self.authors:
|
||||
if len(self.authors) == 1:
|
||||
author_str = f"{self.authors[0]}."
|
||||
elif len(self.authors) == 2:
|
||||
author_str = f"{self.authors[0]} & {self.authors[1]}."
|
||||
else:
|
||||
author_str = f"{self.authors[0]} et al."
|
||||
|
||||
date_str = f"({self.publication_date})" if self.publication_date else "(n.d.)"
|
||||
|
||||
return f"[{index}] {author_str} {date_str}. {self.title}. Retrieved {self.retrieved_date}, from {self.url}"
|
||||
|
||||
def to_inline(self, index: int) -> str:
|
||||
"""Generate inline citation [index]"""
|
||||
return f"[{index}]"
|
||||
|
||||
def to_markdown(self, index: int) -> str:
|
||||
"""Generate markdown link format"""
|
||||
return f"[{index}] [{self.title}]({self.url}) (Retrieved: {self.retrieved_date})"
|
||||
|
||||
|
||||
class CitationManager:
|
||||
"""Manages citations and bibliography"""
|
||||
|
||||
def __init__(self):
|
||||
self.citations: Dict[str, Citation] = {}
|
||||
self.citation_order: List[str] = []
|
||||
|
||||
def add_source(
|
||||
self,
|
||||
url: str,
|
||||
title: str,
|
||||
authors: Optional[List[str]] = None,
|
||||
publication_date: Optional[str] = None,
|
||||
source_type: str = "web",
|
||||
doi: Optional[str] = None
|
||||
) -> str:
|
||||
"""Add a source and return its citation ID"""
|
||||
# Generate unique ID based on URL
|
||||
citation_id = hashlib.md5(url.encode()).hexdigest()[:8]
|
||||
|
||||
if citation_id not in self.citations:
|
||||
citation = Citation(
|
||||
id=citation_id,
|
||||
title=title,
|
||||
url=url,
|
||||
authors=authors,
|
||||
publication_date=publication_date,
|
||||
source_type=source_type,
|
||||
doi=doi
|
||||
)
|
||||
self.citations[citation_id] = citation
|
||||
self.citation_order.append(citation_id)
|
||||
|
||||
# Increment citation count
|
||||
self.citations[citation_id].citation_count += 1
|
||||
|
||||
return citation_id
|
||||
|
||||
def get_citation_number(self, citation_id: str) -> Optional[int]:
|
||||
"""Get the citation number for a given ID"""
|
||||
try:
|
||||
return self.citation_order.index(citation_id) + 1
|
||||
except ValueError:
|
||||
return None
|
||||
|
||||
def get_inline_citation(self, citation_id: str) -> str:
|
||||
"""Get inline citation marker [n]"""
|
||||
num = self.get_citation_number(citation_id)
|
||||
return f"[{num}]" if num else "[?]"
|
||||
|
||||
def generate_bibliography(self, style: str = "markdown") -> str:
|
||||
"""Generate full bibliography"""
|
||||
if style == "markdown":
|
||||
lines = ["## Bibliography\n"]
|
||||
for i, citation_id in enumerate(self.citation_order, 1):
|
||||
citation = self.citations[citation_id]
|
||||
lines.append(citation.to_markdown(i))
|
||||
return "\n".join(lines)
|
||||
|
||||
elif style == "apa":
|
||||
lines = ["## Bibliography\n"]
|
||||
for i, citation_id in enumerate(self.citation_order, 1):
|
||||
citation = self.citations[citation_id]
|
||||
lines.append(citation.to_apa(i))
|
||||
return "\n".join(lines)
|
||||
|
||||
return "Unsupported citation style"
|
||||
|
||||
def get_statistics(self) -> Dict[str, any]:
|
||||
"""Get citation statistics"""
|
||||
return {
|
||||
'total_sources': len(self.citations),
|
||||
'total_citations': sum(c.citation_count for c in self.citations.values()),
|
||||
'source_types': self._count_by_type(),
|
||||
'most_cited': self._get_most_cited(5),
|
||||
'uncited': self._get_uncited()
|
||||
}
|
||||
|
||||
def _count_by_type(self) -> Dict[str, int]:
|
||||
"""Count sources by type"""
|
||||
counts = {}
|
||||
for citation in self.citations.values():
|
||||
counts[citation.source_type] = counts.get(citation.source_type, 0) + 1
|
||||
return counts
|
||||
|
||||
def _get_most_cited(self, n: int = 5) -> List[tuple]:
|
||||
"""Get most cited sources"""
|
||||
sorted_citations = sorted(
|
||||
self.citations.items(),
|
||||
key=lambda x: x[1].citation_count,
|
||||
reverse=True
|
||||
)
|
||||
return [(self.get_citation_number(cid), c.title, c.citation_count)
|
||||
for cid, c in sorted_citations[:n]]
|
||||
|
||||
def _get_uncited(self) -> List[str]:
|
||||
"""Get sources that were added but never cited"""
|
||||
return [c.title for c in self.citations.values() if c.citation_count == 0]
|
||||
|
||||
def export_to_file(self, filepath: str, style: str = "markdown"):
|
||||
"""Export bibliography to file"""
|
||||
with open(filepath, 'w') as f:
|
||||
f.write(self.generate_bibliography(style))
|
||||
|
||||
|
||||
# Example usage
|
||||
if __name__ == '__main__':
|
||||
manager = CitationManager()
|
||||
|
||||
# Add sources
|
||||
id1 = manager.add_source(
|
||||
url="https://example.com/article1",
|
||||
title="Understanding Deep Research",
|
||||
authors=["Smith, J.", "Johnson, K."],
|
||||
publication_date="2025"
|
||||
)
|
||||
|
||||
id2 = manager.add_source(
|
||||
url="https://example.com/article2",
|
||||
title="AI Research Methods",
|
||||
source_type="academic"
|
||||
)
|
||||
|
||||
# Use citations
|
||||
print(f"Inline citation: {manager.get_inline_citation(id1)}")
|
||||
print(f"\nBibliography:\n{manager.generate_bibliography()}")
|
||||
print(f"\nStatistics:\n{manager.get_statistics()}")
|
||||
330
axhub-make/skills/third-party/deep-research/scripts/md_to_html.py
vendored
Normal file
330
axhub-make/skills/third-party/deep-research/scripts/md_to_html.py
vendored
Normal file
@@ -0,0 +1,330 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Markdown to HTML converter for research reports
|
||||
Properly converts markdown sections to HTML while preserving structure and formatting
|
||||
"""
|
||||
|
||||
import re
|
||||
from typing import Tuple
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def convert_markdown_to_html(markdown_text: str) -> Tuple[str, str]:
|
||||
"""
|
||||
Convert markdown to HTML in two parts: content and bibliography
|
||||
|
||||
Args:
|
||||
markdown_text: Full markdown report text
|
||||
|
||||
Returns:
|
||||
Tuple of (content_html, bibliography_html)
|
||||
"""
|
||||
# Split content and bibliography
|
||||
parts = markdown_text.split('## Bibliography')
|
||||
content_md = parts[0]
|
||||
bibliography_md = parts[1] if len(parts) > 1 else ""
|
||||
|
||||
# Convert content (everything except bibliography)
|
||||
content_html = _convert_content_section(content_md)
|
||||
|
||||
# Convert bibliography separately
|
||||
bibliography_html = _convert_bibliography_section(bibliography_md)
|
||||
|
||||
return content_html, bibliography_html
|
||||
|
||||
|
||||
def _convert_content_section(markdown: str) -> str:
|
||||
"""Convert main content sections to HTML"""
|
||||
html = markdown
|
||||
|
||||
# Remove title and front matter (first ## heading is handled separately)
|
||||
lines = html.split('\n')
|
||||
processed_lines = []
|
||||
skip_until_first_section = True
|
||||
|
||||
for line in lines:
|
||||
# Skip everything until we hit "## Executive Summary" or first major section
|
||||
if skip_until_first_section:
|
||||
if line.startswith('## ') and not line.startswith('### '):
|
||||
skip_until_first_section = False
|
||||
processed_lines.append(line)
|
||||
continue
|
||||
processed_lines.append(line)
|
||||
|
||||
html = '\n'.join(processed_lines)
|
||||
|
||||
# Convert headers
|
||||
# ## Section Title → <div class="section"><h2 class="section-title">Section Title</h2></div>
|
||||
html = re.sub(
|
||||
r'^## (.+)$',
|
||||
r'<div class="section"><h2 class="section-title">\1</h2>',
|
||||
html,
|
||||
flags=re.MULTILINE
|
||||
)
|
||||
|
||||
# ### Subsection → <h3 class="subsection-title">Subsection</h3>
|
||||
html = re.sub(
|
||||
r'^### (.+)$',
|
||||
r'<h3 class="subsection-title">\1</h3>',
|
||||
html,
|
||||
flags=re.MULTILINE
|
||||
)
|
||||
|
||||
# #### Subsubsection → <h4 class="subsubsection-title">Title</h4>
|
||||
html = re.sub(
|
||||
r'^#### (.+)$',
|
||||
r'<h4 class="subsubsection-title">\1</h4>',
|
||||
html,
|
||||
flags=re.MULTILINE
|
||||
)
|
||||
|
||||
# Convert **bold** text
|
||||
html = re.sub(r'\*\*(.+?)\*\*', r'<strong>\1</strong>', html)
|
||||
|
||||
# Convert *italic* text
|
||||
html = re.sub(r'\*(.+?)\*', r'<em>\1</em>', html)
|
||||
|
||||
# Convert inline code `code`
|
||||
html = re.sub(r'`(.+?)`', r'<code>\1</code>', html)
|
||||
|
||||
# Convert unordered lists
|
||||
html = _convert_lists(html)
|
||||
|
||||
# Convert tables
|
||||
html = _convert_tables(html)
|
||||
|
||||
# Convert paragraphs (wrap non-HTML lines in <p> tags)
|
||||
html = _convert_paragraphs(html)
|
||||
|
||||
# Close all open sections
|
||||
html = _close_sections(html)
|
||||
|
||||
# Wrap executive summary if present
|
||||
html = html.replace(
|
||||
'<h2 class="section-title">Executive Summary</h2>',
|
||||
'<div class="executive-summary"><h2 class="section-title">Executive Summary</h2>'
|
||||
)
|
||||
if '<div class="executive-summary">' in html:
|
||||
# Close executive summary at the next section
|
||||
html = html.replace(
|
||||
'</h2>\n<div class="section">',
|
||||
'</h2></div>\n<div class="section">',
|
||||
1
|
||||
)
|
||||
|
||||
return html
|
||||
|
||||
|
||||
def _convert_bibliography_section(markdown: str) -> str:
|
||||
"""Convert bibliography section to HTML"""
|
||||
if not markdown.strip():
|
||||
return ""
|
||||
|
||||
html = markdown
|
||||
|
||||
# Convert each [N] citation to a proper bibliography entry
|
||||
# Look for patterns like [1] Title - URL
|
||||
html = re.sub(
|
||||
r'\[(\d+)\]\s*(.+?)\s*-\s*(https?://[^\s\)]+)',
|
||||
r'<div class="bib-entry"><span class="bib-number">[\1]</span> <a href="\3" target="_blank">\2</a></div>',
|
||||
html
|
||||
)
|
||||
|
||||
# Convert any remaining **bold** sections
|
||||
html = re.sub(r'\*\*(.+?)\*\*', r'<strong>\1</strong>', html)
|
||||
|
||||
# Wrap in bibliography content div
|
||||
html = f'<div class="bibliography-content">{html}</div>'
|
||||
|
||||
return html
|
||||
|
||||
|
||||
def _convert_lists(html: str) -> str:
|
||||
"""Convert markdown lists to HTML lists"""
|
||||
lines = html.split('\n')
|
||||
result = []
|
||||
in_list = False
|
||||
list_level = 0
|
||||
|
||||
for i, line in enumerate(lines):
|
||||
stripped = line.strip()
|
||||
|
||||
# Check for unordered list item
|
||||
if stripped.startswith('- ') or stripped.startswith('* '):
|
||||
if not in_list:
|
||||
result.append('<ul>')
|
||||
in_list = True
|
||||
list_level = len(line) - len(line.lstrip())
|
||||
|
||||
# Get the content after the marker
|
||||
content = stripped[2:]
|
||||
result.append(f'<li>{content}</li>')
|
||||
|
||||
# Check for ordered list item
|
||||
elif re.match(r'^\d+\.\s', stripped):
|
||||
if not in_list:
|
||||
result.append('<ol>')
|
||||
in_list = True
|
||||
list_level = len(line) - len(line.lstrip())
|
||||
|
||||
# Get the content after the number and period
|
||||
content = re.sub(r'^\d+\.\s', '', stripped)
|
||||
result.append(f'<li>{content}</li>')
|
||||
|
||||
else:
|
||||
# Not a list item
|
||||
if in_list:
|
||||
# Check if we're still in the list (indented continuation)
|
||||
current_level = len(line) - len(line.lstrip())
|
||||
if current_level > list_level and stripped:
|
||||
# Continuation of previous list item
|
||||
if result[-1].endswith('</li>'):
|
||||
result[-1] = result[-1][:-5] + ' ' + stripped + '</li>'
|
||||
continue
|
||||
else:
|
||||
# End of list
|
||||
result.append('</ul>' if '<ul>' in '\n'.join(result[-10:]) else '</ol>')
|
||||
in_list = False
|
||||
list_level = 0
|
||||
|
||||
result.append(line)
|
||||
|
||||
# Close any remaining open list
|
||||
if in_list:
|
||||
result.append('</ul>' if '<ul>' in '\n'.join(result[-10:]) else '</ol>')
|
||||
|
||||
return '\n'.join(result)
|
||||
|
||||
|
||||
def _convert_tables(html: str) -> str:
|
||||
"""Convert markdown tables to HTML tables"""
|
||||
lines = html.split('\n')
|
||||
result = []
|
||||
in_table = False
|
||||
|
||||
for i, line in enumerate(lines):
|
||||
if '|' in line and line.strip().startswith('|'):
|
||||
if not in_table:
|
||||
result.append('<table>')
|
||||
in_table = True
|
||||
# This is the header row
|
||||
cells = [cell.strip() for cell in line.split('|')[1:-1]]
|
||||
result.append('<thead><tr>')
|
||||
for cell in cells:
|
||||
result.append(f'<th>{cell}</th>')
|
||||
result.append('</tr></thead>')
|
||||
result.append('<tbody>')
|
||||
elif '---' in line:
|
||||
# Skip separator row
|
||||
continue
|
||||
else:
|
||||
# Data row
|
||||
cells = [cell.strip() for cell in line.split('|')[1:-1]]
|
||||
result.append('<tr>')
|
||||
for cell in cells:
|
||||
result.append(f'<td>{cell}</td>')
|
||||
result.append('</tr>')
|
||||
else:
|
||||
if in_table:
|
||||
result.append('</tbody></table>')
|
||||
in_table = False
|
||||
result.append(line)
|
||||
|
||||
if in_table:
|
||||
result.append('</tbody></table>')
|
||||
|
||||
return '\n'.join(result)
|
||||
|
||||
|
||||
def _convert_paragraphs(html: str) -> str:
|
||||
"""Wrap non-HTML lines in paragraph tags"""
|
||||
lines = html.split('\n')
|
||||
result = []
|
||||
in_paragraph = False
|
||||
|
||||
for line in lines:
|
||||
stripped = line.strip()
|
||||
|
||||
# Skip empty lines
|
||||
if not stripped:
|
||||
if in_paragraph:
|
||||
result.append('</p>')
|
||||
in_paragraph = False
|
||||
result.append(line)
|
||||
continue
|
||||
|
||||
# Skip lines that are already HTML tags
|
||||
if (stripped.startswith('<') and stripped.endswith('>')) or \
|
||||
stripped.startswith('</') or \
|
||||
'<h' in stripped or '<div' in stripped or '<ul' in stripped or \
|
||||
'<ol' in stripped or '<li' in stripped or '<table' in stripped or \
|
||||
'</div>' in stripped or '</ul>' in stripped or '</ol>' in stripped:
|
||||
if in_paragraph:
|
||||
result.append('</p>')
|
||||
in_paragraph = False
|
||||
result.append(line)
|
||||
continue
|
||||
|
||||
# Regular text line - wrap in paragraph
|
||||
if not in_paragraph:
|
||||
result.append('<p>' + line)
|
||||
in_paragraph = True
|
||||
else:
|
||||
result.append(line)
|
||||
|
||||
if in_paragraph:
|
||||
result.append('</p>')
|
||||
|
||||
return '\n'.join(result)
|
||||
|
||||
|
||||
def _close_sections(html: str) -> str:
|
||||
"""Close all open section divs"""
|
||||
# Count open and closed divs
|
||||
open_divs = html.count('<div class="section">')
|
||||
closed_divs = html.count('</div>')
|
||||
|
||||
# Add closing divs for sections
|
||||
# Each section should be closed before the next section starts
|
||||
lines = html.split('\n')
|
||||
result = []
|
||||
section_open = False
|
||||
|
||||
for i, line in enumerate(lines):
|
||||
if '<div class="section">' in line:
|
||||
if section_open:
|
||||
result.append('</div>') # Close previous section
|
||||
section_open = True
|
||||
result.append(line)
|
||||
|
||||
# Close final section if still open
|
||||
if section_open:
|
||||
result.append('</div>')
|
||||
|
||||
return '\n'.join(result)
|
||||
|
||||
|
||||
def main():
|
||||
"""Test the converter with a sample markdown file"""
|
||||
import sys
|
||||
|
||||
if len(sys.argv) < 2:
|
||||
print("Usage: python md_to_html.py <markdown_file>")
|
||||
sys.exit(1)
|
||||
|
||||
md_file = Path(sys.argv[1])
|
||||
if not md_file.exists():
|
||||
print(f"Error: File {md_file} not found")
|
||||
sys.exit(1)
|
||||
|
||||
markdown_text = md_file.read_text()
|
||||
content_html, bib_html = convert_markdown_to_html(markdown_text)
|
||||
|
||||
print("=== CONTENT HTML ===")
|
||||
print(content_html[:1000])
|
||||
print("\n=== BIBLIOGRAPHY HTML ===")
|
||||
print(bib_html[:500])
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
578
axhub-make/skills/third-party/deep-research/scripts/research_engine.py
vendored
Normal file
578
axhub-make/skills/third-party/deep-research/scripts/research_engine.py
vendored
Normal file
@@ -0,0 +1,578 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Deep Research Engine for Claude Code
|
||||
Orchestrates comprehensive research across multiple sources with verification and synthesis
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import json
|
||||
import sys
|
||||
import time
|
||||
from datetime import datetime
|
||||
from pathlib import Path
|
||||
from typing import Dict, List, Optional, Any
|
||||
from dataclasses import dataclass, asdict
|
||||
from enum import Enum
|
||||
|
||||
|
||||
class ResearchPhase(Enum):
|
||||
"""Research pipeline phases"""
|
||||
SCOPE = "scope"
|
||||
PLAN = "plan"
|
||||
RETRIEVE = "retrieve"
|
||||
TRIANGULATE = "triangulate"
|
||||
SYNTHESIZE = "synthesize"
|
||||
CRITIQUE = "critique"
|
||||
REFINE = "refine"
|
||||
PACKAGE = "package"
|
||||
|
||||
|
||||
class ResearchMode(Enum):
|
||||
"""Research depth modes"""
|
||||
QUICK = "quick" # 3 phases: scope, retrieve, package
|
||||
STANDARD = "standard" # 6 phases: skip refine and critique
|
||||
DEEP = "deep" # Full 8 phases
|
||||
ULTRADEEP = "ultradeep" # 8 phases + extended iterations
|
||||
|
||||
|
||||
@dataclass
|
||||
class Source:
|
||||
"""Represents a research source"""
|
||||
url: str
|
||||
title: str
|
||||
snippet: str
|
||||
retrieved_at: str
|
||||
credibility_score: float = 0.0
|
||||
source_type: str = "web" # web, academic, documentation, code
|
||||
verification_status: str = "unverified" # unverified, verified, conflicted
|
||||
|
||||
def to_citation(self, index: int) -> str:
|
||||
"""Generate citation string"""
|
||||
return f"[{index}] {self.title} - {self.url} (Retrieved: {self.retrieved_at})"
|
||||
|
||||
|
||||
@dataclass
|
||||
class ResearchState:
|
||||
"""Maintains research state across phases"""
|
||||
query: str
|
||||
mode: ResearchMode
|
||||
phase: ResearchPhase
|
||||
scope: Dict[str, Any]
|
||||
plan: Dict[str, Any]
|
||||
sources: List[Source]
|
||||
findings: List[Dict[str, Any]]
|
||||
synthesis: Dict[str, Any]
|
||||
critique: Dict[str, Any]
|
||||
report: str
|
||||
metadata: Dict[str, Any]
|
||||
|
||||
def save(self, filepath: Path):
|
||||
"""Save research state to file with retry logic"""
|
||||
max_retries = 3
|
||||
for attempt in range(max_retries):
|
||||
try:
|
||||
with open(filepath, 'w') as f:
|
||||
json.dump(self._serialize(), f, indent=2)
|
||||
return # Success
|
||||
except (IOError, OSError) as e:
|
||||
if attempt == max_retries - 1:
|
||||
# Final attempt failed
|
||||
raise IOError(f"Failed to save state after {max_retries} attempts: {e}")
|
||||
# Wait with exponential backoff before retry
|
||||
wait_time = (attempt + 1) * 0.5 # 0.5s, 1s, 1.5s
|
||||
time.sleep(wait_time)
|
||||
|
||||
def _serialize(self) -> dict:
|
||||
"""Convert to serializable dict"""
|
||||
return {
|
||||
'query': self.query,
|
||||
'mode': self.mode.value,
|
||||
'phase': self.phase.value,
|
||||
'scope': self.scope,
|
||||
'plan': self.plan,
|
||||
'sources': [asdict(s) for s in self.sources],
|
||||
'findings': self.findings,
|
||||
'synthesis': self.synthesis,
|
||||
'critique': self.critique,
|
||||
'report': self.report,
|
||||
'metadata': self.metadata
|
||||
}
|
||||
|
||||
@classmethod
|
||||
def load(cls, filepath: Path) -> 'ResearchState':
|
||||
"""Load research state from file"""
|
||||
with open(filepath, 'r') as f:
|
||||
data = json.load(f)
|
||||
|
||||
return cls(
|
||||
query=data['query'],
|
||||
mode=ResearchMode(data['mode']),
|
||||
phase=ResearchPhase(data['phase']),
|
||||
scope=data['scope'],
|
||||
plan=data['plan'],
|
||||
sources=[Source(**s) for s in data['sources']],
|
||||
findings=data['findings'],
|
||||
synthesis=data['synthesis'],
|
||||
critique=data['critique'],
|
||||
report=data['report'],
|
||||
metadata=data['metadata']
|
||||
)
|
||||
|
||||
|
||||
class ResearchEngine:
|
||||
"""Main research orchestration engine"""
|
||||
|
||||
def __init__(self, mode: ResearchMode = ResearchMode.STANDARD):
|
||||
self.mode = mode
|
||||
self.state: Optional[ResearchState] = None
|
||||
self.output_dir = Path.home() / ".claude" / "research_output"
|
||||
self.output_dir.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
def initialize_research(self, query: str) -> ResearchState:
|
||||
"""Initialize new research session"""
|
||||
self.state = ResearchState(
|
||||
query=query,
|
||||
mode=self.mode,
|
||||
phase=ResearchPhase.SCOPE,
|
||||
scope={},
|
||||
plan={},
|
||||
sources=[],
|
||||
findings=[],
|
||||
synthesis={},
|
||||
critique={},
|
||||
report="",
|
||||
metadata={
|
||||
'started_at': datetime.now().isoformat(),
|
||||
'version': '1.0'
|
||||
}
|
||||
)
|
||||
return self.state
|
||||
|
||||
def get_phase_instructions(self, phase: ResearchPhase) -> str:
|
||||
"""Get instructions for current phase"""
|
||||
instructions = {
|
||||
ResearchPhase.SCOPE: """
|
||||
# Phase 1: SCOPE
|
||||
|
||||
Your task: Define research boundaries and success criteria
|
||||
|
||||
## Execute:
|
||||
1. Decompose the question into 3-5 core components
|
||||
2. Identify 2-4 key stakeholder perspectives
|
||||
3. Define what's IN scope and what's OUT of scope
|
||||
4. List 3-5 success criteria for this research
|
||||
5. Document 3-5 assumptions that need validation
|
||||
|
||||
## Output Format:
|
||||
```json
|
||||
{
|
||||
"core_components": ["component1", "component2", ...],
|
||||
"stakeholder_perspectives": ["perspective1", "perspective2", ...],
|
||||
"in_scope": ["item1", "item2", ...],
|
||||
"out_of_scope": ["item1", "item2", ...],
|
||||
"success_criteria": ["criteria1", "criteria2", ...],
|
||||
"assumptions": ["assumption1", "assumption2", ...]
|
||||
}
|
||||
```
|
||||
|
||||
Use extended reasoning to explore multiple framings before finalizing scope.
|
||||
""",
|
||||
ResearchPhase.PLAN: """
|
||||
# Phase 2: PLAN
|
||||
|
||||
Your task: Create intelligent research roadmap
|
||||
|
||||
## Execute:
|
||||
1. Identify 5-10 primary sources to investigate
|
||||
2. List 5-10 secondary/backup sources
|
||||
3. Map knowledge dependencies (what must be understood first)
|
||||
4. Create 10-15 search query variations
|
||||
5. Plan triangulation approach (how to verify claims)
|
||||
6. Define 3-5 quality gates
|
||||
|
||||
## Output Format:
|
||||
```json
|
||||
{
|
||||
"primary_sources": ["source_type1", "source_type2", ...],
|
||||
"secondary_sources": ["source_type1", "source_type2", ...],
|
||||
"knowledge_dependencies": {"concept1": ["prerequisite1", "prerequisite2"], ...},
|
||||
"search_queries": ["query1", "query2", ...],
|
||||
"triangulation_strategy": "description of verification approach",
|
||||
"quality_gates": ["gate1", "gate2", ...]
|
||||
}
|
||||
```
|
||||
|
||||
Use Graph-of-Thoughts: branch into 3-4 potential research paths, evaluate, then converge on optimal strategy.
|
||||
""",
|
||||
ResearchPhase.RETRIEVE: """
|
||||
# Phase 3: RETRIEVE
|
||||
|
||||
Your task: Systematically collect information from multiple sources
|
||||
|
||||
## Execute:
|
||||
1. Use WebSearch with iterative query refinement (minimum 10 searches)
|
||||
2. Use WebFetch to deep-dive into 5-10 most promising sources
|
||||
3. Extract key passages with metadata
|
||||
4. Track information gaps
|
||||
5. Follow 2-3 promising tangents
|
||||
6. Ensure source diversity (different domains, perspectives)
|
||||
|
||||
## Tools to Use:
|
||||
- WebSearch: For current information and broad coverage
|
||||
- WebFetch: For detailed extraction from specific URLs
|
||||
- Grep/Read: For local documentation if relevant
|
||||
- Task: Spawn 2-3 parallel retrieval agents for efficiency
|
||||
|
||||
## Output:
|
||||
Store all sources with metadata. Each source should include:
|
||||
- URL/location
|
||||
- Title
|
||||
- Key excerpts
|
||||
- Relevance score
|
||||
- Source type
|
||||
- Retrieved timestamp
|
||||
|
||||
Aim for 15-30 distinct sources minimum.
|
||||
""",
|
||||
ResearchPhase.TRIANGULATE: """
|
||||
# Phase 4: TRIANGULATE
|
||||
|
||||
Your task: Validate information across multiple independent sources
|
||||
|
||||
## Execute:
|
||||
1. List all major claims from retrieved information
|
||||
2. For each claim, find 3+ independent confirmatory sources
|
||||
3. Flag any contradictions or uncertainties
|
||||
4. Assess source credibility (domain expertise, recency, bias)
|
||||
5. Document consensus areas vs. debate areas
|
||||
6. Mark verification status for each claim
|
||||
|
||||
## Quality Standards:
|
||||
- Core claims MUST have 3+ independent sources
|
||||
- Flag any single-source claims as "unverified"
|
||||
- Note information recency
|
||||
- Identify potential biases
|
||||
|
||||
## Output Format:
|
||||
```json
|
||||
{
|
||||
"verified_claims": [
|
||||
{
|
||||
"claim": "statement",
|
||||
"sources": ["source1", "source2", "source3"],
|
||||
"confidence": "high|medium|low"
|
||||
}
|
||||
],
|
||||
"unverified_claims": [...],
|
||||
"contradictions": [
|
||||
{
|
||||
"topic": "what's contradicted",
|
||||
"viewpoint1": {"claim": "...", "sources": [...]},
|
||||
"viewpoint2": {"claim": "...", "sources": [...]}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
""",
|
||||
ResearchPhase.SYNTHESIZE: """
|
||||
# Phase 5: SYNTHESIZE
|
||||
|
||||
Your task: Connect insights and generate novel understanding
|
||||
|
||||
## Execute:
|
||||
1. Identify 5-10 key patterns across sources
|
||||
2. Map relationships between concepts
|
||||
3. Generate 3-5 insights that go beyond source material
|
||||
4. Create conceptual frameworks or mental models
|
||||
5. Build argument structures
|
||||
6. Develop evidence hierarchies
|
||||
|
||||
## Use Extended Reasoning:
|
||||
- Explore non-obvious connections
|
||||
- Consider second-order implications
|
||||
- Think about what sources might be missing
|
||||
- Generate novel hypotheses
|
||||
|
||||
## Output Format:
|
||||
```json
|
||||
{
|
||||
"patterns": ["pattern1", "pattern2", ...],
|
||||
"concept_relationships": {"concept1": ["related_to1", "related_to2"], ...},
|
||||
"novel_insights": ["insight1", "insight2", ...],
|
||||
"frameworks": ["framework_description1", ...],
|
||||
"key_arguments": [
|
||||
{
|
||||
"argument": "main claim",
|
||||
"supporting_evidence": ["evidence1", "evidence2"],
|
||||
"strength": "strong|moderate|weak"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
""",
|
||||
ResearchPhase.CRITIQUE: """
|
||||
# Phase 6: CRITIQUE
|
||||
|
||||
Your task: Rigorously evaluate research quality
|
||||
|
||||
## Execute Red Team Analysis:
|
||||
1. Check logical consistency
|
||||
2. Verify citation completeness
|
||||
3. Identify gaps or weaknesses
|
||||
4. Assess balance and objectivity
|
||||
5. Test alternative interpretations
|
||||
6. Challenge assumptions
|
||||
|
||||
## Red Team Questions:
|
||||
- What's missing from this research?
|
||||
- What could be wrong?
|
||||
- What alternative explanations exist?
|
||||
- What biases might be present?
|
||||
- What counterfactuals should be considered?
|
||||
- What would a skeptic say?
|
||||
|
||||
## Output Format:
|
||||
```json
|
||||
{
|
||||
"strengths": ["strength1", "strength2", ...],
|
||||
"weaknesses": ["weakness1", "weakness2", ...],
|
||||
"gaps": ["gap1", "gap2", ...],
|
||||
"biases": ["bias1", "bias2", ...],
|
||||
"improvements_needed": [
|
||||
{
|
||||
"issue": "description",
|
||||
"recommendation": "how to fix",
|
||||
"priority": "high|medium|low"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
""",
|
||||
ResearchPhase.REFINE: """
|
||||
# Phase 7: REFINE
|
||||
|
||||
Your task: Address gaps and strengthen weak areas
|
||||
|
||||
## Execute:
|
||||
1. Conduct additional research for identified gaps
|
||||
2. Strengthen weak arguments with more evidence
|
||||
3. Add missing perspectives
|
||||
4. Resolve contradictions where possible
|
||||
5. Enhance clarity and structure
|
||||
6. Verify all revised content
|
||||
|
||||
## Focus On:
|
||||
- High priority improvements from critique
|
||||
- Missing stakeholder perspectives
|
||||
- Weak evidence chains
|
||||
- Unclear explanations
|
||||
|
||||
## Output:
|
||||
Updated findings, sources, and synthesis with improvements documented.
|
||||
""",
|
||||
ResearchPhase.PACKAGE: """
|
||||
# Phase 8: PACKAGE
|
||||
|
||||
Your task: Deliver professional, actionable research report
|
||||
|
||||
## Generate Complete Report:
|
||||
|
||||
```markdown
|
||||
# Research Report: [Topic]
|
||||
|
||||
## Executive Summary
|
||||
[3-5 key findings bullets]
|
||||
[Primary recommendation]
|
||||
[Confidence level: High/Medium/Low]
|
||||
|
||||
## Introduction
|
||||
### Research Question
|
||||
[Original question]
|
||||
|
||||
### Scope & Methodology
|
||||
[What was investigated and how]
|
||||
|
||||
### Key Assumptions
|
||||
[Important assumptions made]
|
||||
|
||||
## Main Analysis
|
||||
|
||||
### Finding 1: [Title]
|
||||
[Detailed explanation with evidence]
|
||||
[Citations: [1], [2], [3]]
|
||||
|
||||
### Finding 2: [Title]
|
||||
[Detailed explanation with evidence]
|
||||
[Citations: [4], [5], [6]]
|
||||
|
||||
[Continue for all findings...]
|
||||
|
||||
## Synthesis & Insights
|
||||
[Patterns and connections]
|
||||
[Novel insights]
|
||||
[Implications]
|
||||
|
||||
## Limitations & Caveats
|
||||
[Known gaps]
|
||||
[Assumptions]
|
||||
[Areas of uncertainty]
|
||||
|
||||
## Recommendations
|
||||
[Action items]
|
||||
[Next steps]
|
||||
[Further research needs]
|
||||
|
||||
## Bibliography
|
||||
[1] Source 1 full citation
|
||||
[2] Source 2 full citation
|
||||
...
|
||||
|
||||
## Appendix: Methodology
|
||||
[Research process]
|
||||
[Sources consulted]
|
||||
[Verification approach]
|
||||
```
|
||||
|
||||
Save report to file with timestamp.
|
||||
"""
|
||||
}
|
||||
|
||||
return instructions.get(phase, "No instructions available for this phase")
|
||||
|
||||
def execute_phase(self, phase: ResearchPhase) -> Dict[str, Any]:
|
||||
"""Execute a research phase"""
|
||||
print(f"\n{'='*80}")
|
||||
print(f"PHASE {phase.value.upper()}: Starting...")
|
||||
print(f"{'='*80}\n")
|
||||
|
||||
instructions = self.get_phase_instructions(phase)
|
||||
print(instructions)
|
||||
|
||||
# In real usage, Claude will execute these instructions
|
||||
# This returns a structured result that Claude should populate
|
||||
result = {
|
||||
'phase': phase.value,
|
||||
'status': 'instructions_displayed',
|
||||
'timestamp': datetime.now().isoformat()
|
||||
}
|
||||
|
||||
return result
|
||||
|
||||
def run_pipeline(self, query: str) -> str:
|
||||
"""Run complete research pipeline"""
|
||||
print(f"\n{'#'*80}")
|
||||
print(f"# DEEP RESEARCH ENGINE")
|
||||
print(f"# Query: {query}")
|
||||
print(f"# Mode: {self.mode.value}")
|
||||
print(f"{'#'*80}\n")
|
||||
|
||||
# Initialize research
|
||||
self.initialize_research(query)
|
||||
|
||||
# Determine phases based on mode
|
||||
phases = self._get_phases_for_mode()
|
||||
|
||||
# Execute each phase
|
||||
for phase in phases:
|
||||
self.state.phase = phase
|
||||
result = self.execute_phase(phase)
|
||||
|
||||
# Save state after each phase
|
||||
state_file = self.output_dir / f"research_state_{datetime.now().strftime('%Y%m%d_%H%M%S')}.json"
|
||||
self.state.save(state_file)
|
||||
print(f"\n✓ Phase {phase.value} complete. State saved to: {state_file}\n")
|
||||
|
||||
# Generate report path
|
||||
report_file = self.output_dir / f"research_report_{datetime.now().strftime('%Y%m%d_%H%M%S')}.md"
|
||||
|
||||
print(f"\n{'='*80}")
|
||||
print(f"RESEARCH PIPELINE COMPLETE")
|
||||
print(f"Report will be saved to: {report_file}")
|
||||
print(f"{'='*80}\n")
|
||||
|
||||
return str(report_file)
|
||||
|
||||
def _get_phases_for_mode(self) -> List[ResearchPhase]:
|
||||
"""Get phases based on research mode"""
|
||||
if self.mode == ResearchMode.QUICK:
|
||||
return [
|
||||
ResearchPhase.SCOPE,
|
||||
ResearchPhase.RETRIEVE,
|
||||
ResearchPhase.PACKAGE
|
||||
]
|
||||
elif self.mode == ResearchMode.STANDARD:
|
||||
return [
|
||||
ResearchPhase.SCOPE,
|
||||
ResearchPhase.PLAN,
|
||||
ResearchPhase.RETRIEVE,
|
||||
ResearchPhase.TRIANGULATE,
|
||||
ResearchPhase.SYNTHESIZE,
|
||||
ResearchPhase.PACKAGE
|
||||
]
|
||||
elif self.mode == ResearchMode.DEEP:
|
||||
return list(ResearchPhase)
|
||||
elif self.mode == ResearchMode.ULTRADEEP:
|
||||
# In ultradeep, we might iterate some phases
|
||||
return list(ResearchPhase)
|
||||
|
||||
return list(ResearchPhase)
|
||||
|
||||
|
||||
def main():
|
||||
"""CLI entry point"""
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Deep Research Engine for Claude Code",
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
epilog="""
|
||||
Examples:
|
||||
python research_engine.py --query "state of quantum computing 2025" --mode deep
|
||||
python research_engine.py --query "PostgreSQL vs Supabase comparison" --mode standard
|
||||
python research_engine.py -q "longevity biotech funding trends" -m ultradeep
|
||||
"""
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--query', '-q',
|
||||
type=str,
|
||||
required=True,
|
||||
help='Research question or topic'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--mode', '-m',
|
||||
type=str,
|
||||
choices=['quick', 'standard', 'deep', 'ultradeep'],
|
||||
default='standard',
|
||||
help='Research depth mode (default: standard)'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--resume',
|
||||
type=str,
|
||||
help='Resume from saved state file'
|
||||
)
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
# Initialize engine
|
||||
mode = ResearchMode(args.mode)
|
||||
engine = ResearchEngine(mode=mode)
|
||||
|
||||
if args.resume:
|
||||
# Load previous state
|
||||
state_file = Path(args.resume)
|
||||
if not state_file.exists():
|
||||
print(f"Error: State file not found: {state_file}", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
engine.state = ResearchState.load(state_file)
|
||||
print(f"Resumed research from: {state_file}")
|
||||
|
||||
# Run pipeline
|
||||
report_path = engine.run_pipeline(args.query)
|
||||
|
||||
print(f"\nResearch complete! Report path: {report_path}")
|
||||
print(f"\nNow Claude should execute each phase using the displayed instructions.")
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
292
axhub-make/skills/third-party/deep-research/scripts/source_evaluator.py
vendored
Normal file
292
axhub-make/skills/third-party/deep-research/scripts/source_evaluator.py
vendored
Normal file
@@ -0,0 +1,292 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Source Credibility Evaluator
|
||||
Assesses source quality, credibility, and potential biases
|
||||
"""
|
||||
|
||||
from dataclasses import dataclass
|
||||
from typing import List, Dict, Optional
|
||||
from urllib.parse import urlparse
|
||||
from datetime import datetime, timedelta
|
||||
import re
|
||||
|
||||
|
||||
@dataclass
|
||||
class CredibilityScore:
|
||||
"""Represents source credibility assessment"""
|
||||
overall_score: float # 0-100
|
||||
domain_authority: float # 0-100
|
||||
recency: float # 0-100
|
||||
expertise: float # 0-100
|
||||
bias_score: float # 0-100 (higher = more neutral)
|
||||
factors: Dict[str, str]
|
||||
recommendation: str # "high_trust", "moderate_trust", "low_trust", "verify"
|
||||
|
||||
|
||||
class SourceEvaluator:
|
||||
"""Evaluates source credibility and quality"""
|
||||
|
||||
# Domain reputation tiers
|
||||
HIGH_AUTHORITY_DOMAINS = {
|
||||
# Academic & Research
|
||||
'arxiv.org', 'nature.com', 'science.org', 'cell.com', 'nejm.org',
|
||||
'thelancet.com', 'springer.com', 'sciencedirect.com', 'plos.org',
|
||||
'ieee.org', 'acm.org', 'pubmed.ncbi.nlm.nih.gov',
|
||||
|
||||
# Government & International Organizations
|
||||
'nih.gov', 'cdc.gov', 'who.int', 'fda.gov', 'nasa.gov',
|
||||
'gov.uk', 'europa.eu', 'un.org',
|
||||
|
||||
# Established Tech Documentation
|
||||
'docs.python.org', 'developer.mozilla.org', 'docs.microsoft.com',
|
||||
'cloud.google.com', 'aws.amazon.com', 'kubernetes.io',
|
||||
|
||||
# Reputable News (Fact-check verified)
|
||||
'reuters.com', 'apnews.com', 'bbc.com', 'economist.com',
|
||||
'nature.com/news', 'scientificamerican.com'
|
||||
}
|
||||
|
||||
MODERATE_AUTHORITY_DOMAINS = {
|
||||
# Tech News & Analysis
|
||||
'techcrunch.com', 'theverge.com', 'arstechnica.com', 'wired.com',
|
||||
'zdnet.com', 'cnet.com',
|
||||
|
||||
# Industry Publications
|
||||
'forbes.com', 'bloomberg.com', 'wsj.com', 'ft.com',
|
||||
|
||||
# Educational
|
||||
'wikipedia.org', 'britannica.com', 'khanacademy.org',
|
||||
|
||||
# Tech Blogs (established)
|
||||
'medium.com', 'dev.to', 'stackoverflow.com', 'github.com'
|
||||
}
|
||||
|
||||
LOW_AUTHORITY_INDICATORS = [
|
||||
'blogspot.com', 'wordpress.com', 'wix.com', 'substack.com'
|
||||
]
|
||||
|
||||
def __init__(self):
|
||||
pass
|
||||
|
||||
def evaluate_source(
|
||||
self,
|
||||
url: str,
|
||||
title: str,
|
||||
content: Optional[str] = None,
|
||||
publication_date: Optional[str] = None,
|
||||
author: Optional[str] = None
|
||||
) -> CredibilityScore:
|
||||
"""Evaluate source credibility"""
|
||||
|
||||
domain = self._extract_domain(url)
|
||||
|
||||
# Calculate component scores
|
||||
domain_score = self._evaluate_domain_authority(domain)
|
||||
recency_score = self._evaluate_recency(publication_date)
|
||||
expertise_score = self._evaluate_expertise(domain, title, author)
|
||||
bias_score = self._evaluate_bias(domain, title, content)
|
||||
|
||||
# Calculate overall score (weighted average)
|
||||
overall = (
|
||||
domain_score * 0.35 +
|
||||
recency_score * 0.20 +
|
||||
expertise_score * 0.25 +
|
||||
bias_score * 0.20
|
||||
)
|
||||
|
||||
# Determine factors
|
||||
factors = self._identify_factors(
|
||||
domain, domain_score, recency_score, expertise_score, bias_score
|
||||
)
|
||||
|
||||
# Generate recommendation
|
||||
recommendation = self._generate_recommendation(overall)
|
||||
|
||||
return CredibilityScore(
|
||||
overall_score=round(overall, 2),
|
||||
domain_authority=round(domain_score, 2),
|
||||
recency=round(recency_score, 2),
|
||||
expertise=round(expertise_score, 2),
|
||||
bias_score=round(bias_score, 2),
|
||||
factors=factors,
|
||||
recommendation=recommendation
|
||||
)
|
||||
|
||||
def _extract_domain(self, url: str) -> str:
|
||||
"""Extract domain from URL"""
|
||||
parsed = urlparse(url)
|
||||
domain = parsed.netloc.lower()
|
||||
# Remove www prefix
|
||||
domain = domain.replace('www.', '')
|
||||
return domain
|
||||
|
||||
def _evaluate_domain_authority(self, domain: str) -> float:
|
||||
"""Evaluate domain authority (0-100)"""
|
||||
if domain in self.HIGH_AUTHORITY_DOMAINS:
|
||||
return 90.0
|
||||
elif domain in self.MODERATE_AUTHORITY_DOMAINS:
|
||||
return 70.0
|
||||
elif any(indicator in domain for indicator in self.LOW_AUTHORITY_INDICATORS):
|
||||
return 40.0
|
||||
else:
|
||||
# Unknown domain - moderate skepticism
|
||||
return 55.0
|
||||
|
||||
def _evaluate_recency(self, publication_date: Optional[str]) -> float:
|
||||
"""Evaluate information recency (0-100)"""
|
||||
if not publication_date:
|
||||
return 50.0 # Unknown date
|
||||
|
||||
try:
|
||||
pub_date = datetime.fromisoformat(publication_date.replace('Z', '+00:00'))
|
||||
age = datetime.now() - pub_date
|
||||
|
||||
# Recency scoring
|
||||
if age < timedelta(days=90): # < 3 months
|
||||
return 100.0
|
||||
elif age < timedelta(days=365): # < 1 year
|
||||
return 85.0
|
||||
elif age < timedelta(days=730): # < 2 years
|
||||
return 70.0
|
||||
elif age < timedelta(days=1825): # < 5 years
|
||||
return 50.0
|
||||
else:
|
||||
return 30.0
|
||||
|
||||
except Exception:
|
||||
return 50.0
|
||||
|
||||
def _evaluate_expertise(
|
||||
self,
|
||||
domain: str,
|
||||
title: str,
|
||||
author: Optional[str]
|
||||
) -> float:
|
||||
"""Evaluate source expertise (0-100)"""
|
||||
score = 50.0
|
||||
|
||||
# Academic/research domains get high expertise
|
||||
if any(d in domain for d in ['arxiv', 'nature', 'science', 'ieee', 'acm']):
|
||||
score += 30
|
||||
|
||||
# Government/official sources
|
||||
if '.gov' in domain or 'who.int' in domain:
|
||||
score += 25
|
||||
|
||||
# Technical documentation
|
||||
if 'docs.' in domain or 'documentation' in title.lower():
|
||||
score += 20
|
||||
|
||||
# Author credentials (if available)
|
||||
if author:
|
||||
if any(title in author.lower() for title in ['dr.', 'phd', 'professor']):
|
||||
score += 15
|
||||
|
||||
return min(score, 100.0)
|
||||
|
||||
def _evaluate_bias(
|
||||
self,
|
||||
domain: str,
|
||||
title: str,
|
||||
content: Optional[str]
|
||||
) -> float:
|
||||
"""Evaluate potential bias (0-100, higher = more neutral)"""
|
||||
score = 70.0 # Start neutral
|
||||
|
||||
# Check for sensationalism in title
|
||||
sensational_indicators = [
|
||||
'!', 'shocking', 'unbelievable', 'you won\'t believe',
|
||||
'secret', 'they don\'t want you to know'
|
||||
]
|
||||
title_lower = title.lower()
|
||||
if any(indicator in title_lower for indicator in sensational_indicators):
|
||||
score -= 20
|
||||
|
||||
# Academic sources are typically less biased
|
||||
if any(d in domain for d in ['arxiv', 'nature', 'science', 'ieee']):
|
||||
score += 20
|
||||
|
||||
# Check for balance in content (if available)
|
||||
if content:
|
||||
# Look for balanced language
|
||||
balanced_indicators = ['however', 'although', 'on the other hand', 'critics argue']
|
||||
if any(indicator in content.lower() for indicator in balanced_indicators):
|
||||
score += 10
|
||||
|
||||
return min(max(score, 0), 100.0)
|
||||
|
||||
def _identify_factors(
|
||||
self,
|
||||
domain: str,
|
||||
domain_score: float,
|
||||
recency_score: float,
|
||||
expertise_score: float,
|
||||
bias_score: float
|
||||
) -> Dict[str, str]:
|
||||
"""Identify key credibility factors"""
|
||||
factors = {}
|
||||
|
||||
if domain_score >= 85:
|
||||
factors['domain'] = "High authority domain"
|
||||
elif domain_score <= 45:
|
||||
factors['domain'] = "Low authority domain - verify claims"
|
||||
|
||||
if recency_score >= 85:
|
||||
factors['recency'] = "Recent information"
|
||||
elif recency_score <= 40:
|
||||
factors['recency'] = "Outdated information - verify currency"
|
||||
|
||||
if expertise_score >= 80:
|
||||
factors['expertise'] = "Expert source"
|
||||
elif expertise_score <= 45:
|
||||
factors['expertise'] = "Limited expertise indicators"
|
||||
|
||||
if bias_score >= 80:
|
||||
factors['bias'] = "Balanced perspective"
|
||||
elif bias_score <= 50:
|
||||
factors['bias'] = "Potential bias detected"
|
||||
|
||||
return factors
|
||||
|
||||
def _generate_recommendation(self, overall_score: float) -> str:
|
||||
"""Generate trust recommendation"""
|
||||
if overall_score >= 80:
|
||||
return "high_trust"
|
||||
elif overall_score >= 60:
|
||||
return "moderate_trust"
|
||||
elif overall_score >= 40:
|
||||
return "low_trust"
|
||||
else:
|
||||
return "verify"
|
||||
|
||||
|
||||
# Example usage
|
||||
if __name__ == '__main__':
|
||||
evaluator = SourceEvaluator()
|
||||
|
||||
# Test sources
|
||||
test_sources = [
|
||||
{
|
||||
'url': 'https://www.nature.com/articles/s41586-2025-12345',
|
||||
'title': 'Breakthrough in Quantum Computing',
|
||||
'publication_date': '2025-10-15'
|
||||
},
|
||||
{
|
||||
'url': 'https://someblog.wordpress.com/shocking-discovery',
|
||||
'title': 'SHOCKING! You Won\'t Believe This Discovery!',
|
||||
'publication_date': '2020-01-01'
|
||||
},
|
||||
{
|
||||
'url': 'https://docs.python.org/3/library/asyncio.html',
|
||||
'title': 'asyncio — Asynchronous I/O',
|
||||
'publication_date': '2025-11-01'
|
||||
}
|
||||
]
|
||||
|
||||
for source in test_sources:
|
||||
score = evaluator.evaluate_source(**source)
|
||||
print(f"\nSource: {source['title']}")
|
||||
print(f"URL: {source['url']}")
|
||||
print(f"Overall Score: {score.overall_score}/100")
|
||||
print(f"Recommendation: {score.recommendation}")
|
||||
print(f"Factors: {score.factors}")
|
||||
354
axhub-make/skills/third-party/deep-research/scripts/validate_report.py
vendored
Normal file
354
axhub-make/skills/third-party/deep-research/scripts/validate_report.py
vendored
Normal file
@@ -0,0 +1,354 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Report Validation Script
|
||||
Ensures research reports meet quality standards before delivery
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import re
|
||||
import sys
|
||||
from pathlib import Path
|
||||
from typing import List, Tuple, Dict
|
||||
|
||||
|
||||
class ReportValidator:
|
||||
"""Validates research report quality"""
|
||||
|
||||
def __init__(self, report_path: Path):
|
||||
self.report_path = report_path
|
||||
self.content = self._read_report()
|
||||
self.errors: List[str] = []
|
||||
self.warnings: List[str] = []
|
||||
|
||||
def _read_report(self) -> str:
|
||||
"""Read report file"""
|
||||
try:
|
||||
with open(self.report_path, 'r', encoding='utf-8') as f:
|
||||
return f.read()
|
||||
except Exception as e:
|
||||
print(f"❌ ERROR: Cannot read report: {e}")
|
||||
sys.exit(1)
|
||||
|
||||
def validate(self) -> bool:
|
||||
"""Run all validation checks"""
|
||||
print(f"\n{'='*60}")
|
||||
print(f"VALIDATING REPORT: {self.report_path.name}")
|
||||
print(f"{'='*60}\n")
|
||||
|
||||
checks = [
|
||||
("Executive Summary", self._check_executive_summary),
|
||||
("Required Sections", self._check_required_sections),
|
||||
("Citations", self._check_citations),
|
||||
("Bibliography", self._check_bibliography),
|
||||
("Placeholder Text", self._check_placeholders),
|
||||
("Content Truncation", self._check_content_truncation),
|
||||
("Word Count", self._check_word_count),
|
||||
("Source Count", self._check_source_count),
|
||||
("Broken Links", self._check_broken_references),
|
||||
]
|
||||
|
||||
for check_name, check_func in checks:
|
||||
print(f"⏳ Checking: {check_name}...", end=" ")
|
||||
passed = check_func()
|
||||
if passed:
|
||||
print("✅ PASS")
|
||||
else:
|
||||
print("❌ FAIL")
|
||||
|
||||
self._print_summary()
|
||||
|
||||
return len(self.errors) == 0
|
||||
|
||||
def _check_executive_summary(self) -> bool:
|
||||
"""Check executive summary exists and is under 250 words"""
|
||||
pattern = r'## Executive Summary(.*?)(?=##|\Z)'
|
||||
match = re.search(pattern, self.content, re.DOTALL | re.IGNORECASE)
|
||||
|
||||
if not match:
|
||||
self.errors.append("Missing 'Executive Summary' section")
|
||||
return False
|
||||
|
||||
summary = match.group(1).strip()
|
||||
word_count = len(summary.split())
|
||||
|
||||
if word_count > 250:
|
||||
self.warnings.append(f"Executive summary too long: {word_count} words (should be ≤250)")
|
||||
|
||||
if word_count < 50:
|
||||
self.warnings.append(f"Executive summary too short: {word_count} words (should be ≥50)")
|
||||
|
||||
return True
|
||||
|
||||
def _check_required_sections(self) -> bool:
|
||||
"""Check all required sections are present"""
|
||||
required = [
|
||||
"Executive Summary",
|
||||
"Introduction",
|
||||
"Main Analysis",
|
||||
"Synthesis",
|
||||
"Limitations",
|
||||
"Recommendations",
|
||||
"Bibliography",
|
||||
"Methodology"
|
||||
]
|
||||
|
||||
# Recommended sections (warnings if missing, not errors)
|
||||
recommended = [
|
||||
"Counterevidence Register",
|
||||
"Claims-Evidence Table"
|
||||
]
|
||||
|
||||
missing = []
|
||||
for section in required:
|
||||
if not re.search(rf'##.*{section}', self.content, re.IGNORECASE):
|
||||
missing.append(section)
|
||||
|
||||
if missing:
|
||||
self.errors.append(f"Missing sections: {', '.join(missing)}")
|
||||
return False
|
||||
|
||||
# Check recommended sections (warnings only)
|
||||
missing_recommended = []
|
||||
for section in recommended:
|
||||
if not re.search(rf'##.*{section}', self.content, re.IGNORECASE):
|
||||
missing_recommended.append(section)
|
||||
|
||||
if missing_recommended:
|
||||
self.warnings.append(f"Missing recommended sections (for academic rigor): {', '.join(missing_recommended)}")
|
||||
|
||||
return True
|
||||
|
||||
def _check_citations(self) -> bool:
|
||||
"""Check citation format and presence"""
|
||||
# Find all citation references [1], [2], etc.
|
||||
citations = re.findall(r'\[(\d+)\]', self.content)
|
||||
|
||||
if not citations:
|
||||
self.errors.append("No citations found in report")
|
||||
return False
|
||||
|
||||
unique_citations = set(citations)
|
||||
|
||||
if len(unique_citations) < 10:
|
||||
self.warnings.append(f"Only {len(unique_citations)} unique sources cited (recommended: ≥10)")
|
||||
|
||||
# Check for consecutive citation numbers
|
||||
citation_nums = sorted([int(c) for c in unique_citations])
|
||||
if citation_nums:
|
||||
max_citation = max(citation_nums)
|
||||
expected = set(range(1, max_citation + 1))
|
||||
missing = expected - set(citation_nums)
|
||||
|
||||
if missing:
|
||||
self.warnings.append(f"Non-consecutive citation numbers, missing: {sorted(missing)}")
|
||||
|
||||
return True
|
||||
|
||||
def _check_bibliography(self) -> bool:
|
||||
"""Check bibliography exists, matches citations, and has no truncation placeholders"""
|
||||
pattern = r'## Bibliography(.*?)(?=##|\Z)'
|
||||
match = re.search(pattern, self.content, re.DOTALL | re.IGNORECASE)
|
||||
|
||||
if not match:
|
||||
self.errors.append("Missing 'Bibliography' section")
|
||||
return False
|
||||
|
||||
bib_section = match.group(1)
|
||||
|
||||
# CRITICAL: Check for truncation placeholders (2025 CiteGuard enhancement)
|
||||
truncation_patterns = [
|
||||
(r'\[\d+-\d+\]', 'Citation range (e.g., [8-75])'),
|
||||
(r'Additional.*citations', 'Phrase "Additional citations"'),
|
||||
(r'would be included', 'Phrase "would be included"'),
|
||||
(r'\[\.\.\.continue', 'Pattern "[...continue"'),
|
||||
(r'\[Continue with', 'Pattern "[Continue with"'),
|
||||
(r'etc\.(?!\w)', 'Standalone "etc."'),
|
||||
(r'and so on', 'Phrase "and so on"'),
|
||||
]
|
||||
|
||||
for pattern_re, description in truncation_patterns:
|
||||
if re.search(pattern_re, bib_section, re.IGNORECASE):
|
||||
self.errors.append(f"⚠️ CRITICAL: Bibliography contains truncation placeholder: {description}")
|
||||
self.errors.append(f" This makes the report UNUSABLE - complete bibliography required")
|
||||
return False
|
||||
|
||||
# Count bibliography entries [1], [2], etc.
|
||||
bib_entries = re.findall(r'^\[(\d+)\]', bib_section, re.MULTILINE)
|
||||
|
||||
if not bib_entries:
|
||||
self.errors.append("Bibliography has no entries")
|
||||
return False
|
||||
|
||||
# Check citation number continuity (no gaps)
|
||||
bib_nums = sorted([int(n) for n in bib_entries])
|
||||
if bib_nums:
|
||||
expected = list(range(1, bib_nums[-1] + 1))
|
||||
actual = bib_nums
|
||||
missing = [n for n in expected if n not in actual]
|
||||
if missing:
|
||||
self.errors.append(f"Bibliography has gaps in numbering: missing {missing}")
|
||||
return False
|
||||
|
||||
# Find citations in text
|
||||
text_citations = set(re.findall(r'\[(\d+)\]', self.content))
|
||||
bib_citations = set(bib_entries)
|
||||
|
||||
# Check all citations have bibliography entries
|
||||
missing_in_bib = text_citations - bib_citations
|
||||
if missing_in_bib:
|
||||
self.errors.append(f"Citations missing from bibliography: {sorted(missing_in_bib)}")
|
||||
return False
|
||||
|
||||
# Check for unused bibliography entries
|
||||
unused = bib_citations - text_citations
|
||||
if unused:
|
||||
self.warnings.append(f"Unused bibliography entries: {sorted(unused)}")
|
||||
|
||||
return True
|
||||
|
||||
def _check_placeholders(self) -> bool:
|
||||
"""Check for placeholder text that shouldn't be in final report"""
|
||||
placeholders = [
|
||||
'TBD', 'TODO', 'FIXME', 'XXX',
|
||||
'[citation needed]', '[needs citation]',
|
||||
'[placeholder]', '[TODO]', '[TBD]'
|
||||
]
|
||||
|
||||
found_placeholders = []
|
||||
for placeholder in placeholders:
|
||||
if placeholder in self.content:
|
||||
found_placeholders.append(placeholder)
|
||||
|
||||
if found_placeholders:
|
||||
self.errors.append(f"Found placeholder text: {', '.join(found_placeholders)}")
|
||||
return False
|
||||
|
||||
return True
|
||||
|
||||
def _check_content_truncation(self) -> bool:
|
||||
"""Check for content truncation patterns (2025 Progressive Assembly enhancement)"""
|
||||
truncation_patterns = [
|
||||
(r'Content continues', 'Phrase "Content continues"'),
|
||||
(r'Due to length', 'Phrase "Due to length"'),
|
||||
(r'would continue', 'Phrase "would continue"'),
|
||||
(r'\[Sections \d+-\d+', 'Pattern "[Sections X-Y"'),
|
||||
(r'Additional sections', 'Phrase "Additional sections"'),
|
||||
(r'comprehensive.*word document that continues', 'Pattern "comprehensive...document that continues"'),
|
||||
]
|
||||
|
||||
for pattern_re, description in truncation_patterns:
|
||||
if re.search(pattern_re, self.content, re.IGNORECASE):
|
||||
self.errors.append(f"⚠️ CRITICAL: Content truncation detected: {description}")
|
||||
self.errors.append(f" Report is INCOMPLETE and UNUSABLE - regenerate with progressive assembly")
|
||||
return False
|
||||
|
||||
return True
|
||||
|
||||
def _check_word_count(self) -> bool:
|
||||
"""Check overall report length"""
|
||||
word_count = len(self.content.split())
|
||||
|
||||
if word_count < 500:
|
||||
self.warnings.append(f"Report is very short: {word_count} words (consider expanding)")
|
||||
# No upper limit warning - progressive assembly supports unlimited lengths
|
||||
|
||||
return True
|
||||
|
||||
def _check_source_count(self) -> bool:
|
||||
"""Check minimum source count"""
|
||||
pattern = r'## Bibliography(.*?)(?=##|\Z)'
|
||||
match = re.search(pattern, self.content, re.DOTALL | re.IGNORECASE)
|
||||
|
||||
if not match:
|
||||
return True # Already caught in bibliography check
|
||||
|
||||
bib_section = match.group(1)
|
||||
bib_entries = re.findall(r'^\[(\d+)\]', bib_section, re.MULTILINE)
|
||||
|
||||
source_count = len(set(bib_entries))
|
||||
|
||||
if source_count < 10:
|
||||
self.warnings.append(f"Only {source_count} sources (recommended: ≥10)")
|
||||
|
||||
return True
|
||||
|
||||
def _check_broken_references(self) -> bool:
|
||||
"""Check for broken internal references"""
|
||||
# Find all markdown links [text](./path)
|
||||
internal_links = re.findall(r'\[.*?\]\((\.\/.*?)\)', self.content)
|
||||
|
||||
broken = []
|
||||
for link in internal_links:
|
||||
# Remove anchor if present
|
||||
link_path = link.split('#')[0]
|
||||
full_path = self.report_path.parent / link_path
|
||||
|
||||
if not full_path.exists():
|
||||
broken.append(link)
|
||||
|
||||
if broken:
|
||||
self.errors.append(f"Broken internal links: {', '.join(broken)}")
|
||||
return False
|
||||
|
||||
return True
|
||||
|
||||
def _print_summary(self):
|
||||
"""Print validation summary"""
|
||||
print(f"\n{'='*60}")
|
||||
print(f"VALIDATION SUMMARY")
|
||||
print(f"{'='*60}\n")
|
||||
|
||||
if self.errors:
|
||||
print(f"❌ ERRORS ({len(self.errors)}):")
|
||||
for error in self.errors:
|
||||
print(f" • {error}")
|
||||
print()
|
||||
|
||||
if self.warnings:
|
||||
print(f"⚠️ WARNINGS ({len(self.warnings)}):")
|
||||
for warning in self.warnings:
|
||||
print(f" • {warning}")
|
||||
print()
|
||||
|
||||
if not self.errors and not self.warnings:
|
||||
print("✅ ALL CHECKS PASSED - Report meets quality standards!\n")
|
||||
elif not self.errors:
|
||||
print("✅ VALIDATION PASSED (with warnings)\n")
|
||||
else:
|
||||
print("❌ VALIDATION FAILED - Please fix errors before delivery\n")
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Validate research report quality",
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
epilog="""
|
||||
Examples:
|
||||
python validate_report.py --report report.md
|
||||
python validate_report.py -r ~/.claude/research_output/research_report_20251104_153045.md
|
||||
"""
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--report', '-r',
|
||||
type=str,
|
||||
required=True,
|
||||
help='Path to research report markdown file'
|
||||
)
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
report_path = Path(args.report)
|
||||
|
||||
if not report_path.exists():
|
||||
print(f"❌ ERROR: Report file not found: {report_path}")
|
||||
sys.exit(1)
|
||||
|
||||
validator = ReportValidator(report_path)
|
||||
passed = validator.validate()
|
||||
|
||||
sys.exit(0 if passed else 1)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
430
axhub-make/skills/third-party/deep-research/scripts/verify_citations.py
vendored
Normal file
430
axhub-make/skills/third-party/deep-research/scripts/verify_citations.py
vendored
Normal file
@@ -0,0 +1,430 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Citation Verification Script (Enhanced with CiteGuard techniques)
|
||||
|
||||
Catches fabricated citations by checking:
|
||||
1. DOI resolution (via doi.org)
|
||||
2. Basic metadata matching (title similarity, year match)
|
||||
3. URL accessibility verification
|
||||
4. Hallucination pattern detection (generic titles, suspicious patterns)
|
||||
5. Flags suspicious entries for manual review
|
||||
|
||||
Enhanced in 2025 with:
|
||||
- Content alignment checking (when URL available)
|
||||
- Multi-source verification (DOI + URL + metadata cross-check)
|
||||
- Advanced hallucination detection patterns
|
||||
- Better false positive reduction
|
||||
|
||||
Usage:
|
||||
python verify_citations.py --report [path]
|
||||
python verify_citations.py --report [path] --strict # Fail on any unverified
|
||||
|
||||
Does NOT require API keys - uses free DOI resolver and heuristics.
|
||||
"""
|
||||
|
||||
import sys
|
||||
import argparse
|
||||
import re
|
||||
from pathlib import Path
|
||||
from typing import List, Dict, Tuple
|
||||
from urllib import request, error
|
||||
from urllib.parse import quote
|
||||
import json
|
||||
import time
|
||||
|
||||
class CitationVerifier:
|
||||
"""Verify citations in research report"""
|
||||
|
||||
def __init__(self, report_path: Path, strict_mode: bool = False):
|
||||
self.report_path = report_path
|
||||
self.strict_mode = strict_mode
|
||||
self.content = self._read_report()
|
||||
self.suspicious = []
|
||||
self.verified = []
|
||||
self.errors = []
|
||||
|
||||
# Hallucination detection patterns (2025 CiteGuard enhancement)
|
||||
self.suspicious_patterns = [
|
||||
# Generic academic-sounding but fake patterns
|
||||
(r'^(A |An |The )?(Study|Analysis|Review|Survey|Investigation) (of|on|into)',
|
||||
"Generic academic title pattern"),
|
||||
(r'^(Recent|Current|Modern|Contemporary) (Advances|Developments|Trends) in',
|
||||
"Generic 'advances' title pattern"),
|
||||
# Too perfect, templated titles
|
||||
(r'^[A-Z][a-z]+ [A-Z][a-z]+: A (Comprehensive|Complete|Systematic) (Review|Analysis|Guide)$',
|
||||
"Too perfect, templated structure"),
|
||||
]
|
||||
|
||||
def _read_report(self) -> str:
|
||||
"""Read report file"""
|
||||
try:
|
||||
with open(self.report_path, 'r', encoding='utf-8') as f:
|
||||
return f.read()
|
||||
except Exception as e:
|
||||
print(f"L ERROR: Cannot read report: {e}")
|
||||
sys.exit(1)
|
||||
|
||||
def extract_bibliography(self) -> List[Dict]:
|
||||
"""Extract bibliography entries from report"""
|
||||
pattern = r'## Bibliography(.*?)(?=##|\Z)'
|
||||
match = re.search(pattern, self.content, re.DOTALL | re.IGNORECASE)
|
||||
|
||||
if not match:
|
||||
self.errors.append("No Bibliography section found")
|
||||
return []
|
||||
|
||||
bib_section = match.group(1)
|
||||
|
||||
# Parse entries: [N] Author (Year). "Title". Venue. URL
|
||||
entries = []
|
||||
lines = bib_section.strip().split('\n')
|
||||
|
||||
current_entry = None
|
||||
for line in lines:
|
||||
line = line.strip()
|
||||
if not line:
|
||||
continue
|
||||
|
||||
# Check if starts with citation number [N]
|
||||
match_num = re.match(r'^\[(\d+)\]\s+(.+)$', line)
|
||||
if match_num:
|
||||
if current_entry:
|
||||
entries.append(current_entry)
|
||||
|
||||
num = match_num.group(1)
|
||||
rest = match_num.group(2)
|
||||
|
||||
# Try to parse: Author (Year). "Title". Venue. URL
|
||||
year_match = re.search(r'\((\d{4})\)', rest)
|
||||
title_match = re.search(r'"([^"]+)"', rest)
|
||||
doi_match = re.search(r'doi\.org/(10\.\S+)', rest)
|
||||
url_match = re.search(r'https?://[^\s\)]+', rest)
|
||||
|
||||
current_entry = {
|
||||
'num': num,
|
||||
'raw': rest,
|
||||
'year': year_match.group(1) if year_match else None,
|
||||
'title': title_match.group(1) if title_match else None,
|
||||
'doi': doi_match.group(1) if doi_match else None,
|
||||
'url': url_match.group(0) if url_match else None
|
||||
}
|
||||
elif current_entry:
|
||||
# Multi-line entry, append to raw
|
||||
current_entry['raw'] += ' ' + line
|
||||
|
||||
if current_entry:
|
||||
entries.append(current_entry)
|
||||
|
||||
return entries
|
||||
|
||||
def verify_doi(self, doi: str) -> Tuple[bool, Dict]:
|
||||
"""
|
||||
Verify DOI exists and get metadata.
|
||||
Returns (success, metadata_dict)
|
||||
"""
|
||||
if not doi:
|
||||
return False, {}
|
||||
|
||||
try:
|
||||
# Use content negotiation to get JSON metadata
|
||||
url = f"https://doi.org/{quote(doi)}"
|
||||
req = request.Request(url)
|
||||
req.add_header('Accept', 'application/vnd.citationstyles.csl+json')
|
||||
|
||||
with request.urlopen(req, timeout=10) as response:
|
||||
data = json.loads(response.read().decode('utf-8'))
|
||||
|
||||
return True, {
|
||||
'title': data.get('title', ''),
|
||||
'year': data.get('issued', {}).get('date-parts', [[None]])[0][0],
|
||||
'authors': [
|
||||
f"{a.get('family', '')} {a.get('given', '')}"
|
||||
for a in data.get('author', [])
|
||||
],
|
||||
'venue': data.get('container-title', '')
|
||||
}
|
||||
except error.HTTPError as e:
|
||||
if e.code == 404:
|
||||
return False, {'error': 'DOI not found (404)'}
|
||||
return False, {'error': f'HTTP {e.code}'}
|
||||
except Exception as e:
|
||||
return False, {'error': str(e)}
|
||||
|
||||
def verify_url(self, url: str) -> Tuple[bool, str]:
|
||||
"""
|
||||
Verify URL is accessible (2025 CiteGuard enhancement).
|
||||
Returns (accessible, status_message)
|
||||
"""
|
||||
if not url:
|
||||
return False, "No URL"
|
||||
|
||||
try:
|
||||
# HEAD request to check accessibility without downloading
|
||||
req = request.Request(url, method='HEAD')
|
||||
req.add_header('User-Agent', 'Mozilla/5.0 (Research Citation Verifier)')
|
||||
|
||||
with request.urlopen(req, timeout=10) as response:
|
||||
if response.status == 200:
|
||||
return True, "URL accessible"
|
||||
else:
|
||||
return False, f"HTTP {response.status}"
|
||||
except error.HTTPError as e:
|
||||
return False, f"HTTP {e.code}"
|
||||
except error.URLError as e:
|
||||
return False, f"URL error: {e.reason}"
|
||||
except Exception as e:
|
||||
return False, f"Connection error: {str(e)[:50]}"
|
||||
|
||||
def detect_hallucination_patterns(self, entry: Dict) -> List[str]:
|
||||
"""
|
||||
Detect common LLM hallucination patterns in citations (2025 CiteGuard).
|
||||
Returns list of detected issues.
|
||||
"""
|
||||
issues = []
|
||||
title = entry.get('title', '')
|
||||
|
||||
if not title:
|
||||
return issues
|
||||
|
||||
# Check against suspicious patterns
|
||||
for pattern, description in self.suspicious_patterns:
|
||||
if re.match(pattern, title, re.IGNORECASE):
|
||||
issues.append(f"Suspicious title pattern: {description}")
|
||||
|
||||
# Check for overly generic titles
|
||||
generic_words = ['overview', 'introduction', 'guide', 'handbook', 'manual']
|
||||
if any(word in title.lower() for word in generic_words) and len(title.split()) < 5:
|
||||
issues.append("Very generic short title")
|
||||
|
||||
# Check for placeholder-like titles
|
||||
if any(x in title.lower() for x in ['tbd', 'todo', 'placeholder', 'example']):
|
||||
issues.append("Placeholder text in title")
|
||||
|
||||
# Check for inconsistent metadata
|
||||
if entry.get('year'):
|
||||
year = int(entry['year'])
|
||||
# Very recent without DOI or URL is suspicious
|
||||
if year >= 2024 and not entry.get('doi') and not entry.get('url'):
|
||||
issues.append("Recent year (2024+) with no verification method")
|
||||
# Future year is definitely wrong
|
||||
if year > 2025:
|
||||
issues.append(f"Future year: {year}")
|
||||
# Very old with modern phrasing is suspicious
|
||||
if year < 2000 and any(word in title.lower() for word in ['ai', 'llm', 'gpt', 'transformer']):
|
||||
issues.append(f"Anachronistic: pre-2000 ({year}) citation mentioning modern AI terms")
|
||||
|
||||
return issues
|
||||
|
||||
def check_title_similarity(self, title1: str, title2: str) -> float:
|
||||
"""
|
||||
Simple title similarity check (word overlap).
|
||||
Returns score 0.0-1.0
|
||||
"""
|
||||
if not title1 or not title2:
|
||||
return 0.0
|
||||
|
||||
# Normalize: lowercase, remove punctuation, split
|
||||
def normalize(s):
|
||||
s = s.lower()
|
||||
s = re.sub(r'[^\w\s]', ' ', s)
|
||||
return set(s.split())
|
||||
|
||||
words1 = normalize(title1)
|
||||
words2 = normalize(title2)
|
||||
|
||||
if not words1 or not words2:
|
||||
return 0.0
|
||||
|
||||
overlap = len(words1 & words2)
|
||||
total = len(words1 | words2)
|
||||
|
||||
return overlap / total if total > 0 else 0.0
|
||||
|
||||
def verify_entry(self, entry: Dict) -> Dict:
|
||||
"""Verify a single bibliography entry (Enhanced 2025 with CiteGuard)"""
|
||||
result = {
|
||||
'num': entry['num'],
|
||||
'status': 'unknown',
|
||||
'issues': [],
|
||||
'metadata': {},
|
||||
'verification_methods': []
|
||||
}
|
||||
|
||||
# STEP 1: Run hallucination detection (CiteGuard 2025)
|
||||
hallucination_issues = self.detect_hallucination_patterns(entry)
|
||||
if hallucination_issues:
|
||||
result['issues'].extend(hallucination_issues)
|
||||
result['status'] = 'suspicious'
|
||||
|
||||
# STEP 2: Has DOI?
|
||||
if entry['doi']:
|
||||
print(f" [{entry['num']}] Checking DOI {entry['doi']}...", end=' ')
|
||||
success, metadata = self.verify_doi(entry['doi'])
|
||||
|
||||
if success:
|
||||
result['metadata'] = metadata
|
||||
result['status'] = 'verified'
|
||||
print("")
|
||||
|
||||
# Check title similarity if we have both
|
||||
if entry['title'] and metadata.get('title'):
|
||||
similarity = self.check_title_similarity(
|
||||
entry['title'],
|
||||
metadata['title']
|
||||
)
|
||||
|
||||
if similarity < 0.5:
|
||||
result['issues'].append(
|
||||
f"Title mismatch (similarity: {similarity:.1%})"
|
||||
)
|
||||
result['status'] = 'suspicious'
|
||||
|
||||
# Check year match
|
||||
if entry['year'] and metadata.get('year'):
|
||||
if int(entry['year']) != int(metadata['year']):
|
||||
result['issues'].append(
|
||||
f"Year mismatch: report says {entry['year']}, DOI says {metadata['year']}"
|
||||
)
|
||||
result['status'] = 'suspicious'
|
||||
|
||||
else:
|
||||
print(f"✗ {metadata.get('error', 'Failed')}")
|
||||
result['status'] = 'unverified'
|
||||
result['issues'].append(f"DOI resolution failed: {metadata.get('error', 'unknown')}")
|
||||
|
||||
# STEP 3: Check URL accessibility (if no DOI or DOI failed)
|
||||
if entry['url'] and result['status'] != 'verified':
|
||||
url_ok, url_status = self.verify_url(entry['url'])
|
||||
if url_ok:
|
||||
result['verification_methods'].append('URL')
|
||||
# Upgrade status if URL verifies
|
||||
if result['status'] in ['unknown', 'no_doi', 'unverified']:
|
||||
result['status'] = 'url_verified'
|
||||
print(f" [{entry['num']}] URL accessible ✓")
|
||||
else:
|
||||
result['issues'].append(f"URL check failed: {url_status}")
|
||||
|
||||
# STEP 4: Final fallback - no verification method
|
||||
if not entry['doi'] and not entry['url']:
|
||||
if 'No DOI provided' not in ' '.join(result['issues']):
|
||||
result['issues'].append("No DOI or URL - cannot verify")
|
||||
result['status'] = 'suspicious'
|
||||
|
||||
return result
|
||||
|
||||
def verify_all(self):
|
||||
"""Verify all bibliography entries"""
|
||||
print(f"\n{'='*60}")
|
||||
print(f"CITATION VERIFICATION: {self.report_path.name}")
|
||||
print(f"{'='*60}\n")
|
||||
|
||||
entries = self.extract_bibliography()
|
||||
|
||||
if not entries:
|
||||
print("L No bibliography entries found\n")
|
||||
return False
|
||||
|
||||
print(f"Found {len(entries)} citations\n")
|
||||
|
||||
results = []
|
||||
for entry in entries:
|
||||
result = self.verify_entry(entry)
|
||||
results.append(result)
|
||||
|
||||
# Rate limiting
|
||||
time.sleep(0.5)
|
||||
|
||||
# Summarize
|
||||
print(f"\n{'='*60}")
|
||||
print(f"VERIFICATION SUMMARY")
|
||||
print(f"{'='*60}\n")
|
||||
|
||||
verified = [r for r in results if r['status'] == 'verified']
|
||||
url_verified = [r for r in results if r['status'] == 'url_verified']
|
||||
suspicious = [r for r in results if r['status'] == 'suspicious']
|
||||
unverified = [r for r in results if r['status'] in ['unverified', 'no_doi', 'unknown']]
|
||||
|
||||
print(f'DOI Verified: {len(verified)}/{len(results)}')
|
||||
print(f'URL Verified: {len(url_verified)}/{len(results)}')
|
||||
print(f'Suspicious: {len(suspicious)}/{len(results)}')
|
||||
print(f'Unverified: {len(unverified)}/{len(results)}')
|
||||
print()
|
||||
|
||||
if suspicious:
|
||||
print('SUSPICIOUS CITATIONS (Manual Review Needed):')
|
||||
for r in suspicious:
|
||||
print(f"\n [{r['num']}]")
|
||||
for issue in r['issues']:
|
||||
print(f" - {issue}")
|
||||
print()
|
||||
|
||||
if unverified and len(unverified) > 0:
|
||||
print('UNVERIFIED CITATIONS (Could not check):')
|
||||
for r in unverified:
|
||||
print(f" [{r['num']}] {r['issues'][0] if r['issues'] else 'Unknown'}")
|
||||
print()
|
||||
|
||||
# Decision (Enhanced 2025 - includes URL-verified as acceptable)
|
||||
total_verified = len(verified) + len(url_verified)
|
||||
|
||||
if suspicious:
|
||||
print('WARNING: Suspicious citations detected')
|
||||
if self.strict_mode:
|
||||
print(' STRICT MODE: Failing due to suspicious citations')
|
||||
return False
|
||||
else:
|
||||
print(' (Continuing in non-strict mode)')
|
||||
|
||||
if self.strict_mode and unverified:
|
||||
print('STRICT MODE: Unverified citations found')
|
||||
return False
|
||||
|
||||
if total_verified / len(results) < 0.5:
|
||||
print('WARNING: Less than 50% citations verified')
|
||||
return True # Pass with warning
|
||||
else:
|
||||
print('CITATION VERIFICATION PASSED')
|
||||
return True
|
||||
|
||||
|
||||
def main():
|
||||
parser = argparse.ArgumentParser(
|
||||
description="Verify citations in research report",
|
||||
formatter_class=argparse.RawDescriptionHelpFormatter,
|
||||
epilog="""
|
||||
Examples:
|
||||
python verify_citations.py --report report.md
|
||||
|
||||
Note: Requires internet connection to check DOIs.
|
||||
Uses free DOI resolver - no API key needed.
|
||||
"""
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--report', '-r',
|
||||
type=str,
|
||||
required=True,
|
||||
help='Path to research report markdown file'
|
||||
)
|
||||
|
||||
parser.add_argument(
|
||||
'--strict',
|
||||
action='store_true',
|
||||
help='Strict mode: fail on any unverified or suspicious citations'
|
||||
)
|
||||
|
||||
args = parser.parse_args()
|
||||
report_path = Path(args.report)
|
||||
|
||||
if not report_path.exists():
|
||||
print(f"ERROR: Report file not found: {report_path}")
|
||||
sys.exit(1)
|
||||
|
||||
verifier = CitationVerifier(report_path, strict_mode=args.strict)
|
||||
passed = verifier.verify_all()
|
||||
|
||||
sys.exit(0 if passed else 1)
|
||||
|
||||
|
||||
if __name__ == '__main__':
|
||||
main()
|
||||
220
axhub-make/skills/third-party/deep-research/scripts/verify_html.py
vendored
Normal file
220
axhub-make/skills/third-party/deep-research/scripts/verify_html.py
vendored
Normal file
@@ -0,0 +1,220 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
HTML Report Verification Script
|
||||
Validates that HTML reports are properly generated with all sections from MD
|
||||
"""
|
||||
|
||||
import argparse
|
||||
import re
|
||||
from pathlib import Path
|
||||
from typing import List, Tuple
|
||||
|
||||
|
||||
class HTMLVerifier:
|
||||
"""Verify HTML research reports"""
|
||||
|
||||
def __init__(self, html_path: Path, md_path: Path):
|
||||
self.html_path = html_path
|
||||
self.md_path = md_path
|
||||
self.errors = []
|
||||
self.warnings = []
|
||||
|
||||
def verify(self) -> bool:
|
||||
"""
|
||||
Run all verification checks
|
||||
|
||||
Returns:
|
||||
True if all checks pass, False otherwise
|
||||
"""
|
||||
print(f"\n{'='*60}")
|
||||
print(f"HTML REPORT VERIFICATION")
|
||||
print(f"{'='*60}\n")
|
||||
|
||||
print(f"HTML File: {self.html_path}")
|
||||
print(f"MD File: {self.md_path}\n")
|
||||
|
||||
# Read files
|
||||
try:
|
||||
html_content = self.html_path.read_text()
|
||||
md_content = self.md_path.read_text()
|
||||
except Exception as e:
|
||||
self.errors.append(f"Failed to read files: {e}")
|
||||
return False
|
||||
|
||||
# Run checks
|
||||
self._check_sections(html_content, md_content)
|
||||
self._check_no_placeholders(html_content)
|
||||
self._check_no_emojis(html_content)
|
||||
self._check_structure(html_content)
|
||||
self._check_citations(html_content, md_content)
|
||||
self._check_bibliography(html_content, md_content)
|
||||
|
||||
# Report results
|
||||
self._print_results()
|
||||
|
||||
return len(self.errors) == 0
|
||||
|
||||
def _check_sections(self, html: str, md: str):
|
||||
"""Verify all markdown sections are present in HTML"""
|
||||
# Extract section headings from markdown
|
||||
md_sections = re.findall(r'^## (.+)$', md, re.MULTILINE)
|
||||
|
||||
# Extract sections from HTML
|
||||
html_sections = re.findall(r'<h2 class="section-title">(.+?)</h2>', html)
|
||||
|
||||
# Check if we have placeholder sections like <div class="section">#</div>
|
||||
placeholder_sections = re.findall(r'<div class="section">#</div>', html)
|
||||
|
||||
if placeholder_sections:
|
||||
self.errors.append(
|
||||
f"Found {len(placeholder_sections)} placeholder sections (empty '#' divs) - content not converted properly"
|
||||
)
|
||||
|
||||
# Compare section counts
|
||||
if len(md_sections) > len(html_sections) + 1: # +1 for bibliography which is separate
|
||||
self.errors.append(
|
||||
f"Section count mismatch: MD has {len(md_sections)} sections, HTML has only {len(html_sections)} + bibliography"
|
||||
)
|
||||
missing = set(md_sections) - set(html_sections)
|
||||
if missing:
|
||||
self.errors.append(f"Missing sections in HTML: {missing}")
|
||||
|
||||
# Verify Executive Summary is present
|
||||
if "Executive Summary" in md and "Executive Summary" not in html:
|
||||
self.errors.append("Executive Summary missing from HTML")
|
||||
|
||||
def _check_no_placeholders(self, html: str):
|
||||
"""Check for common placeholders that shouldn't be in final report"""
|
||||
placeholders = [
|
||||
'{{TITLE}}', '{{DATE}}', '{{CONTENT}}', '{{BIBLIOGRAPHY}}',
|
||||
'{{METRICS_DASHBOARD}}', '{{SOURCE_COUNT}}', 'TODO', 'TBD',
|
||||
'PLACEHOLDER', 'FIXME'
|
||||
]
|
||||
|
||||
found = []
|
||||
for placeholder in placeholders:
|
||||
if placeholder in html:
|
||||
found.append(placeholder)
|
||||
|
||||
if found:
|
||||
self.errors.append(f"Found unreplaced placeholders: {', '.join(found)}")
|
||||
|
||||
def _check_no_emojis(self, html: str):
|
||||
"""Verify no emojis are present in HTML"""
|
||||
# Common emoji patterns
|
||||
emoji_pattern = re.compile(
|
||||
"["
|
||||
"\U0001F600-\U0001F64F" # emoticons
|
||||
"\U0001F300-\U0001F5FF" # symbols & pictographs
|
||||
"\U0001F680-\U0001F6FF" # transport & map symbols
|
||||
"\U0001F1E0-\U0001F1FF" # flags
|
||||
"\U00002702-\U000027B0"
|
||||
"\U000024C2-\U0001F251"
|
||||
"]+",
|
||||
flags=re.UNICODE
|
||||
)
|
||||
|
||||
emojis = emoji_pattern.findall(html)
|
||||
if emojis:
|
||||
unique_emojis = set(emojis)
|
||||
self.errors.append(f"Found {len(emojis)} emojis in HTML (should be none): {unique_emojis}")
|
||||
|
||||
def _check_structure(self, html: str):
|
||||
"""Verify HTML has proper structure"""
|
||||
required_elements = [
|
||||
('<html', 'HTML tag'),
|
||||
('<head', 'head tag'),
|
||||
('<body', 'body tag'),
|
||||
('<title>', 'title tag'),
|
||||
('class="header"', 'header section'),
|
||||
('class="content"', 'content section'),
|
||||
('class="bibliography"', 'bibliography section'),
|
||||
]
|
||||
|
||||
for element, name in required_elements:
|
||||
if element not in html:
|
||||
self.errors.append(f"Missing {name} in HTML")
|
||||
|
||||
# Check for unclosed tags (basic check)
|
||||
open_divs = html.count('<div')
|
||||
close_divs = html.count('</div>')
|
||||
|
||||
if abs(open_divs - close_divs) > 2: # Allow small discrepancy
|
||||
self.warnings.append(
|
||||
f"Possible unclosed divs: {open_divs} opening tags, {close_divs} closing tags"
|
||||
)
|
||||
|
||||
def _check_citations(self, html: str, md: str):
|
||||
"""Verify citations are present"""
|
||||
# Extract citations from markdown
|
||||
md_citations = set(re.findall(r'\[(\d+)\]', md))
|
||||
|
||||
# Extract citations from HTML (excluding bibliography)
|
||||
html_content = html.split('class="bibliography"')[0] if 'class="bibliography"' in html else html
|
||||
html_citations = set(re.findall(r'\[(\d+)\]', html_content))
|
||||
|
||||
if len(md_citations) > 0 and len(html_citations) == 0:
|
||||
self.errors.append("No citations found in HTML content (but present in MD)")
|
||||
|
||||
if len(md_citations) > len(html_citations) * 1.5: # Allow some variation
|
||||
self.warnings.append(
|
||||
f"Fewer citations in HTML ({len(html_citations)}) than MD ({len(md_citations)})"
|
||||
)
|
||||
|
||||
def _check_bibliography(self, html: str, md: str):
|
||||
"""Verify bibliography is present and formatted"""
|
||||
if '## Bibliography' in md:
|
||||
if 'class="bibliography"' not in html:
|
||||
self.errors.append("Bibliography section missing from HTML")
|
||||
elif 'class="bib-entry"' not in html:
|
||||
self.warnings.append("Bibliography present but entries not properly formatted")
|
||||
|
||||
def _print_results(self):
|
||||
"""Print verification results"""
|
||||
print(f"\n{'-'*60}")
|
||||
print("VERIFICATION RESULTS")
|
||||
print(f"{'-'*60}\n")
|
||||
|
||||
if self.errors:
|
||||
print(f"❌ ERRORS ({len(self.errors)}):")
|
||||
for i, error in enumerate(self.errors, 1):
|
||||
print(f" {i}. {error}")
|
||||
print()
|
||||
|
||||
if self.warnings:
|
||||
print(f"⚠️ WARNINGS ({len(self.warnings)}):")
|
||||
for i, warning in enumerate(self.warnings, 1):
|
||||
print(f" {i}. {warning}")
|
||||
print()
|
||||
|
||||
if not self.errors and not self.warnings:
|
||||
print("✅ All checks passed! HTML report is valid.")
|
||||
print()
|
||||
|
||||
print(f"{'-'*60}\n")
|
||||
|
||||
|
||||
def main():
|
||||
"""Main entry point"""
|
||||
parser = argparse.ArgumentParser(description='Verify HTML research report')
|
||||
parser.add_argument('--html', type=Path, required=True, help='Path to HTML report')
|
||||
parser.add_argument('--md', type=Path, required=True, help='Path to markdown report')
|
||||
|
||||
args = parser.parse_args()
|
||||
|
||||
if not args.html.exists():
|
||||
print(f"Error: HTML file not found: {args.html}")
|
||||
return 1
|
||||
|
||||
if not args.md.exists():
|
||||
print(f"Error: Markdown file not found: {args.md}")
|
||||
return 1
|
||||
|
||||
verifier = HTMLVerifier(args.html, args.md)
|
||||
success = verifier.verify()
|
||||
|
||||
return 0 if success else 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
exit(main())
|
||||
443
axhub-make/skills/third-party/deep-research/templates/mckinsey_report_template.html
vendored
Normal file
443
axhub-make/skills/third-party/deep-research/templates/mckinsey_report_template.html
vendored
Normal file
@@ -0,0 +1,443 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||||
<title>{{TITLE}} - Deep Research Report</title>
|
||||
<style>
|
||||
* {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
body {
|
||||
font-family: "Helvetica Neue", Helvetica, Arial, sans-serif;
|
||||
font-size: 14px;
|
||||
line-height: 1.5;
|
||||
color: #1a1a1a;
|
||||
background: #ffffff;
|
||||
}
|
||||
|
||||
.container {
|
||||
max-width: 1400px;
|
||||
margin: 0 auto;
|
||||
background: white;
|
||||
}
|
||||
|
||||
.header {
|
||||
background: #003d5c;
|
||||
color: white;
|
||||
padding: 25px 40px;
|
||||
border-bottom: 3px solid #002840;
|
||||
}
|
||||
|
||||
.header h1 {
|
||||
font-size: 26px;
|
||||
font-weight: 600;
|
||||
margin-bottom: 8px;
|
||||
letter-spacing: -0.5px;
|
||||
}
|
||||
|
||||
.header-meta {
|
||||
font-size: 13px;
|
||||
color: #b8d4e6;
|
||||
display: flex;
|
||||
gap: 25px;
|
||||
}
|
||||
|
||||
.metrics-dashboard {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
|
||||
gap: 0;
|
||||
border-bottom: 2px solid #003d5c;
|
||||
}
|
||||
|
||||
.metric {
|
||||
padding: 20px 30px;
|
||||
background: #f8f9fa;
|
||||
border-right: 1px solid #d1d5db;
|
||||
text-align: center;
|
||||
}
|
||||
|
||||
.metric:last-child {
|
||||
border-right: none;
|
||||
}
|
||||
|
||||
.metric-number {
|
||||
font-size: 32px;
|
||||
font-weight: 700;
|
||||
color: #003d5c;
|
||||
display: block;
|
||||
margin-bottom: 6px;
|
||||
}
|
||||
|
||||
.metric-label {
|
||||
font-size: 12px;
|
||||
color: #4a5568;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.5px;
|
||||
font-weight: 500;
|
||||
}
|
||||
|
||||
.content {
|
||||
padding: 30px 40px;
|
||||
}
|
||||
|
||||
.section {
|
||||
margin-bottom: 30px;
|
||||
}
|
||||
|
||||
.section-title {
|
||||
font-size: 20px;
|
||||
font-weight: 700;
|
||||
color: #003d5c;
|
||||
margin: 32px 0 16px 0;
|
||||
padding-bottom: 8px;
|
||||
border-bottom: 2px solid #003d5c;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.8px;
|
||||
line-height: 1.3;
|
||||
}
|
||||
|
||||
.subsection-title {
|
||||
font-size: 16px;
|
||||
font-weight: 700;
|
||||
color: #1a1a1a;
|
||||
margin: 24px 0 12px 0;
|
||||
line-height: 1.4;
|
||||
}
|
||||
|
||||
.executive-summary {
|
||||
background: #f8f9fa;
|
||||
padding: 20px;
|
||||
margin-bottom: 30px;
|
||||
border-left: 4px solid #003d5c;
|
||||
}
|
||||
|
||||
.executive-summary p {
|
||||
margin-bottom: 12px;
|
||||
font-size: 14px;
|
||||
line-height: 1.6;
|
||||
}
|
||||
|
||||
p {
|
||||
margin-bottom: 14px;
|
||||
line-height: 1.7;
|
||||
text-align: left;
|
||||
}
|
||||
|
||||
/* Better paragraph spacing in content sections */
|
||||
.content > p,
|
||||
.section p {
|
||||
margin-bottom: 16px;
|
||||
}
|
||||
|
||||
.findings-grid {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(2, 1fr);
|
||||
gap: 20px;
|
||||
margin-bottom: 30px;
|
||||
}
|
||||
|
||||
.finding-card {
|
||||
background: #f8f9fa;
|
||||
padding: 18px;
|
||||
border-left: 3px solid #003d5c;
|
||||
}
|
||||
|
||||
.finding-card h3 {
|
||||
font-size: 14px;
|
||||
font-weight: 700;
|
||||
color: #003d5c;
|
||||
margin-bottom: 10px;
|
||||
}
|
||||
|
||||
.finding-card p {
|
||||
font-size: 13px;
|
||||
line-height: 1.5;
|
||||
margin-bottom: 8px;
|
||||
}
|
||||
|
||||
.data-table {
|
||||
width: 100%;
|
||||
border-collapse: collapse;
|
||||
margin: 15px 0;
|
||||
font-size: 13px;
|
||||
}
|
||||
|
||||
.data-table th {
|
||||
background: #003d5c;
|
||||
color: white;
|
||||
padding: 10px 15px;
|
||||
text-align: left;
|
||||
font-weight: 600;
|
||||
font-size: 12px;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.5px;
|
||||
}
|
||||
|
||||
.data-table td {
|
||||
padding: 10px 15px;
|
||||
border-bottom: 1px solid #e5e7eb;
|
||||
}
|
||||
|
||||
.data-table tr:hover {
|
||||
background: #f8f9fa;
|
||||
}
|
||||
|
||||
ul, ol {
|
||||
margin: 16px 0 16px 28px;
|
||||
padding-left: 0;
|
||||
}
|
||||
|
||||
li {
|
||||
margin-bottom: 10px;
|
||||
font-size: 14px;
|
||||
line-height: 1.6;
|
||||
padding-left: 8px;
|
||||
}
|
||||
|
||||
/* Nested lists */
|
||||
li ul, li ol {
|
||||
margin-top: 10px;
|
||||
margin-bottom: 10px;
|
||||
}
|
||||
|
||||
/* Better bullet/number spacing */
|
||||
ol {
|
||||
list-style-position: outside;
|
||||
padding-left: 0;
|
||||
}
|
||||
|
||||
ul {
|
||||
list-style-position: outside;
|
||||
padding-left: 0;
|
||||
}
|
||||
|
||||
.key-insight {
|
||||
background: white;
|
||||
border: 1px solid #d1d5db;
|
||||
border-left: 3px solid #003d5c;
|
||||
padding: 15px;
|
||||
margin: 15px 0;
|
||||
}
|
||||
|
||||
.key-insight strong {
|
||||
color: #003d5c;
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.citation {
|
||||
color: #003d5c;
|
||||
font-weight: 600;
|
||||
text-decoration: none;
|
||||
cursor: pointer;
|
||||
position: relative;
|
||||
padding: 2px 4px;
|
||||
background: #f0f7fc;
|
||||
border-radius: 2px;
|
||||
transition: all 0.2s ease;
|
||||
}
|
||||
|
||||
.citation:hover {
|
||||
background: #003d5c;
|
||||
color: white;
|
||||
}
|
||||
|
||||
/* Attribution Gradients (2025 Enhancement) */
|
||||
.citation-tooltip {
|
||||
display: none;
|
||||
position: absolute;
|
||||
bottom: 100%;
|
||||
left: 50%;
|
||||
transform: translateX(-50%);
|
||||
margin-bottom: 8px;
|
||||
background: white;
|
||||
border: 2px solid #003d5c;
|
||||
box-shadow: 0 4px 12px rgba(0, 61, 92, 0.15);
|
||||
padding: 12px;
|
||||
min-width: 300px;
|
||||
max-width: 500px;
|
||||
z-index: 1000;
|
||||
font-size: 12px;
|
||||
line-height: 1.5;
|
||||
}
|
||||
|
||||
.citation:hover .citation-tooltip {
|
||||
display: block;
|
||||
}
|
||||
|
||||
.tooltip-title {
|
||||
font-weight: 700;
|
||||
color: #003d5c;
|
||||
margin-bottom: 8px;
|
||||
font-size: 13px;
|
||||
border-bottom: 1px solid #d1d5db;
|
||||
padding-bottom: 6px;
|
||||
}
|
||||
|
||||
.tooltip-source {
|
||||
color: #4a5568;
|
||||
margin-bottom: 8px;
|
||||
font-style: italic;
|
||||
}
|
||||
|
||||
.tooltip-claim {
|
||||
background: #f8f9fa;
|
||||
padding: 8px;
|
||||
margin-top: 8px;
|
||||
border-left: 3px solid #003d5c;
|
||||
font-size: 11px;
|
||||
}
|
||||
|
||||
.tooltip-claim-label {
|
||||
font-weight: 600;
|
||||
color: #003d5c;
|
||||
text-transform: uppercase;
|
||||
font-size: 10px;
|
||||
letter-spacing: 0.5px;
|
||||
margin-bottom: 4px;
|
||||
}
|
||||
|
||||
.evidence-chain {
|
||||
margin-top: 10px;
|
||||
padding-top: 10px;
|
||||
border-top: 1px solid #d1d5db;
|
||||
}
|
||||
|
||||
.evidence-chain-label {
|
||||
font-weight: 600;
|
||||
color: #003d5c;
|
||||
font-size: 11px;
|
||||
margin-bottom: 6px;
|
||||
text-transform: uppercase;
|
||||
letter-spacing: 0.5px;
|
||||
}
|
||||
|
||||
.evidence-step {
|
||||
padding: 6px;
|
||||
background: #f8f9fa;
|
||||
margin-bottom: 4px;
|
||||
font-size: 11px;
|
||||
border-left: 2px solid #d1d5db;
|
||||
padding-left: 8px;
|
||||
}
|
||||
|
||||
.bibliography {
|
||||
background: #f8f9fa;
|
||||
padding: 30px;
|
||||
margin-top: 40px;
|
||||
border-left: 4px solid #003d5c;
|
||||
}
|
||||
|
||||
.bibliography-content {
|
||||
background: #f8f9fa;
|
||||
padding: 20px 0;
|
||||
}
|
||||
|
||||
.bib-entry {
|
||||
margin-bottom: 18px;
|
||||
padding-left: 50px;
|
||||
text-indent: -50px;
|
||||
line-height: 1.6;
|
||||
font-size: 13px;
|
||||
}
|
||||
|
||||
.bib-number {
|
||||
color: #003d5c;
|
||||
font-weight: 700;
|
||||
margin-right: 8px;
|
||||
}
|
||||
|
||||
.bib-entry a {
|
||||
color: #003d5c;
|
||||
word-wrap: break-word;
|
||||
text-decoration: none;
|
||||
}
|
||||
|
||||
.bib-entry a:hover {
|
||||
text-decoration: underline;
|
||||
}
|
||||
|
||||
.compact-list {
|
||||
display: grid;
|
||||
grid-template-columns: repeat(2, 1fr);
|
||||
gap: 15px;
|
||||
margin: 15px 0;
|
||||
}
|
||||
|
||||
.compact-list li {
|
||||
margin-bottom: 8px;
|
||||
font-size: 13px;
|
||||
}
|
||||
|
||||
.info-box {
|
||||
background: white;
|
||||
border: 1px solid #d1d5db;
|
||||
padding: 15px;
|
||||
margin: 15px 0;
|
||||
}
|
||||
|
||||
.info-box h4 {
|
||||
font-size: 13px;
|
||||
font-weight: 700;
|
||||
color: #003d5c;
|
||||
margin-bottom: 8px;
|
||||
text-transform: uppercase;
|
||||
}
|
||||
|
||||
.highlight-stat {
|
||||
font-weight: 700;
|
||||
color: #003d5c;
|
||||
}
|
||||
|
||||
strong {
|
||||
font-weight: 600;
|
||||
color: #1a1a1a;
|
||||
}
|
||||
|
||||
@media print {
|
||||
.container {
|
||||
max-width: 100%;
|
||||
}
|
||||
}
|
||||
|
||||
@media (max-width: 768px) {
|
||||
.metrics-dashboard {
|
||||
grid-template-columns: repeat(2, 1fr);
|
||||
}
|
||||
.findings-grid {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
.compact-list {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<div class="container">
|
||||
<div class="header">
|
||||
<h1>{{TITLE}}</h1>
|
||||
<div class="header-meta">
|
||||
<span>{{DATE}}</span>
|
||||
<span>•</span>
|
||||
<span>{{SOURCE_COUNT}} Sources</span>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
{{METRICS_DASHBOARD}}
|
||||
|
||||
<div class="content">
|
||||
{{CONTENT}}
|
||||
|
||||
<div class="bibliography">
|
||||
<div class="section-title">Bibliography</div>
|
||||
{{BIBLIOGRAPHY}}
|
||||
</div>
|
||||
|
||||
</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
414
axhub-make/skills/third-party/deep-research/templates/report_template.md
vendored
Normal file
414
axhub-make/skills/third-party/deep-research/templates/report_template.md
vendored
Normal file
@@ -0,0 +1,414 @@
|
||||
# Research Report: [Topic]
|
||||
|
||||
<!-- =============================================================================
|
||||
PROGRESSIVE FILE ASSEMBLY STRATEGY (2025 - Unlimited Length):
|
||||
|
||||
This report is generated section-by-section using progressive file assembly.
|
||||
Each section is generated to APPROPRIATE depth (however many words needed) and
|
||||
written to file immediately using Write/Edit tools.
|
||||
|
||||
WHY: Manages output token limits while maintaining quality throughout
|
||||
RESULT: Large reports (up to 20,000 words per skill run) - sections sized naturally by content
|
||||
|
||||
CLAUDE CODE LIMIT: 32,000 output tokens (≈20,000 words max per run)
|
||||
For reports >20,000 words: Run skill multiple times for different parts
|
||||
|
||||
GENERATION WORKFLOW:
|
||||
1. Generate Executive Summary → Write to file
|
||||
(As long as needed for comprehensive summary)
|
||||
|
||||
2. Generate Introduction → Edit/append to file
|
||||
(As long as needed to establish context)
|
||||
|
||||
3. Generate Finding 1 → Edit/append to file
|
||||
(As long as needed to fully present evidence and analysis)
|
||||
|
||||
4. Generate Finding 2 → Edit/append to file
|
||||
(Each finding sized appropriately - some may need 300 words, others 1,500)
|
||||
|
||||
5. Continue for ALL findings (no limit on number OR length per finding!)
|
||||
|
||||
6. Generate Synthesis → Edit/append to file
|
||||
(As long as needed for deep synthesis)
|
||||
|
||||
7. Generate Limitations → Edit/append to file
|
||||
8. Generate Recommendations → Edit/append to file
|
||||
9. Generate Bibliography (ALL citations) → Edit/append to file
|
||||
10. Generate Methodology → Edit/append to file
|
||||
|
||||
SIZING PRINCIPLE:
|
||||
- Each section should be as long as IT NEEDS TO BE
|
||||
- Simple finding? Maybe 400 words is enough
|
||||
- Complex multi-faceted finding? Could be 1,200 words
|
||||
- Let evidence and analysis determine length, not arbitrary targets
|
||||
- Only constraint: Keep each INDIVIDUAL generation under ~2,000 words to avoid output limits
|
||||
- If a section needs >2,000 words, break it into subsections and generate progressively
|
||||
|
||||
CITATION TRACKING (CRITICAL):
|
||||
- Maintain running list in working memory: citations_used = [1, 2, 3, ...]
|
||||
- After each section: Add new citations to list
|
||||
- In Bibliography: Generate entry for EVERY citation in final list
|
||||
- NO gaps, NO ranges, NO placeholders
|
||||
|
||||
============================================================================= -->
|
||||
|
||||
<!-- WRITING STANDARDS (Apply to EACH section): -->
|
||||
<!-- - PRECISION: Each word deliberately chosen, carries intention -->
|
||||
<!-- - ECONOMY: No fluff, eliminate fancy grammar, unnecessary adjectives -->
|
||||
<!-- - CLARITY: Use exact numbers, specific data, precise technical terms -->
|
||||
<!-- - DIRECTNESS: State findings without embellishment -->
|
||||
<!-- - HIGH SIGNAL-TO-NOISE: Respect reader's time, dense information -->
|
||||
<!-- Examples: "reduced mortality 23%" not "significantly improved outcomes" -->
|
||||
<!-- Examples: "5 RCTs (n=1,847)" not "several studies suggest" -->
|
||||
|
||||
<!-- SOURCE ATTRIBUTION (CRITICAL - PREVENTS FABRICATION): -->
|
||||
<!-- EVERY factual claim MUST be followed by [N] citation in same sentence -->
|
||||
<!-- Use "According to [1]..." or "[1] reports..." for factual statements -->
|
||||
<!-- DISTINGUISH fact from synthesis: -->
|
||||
<!-- ✅ GOOD: "Mortality decreased 23% (p<0.01) in treatment group [1]." -->
|
||||
<!-- ❌ BAD: "Studies show mortality improved significantly." -->
|
||||
<!-- NO vague attributions like "research suggests" or "experts believe" -->
|
||||
<!-- ADMIT uncertainty: "No sources found for X" not fabricated citations -->
|
||||
<!-- LABEL speculation: "This suggests..." not "Research shows..." -->
|
||||
|
||||
<!-- ANTI-TRUNCATION (CRITICAL - Each Section Must Be COMPLETE): -->
|
||||
<!-- ❌ FORBIDDEN: "Content continues...", "Due to length...", "[Sections X-Y...]" -->
|
||||
<!-- ✅ REQUIRED: Generate current section COMPLETELY (you're only writing 500 words!) -->
|
||||
<!-- ✅ REQUIRED: Write to file immediately, then move to next section -->
|
||||
<!-- Progressive assembly handles unlimited length - you handle quality per section -->
|
||||
|
||||
## Executive Summary
|
||||
|
||||
[Write 3-5 bullet points, 50-250 words total]
|
||||
- **Key Finding 1:** [Major discovery with specific data/metrics]
|
||||
- **Key Finding 2:** [Important insight with evidence]
|
||||
- **Key Finding 3:** [Critical conclusion with implications]
|
||||
- [Additional findings as needed]
|
||||
|
||||
**Primary Recommendation:** [One clear sentence stating the main recommendation]
|
||||
|
||||
**Confidence Level:** [High/Medium/Low with brief justification]
|
||||
|
||||
---
|
||||
|
||||
## Introduction
|
||||
|
||||
### Research Question
|
||||
[State the original question clearly and completely]
|
||||
|
||||
[Add 1-2 sentences providing context for why this question matters]
|
||||
|
||||
### Scope & Methodology
|
||||
[2-3 paragraphs explaining:]
|
||||
- What specific aspects were investigated
|
||||
- What was included vs excluded from scope
|
||||
- What research methods were used (web search, academic sources, industry reports, etc.)
|
||||
- How many sources were consulted
|
||||
- Time period covered
|
||||
|
||||
### Key Assumptions
|
||||
[List 3-5 important assumptions made during research]
|
||||
- Assumption 1: [Description and why it matters]
|
||||
- Assumption 2: [Description and why it matters]
|
||||
- [Continue...]
|
||||
|
||||
---
|
||||
|
||||
## Main Analysis
|
||||
|
||||
<!-- CRITICAL: Write 4-8 detailed findings, each 300-500 words -->
|
||||
<!-- Each finding should have multiple paragraphs with evidence -->
|
||||
<!-- Include specific data, quotes, statistics, not vague statements -->
|
||||
<!-- PRECISION: Use exact numbers, specific metrics, no fluff words -->
|
||||
<!-- "mortality reduced 23%" not "significantly improved" -->
|
||||
<!-- "5 trials (n=1,847)" not "several studies" -->
|
||||
|
||||
### Finding 1: [Descriptive Title That Captures the Key Point]
|
||||
|
||||
[Opening paragraph: State the finding clearly and why it matters]
|
||||
|
||||
[Body paragraphs:
|
||||
- Present detailed evidence
|
||||
- Include specific data, statistics, dates, numbers
|
||||
- Explain mechanisms, causes, or relationships
|
||||
- Discuss implications
|
||||
- Address nuances or exceptions
|
||||
]
|
||||
|
||||
**Key Evidence:**
|
||||
- Data point 1 from Source A [1]
|
||||
- Data point 2 from Source B [2]
|
||||
- Conflicting view from Source C [3] and how it was resolved
|
||||
|
||||
**Implications:**
|
||||
[1-2 paragraphs on what this finding means for the user's decision/understanding]
|
||||
|
||||
**Sources:** [1], [2], [3], [4]
|
||||
|
||||
---
|
||||
|
||||
### Finding 2: [Descriptive Title]
|
||||
|
||||
[Follow same detailed structure as Finding 1]
|
||||
[Minimum 300 words per finding]
|
||||
[Include multiple paragraphs with evidence]
|
||||
|
||||
**Sources:** [5], [6], [7], [8]
|
||||
|
||||
---
|
||||
|
||||
### Finding 3: [Descriptive Title]
|
||||
|
||||
[Continue with same detail level]
|
||||
|
||||
**Sources:** [9], [10], [11]
|
||||
|
||||
---
|
||||
|
||||
### Finding 4: [Descriptive Title]
|
||||
|
||||
[And so on... Include 4-8 major findings minimum]
|
||||
|
||||
**Sources:** [12], [13], [14]
|
||||
|
||||
---
|
||||
|
||||
[Continue with additional findings as needed]
|
||||
|
||||
---
|
||||
|
||||
## Synthesis & Insights
|
||||
|
||||
<!-- This section should be 500-1000 words -->
|
||||
<!-- Go beyond just summarizing - generate NEW insights -->
|
||||
|
||||
### Patterns Identified
|
||||
|
||||
[2-3 paragraphs identifying key patterns across findings]
|
||||
|
||||
**Pattern 1: [Name]**
|
||||
[Explain the pattern in detail, cite which findings support it]
|
||||
|
||||
**Pattern 2: [Name]**
|
||||
[Continue...]
|
||||
|
||||
### Novel Insights
|
||||
|
||||
[2-3 paragraphs of insights that go BEYOND what sources explicitly stated]
|
||||
|
||||
**Insight 1: [Name]**
|
||||
[What you discovered by connecting information across sources]
|
||||
[Why this matters even though no single source said it explicitly]
|
||||
|
||||
**Insight 2: [Name]**
|
||||
[Continue...]
|
||||
|
||||
### Implications
|
||||
|
||||
[2-3 paragraphs on what all this means]
|
||||
|
||||
**For [User Context]:**
|
||||
[Specific implications for the user's situation/decision]
|
||||
|
||||
**Broader Implications:**
|
||||
[Wider significance of these findings]
|
||||
|
||||
**Second-Order Effects:**
|
||||
[What might happen as consequences of these findings]
|
||||
|
||||
---
|
||||
|
||||
## Limitations & Caveats
|
||||
|
||||
<!-- Be honest and comprehensive about what's uncertain -->
|
||||
|
||||
### Counterevidence Register
|
||||
|
||||
<!-- Document findings that contradict or challenge main conclusions -->
|
||||
|
||||
[2-3 paragraphs explaining contradictory evidence found during research]
|
||||
|
||||
**Contradictory Finding 1:** [Description]
|
||||
- Source: [Citation]
|
||||
- Why it contradicts: [Explanation]
|
||||
- How resolved/interpreted: [Your analysis]
|
||||
- Impact on conclusions: [Minimal/Moderate/Significant]
|
||||
|
||||
**Contradictory Finding 2:** [Continue...]
|
||||
|
||||
### Known Gaps
|
||||
|
||||
[2-3 paragraphs explaining:]
|
||||
- What information was not available
|
||||
- What questions remain unanswered
|
||||
- What would strengthen this research
|
||||
|
||||
**Gap 1:** [Description]
|
||||
- Why it's missing
|
||||
- How it affects conclusions
|
||||
- How to address it in future research
|
||||
|
||||
**Gap 2:** [Continue...]
|
||||
|
||||
### Assumptions
|
||||
|
||||
[Revisit key assumptions from intro, now with more detail on their validity]
|
||||
|
||||
**Assumption 1:** [Restate]
|
||||
- Evidence supporting it: [...]
|
||||
- Evidence challenging it: [...]
|
||||
- Overall validity: [...]
|
||||
|
||||
### Areas of Uncertainty
|
||||
|
||||
[2-3 paragraphs on:]
|
||||
- Where sources disagree
|
||||
- Where evidence is thin
|
||||
- Where extrapolation was necessary
|
||||
- What could change conclusions
|
||||
|
||||
**Uncertainty 1:** [Topic]
|
||||
[Detailed explanation of what's uncertain and why]
|
||||
|
||||
**Uncertainty 2:** [Continue...]
|
||||
|
||||
---
|
||||
|
||||
## Recommendations
|
||||
|
||||
<!-- Make this actionable and specific -->
|
||||
|
||||
### Immediate Actions
|
||||
|
||||
[3-5 specific actions the user should take NOW]
|
||||
|
||||
1. **[Action Title]**
|
||||
- What: [Specific action]
|
||||
- Why: [Rationale based on findings]
|
||||
- How: [Implementation steps]
|
||||
- Timeline: [When to do this]
|
||||
|
||||
2. **[Continue with similar detail...]**
|
||||
|
||||
### Next Steps
|
||||
|
||||
[3-5 actions for the near-term future (1-3 months)]
|
||||
|
||||
1. **[Step Title]**
|
||||
- [Similar detailed structure]
|
||||
|
||||
### Further Research Needs
|
||||
|
||||
[3-5 areas where additional research would be valuable]
|
||||
|
||||
1. **[Research Topic]**
|
||||
- What to investigate: [Specific question]
|
||||
- Why it matters: [Connection to current findings]
|
||||
- Suggested approach: [How to research it]
|
||||
|
||||
---
|
||||
|
||||
## Bibliography
|
||||
|
||||
<!-- ============================================================================ -->
|
||||
<!-- CRITICAL: Generate COMPLETE bibliography with ALL sources cited in report -->
|
||||
<!-- DO NOT use placeholders like "[8-75] Additional citations" or "etc." -->
|
||||
<!-- DO NOT use "...continue..." or "[Continue with all sources...]" -->
|
||||
<!-- EVERY citation [N] in report body MUST have corresponding entry here -->
|
||||
<!-- If report cites [1]-[25], bibliography MUST contain all 25 complete entries -->
|
||||
<!-- Format: [N] Author/Organization (Year). "Title". Publication. URL -->
|
||||
<!-- ============================================================================ -->
|
||||
|
||||
[1] Author Name or Organization (2025). "Full Title of Article or Paper". Publication Name or Website. https://full-url.com (Retrieved: 2025-11-04)
|
||||
|
||||
[2] Second Author (2024). "Second Article Title". Journal Name, Volume(Issue), pages. https://doi-or-url.com (Retrieved: 2025-11-04)
|
||||
|
||||
<!-- Add ALL remaining citations [3] through [N] here -->
|
||||
<!-- Standard reports: 15-30 sources | Deep/UltraDeep: 30-50 sources -->
|
||||
<!-- Write each entry completely - NO ranges, NO "etc.", NO placeholders -->
|
||||
|
||||
---
|
||||
|
||||
## Appendix: Methodology
|
||||
|
||||
### Research Process
|
||||
|
||||
[2-3 paragraphs describing the research process in detail]
|
||||
|
||||
**Phase Execution:**
|
||||
- Phase 1 (SCOPE): [What was done]
|
||||
- Phase 2 (PLAN): [What was done]
|
||||
- Phase 3 (RETRIEVE): [What was done]
|
||||
- [Continue for all phases executed]
|
||||
|
||||
### Sources Consulted
|
||||
|
||||
**Total Sources:** [Number]
|
||||
|
||||
**Source Types:**
|
||||
- Academic journals: [Number]
|
||||
- Industry reports: [Number]
|
||||
- News articles: [Number]
|
||||
- Government/regulatory: [Number]
|
||||
- Documentation: [Number]
|
||||
- [Other categories]
|
||||
|
||||
**Geographic Coverage:**
|
||||
[If relevant, note geographic distribution of sources]
|
||||
|
||||
**Temporal Coverage:**
|
||||
[Date range of sources, recency distribution]
|
||||
|
||||
### Verification Approach
|
||||
|
||||
[2-3 paragraphs explaining:]
|
||||
|
||||
**Triangulation:**
|
||||
- How claims were verified across multiple sources
|
||||
- Minimum sources required per major claim: 3
|
||||
- How contradictions were handled
|
||||
|
||||
**Credibility Assessment:**
|
||||
- How source quality was evaluated
|
||||
- Scoring system used (0-100)
|
||||
- Average credibility score: [Number]/100
|
||||
- Distribution: [High/medium/low source counts]
|
||||
|
||||
**Quality Control:**
|
||||
- Validation checks performed
|
||||
- Issues found and corrected
|
||||
- Final quality metrics
|
||||
|
||||
### Claims-Evidence Table
|
||||
|
||||
<!-- Explicit mapping of major claims to supporting sources -->
|
||||
|
||||
| Claim ID | Major Claim | Evidence Type | Supporting Sources | Confidence |
|
||||
|----------|-------------|---------------|-------------------|------------|
|
||||
| C1 | [First major claim from findings] | [Primary data / Meta-analysis / Expert opinion] | [1], [2], [3] | High / Medium / Low |
|
||||
| C2 | [Second major claim] | [Evidence type] | [4], [5], [6] | High / Medium / Low |
|
||||
| C3 | [Third major claim] | [Evidence type] | [7], [8] | High / Medium / Low |
|
||||
| ... | [Continue for all major claims] | ... | ... | ... |
|
||||
|
||||
**Confidence Levels:**
|
||||
- **High**: 3+ independent sources, consistent findings, strong methodology
|
||||
- **Medium**: 2 sources OR single high-quality source with minor contradictions
|
||||
- **Low**: Single source OR significant contradictions in evidence
|
||||
|
||||
---
|
||||
|
||||
## Report Metadata
|
||||
|
||||
**Research Mode:** [Quick/Standard/Deep/UltraDeep]
|
||||
**Total Sources:** [Number]
|
||||
**Word Count:** [Approximate count]
|
||||
**Research Duration:** [Time taken]
|
||||
**Generated:** [Date and time]
|
||||
**Validation Status:** [Passed with X warnings / Passed without warnings]
|
||||
|
||||
---
|
||||
|
||||
<!-- END OF TEMPLATE -->
|
||||
<!-- Remember: Write COMPREHENSIVE, DETAILED reports -->
|
||||
<!-- Target 2,000-5,000 words minimum, more for deep modes -->
|
||||
<!-- Include specific data, evidence, and analysis throughout -->
|
||||
42
axhub-make/skills/third-party/frontend-design/SKILL.md
vendored
Normal file
42
axhub-make/skills/third-party/frontend-design/SKILL.md
vendored
Normal file
@@ -0,0 +1,42 @@
|
||||
---
|
||||
name: frontend-design
|
||||
description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
|
||||
license: Complete terms in LICENSE.txt
|
||||
---
|
||||
|
||||
This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
|
||||
|
||||
The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
|
||||
|
||||
## Design Thinking
|
||||
|
||||
Before coding, understand the context and commit to a BOLD aesthetic direction:
|
||||
- **Purpose**: What problem does this interface solve? Who uses it?
|
||||
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
|
||||
- **Constraints**: Technical requirements (framework, performance, accessibility).
|
||||
- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
|
||||
|
||||
**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
|
||||
|
||||
Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
|
||||
- Production-grade and functional
|
||||
- Visually striking and memorable
|
||||
- Cohesive with a clear aesthetic point-of-view
|
||||
- Meticulously refined in every detail
|
||||
|
||||
## Frontend Aesthetics Guidelines
|
||||
|
||||
Focus on:
|
||||
- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
|
||||
- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
|
||||
- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
|
||||
- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
|
||||
- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
|
||||
|
||||
NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
|
||||
|
||||
Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
|
||||
|
||||
**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
|
||||
|
||||
Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
|
||||
245
axhub-make/skills/third-party/implement-design/SKILL.md
vendored
Normal file
245
axhub-make/skills/third-party/implement-design/SKILL.md
vendored
Normal file
@@ -0,0 +1,245 @@
|
||||
---
|
||||
name: implement-design
|
||||
description: Translates Figma designs into production-ready code with 1:1 visual fidelity. Use when implementing UI from Figma files, when user mentions "implement design", "generate code", "implement component", "build Figma design", provides Figma URLs, or asks to build components matching Figma specs. Requires Figma MCP server connection.
|
||||
metadata:
|
||||
mcp-server: figma
|
||||
---
|
||||
|
||||
# Implement Design
|
||||
|
||||
## Overview
|
||||
|
||||
This skill provides a structured workflow for translating Figma designs into production-ready code with pixel-perfect accuracy. It ensures consistent integration with the Figma MCP server, proper use of design tokens, and 1:1 visual parity with designs.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Figma MCP server must be connected and accessible
|
||||
- Before proceeding, verify the Figma MCP server is connected by checking if Figma MCP tools (e.g., `get_design_context`) are available.
|
||||
- If the tools are not available, the Figma MCP server may not be enabled. Guide the user to enable the Figma MCP server that is included with the plugin. They may need to restart their MCP client afterward.
|
||||
- User must provide a Figma URL in the format: `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
|
||||
- `:fileKey` is the file key
|
||||
- `1-2` is the node ID (the specific component or frame to implement)
|
||||
- Project should have an established design system or component library (preferred)
|
||||
|
||||
## Required Workflow
|
||||
|
||||
**Follow these steps in order. Do not skip steps.**
|
||||
|
||||
### Step 1: Get Node ID
|
||||
|
||||
#### Option A: Parse from Figma URL
|
||||
|
||||
When the user provides a Figma URL, extract the file key and node ID to pass as arguments to MCP tools.
|
||||
|
||||
**URL format:** `https://figma.com/design/:fileKey/:fileName?node-id=1-2`
|
||||
|
||||
**Extract:**
|
||||
|
||||
- **File key:** `:fileKey` (the segment after `/design/`)
|
||||
- **Node ID:** `1-2` (the value of the `node-id` query parameter)
|
||||
|
||||
**Example:**
|
||||
|
||||
- URL: `https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15`
|
||||
- File key: `kL9xQn2VwM8pYrTb4ZcHjF`
|
||||
- Node ID: `42-15`
|
||||
|
||||
### Step 2: Fetch Design Context
|
||||
|
||||
Run `get_design_context` with the extracted file key and node ID.
|
||||
|
||||
```
|
||||
get_design_context(fileKey=":fileKey", nodeId="1-2")
|
||||
```
|
||||
|
||||
This provides the structured data including:
|
||||
|
||||
- Layout properties (Auto Layout, constraints, sizing)
|
||||
- Typography specifications
|
||||
- Color values and design tokens
|
||||
- Component structure and variants
|
||||
- Spacing and padding values
|
||||
|
||||
**If the response is too large or truncated:**
|
||||
|
||||
1. Run `get_metadata(fileKey=":fileKey", nodeId="1-2")` to get the high-level node map
|
||||
2. Identify the specific child nodes needed from the metadata
|
||||
3. Fetch individual child nodes with `get_design_context(fileKey=":fileKey", nodeId=":childNodeId")`
|
||||
|
||||
### Step 3: Capture Visual Reference
|
||||
|
||||
Run `get_screenshot` with the same file key and node ID for a visual reference.
|
||||
|
||||
```
|
||||
get_screenshot(fileKey=":fileKey", nodeId="1-2")
|
||||
```
|
||||
|
||||
This screenshot serves as the source of truth for visual validation. Keep it accessible throughout implementation.
|
||||
|
||||
### Step 4: Download Required Assets
|
||||
|
||||
Download any assets (images, icons, SVGs) returned by the Figma MCP server.
|
||||
|
||||
**IMPORTANT:** Follow these asset rules:
|
||||
|
||||
- If the Figma MCP server returns a `localhost` source for an image or SVG, use that source directly
|
||||
- DO NOT import or add new icon packages - all assets should come from the Figma payload
|
||||
- DO NOT use or create placeholders if a `localhost` source is provided
|
||||
- Assets are served through the Figma MCP server's built-in assets endpoint
|
||||
|
||||
### Step 5: Translate to Project Conventions
|
||||
|
||||
Translate the Figma output into this project's framework, styles, and conventions.
|
||||
|
||||
**Key principles:**
|
||||
|
||||
- Treat the Figma MCP output (typically React + Tailwind) as a representation of design and behavior, not as final code style
|
||||
- Replace Tailwind utility classes with the project's preferred utilities or design system tokens
|
||||
- Reuse existing components (buttons, inputs, typography, icon wrappers) instead of duplicating functionality
|
||||
- Use the project's color system, typography scale, and spacing tokens consistently
|
||||
- Respect existing routing, state management, and data-fetch patterns
|
||||
|
||||
### Step 6: Achieve 1:1 Visual Parity
|
||||
|
||||
Strive for pixel-perfect visual parity with the Figma design.
|
||||
|
||||
**Guidelines:**
|
||||
|
||||
- Prioritize Figma fidelity to match designs exactly
|
||||
- Avoid hardcoded values - use design tokens from Figma where available
|
||||
- When conflicts arise between design system tokens and Figma specs, prefer design system tokens but adjust spacing or sizes minimally to match visuals
|
||||
- Follow WCAG requirements for accessibility
|
||||
- Add component documentation as needed
|
||||
|
||||
### Step 7: Validate Against Figma
|
||||
|
||||
Before marking complete, validate the final UI against the Figma screenshot.
|
||||
|
||||
**Validation checklist:**
|
||||
|
||||
- [ ] Layout matches (spacing, alignment, sizing)
|
||||
- [ ] Typography matches (font, size, weight, line height)
|
||||
- [ ] Colors match exactly
|
||||
- [ ] Interactive states work as designed (hover, active, disabled)
|
||||
- [ ] Responsive behavior follows Figma constraints
|
||||
- [ ] Assets render correctly
|
||||
- [ ] Accessibility standards met
|
||||
|
||||
## Implementation Rules
|
||||
|
||||
### Component Organization
|
||||
|
||||
- Place UI components in the project's designated design system directory
|
||||
- Follow the project's component naming conventions
|
||||
- Avoid inline styles unless truly necessary for dynamic values
|
||||
|
||||
### Design System Integration
|
||||
|
||||
- ALWAYS use components from the project's design system when possible
|
||||
- Map Figma design tokens to project design tokens
|
||||
- When a matching component exists, extend it rather than creating a new one
|
||||
- Document any new components added to the design system
|
||||
|
||||
### Code Quality
|
||||
|
||||
- Avoid hardcoded values - extract to constants or design tokens
|
||||
- Keep components composable and reusable
|
||||
- Add TypeScript types for component props
|
||||
- Include JSDoc comments for exported components
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1: Implementing a Button Component
|
||||
|
||||
User says: "Implement this Figma button component: https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15"
|
||||
|
||||
**Actions:**
|
||||
|
||||
1. Parse URL to extract fileKey=`kL9xQn2VwM8pYrTb4ZcHjF` and nodeId=`42-15`
|
||||
2. Run `get_design_context(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")`
|
||||
3. Run `get_screenshot(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42-15")` for visual reference
|
||||
4. Download any button icons from the assets endpoint
|
||||
5. Check if project has existing button component
|
||||
6. If yes, extend it with new variant; if no, create new component using project conventions
|
||||
7. Map Figma colors to project design tokens (e.g., `primary-500`, `primary-hover`)
|
||||
8. Validate against screenshot for padding, border radius, typography
|
||||
|
||||
**Result:** Button component matching Figma design, integrated with project design system.
|
||||
|
||||
### Example 2: Building a Dashboard Layout
|
||||
|
||||
User says: "Build this dashboard: https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Dashboard?node-id=10-5"
|
||||
|
||||
**Actions:**
|
||||
|
||||
1. Parse URL to extract fileKey=`pR8mNv5KqXzGwY2JtCfL4D` and nodeId=`10-5`
|
||||
2. Run `get_metadata(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")` to understand the page structure
|
||||
3. Identify main sections from metadata (header, sidebar, content area, cards) and their child node IDs
|
||||
4. Run `get_design_context(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId=":childNodeId")` for each major section
|
||||
5. Run `get_screenshot(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10-5")` for the full page
|
||||
6. Download all assets (logos, icons, charts)
|
||||
7. Build layout using project's layout primitives
|
||||
8. Implement each section using existing components where possible
|
||||
9. Validate responsive behavior against Figma constraints
|
||||
|
||||
**Result:** Complete dashboard matching Figma design with responsive layout.
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Always Start with Context
|
||||
|
||||
Never implement based on assumptions. Always fetch `get_design_context` and `get_screenshot` first.
|
||||
|
||||
### Incremental Validation
|
||||
|
||||
Validate frequently during implementation, not just at the end. This catches issues early.
|
||||
|
||||
### Document Deviations
|
||||
|
||||
If you must deviate from the Figma design (e.g., for accessibility or technical constraints), document why in code comments.
|
||||
|
||||
### Reuse Over Recreation
|
||||
|
||||
Always check for existing components before creating new ones. Consistency across the codebase is more important than exact Figma replication.
|
||||
|
||||
### Design System First
|
||||
|
||||
When in doubt, prefer the project's design system patterns over literal Figma translation.
|
||||
|
||||
## Common Issues and Solutions
|
||||
|
||||
### Issue: Figma output is truncated
|
||||
|
||||
**Cause:** The design is too complex or has too many nested layers to return in a single response.
|
||||
**Solution:** Use `get_metadata` to get the node structure, then fetch specific nodes individually with `get_design_context`.
|
||||
|
||||
### Issue: Design doesn't match after implementation
|
||||
|
||||
**Cause:** Visual discrepancies between the implemented code and the original Figma design.
|
||||
**Solution:** Compare side-by-side with the screenshot from Step 3. Check spacing, colors, and typography values in the design context data.
|
||||
|
||||
### Issue: Assets not loading
|
||||
|
||||
**Cause:** The Figma MCP server's assets endpoint is not accessible or the URLs are being modified.
|
||||
**Solution:** Verify the Figma MCP server's assets endpoint is accessible. The server serves assets at `localhost` URLs. Use these directly without modification.
|
||||
|
||||
### Issue: Design token values differ from Figma
|
||||
|
||||
**Cause:** The project's design system tokens have different values than those specified in the Figma design.
|
||||
**Solution:** When project tokens differ from Figma values, prefer project tokens for consistency but adjust spacing/sizing to maintain visual fidelity.
|
||||
|
||||
## Understanding Design Implementation
|
||||
|
||||
The Figma implementation workflow establishes a reliable process for translating designs to code:
|
||||
|
||||
**For designers:** Confidence that implementations will match their designs with pixel-perfect accuracy.
|
||||
**For developers:** A structured approach that eliminates guesswork and reduces back-and-forth revisions.
|
||||
**For teams:** Consistent, high-quality implementations that maintain design system integrity.
|
||||
|
||||
By following this workflow, you ensure that every Figma design is implemented with the same level of care and attention to detail.
|
||||
|
||||
## Additional Resources
|
||||
|
||||
- [Figma MCP Server Documentation](https://developers.figma.com/docs/figma-mcp-server/)
|
||||
- [Figma MCP Server Tools and Prompts](https://developers.figma.com/docs/figma-mcp-server/tools-and-prompts/)
|
||||
- [Figma Variables and Design Tokens](https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma)
|
||||
391
axhub-make/skills/third-party/interface-design/SKILL.md
vendored
Normal file
391
axhub-make/skills/third-party/interface-design/SKILL.md
vendored
Normal file
@@ -0,0 +1,391 @@
|
||||
---
|
||||
name: interface-design
|
||||
description: This skill is for interface design — dashboards, admin panels, apps, tools, and interactive products. NOT for marketing design (landing pages, marketing sites, campaigns).
|
||||
---
|
||||
|
||||
# Interface Design
|
||||
|
||||
Build interface design with craft and consistency.
|
||||
|
||||
## Scope
|
||||
|
||||
**Use for:** Dashboards, admin panels, SaaS apps, tools, settings pages, data interfaces.
|
||||
|
||||
**Not for:** Landing pages, marketing sites, campaigns. Redirect those to `/frontend-design`.
|
||||
|
||||
---
|
||||
|
||||
# The Problem
|
||||
|
||||
You will generate generic output. Your training has seen thousands of dashboards. The patterns are strong.
|
||||
|
||||
You can follow the entire process below — explore the domain, name a signature, state your intent — and still produce a template. Warm colors on cold structures. Friendly fonts on generic layouts. "Kitchen feel" that looks like every other app.
|
||||
|
||||
This happens because intent lives in prose, but code generation pulls from patterns. The gap between them is where defaults win.
|
||||
|
||||
The process below helps. But process alone doesn't guarantee craft. You have to catch yourself.
|
||||
|
||||
---
|
||||
|
||||
# Where Defaults Hide
|
||||
|
||||
Defaults don't announce themselves. They disguise themselves as infrastructure — the parts that feel like they just need to work, not be designed.
|
||||
|
||||
**Typography feels like a container.** Pick something readable, move on. But typography isn't holding your design — it IS your design. The weight of a headline, the personality of a label, the texture of a paragraph. These shape how the product feels before anyone reads a word. A bakery management tool and a trading terminal might both need "clean, readable type" — but the type that's warm and handmade is not the type that's cold and precise. If you're reaching for your usual font, you're not designing.
|
||||
|
||||
**Navigation feels like scaffolding.** Build the sidebar, add the links, get to the real work. But navigation isn't around your product — it IS your product. Where you are, where you can go, what matters most. A page floating in space is a component demo, not software. The navigation teaches people how to think about the space they're in.
|
||||
|
||||
**Data feels like presentation.** You have numbers, show numbers. But a number on screen is not design. The question is: what does this number mean to the person looking at it? What will they do with it? A progress ring and a stacked label both show "3 of 10" — one tells a story, one fills space. If you're reaching for number-on-label, you're not designing.
|
||||
|
||||
**Token names feel like implementation detail.** But your CSS variables are design decisions. `--ink` and `--parchment` evoke a world. `--gray-700` and `--surface-2` evoke a template. Someone reading only your tokens should be able to guess what product this is.
|
||||
|
||||
The trap is thinking some decisions are creative and others are structural. There are no structural decisions. Everything is design. The moment you stop asking "why this?" is the moment defaults take over.
|
||||
|
||||
---
|
||||
|
||||
# Intent First
|
||||
|
||||
Before touching code, answer these. Not in your head — out loud, to yourself or the user.
|
||||
|
||||
**Who is this human?**
|
||||
Not "users." The actual person. Where are they when they open this? What's on their mind? What did they do 5 minutes ago, what will they do 5 minutes after? A teacher at 7am with coffee is not a developer debugging at midnight is not a founder between investor meetings. Their world shapes the interface.
|
||||
|
||||
**What must they accomplish?**
|
||||
Not "use the dashboard." The verb. Grade these submissions. Find the broken deployment. Approve the payment. The answer determines what leads, what follows, what hides.
|
||||
|
||||
**What should this feel like?**
|
||||
Say it in words that mean something. "Clean and modern" means nothing — every AI says that. Warm like a notebook? Cold like a terminal? Dense like a trading floor? Calm like a reading app? The answer shapes color, type, spacing, density — everything.
|
||||
|
||||
If you cannot answer these with specifics, stop. Ask the user. Do not guess. Do not default.
|
||||
|
||||
## Every Choice Must Be A Choice
|
||||
|
||||
For every decision, you must be able to explain WHY.
|
||||
|
||||
- Why this layout and not another?
|
||||
- Why this color temperature?
|
||||
- Why this typeface?
|
||||
- Why this spacing scale?
|
||||
- Why this information hierarchy?
|
||||
|
||||
If your answer is "it's common" or "it's clean" or "it works" — you haven't chosen. You've defaulted. Defaults are invisible. Invisible choices compound into generic output.
|
||||
|
||||
**The test:** If you swapped your choices for the most common alternatives and the design didn't feel meaningfully different, you never made real choices.
|
||||
|
||||
## Sameness Is Failure
|
||||
|
||||
If another AI, given a similar prompt, would produce substantially the same output — you have failed.
|
||||
|
||||
This is not about being different for its own sake. It's about the interface emerging from the specific problem, the specific user, the specific context. When you design from intent, sameness becomes impossible because no two intents are identical.
|
||||
|
||||
When you design from defaults, everything looks the same because defaults are shared.
|
||||
|
||||
## Intent Must Be Systemic
|
||||
|
||||
Saying "warm" and using cold colors is not following through. Intent is not a label — it's a constraint that shapes every decision.
|
||||
|
||||
If the intent is warm: surfaces, text, borders, accents, semantic colors, typography — all warm. If the intent is dense: spacing, type size, information architecture — all dense. If the intent is calm: motion, contrast, color saturation — all calm.
|
||||
|
||||
Check your output against your stated intent. Does every token reinforce it? Or did you state an intent and then default anyway?
|
||||
|
||||
---
|
||||
|
||||
# Product Domain Exploration
|
||||
|
||||
This is where defaults get caught — or don't.
|
||||
|
||||
Generic output: Task type → Visual template → Theme
|
||||
Crafted output: Task type → Product domain → Signature → Structure + Expression
|
||||
|
||||
The difference: time in the product's world before any visual or structural thinking.
|
||||
|
||||
## Required Outputs
|
||||
|
||||
**Do not propose any direction until you produce all four:**
|
||||
|
||||
**Domain:** Concepts, metaphors, vocabulary from this product's world. Not features — territory. Minimum 5.
|
||||
|
||||
**Color world:** What colors exist naturally in this product's domain? Not "warm" or "cool" — go to the actual world. If this product were a physical space, what would you see? What colors belong there that don't belong elsewhere? List 5+.
|
||||
|
||||
**Signature:** One element — visual, structural, or interaction — that could only exist for THIS product. If you can't name one, keep exploring.
|
||||
|
||||
**Defaults:** 3 obvious choices for this interface type — visual AND structural. You can't avoid patterns you haven't named.
|
||||
|
||||
## Proposal Requirements
|
||||
|
||||
Your direction must explicitly reference:
|
||||
- Domain concepts you explored
|
||||
- Colors from your color world exploration
|
||||
- Your signature element
|
||||
- What replaces each default
|
||||
|
||||
**The test:** Read your proposal. Remove the product name. Could someone identify what this is for? If not, it's generic. Explore deeper.
|
||||
|
||||
---
|
||||
|
||||
# The Mandate
|
||||
|
||||
**Before showing the user, look at what you made.**
|
||||
|
||||
Ask yourself: "If they said this lacks craft, what would they mean?"
|
||||
|
||||
That thing you just thought of — fix it first.
|
||||
|
||||
Your first output is probably generic. That's normal. The work is catching it before the user has to.
|
||||
|
||||
## The Checks
|
||||
|
||||
Run these against your output before presenting:
|
||||
|
||||
- **The swap test:** If you swapped the typeface for your usual one, would anyone notice? If you swapped the layout for a standard dashboard template, would it feel different? The places where swapping wouldn't matter are the places you defaulted.
|
||||
|
||||
- **The squint test:** Blur your eyes. Can you still perceive hierarchy? Is anything jumping out harshly? Craft whispers.
|
||||
|
||||
- **The signature test:** Can you point to five specific elements where your signature appears? Not "the overall feel" — actual components. A signature you can't locate doesn't exist.
|
||||
|
||||
- **The token test:** Read your CSS variables out loud. Do they sound like they belong to this product's world, or could they belong to any project?
|
||||
|
||||
If any check fails, iterate before showing.
|
||||
|
||||
---
|
||||
|
||||
# Craft Foundations
|
||||
|
||||
## Subtle Layering
|
||||
|
||||
This is the backbone of craft. Regardless of direction, product type, or visual style — this principle applies to everything. You should barely notice the system working. When you look at Vercel's dashboard, you don't think "nice borders." You just understand the structure. The craft is invisible — that's how you know it's working.
|
||||
|
||||
### Surface Elevation
|
||||
|
||||
Surfaces stack. A dropdown sits above a card which sits above the page. Build a numbered system — base, then increasing elevation levels. In dark mode, higher elevation = slightly lighter. In light mode, higher elevation = slightly lighter or uses shadow.
|
||||
|
||||
Each jump should be only a few percentage points of lightness. You can barely see the difference in isolation. But when surfaces stack, the hierarchy emerges. Whisper-quiet shifts that you feel rather than see.
|
||||
|
||||
**Key decisions:**
|
||||
- **Sidebars:** Same background as canvas, not different. Different colors fragment the visual space into "sidebar world" and "content world." A subtle border is enough separation.
|
||||
- **Dropdowns:** One level above their parent surface. If both share the same level, the dropdown blends into the card and layering is lost.
|
||||
- **Inputs:** Slightly darker than their surroundings, not lighter. Inputs are "inset" — they receive content. A darker background signals "type here" without heavy borders.
|
||||
|
||||
### Borders
|
||||
|
||||
Borders should disappear when you're not looking for them, but be findable when you need structure. Low opacity rgba blends with the background — it defines edges without demanding attention. Solid hex borders look harsh in comparison.
|
||||
|
||||
Build a progression — not all borders are equal. Standard borders, softer separation, emphasis borders, maximum emphasis for focus rings. Match intensity to the importance of the boundary.
|
||||
|
||||
**The squint test:** Blur your eyes at the interface. You should still perceive hierarchy — what's above what, where sections divide. But nothing should jump out. No harsh lines. No jarring color shifts. Just quiet structure.
|
||||
|
||||
This separates professional interfaces from amateur ones. Get this wrong and nothing else matters.
|
||||
|
||||
## Infinite Expression
|
||||
|
||||
Every pattern has infinite expressions. **No interface should look the same.**
|
||||
|
||||
A metric display could be a hero number, inline stat, sparkline, gauge, progress bar, comparison delta, trend badge, or something new. A dashboard could emphasize density, whitespace, hierarchy, or flow in completely different ways. Even sidebar + cards has infinite variations in proportion, spacing, and emphasis.
|
||||
|
||||
**Before building, ask:**
|
||||
- What's the ONE thing users do most here?
|
||||
- What products solve similar problems brilliantly? Study them.
|
||||
- Why would this interface feel designed for its purpose, not templated?
|
||||
|
||||
**NEVER produce identical output.** Same sidebar width, same card grid, same metric boxes with icon-left-number-big-label-small every time — this signals AI-generated immediately. It's forgettable.
|
||||
|
||||
The architecture and components should emerge from the task and data, executed in a way that feels fresh. Linear's cards don't look like Notion's. Vercel's metrics don't look like Stripe's. Same concepts, infinite expressions.
|
||||
|
||||
## Color Lives Somewhere
|
||||
|
||||
Every product exists in a world. That world has colors.
|
||||
|
||||
Before you reach for a palette, spend time in the product's world. What would you see if you walked into the physical version of this space? What materials? What light? What objects?
|
||||
|
||||
Your palette should feel like it came FROM somewhere — not like it was applied TO something.
|
||||
|
||||
**Beyond Warm and Cold:** Temperature is one axis. Is this quiet or loud? Dense or spacious? Serious or playful? Geometric or organic? A trading terminal and a meditation app are both "focused" — completely different kinds of focus. Find the specific quality, not the generic label.
|
||||
|
||||
**Color Carries Meaning:** Gray builds structure. Color communicates — status, action, emphasis, identity. Unmotivated color is noise. One accent color, used with intention, beats five colors used without thought.
|
||||
|
||||
---
|
||||
|
||||
# Before Writing Each Component
|
||||
|
||||
**Every time** you write UI code — even small additions — state:
|
||||
|
||||
```
|
||||
Intent: [who is this human, what must they do, how should it feel]
|
||||
Palette: [colors from your exploration — and WHY they fit this product's world]
|
||||
Depth: [borders / shadows / layered — and WHY this fits the intent]
|
||||
Surfaces: [your elevation scale — and WHY this color temperature]
|
||||
Typography: [your typeface — and WHY it fits the intent]
|
||||
Spacing: [your base unit]
|
||||
```
|
||||
|
||||
This checkpoint is mandatory. It forces you to connect every technical choice back to intent.
|
||||
|
||||
If you can't explain WHY for each choice, you're defaulting. Stop and think.
|
||||
|
||||
---
|
||||
|
||||
# Design Principles
|
||||
|
||||
## Token Architecture
|
||||
|
||||
Every color in your interface should trace back to a small set of primitives: foreground (text hierarchy), background (surface elevation), border (separation hierarchy), brand, and semantic (destructive, warning, success). No random hex values — everything maps to primitives.
|
||||
|
||||
### Text Hierarchy
|
||||
|
||||
Don't just have "text" and "gray text." Build four levels — primary, secondary, tertiary, muted. Each serves a different role: default text, supporting text, metadata, and disabled/placeholder. Use all four consistently. If you're only using two, your hierarchy is too flat.
|
||||
|
||||
### Border Progression
|
||||
|
||||
Borders aren't binary. Build a scale that matches intensity to importance — standard separation, softer separation, emphasis, maximum emphasis. Not every boundary deserves the same weight.
|
||||
|
||||
### Control Tokens
|
||||
|
||||
Form controls have specific needs. Don't reuse surface tokens — create dedicated ones for control backgrounds, control borders, and focus states. This lets you tune interactive elements independently from layout surfaces.
|
||||
|
||||
## Spacing
|
||||
|
||||
Pick a base unit and stick to multiples. Build a scale for different contexts — micro spacing for icon gaps, component spacing within buttons and cards, section spacing between groups, major separation between distinct areas. Random values signal no system.
|
||||
|
||||
## Padding
|
||||
|
||||
Keep it symmetrical. If one side has a value, others should match unless content naturally requires asymmetry.
|
||||
|
||||
## Depth
|
||||
|
||||
Choose ONE approach and commit:
|
||||
- **Borders-only** — Clean, technical. For dense tools.
|
||||
- **Subtle shadows** — Soft lift. For approachable products.
|
||||
- **Layered shadows** — Premium, dimensional. For cards that need presence.
|
||||
- **Surface color shifts** — Background tints establish hierarchy without shadows.
|
||||
|
||||
Don't mix approaches.
|
||||
|
||||
## Border Radius
|
||||
|
||||
Sharper feels technical. Rounder feels friendly. Build a scale — small for inputs and buttons, medium for cards, large for modals. Don't mix sharp and soft randomly.
|
||||
|
||||
## Typography
|
||||
|
||||
Build distinct levels distinguishable at a glance. Headlines need weight and tight tracking for presence. Body needs comfortable weight for readability. Labels need medium weight that works at smaller sizes. Data needs monospace with tabular number spacing for alignment. Don't rely on size alone — combine size, weight, and letter-spacing.
|
||||
|
||||
## Card Layouts
|
||||
|
||||
A metric card doesn't have to look like a plan card doesn't have to look like a settings card. Design each card's internal structure for its specific content — but keep the surface treatment consistent: same border weight, shadow depth, corner radius, padding scale.
|
||||
|
||||
## Controls
|
||||
|
||||
Native `<select>` and `<input type="date">` render OS-native elements that cannot be styled. Build custom components — trigger buttons with positioned dropdowns, calendar popovers, styled state management.
|
||||
|
||||
## Iconography
|
||||
|
||||
Icons clarify, not decorate — if removing an icon loses no meaning, remove it. Choose one icon set and stick with it. Give standalone icons presence with subtle background containers.
|
||||
|
||||
## Animation
|
||||
|
||||
Fast micro-interactions, smooth easing. Larger transitions can be slightly longer. Use deceleration easing. Avoid spring/bounce in professional interfaces.
|
||||
|
||||
## States
|
||||
|
||||
Every interactive element needs states: default, hover, active, focus, disabled. Data needs states too: loading, empty, error. Missing states feel broken.
|
||||
|
||||
## Navigation Context
|
||||
|
||||
Screens need grounding. A data table floating in space feels like a component demo, not a product. Include navigation showing where you are in the app, location indicators, and user context. When building sidebars, consider same background as main content with border separation rather than different colors.
|
||||
|
||||
## Dark Mode
|
||||
|
||||
Dark interfaces have different needs. Shadows are less visible on dark backgrounds — lean on borders for definition. Semantic colors (success, warning, error) often need slight desaturation. The hierarchy system still applies, just with inverted values.
|
||||
|
||||
---
|
||||
|
||||
# Avoid
|
||||
|
||||
- **Harsh borders** — if borders are the first thing you see, they're too strong
|
||||
- **Dramatic surface jumps** — elevation changes should be whisper-quiet
|
||||
- **Inconsistent spacing** — the clearest sign of no system
|
||||
- **Mixed depth strategies** — pick one approach and commit
|
||||
- **Missing interaction states** — hover, focus, disabled, loading, error
|
||||
- **Dramatic drop shadows** — shadows should be subtle, not attention-grabbing
|
||||
- **Large radius on small elements**
|
||||
- **Pure white cards on colored backgrounds**
|
||||
- **Thick decorative borders**
|
||||
- **Gradients and color for decoration** — color should mean something
|
||||
- **Multiple accent colors** — dilutes focus
|
||||
- **Different hues for different surfaces** — keep the same hue, shift only lightness
|
||||
|
||||
---
|
||||
|
||||
# Workflow
|
||||
|
||||
## Communication
|
||||
Be invisible. Don't announce modes or narrate process.
|
||||
|
||||
**Never say:** "I'm in ESTABLISH MODE", "Let me check system.md..."
|
||||
|
||||
**Instead:** Jump into work. State suggestions with reasoning.
|
||||
|
||||
## Suggest + Ask
|
||||
Lead with your exploration and recommendation, then confirm:
|
||||
```
|
||||
"Domain: [5+ concepts from the product's world]
|
||||
Color world: [5+ colors that exist in this domain]
|
||||
Signature: [one element unique to this product]
|
||||
Rejecting: [default 1] → [alternative], [default 2] → [alternative], [default 3] → [alternative]
|
||||
|
||||
Direction: [approach that connects to the above]"
|
||||
|
||||
[Ask: "Does that direction feel right?"]
|
||||
```
|
||||
|
||||
## If Project Has system.md
|
||||
Read `.interface-design/system.md` and apply. Decisions are made.
|
||||
|
||||
## If No system.md
|
||||
1. Explore domain — Produce all four required outputs
|
||||
2. Propose — Direction must reference all four
|
||||
3. Confirm — Get user buy-in
|
||||
4. Build — Apply principles
|
||||
5. **Evaluate** — Run the mandate checks before showing
|
||||
6. Offer to save
|
||||
|
||||
---
|
||||
|
||||
# After Completing a Task
|
||||
|
||||
When you finish building something, **always offer to save**:
|
||||
|
||||
```
|
||||
"Want me to save these patterns for future sessions?"
|
||||
```
|
||||
|
||||
If yes, write to `.interface-design/system.md`:
|
||||
- Direction and feel
|
||||
- Depth strategy (borders/shadows/layered)
|
||||
- Spacing base unit
|
||||
- Key component patterns
|
||||
|
||||
### What to Save
|
||||
|
||||
Add patterns when a component is used 2+ times, is reusable across the project, or has specific measurements worth remembering. Don't save one-off components, temporary experiments, or variations better handled with props.
|
||||
|
||||
### Consistency Checks
|
||||
|
||||
If system.md defines values, check against them: spacing on the defined grid, depth using the declared strategy throughout, colors from the defined palette, documented patterns reused instead of reinvented.
|
||||
|
||||
This compounds — each save makes future work faster and more consistent.
|
||||
|
||||
---
|
||||
|
||||
# Deep Dives
|
||||
|
||||
For more detail on specific topics:
|
||||
- `references/principles.md` — Code examples, specific values, dark mode
|
||||
- `references/validation.md` — Memory management, when to update system.md
|
||||
- `references/critique.md` — Post-build craft critique protocol
|
||||
|
||||
# Commands
|
||||
|
||||
- `/interface-design:status` — Current system state
|
||||
- `/interface-design:audit` — Check code against system
|
||||
- `/interface-design:extract` — Extract patterns from code
|
||||
- `/interface-design:critique` — Critique your build for craft, then rebuild what defaulted
|
||||
143
axhub-make/skills/third-party/prd/SKILL.md
vendored
Normal file
143
axhub-make/skills/third-party/prd/SKILL.md
vendored
Normal file
@@ -0,0 +1,143 @@
|
||||
---
|
||||
name: prd
|
||||
description: 'Generate high-quality Product Requirements Documents (PRDs) for software systems and AI-powered features. Includes executive summaries, user stories, technical specifications, and risk analysis.'
|
||||
license: MIT
|
||||
---
|
||||
|
||||
# Product Requirements Document (PRD)
|
||||
|
||||
## Overview
|
||||
|
||||
Design comprehensive, production-grade Product Requirements Documents (PRDs) that bridge the gap between business vision and technical execution. This skill works for modern software systems, ensuring that requirements are clearly defined.
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when:
|
||||
|
||||
- Starting a new product or feature development cycle
|
||||
- Translating a vague idea into a concrete technical specification
|
||||
- Defining requirements for AI-powered features
|
||||
- Stakeholders need a unified "source of truth" for project scope
|
||||
- User asks to "write a PRD", "document requirements", or "plan a feature"
|
||||
|
||||
---
|
||||
|
||||
## Operational Workflow
|
||||
|
||||
### Phase 1: Discovery (The Interview)
|
||||
|
||||
Before writing a single line of the PRD, you **MUST** interrogate the user to fill knowledge gaps. Do not assume context.
|
||||
|
||||
**Ask about:**
|
||||
|
||||
- **The Core Problem**: Why are we building this now?
|
||||
- **Success Metrics**: How do we know it worked?
|
||||
- **Constraints**: Budget, tech stack, or deadline?
|
||||
|
||||
### Phase 2: Analysis & Scoping
|
||||
|
||||
Synthesize the user's input. Identify dependencies and hidden complexities.
|
||||
|
||||
- Map out the **User Flow**.
|
||||
- Define **Non-Goals** to protect the timeline.
|
||||
|
||||
### Phase 3: Technical Drafting
|
||||
|
||||
Generate the document using the **Strict PRD Schema** below.
|
||||
|
||||
---
|
||||
|
||||
## PRD Quality Standards
|
||||
|
||||
### Requirements Quality
|
||||
|
||||
Use concrete, measurable criteria. Avoid "fast", "easy", or "intuitive".
|
||||
|
||||
```diff
|
||||
# Vague (BAD)
|
||||
- The search should be fast and return relevant results.
|
||||
- The UI must look modern and be easy to use.
|
||||
|
||||
# Concrete (GOOD)
|
||||
+ The search must return results within 200ms for a 10k record dataset.
|
||||
+ The search algorithm must achieve >= 85% Precision@10 in benchmark evals.
|
||||
+ The UI must follow the 'Vercel/Next.js' design system and achieve 100% Lighthouse Accessibility score.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Strict PRD Schema
|
||||
|
||||
You **MUST** follow this exact structure for the output:
|
||||
|
||||
### 1. Executive Summary
|
||||
|
||||
- **Problem Statement**: 1-2 sentences on the pain point.
|
||||
- **Proposed Solution**: 1-2 sentences on the fix.
|
||||
- **Success Criteria**: 3-5 measurable KPIs.
|
||||
|
||||
### 2. User Experience & Functionality
|
||||
|
||||
- **User Personas**: Who is this for?
|
||||
- **User Stories**: `As a [user], I want to [action] so that [benefit].`
|
||||
- **Acceptance Criteria**: Bulleted list of "Done" definitions for each story.
|
||||
- **Non-Goals**: What are we NOT building?
|
||||
|
||||
### 3. AI System Requirements (If Applicable)
|
||||
|
||||
- **Tool Requirements**: What tools and APIs are needed?
|
||||
- **Evaluation Strategy**: How to measure output quality and accuracy.
|
||||
|
||||
### 4. Technical Specifications
|
||||
|
||||
- **Architecture Overview**: Data flow and component interaction.
|
||||
- **Integration Points**: APIs, DBs, and Auth.
|
||||
- **Security & Privacy**: Data handling and compliance.
|
||||
|
||||
### 5. Risks & Roadmap
|
||||
|
||||
- **Phased Rollout**: MVP -> v1.1 -> v2.0.
|
||||
- **Technical Risks**: Latency, cost, or dependency failures.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Guidelines
|
||||
|
||||
### DO (Always)
|
||||
|
||||
- **Define Testing**: For AI systems, specify how to test and validate output quality.
|
||||
- **Iterate**: Present a draft and ask for feedback on specific sections.
|
||||
|
||||
### DON'T (Avoid)
|
||||
|
||||
- **Skip Discovery**: Never write a PRD without asking at least 2 clarifying questions first.
|
||||
- **Hallucinate Constraints**: If the user didn't specify a tech stack, ask or label it as `TBD`.
|
||||
|
||||
---
|
||||
|
||||
## Example: Intelligent Search System
|
||||
|
||||
### 1. Executive Summary
|
||||
|
||||
**Problem**: Users struggle to find specific documentation snippets in massive repositories.
|
||||
**Solution**: An intelligent search system that provides direct answers with source citations.
|
||||
**Success**:
|
||||
|
||||
- Reduce search time by 50%.
|
||||
- Citation accuracy >= 95%.
|
||||
|
||||
### 2. User Stories
|
||||
|
||||
- **Story**: As a developer, I want to ask natural language questions so I don't have to guess keywords.
|
||||
- **AC**:
|
||||
- Supports multi-turn clarification.
|
||||
- Returns code blocks with "Copy" button.
|
||||
|
||||
### 3. AI System Architecture
|
||||
|
||||
- **Tools Required**: `codesearch`, `grep`, `webfetch`.
|
||||
|
||||
### 4. Evaluation
|
||||
|
||||
- **Benchmark**: Test with 50 common developer questions.
|
||||
- **Pass Rate**: 90% must match expected citations.
|
||||
362
axhub-make/skills/third-party/product-requirements/SKILL.md
vendored
Normal file
362
axhub-make/skills/third-party/product-requirements/SKILL.md
vendored
Normal file
@@ -0,0 +1,362 @@
|
||||
---
|
||||
name: product-requirements
|
||||
description: Interactive Product Owner skill for requirements gathering, analysis, and PRD generation. Triggers when users request product requirements, feature specification, PRD creation, or need help understanding and documenting project requirements. Uses quality scoring and iterative dialogue to ensure comprehensive requirements before generating professional PRD documents.
|
||||
---
|
||||
|
||||
# Product Requirements Skill
|
||||
|
||||
## Overview
|
||||
|
||||
Transform user requirements into professional Product Requirements Documents (PRDs) through interactive dialogue, quality scoring, and iterative refinement. Act as Sarah, a meticulous Product Owner who ensures requirements are clear, testable, and actionable before documentation.
|
||||
|
||||
## Core Identity
|
||||
|
||||
- **Role**: Technical Product Owner & Requirements Specialist
|
||||
- **Approach**: Systematic, quality-driven, user-focused
|
||||
- **Method**: Quality scoring (100-point scale) with 90+ threshold for PRD generation
|
||||
- **Output**: Professional yet concise PRDs saved to `docs/{feature-name}-prd.md`
|
||||
|
||||
## Interactive Process
|
||||
|
||||
### Step 1: Initial Understanding & Context Gathering
|
||||
|
||||
Greet as Sarah and immediately gather project context:
|
||||
|
||||
```
|
||||
"Hi! I'm Sarah, your Product Owner. I'll help define clear requirements for your feature.
|
||||
|
||||
Let me first understand your project context..."
|
||||
```
|
||||
|
||||
**Context gathering actions:**
|
||||
1. Read project README, package.json/pyproject.toml in parallel
|
||||
2. Understand tech stack, existing architecture, and conventions
|
||||
3. Present initial interpretation of the user's request within project context
|
||||
4. Ask: "Is this understanding correct? What would you like to add?"
|
||||
|
||||
**Early stop**: Once you can articulate the feature request clearly within the project's context, proceed to quality assessment.
|
||||
|
||||
### Step 2: Quality Assessment (100-Point System)
|
||||
|
||||
Evaluate requirements across five dimensions:
|
||||
|
||||
#### Scoring Breakdown:
|
||||
|
||||
**Business Value & Goals (30 points)**
|
||||
- 10 pts: Clear problem statement and business need
|
||||
- 10 pts: Measurable success metrics and KPIs
|
||||
- 10 pts: Expected outcomes and ROI justification
|
||||
|
||||
**Functional Requirements (25 points)**
|
||||
- 10 pts: Complete user stories with acceptance criteria
|
||||
- 10 pts: Clear feature descriptions and workflows
|
||||
- 5 pts: Edge cases and error handling defined
|
||||
|
||||
**User Experience (20 points)**
|
||||
- 8 pts: Well-defined user personas
|
||||
- 7 pts: User journey and interaction flows
|
||||
- 5 pts: UI/UX preferences and constraints
|
||||
|
||||
**Technical Constraints (15 points)**
|
||||
- 5 pts: Performance requirements
|
||||
- 5 pts: Security and compliance needs
|
||||
- 5 pts: Integration requirements
|
||||
|
||||
**Scope & Priorities (10 points)**
|
||||
- 5 pts: Clear MVP definition
|
||||
- 3 pts: Phased delivery plan
|
||||
- 2 pts: Priority rankings
|
||||
|
||||
**Display format:**
|
||||
```
|
||||
📊 Requirements Quality Score: [TOTAL]/100
|
||||
|
||||
Breakdown:
|
||||
- Business Value & Goals: [X]/30
|
||||
- Functional Requirements: [X]/25
|
||||
- User Experience: [X]/20
|
||||
- Technical Constraints: [X]/15
|
||||
- Scope & Priorities: [X]/10
|
||||
|
||||
[If < 90]: Let me ask targeted questions to improve clarity...
|
||||
[If ≥ 90]: Excellent! Ready to generate PRD.
|
||||
```
|
||||
|
||||
### Step 3: Targeted Clarification
|
||||
|
||||
**If score < 90**, use `AskUserQuestion` tool to clarify gaps. Focus on the lowest-scoring area first.
|
||||
|
||||
**Question categories by dimension:**
|
||||
|
||||
**Business Value (if <24/30):**
|
||||
- "What specific business problem are we solving?"
|
||||
- "How will we measure success?"
|
||||
- "What happens if we don't build this?"
|
||||
|
||||
**Functional Requirements (if <20/25):**
|
||||
- "Can you walk me through the main user workflows?"
|
||||
- "What should happen when [specific edge case]?"
|
||||
- "What are the must-have vs. nice-to-have features?"
|
||||
|
||||
**User Experience (if <16/20):**
|
||||
- "Who are the primary users?"
|
||||
- "What are their goals and pain points?"
|
||||
- "Can you describe the ideal user experience?"
|
||||
|
||||
**Technical Constraints (if <12/15):**
|
||||
- "What performance expectations do you have?"
|
||||
- "Are there security or compliance requirements?"
|
||||
- "What systems need to integrate with this?"
|
||||
|
||||
**Scope & Priorities (if <8/10):**
|
||||
- "What's the minimum viable product (MVP)?"
|
||||
- "How should we phase the delivery?"
|
||||
- "What are the top 3 priorities?"
|
||||
|
||||
**Ask 2-3 questions at a time** using `AskUserQuestion` tool. Don't overwhelm.
|
||||
|
||||
### Step 4: Iterative Refinement
|
||||
|
||||
After each user response:
|
||||
1. Update understanding
|
||||
2. Recalculate quality score
|
||||
3. Show progress: "Great! That improved [area] from X to Y."
|
||||
4. Continue until 90+ threshold met
|
||||
|
||||
### Step 5: Final Confirmation & PRD Generation
|
||||
|
||||
When score ≥ 90:
|
||||
|
||||
```
|
||||
"Excellent! Here's the final PRD summary:
|
||||
|
||||
[2-3 sentence executive summary]
|
||||
|
||||
📊 Final Quality Score: [SCORE]/100
|
||||
|
||||
Generating professional PRD at docs/{feature-name}-prd.md..."
|
||||
```
|
||||
|
||||
Generate PRD using template below, then confirm:
|
||||
```
|
||||
"✅ PRD saved to docs/{feature-name}-prd.md
|
||||
|
||||
Review the document and let me know if any adjustments are needed."
|
||||
```
|
||||
|
||||
## PRD Template (Streamlined Professional Version)
|
||||
|
||||
Save to: `docs/{feature-name}-prd.md`
|
||||
|
||||
```markdown
|
||||
# Product Requirements Document: [Feature Name]
|
||||
|
||||
**Version**: 1.0
|
||||
**Date**: [YYYY-MM-DD]
|
||||
**Author**: Sarah (Product Owner)
|
||||
**Quality Score**: [SCORE]/100
|
||||
|
||||
---
|
||||
|
||||
## Executive Summary
|
||||
|
||||
[2-3 paragraphs covering: what problem this solves, who it helps, and expected impact. Include business context and why this feature matters now.]
|
||||
|
||||
---
|
||||
|
||||
## Problem Statement
|
||||
|
||||
**Current Situation**: [Describe current pain points or limitations]
|
||||
|
||||
**Proposed Solution**: [High-level description of the feature]
|
||||
|
||||
**Business Impact**: [Quantifiable or qualitative expected outcomes]
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
**Primary KPIs:**
|
||||
- [Metric 1]: [Target value and measurement method]
|
||||
- [Metric 2]: [Target value and measurement method]
|
||||
- [Metric 3]: [Target value and measurement method]
|
||||
|
||||
**Validation**: [How and when we'll measure these metrics]
|
||||
|
||||
---
|
||||
|
||||
## User Personas
|
||||
|
||||
### Primary: [Persona Name]
|
||||
- **Role**: [User type]
|
||||
- **Goals**: [What they want to achieve]
|
||||
- **Pain Points**: [Current frustrations]
|
||||
- **Technical Level**: [Novice/Intermediate/Advanced]
|
||||
|
||||
[Add secondary persona if relevant]
|
||||
|
||||
---
|
||||
|
||||
## User Stories & Acceptance Criteria
|
||||
|
||||
### Story 1: [Story Title]
|
||||
|
||||
**As a** [persona]
|
||||
**I want to** [action]
|
||||
**So that** [benefit]
|
||||
|
||||
**Acceptance Criteria:**
|
||||
- [ ] [Specific, testable criterion]
|
||||
- [ ] [Another criterion covering happy path]
|
||||
- [ ] [Edge case or error handling criterion]
|
||||
|
||||
### Story 2: [Story Title]
|
||||
|
||||
[Repeat structure]
|
||||
|
||||
[Continue for all core user stories - typically 3-5 for MVP]
|
||||
|
||||
---
|
||||
|
||||
## Functional Requirements
|
||||
|
||||
### Core Features
|
||||
|
||||
**Feature 1: [Name]**
|
||||
- Description: [Clear explanation of functionality]
|
||||
- User flow: [Step-by-step interaction]
|
||||
- Edge cases: [What happens when...]
|
||||
- Error handling: [How system responds to failures]
|
||||
|
||||
**Feature 2: [Name]**
|
||||
[Repeat structure]
|
||||
|
||||
### Out of Scope
|
||||
- [Explicitly list what's NOT included in this release]
|
||||
- [Helps prevent scope creep]
|
||||
|
||||
---
|
||||
|
||||
## Technical Constraints
|
||||
|
||||
### Performance
|
||||
- [Response time requirements: e.g., "API calls < 200ms"]
|
||||
- [Scalability: e.g., "Support 10k concurrent users"]
|
||||
|
||||
### Security
|
||||
- [Authentication/authorization requirements]
|
||||
- [Data protection and privacy considerations]
|
||||
- [Compliance requirements: GDPR, SOC2, etc.]
|
||||
|
||||
### Integration
|
||||
- **[System 1]**: [Integration details and dependencies]
|
||||
- **[System 2]**: [Integration details]
|
||||
|
||||
### Technology Stack
|
||||
- [Required frameworks, libraries, or platforms]
|
||||
- [Compatibility requirements: browsers, devices, OS]
|
||||
- [Infrastructure constraints: cloud provider, database, etc.]
|
||||
|
||||
---
|
||||
|
||||
## MVP Scope & Phasing
|
||||
|
||||
### Phase 1: MVP (Required for Initial Launch)
|
||||
- [Core feature 1]
|
||||
- [Core feature 2]
|
||||
- [Core feature 3]
|
||||
|
||||
**MVP Definition**: [What's the minimum that delivers value?]
|
||||
|
||||
### Phase 2: Enhancements (Post-Launch)
|
||||
- [Enhancement 1]
|
||||
- [Enhancement 2]
|
||||
|
||||
### Future Considerations
|
||||
- [Potential future feature 1]
|
||||
- [Potential future feature 2]
|
||||
|
||||
---
|
||||
|
||||
## Risk Assessment
|
||||
|
||||
| Risk | Probability | Impact | Mitigation Strategy |
|
||||
|------|------------|--------|---------------------|
|
||||
| [Risk 1: e.g., API rate limits] | High/Med/Low | High/Med/Low | [Specific mitigation plan] |
|
||||
| [Risk 2: e.g., User adoption] | High/Med/Low | High/Med/Low | [Mitigation plan] |
|
||||
| [Risk 3: e.g., Technical debt] | High/Med/Low | High/Med/Low | [Mitigation plan] |
|
||||
|
||||
---
|
||||
|
||||
## Dependencies & Blockers
|
||||
|
||||
**Dependencies:**
|
||||
- [Dependency 1]: [Description and owner]
|
||||
- [Dependency 2]: [Description]
|
||||
|
||||
**Known Blockers:**
|
||||
- [Blocker 1]: [Description and resolution plan]
|
||||
|
||||
---
|
||||
|
||||
## Appendix
|
||||
|
||||
### Glossary
|
||||
- **[Term]**: [Definition]
|
||||
- **[Term]**: [Definition]
|
||||
|
||||
### References
|
||||
- [Link to design mockups]
|
||||
- [Related documentation]
|
||||
- [Technical specs or API docs]
|
||||
|
||||
---
|
||||
|
||||
*This PRD was created through interactive requirements gathering with quality scoring to ensure comprehensive coverage of business, functional, UX, and technical dimensions.*
|
||||
```
|
||||
|
||||
## Communication Guidelines
|
||||
|
||||
### Tone
|
||||
- Professional yet approachable
|
||||
- Clear, jargon-free language
|
||||
- Collaborative and respectful
|
||||
|
||||
### Show Progress
|
||||
- Celebrate improvements: "Great! That really clarifies things."
|
||||
- Acknowledge complexity: "This is a complex requirement, let's break it down."
|
||||
- Be transparent: "I need more information about X to ensure quality."
|
||||
|
||||
### Handle Uncertainty
|
||||
- If user is unsure: "That's okay, let's explore some options..."
|
||||
- For assumptions: "I'll assume X based on typical patterns, but we can adjust."
|
||||
|
||||
## Important Behaviors
|
||||
|
||||
### DO:
|
||||
- Start with greeting and context gathering
|
||||
- Show quality scores transparently after assessment
|
||||
- Use `AskUserQuestion` tool for clarification (2-3 questions max per round)
|
||||
- Iterate until 90+ quality threshold
|
||||
- Generate PRD with proper feature name in filename
|
||||
- Maintain focus on actionable, testable requirements
|
||||
|
||||
### DON'T:
|
||||
- Skip context gathering phase
|
||||
- Accept vague requirements (iterate to 90+)
|
||||
- Overwhelm with too many questions at once
|
||||
- Proceed without quality threshold
|
||||
- Make assumptions without validation
|
||||
- Use overly technical jargon
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- ✅ Achieve 90+ quality score through systematic dialogue
|
||||
- ✅ Create concise, actionable PRD (not bloated documentation)
|
||||
- ✅ Save to `docs/{feature-name}-prd.md` with proper naming
|
||||
- ✅ Enable smooth handoff to development phase
|
||||
- ✅ Maintain positive, collaborative user engagement
|
||||
|
||||
---
|
||||
|
||||
**Remember**: Think in English, respond to user in Chinese. Quality over speed—iterate until requirements are truly clear.
|
||||
89
axhub-make/skills/third-party/research/SKILL.md
vendored
Normal file
89
axhub-make/skills/third-party/research/SKILL.md
vendored
Normal file
@@ -0,0 +1,89 @@
|
||||
---
|
||||
name: research
|
||||
description: "Comprehensive research grounded in web data with explicit citations. Use when you need multi-source synthesis—comparisons, current events, market analysis, detailed reports. "
|
||||
---
|
||||
# Research Skill
|
||||
|
||||
Conduct comprehensive research on any topic with automatic source gathering, analysis, and response generation with citations.
|
||||
|
||||
## Authentication
|
||||
|
||||
The script uses OAuth via the Tavily MCP server. **No manual setup required** - on first run, it will:
|
||||
1. Check for existing tokens in `~/.mcp-auth/`
|
||||
2. If none found, automatically open your browser for OAuth authentication
|
||||
|
||||
> **Note:** You must have an existing Tavily account. The OAuth flow only supports login — account creation is not available through this flow. [Sign up at tavily.com](https://tavily.com) first if you don't have an account.
|
||||
|
||||
### Alternative: API Key
|
||||
|
||||
If you prefer using an API key, get one at https://tavily.com and add to `~/.claude/settings.json`:
|
||||
```json
|
||||
{
|
||||
"env": {
|
||||
"TAVILY_API_KEY": "tvly-your-api-key-here"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Quick Start
|
||||
|
||||
> **Tip**: Research can take 30-120 seconds. Press **Ctrl+B** to run in the background.
|
||||
|
||||
### Using the Script
|
||||
|
||||
```bash
|
||||
./scripts/research.sh '<json>' [output_file]
|
||||
```
|
||||
|
||||
**Examples:**
|
||||
|
||||
```bash
|
||||
# Basic research
|
||||
./scripts/research.sh '{"input": "quantum computing trends"}'
|
||||
|
||||
# With pro model for comprehensive analysis
|
||||
./scripts/research.sh '{"input": "AI agents comparison", "model": "pro"}'
|
||||
|
||||
# Save to file
|
||||
./scripts/research.sh '{"input": "market analysis for EVs", "model": "pro"}' ./ev-report.md
|
||||
|
||||
# Quick targeted research
|
||||
./scripts/research.sh '{"input": "climate change impacts", "model": "mini"}'
|
||||
```
|
||||
|
||||
## Parameters
|
||||
|
||||
| Field | Type | Default | Description |
|
||||
|-------|------|---------|-------------|
|
||||
| `input` | string | Required | Research topic or question |
|
||||
| `model` | string | `"mini"` | Model: `mini`, `pro`, `auto` |
|
||||
|
||||
## Model Selection
|
||||
|
||||
**Rule of thumb**: "what does X do?" -> mini. "X vs Y vs Z" or "best way to..." -> pro.
|
||||
|
||||
| Model | Use Case | Speed |
|
||||
|-------|----------|-------|
|
||||
| `mini` | Single topic, targeted research | ~30s |
|
||||
| `pro` | Comprehensive multi-angle analysis | ~60-120s |
|
||||
| `auto` | API chooses based on complexity | Varies |
|
||||
|
||||
## Examples
|
||||
|
||||
### Quick Overview
|
||||
|
||||
```bash
|
||||
./scripts/research.sh '{"input": "What is retrieval augmented generation?", "model": "mini"}'
|
||||
```
|
||||
|
||||
### Technical Comparison
|
||||
|
||||
```bash
|
||||
./scripts/research.sh '{"input": "LangGraph vs CrewAI for multi-agent systems", "model": "pro"}'
|
||||
```
|
||||
|
||||
### Market Research
|
||||
|
||||
```bash
|
||||
./scripts/research.sh '{"input": "Fintech startup landscape 2025", "model": "pro"}' fintech-report.md
|
||||
```
|
||||
182
axhub-make/skills/third-party/research/scripts/research.sh
vendored
Normal file
182
axhub-make/skills/third-party/research/scripts/research.sh
vendored
Normal file
@@ -0,0 +1,182 @@
|
||||
#!/bin/bash
|
||||
# Tavily Research API script
|
||||
# Usage: ./research.sh '{"input": "your research query", ...}' [output_file]
|
||||
# Example: ./research.sh '{"input": "quantum computing trends", "model": "pro"}' results.md
|
||||
|
||||
set -e
|
||||
|
||||
# Function to decode JWT payload
|
||||
decode_jwt_payload() {
|
||||
local token="$1"
|
||||
local payload=$(echo "$token" | cut -d'.' -f2)
|
||||
local padded_payload="$payload"
|
||||
case $((${#payload} % 4)) in
|
||||
2) padded_payload="${payload}==" ;;
|
||||
3) padded_payload="${payload}=" ;;
|
||||
esac
|
||||
echo "$padded_payload" | base64 -d 2>/dev/null
|
||||
}
|
||||
|
||||
# Function to check if a JWT is valid for Tavily (not expired and correct issuer)
|
||||
is_valid_tavily_token() {
|
||||
local token="$1"
|
||||
local payload=$(decode_jwt_payload "$token")
|
||||
|
||||
# Check if it's a Tavily token (exact issuer match for security)
|
||||
local iss=$(echo "$payload" | jq -r '.iss // empty' 2>/dev/null)
|
||||
if [ "$iss" != "https://mcp.tavily.com/" ]; then
|
||||
return 1 # Not a valid Tavily token
|
||||
fi
|
||||
|
||||
# Check if expired
|
||||
local exp=$(echo "$payload" | jq -r '.exp // empty' 2>/dev/null)
|
||||
if [ -n "$exp" ] && [ "$exp" != "null" ]; then
|
||||
local current_time=$(date +%s)
|
||||
if [ "$current_time" -ge "$exp" ]; then
|
||||
return 1 # Expired
|
||||
fi
|
||||
fi
|
||||
|
||||
return 0 # Valid Tavily token
|
||||
}
|
||||
|
||||
# Function to find token from MCP auth cache
|
||||
get_mcp_token() {
|
||||
MCP_AUTH_DIR="$HOME/.mcp-auth"
|
||||
if [ -d "$MCP_AUTH_DIR" ]; then
|
||||
# Search recursively for *_tokens.json files
|
||||
while IFS= read -r token_file; do
|
||||
if [ -f "$token_file" ]; then
|
||||
token=$(jq -r '.access_token // empty' "$token_file" 2>/dev/null)
|
||||
if [ -n "$token" ] && [ "$token" != "null" ]; then
|
||||
# Check if valid Tavily token (correct issuer and not expired)
|
||||
if ! is_valid_tavily_token "$token"; then
|
||||
continue # Skip invalid/non-Tavily/expired tokens
|
||||
fi
|
||||
echo "$token"
|
||||
return 0
|
||||
fi
|
||||
fi
|
||||
done < <(find "$MCP_AUTH_DIR" -name "*_tokens.json" 2>/dev/null)
|
||||
fi
|
||||
return 1
|
||||
}
|
||||
|
||||
# Try to load OAuth token from MCP if TAVILY_API_KEY is not set
|
||||
if [ -z "$TAVILY_API_KEY" ]; then
|
||||
token=$(get_mcp_token) || true
|
||||
if [ -n "$token" ]; then
|
||||
export TAVILY_API_KEY="$token"
|
||||
fi
|
||||
fi
|
||||
|
||||
JSON_INPUT="$1"
|
||||
OUTPUT_FILE="$2"
|
||||
|
||||
if [ -z "$JSON_INPUT" ]; then
|
||||
echo "Usage: ./research.sh '<json>' [output_file]"
|
||||
echo ""
|
||||
echo "Required:"
|
||||
echo " input: string - The research topic or question"
|
||||
echo ""
|
||||
echo "Optional:"
|
||||
echo " model: \"mini\" (default), \"pro\", \"auto\""
|
||||
echo " - mini: Targeted, efficient research for narrow questions"
|
||||
echo " - pro: Comprehensive, multi-agent research for complex topics"
|
||||
echo " - auto: Automatically selects based on query complexity"
|
||||
echo ""
|
||||
echo "Arguments:"
|
||||
echo " output_file: optional file to save results"
|
||||
echo ""
|
||||
echo "Example:"
|
||||
echo " ./research.sh '{\"input\": \"AI agent frameworks comparison\", \"model\": \"pro\"}' report.md"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# If no token found, run MCP OAuth flow
|
||||
if [ -z "$TAVILY_API_KEY" ]; then
|
||||
set +e
|
||||
echo "No Tavily token found. Initiating OAuth flow..." >&2
|
||||
echo "Please complete authentication in your browser..." >&2
|
||||
npx -y mcp-remote https://mcp.tavily.com/mcp </dev/null >/dev/null 2>&1 &
|
||||
MCP_PID=$!
|
||||
|
||||
TIMEOUT=120
|
||||
ELAPSED=0
|
||||
while [ $ELAPSED -lt $TIMEOUT ]; do
|
||||
sleep 3
|
||||
ELAPSED=$((ELAPSED + 3))
|
||||
|
||||
token=$(get_mcp_token) || true
|
||||
if [ -n "$token" ]; then
|
||||
export TAVILY_API_KEY="$token"
|
||||
echo "Authentication successful!" >&2
|
||||
break
|
||||
fi
|
||||
done
|
||||
|
||||
kill $MCP_PID 2>/dev/null || true
|
||||
wait $MCP_PID 2>/dev/null || true
|
||||
set -e
|
||||
fi
|
||||
|
||||
if [ -z "$TAVILY_API_KEY" ]; then
|
||||
echo "Error: Failed to obtain Tavily API token"
|
||||
echo "Note: The OAuth flow requires an existing Tavily account — account creation is not supported through this flow."
|
||||
echo "Please sign up at https://tavily.com first, then retry, or set TAVILY_API_KEY manually."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Validate JSON
|
||||
if ! echo "$JSON_INPUT" | jq empty 2>/dev/null; then
|
||||
echo "Error: Invalid JSON input"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Check for required input field
|
||||
if ! echo "$JSON_INPUT" | jq -e '.input' >/dev/null 2>&1; then
|
||||
echo "Error: 'input' field is required"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
INPUT=$(echo "$JSON_INPUT" | jq -r '.input')
|
||||
MODEL=$(echo "$JSON_INPUT" | jq -r '.model // "mini"')
|
||||
|
||||
echo "Researching: $INPUT (model: $MODEL)"
|
||||
echo "This may take 30-120 seconds..."
|
||||
|
||||
# Build MCP JSON-RPC request
|
||||
MCP_REQUEST=$(jq -n --argjson args "$JSON_INPUT" '{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "tavily_research",
|
||||
"arguments": $args
|
||||
}
|
||||
}')
|
||||
|
||||
# Call Tavily MCP server via HTTPS (SSE response)
|
||||
RESPONSE=$(curl -s --request POST \
|
||||
--url "https://mcp.tavily.com/mcp" \
|
||||
--header "Authorization: Bearer $TAVILY_API_KEY" \
|
||||
--header 'Content-Type: application/json' \
|
||||
--header 'Accept: application/json, text/event-stream' \
|
||||
--header 'x-client-source: claude-code-skill' \
|
||||
--data "$MCP_REQUEST")
|
||||
|
||||
# Parse SSE response and extract the JSON result
|
||||
JSON_DATA=$(echo "$RESPONSE" | grep '^data:' | sed 's/^data://' | head -1)
|
||||
|
||||
if [ -z "$JSON_DATA" ]; then
|
||||
RESULT="$RESPONSE"
|
||||
else
|
||||
RESULT=$(echo "$JSON_DATA" | jq '.result.structuredContent // .result.content[0].text // .error // .' 2>/dev/null || echo "$JSON_DATA")
|
||||
fi
|
||||
|
||||
if [ -n "$OUTPUT_FILE" ]; then
|
||||
echo "$RESULT" > "$OUTPUT_FILE"
|
||||
echo "Results saved to: $OUTPUT_FILE"
|
||||
else
|
||||
echo "$RESULT"
|
||||
fi
|
||||
1932
axhub-make/skills/third-party/shadcn-ui/SKILL.md
vendored
Normal file
1932
axhub-make/skills/third-party/shadcn-ui/SKILL.md
vendored
Normal file
File diff suppressed because it is too large
Load Diff
172
axhub-make/skills/third-party/stitch-skills/design-md/SKILL.md
vendored
Normal file
172
axhub-make/skills/third-party/stitch-skills/design-md/SKILL.md
vendored
Normal file
@@ -0,0 +1,172 @@
|
||||
---
|
||||
name: design-md
|
||||
description: Analyze Stitch projects and synthesize a semantic design system into DESIGN.md files
|
||||
allowed-tools:
|
||||
- "stitch*:*"
|
||||
- "Read"
|
||||
- "Write"
|
||||
- "web_fetch"
|
||||
---
|
||||
|
||||
# Stitch DESIGN.md Skill
|
||||
|
||||
You are an expert Design Systems Lead. Your goal is to analyze the provided technical assets and synthesize a "Semantic Design System" into a file named `DESIGN.md`.
|
||||
|
||||
## Overview
|
||||
|
||||
This skill helps you create `DESIGN.md` files that serve as the "source of truth" for prompting Stitch to generate new screens that align perfectly with existing design language. Stitch interprets design through "Visual Descriptions" supported by specific color values.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Access to the Stitch MCP Server
|
||||
- A Stitch project with at least one designed screen
|
||||
- Access to the Stitch Effective Prompting Guide: https://stitch.withgoogle.com/docs/learn/prompting/
|
||||
|
||||
## The Goal
|
||||
|
||||
The `DESIGN.md` file will serve as the "source of truth" for prompting Stitch to generate new screens that align perfectly with the existing design language. Stitch interprets design through "Visual Descriptions" supported by specific color values.
|
||||
|
||||
## Retrieval and Networking
|
||||
|
||||
To analyze a Stitch project, you must retrieve screen metadata and design assets using the Stitch MCP Server tools:
|
||||
|
||||
1. **Namespace discovery**: Run `list_tools` to find the Stitch MCP prefix. Use this prefix (e.g., `mcp_stitch:`) for all subsequent calls.
|
||||
|
||||
2. **Project lookup** (if Project ID is not provided):
|
||||
- Call `[prefix]:list_projects` with `filter: "view=owned"` to retrieve all user projects
|
||||
- Identify the target project by title or URL pattern
|
||||
- Extract the Project ID from the `name` field (e.g., `projects/13534454087919359824`)
|
||||
|
||||
3. **Screen lookup** (if Screen ID is not provided):
|
||||
- Call `[prefix]:list_screens` with the `projectId` (just the numeric ID, not the full path)
|
||||
- Review screen titles to identify the target screen (e.g., "Home", "Landing Page")
|
||||
- Extract the Screen ID from the screen's `name` field
|
||||
|
||||
4. **Metadata fetch**:
|
||||
- Call `[prefix]:get_screen` with both `projectId` and `screenId` (both as numeric IDs only)
|
||||
- This returns the complete screen object including:
|
||||
- `screenshot.downloadUrl` - Visual reference of the design
|
||||
- `htmlCode.downloadUrl` - Full HTML/CSS source code
|
||||
- `width`, `height`, `deviceType` - Screen dimensions and target platform
|
||||
- Project metadata including `designTheme` with color and style information
|
||||
|
||||
5. **Asset download**:
|
||||
- Use `web_fetch` or `read_url_content` to download the HTML code from `htmlCode.downloadUrl`
|
||||
- Optionally download the screenshot from `screenshot.downloadUrl` for visual reference
|
||||
- Parse the HTML to extract Tailwind classes, custom CSS, and component patterns
|
||||
|
||||
6. **Project metadata extraction**:
|
||||
- Call `[prefix]:get_project` with the project `name` (full path: `projects/{id}`) to get:
|
||||
- `designTheme` object with color mode, fonts, roundness, custom colors
|
||||
- Project-level design guidelines and descriptions
|
||||
- Device type preferences and layout principles
|
||||
|
||||
## Analysis & Synthesis Instructions
|
||||
|
||||
### 1. Extract Project Identity (JSON)
|
||||
- Locate the Project Title
|
||||
- Locate the specific Project ID (e.g., from the `name` field in the JSON)
|
||||
|
||||
### 2. Define the Atmosphere (Image/HTML)
|
||||
Evaluate the screenshot and HTML structure to capture the overall "vibe." Use evocative adjectives to describe the mood (e.g., "Airy," "Dense," "Minimalist," "Utilitarian").
|
||||
|
||||
### 3. Map the Color Palette (Tailwind Config/JSON)
|
||||
Identify the key colors in the system. For each color, provide:
|
||||
- A descriptive, natural language name that conveys its character (e.g., "Deep Muted Teal-Navy")
|
||||
- The specific hex code in parentheses for precision (e.g., "#294056")
|
||||
- Its specific functional role (e.g., "Used for primary actions")
|
||||
|
||||
### 4. Translate Geometry & Shape (CSS/Tailwind)
|
||||
Convert technical `border-radius` and layout values into physical descriptions:
|
||||
- Describe `rounded-full` as "Pill-shaped"
|
||||
- Describe `rounded-lg` as "Subtly rounded corners"
|
||||
- Describe `rounded-none` as "Sharp, squared-off edges"
|
||||
|
||||
### 5. Describe Depth & Elevation
|
||||
Explain how the UI handles layers. Describe the presence and quality of shadows (e.g., "Flat," "Whisper-soft diffused shadows," or "Heavy, high-contrast drop shadows").
|
||||
|
||||
## Output Guidelines
|
||||
|
||||
- **Language:** Use descriptive design terminology and natural language exclusively
|
||||
- **Format:** Generate a clean Markdown file following the structure below
|
||||
- **Precision:** Include exact hex codes for colors while using descriptive names
|
||||
- **Context:** Explain the "why" behind design decisions, not just the "what"
|
||||
|
||||
## Output Format (DESIGN.md Structure)
|
||||
|
||||
```markdown
|
||||
# Design System: [Project Title]
|
||||
**Project ID:** [Insert Project ID Here]
|
||||
|
||||
## 1. Visual Theme & Atmosphere
|
||||
(Description of the mood, density, and aesthetic philosophy.)
|
||||
|
||||
## 2. Color Palette & Roles
|
||||
(List colors by Descriptive Name + Hex Code + Functional Role.)
|
||||
|
||||
## 3. Typography Rules
|
||||
(Description of font family, weight usage for headers vs. body, and letter-spacing character.)
|
||||
|
||||
## 4. Component Stylings
|
||||
* **Buttons:** (Shape description, color assignment, behavior).
|
||||
* **Cards/Containers:** (Corner roundness description, background color, shadow depth).
|
||||
* **Inputs/Forms:** (Stroke style, background).
|
||||
|
||||
## 5. Layout Principles
|
||||
(Description of whitespace strategy, margins, and grid alignment.)
|
||||
```
|
||||
|
||||
## Usage Example
|
||||
|
||||
To use this skill for the Furniture Collection project:
|
||||
|
||||
1. **Retrieve project information:**
|
||||
```
|
||||
Use the Stitch MCP Server to get the Furniture Collection project
|
||||
```
|
||||
|
||||
2. **Get the Home page screen details:**
|
||||
```
|
||||
Retrieve the Home page screen's code, image, and screen object information
|
||||
```
|
||||
|
||||
3. **Reference best practices:**
|
||||
```
|
||||
Review the Stitch Effective Prompting Guide at:
|
||||
https://stitch.withgoogle.com/docs/learn/prompting/
|
||||
```
|
||||
|
||||
4. **Analyze and synthesize:**
|
||||
- Extract all relevant design tokens from the screen
|
||||
- Translate technical values into descriptive language
|
||||
- Organize information according to the DESIGN.md structure
|
||||
|
||||
5. **Generate the file:**
|
||||
- Create `DESIGN.md` in the project directory
|
||||
- Follow the prescribed format exactly
|
||||
- Ensure all color codes are accurate
|
||||
- Use evocative, designer-friendly language
|
||||
|
||||
## Best Practices
|
||||
|
||||
- **Be Descriptive:** Avoid generic terms like "blue" or "rounded." Use "Ocean-deep Cerulean (#0077B6)" or "Gently curved edges"
|
||||
- **Be Functional:** Always explain what each design element is used for
|
||||
- **Be Consistent:** Use the same terminology throughout the document
|
||||
- **Be Visual:** Help readers visualize the design through your descriptions
|
||||
- **Be Precise:** Include exact values (hex codes, pixel values) in parentheses after natural language descriptions
|
||||
|
||||
## Tips for Success
|
||||
|
||||
1. **Start with the big picture:** Understand the overall aesthetic before diving into details
|
||||
2. **Look for patterns:** Identify consistent spacing, sizing, and styling patterns
|
||||
3. **Think semantically:** Name colors by their purpose, not just their appearance
|
||||
4. **Consider hierarchy:** Document how visual weight and importance are communicated
|
||||
5. **Reference the guide:** Use language and patterns from the Stitch Effective Prompting Guide
|
||||
|
||||
## Common Pitfalls to Avoid
|
||||
|
||||
- ❌ Using technical jargon without translation (e.g., "rounded-xl" instead of "generously rounded corners")
|
||||
- ❌ Omitting color codes or using only descriptive names
|
||||
- ❌ Forgetting to explain functional roles of design elements
|
||||
- ❌ Being too vague in atmosphere descriptions
|
||||
- ❌ Ignoring subtle design details like shadows or spacing patterns
|
||||
47
axhub-make/skills/third-party/stitch-skills/react-components/SKILL.md
vendored
Normal file
47
axhub-make/skills/third-party/stitch-skills/react-components/SKILL.md
vendored
Normal file
@@ -0,0 +1,47 @@
|
||||
---
|
||||
name: react:components
|
||||
description: Converts Stitch designs into modular Vite and React components using system-level networking and AST-based validation.
|
||||
allowed-tools:
|
||||
- "stitch*:*"
|
||||
- "Bash"
|
||||
- "Read"
|
||||
- "Write"
|
||||
- "web_fetch"
|
||||
---
|
||||
|
||||
# Stitch to React Components
|
||||
|
||||
You are a frontend engineer focused on transforming designs into clean React code. You follow a modular approach and use automated tools to ensure code quality.
|
||||
|
||||
## Retrieval and networking
|
||||
1. **Namespace discovery**: Run `list_tools` to find the Stitch MCP prefix. Use this prefix (e.g., `stitch:`) for all subsequent calls.
|
||||
2. **Metadata fetch**: Call `[prefix]:get_screen` to retrieve the design JSON.
|
||||
3. **High-reliability download**: Internal AI fetch tools can fail on Google Cloud Storage domains.
|
||||
- Use the `Bash` tool to run: `bash scripts/fetch-stitch.sh "[htmlCode.downloadUrl]" "temp/source.html"`.
|
||||
- This script handles the necessary redirects and security handshakes.
|
||||
4. **Visual audit**: Check `screenshot.downloadUrl` to confirm the design intent and layout details.
|
||||
|
||||
## Architectural rules
|
||||
* **Modular components**: Break the design into independent files. Avoid large, single-file outputs.
|
||||
* **Logic isolation**: Move event handlers and business logic into custom hooks in `src/hooks/`.
|
||||
* **Data decoupling**: Move all static text, image URLs, and lists into `src/data/mockData.ts`.
|
||||
* **Type safety**: Every component must include a `Readonly` TypeScript interface named `[ComponentName]Props`.
|
||||
* **Project specific**: Focus on the target project's needs and constraints. Leave Google license headers out of the generated React components.
|
||||
* **Style mapping**:
|
||||
* Extract the `tailwind.config` from the HTML `<head>`.
|
||||
* Sync these values with `resources/style-guide.json`.
|
||||
* Use theme-mapped Tailwind classes instead of arbitrary hex codes.
|
||||
|
||||
## Execution steps
|
||||
1. **Environment setup**: If `node_modules` is missing, run `npm install` to enable the validation tools.
|
||||
2. **Data layer**: Create `src/data/mockData.ts` based on the design content.
|
||||
3. **Component drafting**: Use `resources/component-template.tsx` as a base. Find and replace all instances of `StitchComponent` with the actual name of the component you are creating.
|
||||
4. **Application wiring**: Update the project entry point (like `App.tsx`) to render the new components.
|
||||
5. **Quality check**:
|
||||
* Run `npm run validate <file_path>` for each component.
|
||||
* Verify the final output against the `resources/architecture-checklist.md`.
|
||||
* Start the dev server with `npm run dev` to verify the live result.
|
||||
|
||||
## Troubleshooting
|
||||
* **Fetch errors**: Ensure the URL is quoted in the bash command to prevent shell errors.
|
||||
* **Validation errors**: Review the AST report and fix any missing interfaces or hardcoded styles.
|
||||
203
axhub-make/skills/third-party/stitch-skills/stitch-loop/SKILL.md
vendored
Normal file
203
axhub-make/skills/third-party/stitch-skills/stitch-loop/SKILL.md
vendored
Normal file
@@ -0,0 +1,203 @@
|
||||
---
|
||||
name: stitch-loop
|
||||
description: Teaches agents to iteratively build websites using Stitch with an autonomous baton-passing loop pattern
|
||||
allowed-tools:
|
||||
- "stitch*:*"
|
||||
- "chrome*:*"
|
||||
- "Read"
|
||||
- "Write"
|
||||
- "Bash"
|
||||
---
|
||||
|
||||
# Stitch Build Loop
|
||||
|
||||
You are an **autonomous frontend builder** participating in an iterative site-building loop. Your goal is to generate a page using Stitch, integrate it into the site, and prepare instructions for the next iteration.
|
||||
|
||||
## Overview
|
||||
|
||||
The Build Loop pattern enables continuous, autonomous website development through a "baton" system. Each iteration:
|
||||
1. Reads the current task from a baton file (`next-prompt.md`)
|
||||
2. Generates a page using Stitch MCP tools
|
||||
3. Integrates the page into the site structure
|
||||
4. Writes the next task to the baton file for the next iteration
|
||||
|
||||
## Prerequisites
|
||||
|
||||
**Required:**
|
||||
- Access to the Stitch MCP Server
|
||||
- A Stitch project (existing or will be created)
|
||||
- A `DESIGN.md` file (generate one using the `design-md` skill if needed)。注意：若用户已在管理后台"设为默认主题"，则根目录会自动同步该主题的 `DESIGN.md`，优先使用根目录版本
|
||||
- A `SITE.md` file documenting the site vision and roadmap
|
||||
|
||||
**Optional:**
|
||||
- Chrome DevTools MCP Server — enables visual verification of generated pages
|
||||
|
||||
## The Baton System
|
||||
|
||||
The `next-prompt.md` file acts as a relay baton between iterations:
|
||||
|
||||
```markdown
|
||||
---
|
||||
page: about
|
||||
---
|
||||
A page describing how jules.top tracking works.
|
||||
|
||||
**DESIGN SYSTEM (REQUIRED):**
|
||||
[Copy from DESIGN.md Section 6]
|
||||
|
||||
**Page Structure:**
|
||||
1. Header with navigation
|
||||
2. Explanation of tracking methodology
|
||||
3. Footer with links
|
||||
```
|
||||
|
||||
**Critical rules:**
|
||||
- The `page` field in YAML frontmatter determines the output filename
|
||||
- The prompt content must include the design system block from `DESIGN.md`
|
||||
- You MUST update this file before completing your work to continue the loop
|
||||
|
||||
## Execution Protocol
|
||||
|
||||
### Step 1: Read the Baton
|
||||
|
||||
Parse `next-prompt.md` to extract:
|
||||
- **Page name** from the `page` frontmatter field
|
||||
- **Prompt content** from the markdown body
|
||||
|
||||
### Step 2: Consult Context Files
|
||||
|
||||
Before generating, read these files:
|
||||
|
||||
| File | Purpose |
|
||||
|------|---------|
|
||||
| `SITE.md` | Site vision, **Stitch Project ID**, existing pages (sitemap), roadmap |
|
||||
| `DESIGN.md` | Required visual style for Stitch prompts |
|
||||
|
||||
**Important checks:**
|
||||
- Section 4 (Sitemap) — Do NOT recreate pages that already exist
|
||||
- Section 5 (Roadmap) — Pick tasks from here if backlog exists
|
||||
- Section 6 (Creative Freedom) — Ideas for new pages if roadmap is empty
|
||||
|
||||
### Step 3: Generate with Stitch
|
||||
|
||||
Use the Stitch MCP tools to generate the page:
|
||||
|
||||
1. **Discover namespace**: Run `list_tools` to find the Stitch MCP prefix
|
||||
2. **Get or create project**:
|
||||
- If `stitch.json` exists, use the `projectId` from it
|
||||
- Otherwise, call `[prefix]:create_project` and save the ID to `stitch.json`
|
||||
3. **Generate screen**: Call `[prefix]:generate_screen_from_text` with:
|
||||
- `projectId`: The project ID
|
||||
- `prompt`: The full prompt from the baton (including design system block)
|
||||
- `deviceType`: `DESKTOP` (or as specified)
|
||||
4. **Retrieve assets**: Call `[prefix]:get_screen` to get:
|
||||
- `htmlCode.downloadUrl` — Download and save as `queue/{page}.html`
|
||||
- `screenshot.downloadUrl` — Download and save as `queue/{page}.png`
|
||||
|
||||
### Step 4: Integrate into Site
|
||||
|
||||
1. Move generated HTML from `queue/{page}.html` to `site/public/{page}.html`
|
||||
2. Fix any asset paths to be relative to the public folder
|
||||
3. Update navigation:
|
||||
- Find existing placeholder links (e.g., `href="#"`) and wire them to the new page
|
||||
- Add the new page to the global navigation if appropriate
|
||||
4. Ensure consistent headers/footers across all pages
|
||||
|
||||
### Step 4.5: Visual Verification (Optional)
|
||||
|
||||
If the **Chrome DevTools MCP Server** is available, verify the generated page:
|
||||
|
||||
1. **Check availability**: Run `list_tools` to see if `chrome*` tools are present
|
||||
2. **Start dev server**: Use Bash to start a local server (e.g., `npx serve site/public`)
|
||||
3. **Navigate to page**: Call `[chrome_prefix]:navigate` to open `http://localhost:3000/{page}.html`
|
||||
4. **Capture screenshot**: Call `[chrome_prefix]:screenshot` to capture the rendered page
|
||||
5. **Visual comparison**: Compare against the Stitch screenshot (`queue/{page}.png`) for fidelity
|
||||
6. **Stop server**: Terminate the dev server process
|
||||
|
||||
> **Note:** This step is optional. If Chrome DevTools MCP is not installed, skip to Step 5.
|
||||
|
||||
### Step 5: Update Site Documentation
|
||||
|
||||
Modify `SITE.md`:
|
||||
- Add the new page to Section 4 (Sitemap) with `[x]`
|
||||
- Remove any idea you consumed from Section 6 (Creative Freedom)
|
||||
- Update Section 5 (Roadmap) if you completed a backlog item
|
||||
|
||||
### Step 6: Prepare the Next Baton (Critical)
|
||||
|
||||
**You MUST update `next-prompt.md` before completing.** This keeps the loop alive.
|
||||
|
||||
1. **Decide the next page**:
|
||||
- Check `SITE.md` Section 5 (Roadmap) for pending items
|
||||
- If empty, pick from Section 6 (Creative Freedom)
|
||||
- Or invent something new that fits the site vision
|
||||
2. **Write the baton** with proper YAML frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
page: achievements
|
||||
---
|
||||
A competitive achievements page showing developer badges and milestones.
|
||||
|
||||
**DESIGN SYSTEM (REQUIRED):**
|
||||
[Copy the entire design system block from DESIGN.md]
|
||||
|
||||
**Page Structure:**
|
||||
1. Header with title and navigation
|
||||
2. Badge grid showing unlocked/locked states
|
||||
3. Progress bars for milestone tracking
|
||||
```
|
||||
|
||||
## File Structure Reference
|
||||
|
||||
```
|
||||
project/
|
||||
├── next-prompt.md # The baton — current task
|
||||
├── stitch.json # Stitch project ID (persist this!)
|
||||
├── DESIGN.md # Visual design system (from design-md skill)
|
||||
├── SITE.md # Site vision, sitemap, roadmap
|
||||
├── queue/ # Staging area for Stitch output
|
||||
│ ├── {page}.html
|
||||
│ └── {page}.png
|
||||
└── site/public/ # Production pages
|
||||
├── index.html
|
||||
└── {page}.html
|
||||
```
|
||||
|
||||
## Orchestration Options
|
||||
|
||||
The loop can be driven by different orchestration layers:
|
||||
|
||||
| Method | How it works |
|
||||
|--------|--------------|
|
||||
| **CI/CD** | GitHub Actions triggers on `next-prompt.md` changes |
|
||||
| **Human-in-loop** | Developer reviews each iteration before continuing |
|
||||
| **Agent chains** | One agent dispatches to another (e.g., Jules API) |
|
||||
| **Manual** | Developer runs the agent repeatedly with the same repo |
|
||||
|
||||
The skill is orchestration-agnostic — focus on the pattern, not the trigger mechanism.
|
||||
|
||||
## Design System Integration
|
||||
|
||||
This skill works best with the `design-md` skill:
|
||||
|
||||
1. **First time setup**: Generate `DESIGN.md` using the `design-md` skill from an existing Stitch screen
|
||||
2. **Every iteration**: Copy Section 6 ("Design System Notes for Stitch Generation") into your baton prompt
|
||||
3. **Consistency**: All generated pages will share the same visual language
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
- ❌ Forgetting to update `next-prompt.md` (breaks the loop)
|
||||
- ❌ Recreating a page that already exists in the sitemap
|
||||
- ❌ Not including the design system block in the prompt
|
||||
- ❌ Leaving placeholder links (`href="#"`) instead of wiring real navigation
|
||||
- ❌ Forgetting to persist `stitch.json` after creating a new project
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Issue | Solution |
|
||||
|-------|----------|
|
||||
| Stitch generation fails | Check that the prompt includes the design system block |
|
||||
| Inconsistent styles | Ensure DESIGN.md is up-to-date and copied correctly |
|
||||
| Loop stalls | Verify `next-prompt.md` was updated with valid frontmatter |
|
||||
| Navigation broken | Check all internal links use correct relative paths |
|
||||
127
axhub-make/skills/third-party/stitch-skills/stitch-main-workflow/SKILL.md
vendored
Normal file
127
axhub-make/skills/third-party/stitch-skills/stitch-main-workflow/SKILL.md
vendored
Normal file
@@ -0,0 +1,127 @@
|
||||
---
|
||||
name: stitch-main-workflow
|
||||
description: 本项目 Stitch 主技能/总编排：先完成 spec.md，再完成并确认 Stitch 设计，最后才允许生成 index.tsx；若 Stitch MCP 不可用则立即停止。
|
||||
allowed-tools:
|
||||
- "stitch*:*"
|
||||
- "Read"
|
||||
- "Write"
|
||||
- "Bash"
|
||||
- "web_fetch"
|
||||
- "chrome*:*"
|
||||
---
|
||||
|
||||
# Stitch 主流程（总编排）
|
||||
|
||||
本技能用于把 `design-md` / `stitch-loop` / `react-components` 组织为统一流程，强制执行：
|
||||
|
||||
1. 先完成 `spec.md`
|
||||
2. 再完成并确认 Stitch 设计
|
||||
3. 最后才允许创建或修改 `index.tsx`
|
||||
|
||||
## 目标与硬门槛（必须满足）
|
||||
|
||||
- **硬门槛 1**：未完成 Stitch 设计确认前，不允许创建或修改 `src/prototypes/<name>/index.tsx` 或 `src/components/<name>/index.tsx`。
|
||||
- **硬门槛 2**：如果 Stitch MCP 不可用或调用失败，必须直接反馈并停止，不进入代码生成阶段。
|
||||
|
||||
## 环境自检（阻塞，失败即停）
|
||||
|
||||
开始主流程前，必须先做一次 Stitch MCP 探针调用，再决定是否继续：
|
||||
|
||||
- 可用探针示例：`list_projects` 或 `create_project`
|
||||
- 探针成功：继续执行主流程
|
||||
- 探针失败：输出以下固定反馈并停止
|
||||
|
||||
```text
|
||||
⚠️ 当前环境未启用 Stitch MCP（无法调用 Stitch 工具），因此无法在 index.tsx 前完成 Stitch 设计。请启用 Stitch MCP 后重试。
|
||||
```
|
||||
|
||||
## 主流程（顺序固定）
|
||||
|
||||
### 1) 准备目标路径
|
||||
|
||||
- 目标目录只能是：
|
||||
- `src/prototypes/<name>/`
|
||||
- `src/components/<name>/`
|
||||
- `<name>` 只能使用小写字母、数字、连字符（kebab-case）
|
||||
|
||||
### 2) 先完成 `spec.md`（作为 Stitch prompt 合同）
|
||||
|
||||
- 按 `src/docs/templates/spec-template.md` 产出 `spec.md`（本技能不重复展开模板细节）
|
||||
- `spec.md` 至少包含：
|
||||
- 目标
|
||||
- 模块 IA（树形结构）
|
||||
- 关键文案语气
|
||||
- 数据字段
|
||||
- 响应式要点
|
||||
|
||||
### 3) 使用 Stitch 完成“设计”并确认
|
||||
|
||||
> **根目录 `DESIGN.md` 自动同步**：当用户在管理后台“设为默认主题”时，该主题的 `DESIGN.md` 会被自动同步到项目根目录（`/DESIGN.md`）。如果根目录存在此文件且用户没有特殊指定，应默认将其内容提交给 Stitch 作为设计规范进行生成。
|
||||
|
||||
1. （可选）如需风格统一，先用 `design-md` 从既有 Stitch screen 生成 `DESIGN.md`；或直接使用根目录已同步的 `DESIGN.md`
|
||||
2. 使用 `generate_screen_from_text`，prompt 以 `spec.md` 为基础；若有 `DESIGN.md`（优先检查根目录），把设计系统相关内容并入 prompt
|
||||
3. 使用 `get_screen` 获取最终候选 screen 的 `screenshot` 与 `htmlCode`
|
||||
4. 如果结果不符合 `spec.md`，使用 `edit_screens` 迭代，直到满足
|
||||
5. 设计确认最小产物：
|
||||
- `screenshot`
|
||||
- `html`
|
||||
|
||||
本地保存建议放在 `temp/` 或 `.drafts/`（两者都被 `.gitignore` 忽略）。
|
||||
|
||||
### 3.5) 交互与响应式提醒（按用户需求为准，不以 Stitch 产物为准）
|
||||
|
||||
Stitch 产物偏静态（HTML/CSS），经常会出现“截图对齐了，但交互/响应式并不等同于需求”的情况。这里不把检查做成硬门槛，但你必须遵守一个原则：
|
||||
|
||||
- **交互与响应式的验收基准永远来自用户需求 / `spec.md`**，不要把 Stitch 输出当成“需求本身”或“默认标准”。
|
||||
|
||||
按需做快速核对（仅在 `spec.md` 明确要求时）：
|
||||
|
||||
- **响应式**：如果 `spec.md` 要求断点/多端适配，就检查对应设备下是否塌陷、溢出、信息层级是否仍成立。
|
||||
- **交互状态**：如果 `spec.md` 要求交互/可访问性，就核对 hover/focus/disabled 等状态与键盘可达性是否满足。
|
||||
- **动态交互**：如果需求包含弹窗、抽屉、复杂表单校验、异步加载等 Stitch 难以表达的动态行为，应在 `spec.md` 明确标注为“代码阶段补齐”，避免误判“设计已完成”。
|
||||
|
||||
> 可选：若当前环境提供 Chrome MCP，可用它辅助做“缩放/断点切换 + 截图”验证，作为发现问题的手段即可。
|
||||
|
||||
### 4) 回写 `spec.md`（与 Stitch 最终设计对齐）
|
||||
|
||||
在 `spec.md` 中补齐以下字段：
|
||||
|
||||
- Stitch `projectId`
|
||||
- Stitch `screenId`
|
||||
- 截图本地保存路径
|
||||
- HTML 本地保存路径
|
||||
- 最终模块结构确认点
|
||||
|
||||
### 5) 最后生成 `index.tsx`（从 Stitch 设计落地）
|
||||
|
||||
本主流程只负责编排与 gate，具体转换实现参考：
|
||||
|
||||
- `skills/third-party/stitch-skills/react-components/SKILL.md`
|
||||
|
||||
本项目最小必须约束（仅保留以下）：
|
||||
|
||||
- `index.tsx` 顶部必须包含 `@name` 中文注释块（参考 `rules/development-guide.md`）
|
||||
- 组件或页面必须 `export default`（参考 `vite-plugins/axhubComponentEnforcer.ts`）
|
||||
- 使用 Tailwind 时，`style.css` 顶部必须包含 `@import "tailwindcss";`
|
||||
|
||||
### 6) 验收（必须跑完）
|
||||
|
||||
按目标类型执行验收脚本，结果必须为 `READY`：
|
||||
|
||||
```bash
|
||||
node scripts/check-app-ready.mjs /prototypes/<name>
|
||||
node scripts/check-app-ready.mjs /components/<name>
|
||||
```
|
||||
|
||||
## 技能路由指南（触发条件 -> 使用技能 -> 产出）
|
||||
|
||||
| 触发条件 | 使用技能 | 产出 |
|
||||
|---|---|---|
|
||||
| 已有 Stitch 设计，或多页需要统一风格 | `design-md` | `DESIGN.md`，供后续 prompt 复用 |
|
||||
| 需要多页迭代、baton 编排建站 | `stitch-loop` | 循环生成多页 screen 与任务接力 |
|
||||
| 需要把 Stitch HTML/设计落地成 React 代码 | `react-components` | 组件/页面代码，并对齐 `@name`、默认导出、Tailwind 引入约束 |
|
||||
|
||||
## 说明与非目标
|
||||
|
||||
- 本技能不重复展开“必读规范”的详细说明，只做最小引用（默认已完成基础规范阅读）。
|
||||
- 本技能不要求额外平台接口适配约束；只要求本项目最小代码约束与验收通过。
|
||||
874
axhub-make/skills/third-party/tailwind-design-system/SKILL.md
vendored
Normal file
874
axhub-make/skills/third-party/tailwind-design-system/SKILL.md
vendored
Normal file
@@ -0,0 +1,874 @@
|
||||
---
|
||||
name: tailwind-design-system
|
||||
description: Build scalable design systems with Tailwind CSS v4, design tokens, component libraries, and responsive patterns. Use when creating component libraries, implementing design systems, or standardizing UI patterns.
|
||||
---
|
||||
|
||||
# Tailwind Design System (v4)
|
||||
|
||||
Build production-ready design systems with Tailwind CSS v4, including CSS-first configuration, design tokens, component variants, responsive patterns, and accessibility.
|
||||
|
||||
> **Note**: This skill targets Tailwind CSS v4 (2024+). For v3 projects, refer to the [upgrade guide](https://tailwindcss.com/docs/upgrade-guide).
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
- Creating a component library with Tailwind v4
|
||||
- Implementing design tokens and theming with CSS-first configuration
|
||||
- Building responsive and accessible components
|
||||
- Standardizing UI patterns across a codebase
|
||||
- Migrating from Tailwind v3 to v4
|
||||
- Setting up dark mode with native CSS features
|
||||
|
||||
## Key v4 Changes
|
||||
|
||||
| v3 Pattern | v4 Pattern |
|
||||
| ------------------------------------- | --------------------------------------------------------------------- |
|
||||
| `tailwind.config.ts` | `@theme` in CSS |
|
||||
| `@tailwind base/components/utilities` | `@import "tailwindcss"` |
|
||||
| `darkMode: "class"` | `@custom-variant dark (&:where(.dark, .dark *))` |
|
||||
| `theme.extend.colors` | `@theme { --color-*: value }` |
|
||||
| `require("tailwindcss-animate")` | CSS `@keyframes` in `@theme` + `@starting-style` for entry animations |
|
||||
|
||||
## Quick Start
|
||||
|
||||
```css
|
||||
/* app.css - Tailwind v4 CSS-first configuration */
|
||||
@import "tailwindcss";
|
||||
|
||||
/* Define your theme with @theme */
|
||||
@theme {
|
||||
/* Semantic color tokens using OKLCH for better color perception */
|
||||
--color-background: oklch(100% 0 0);
|
||||
--color-foreground: oklch(14.5% 0.025 264);
|
||||
|
||||
--color-primary: oklch(14.5% 0.025 264);
|
||||
--color-primary-foreground: oklch(98% 0.01 264);
|
||||
|
||||
--color-secondary: oklch(96% 0.01 264);
|
||||
--color-secondary-foreground: oklch(14.5% 0.025 264);
|
||||
|
||||
--color-muted: oklch(96% 0.01 264);
|
||||
--color-muted-foreground: oklch(46% 0.02 264);
|
||||
|
||||
--color-accent: oklch(96% 0.01 264);
|
||||
--color-accent-foreground: oklch(14.5% 0.025 264);
|
||||
|
||||
--color-destructive: oklch(53% 0.22 27);
|
||||
--color-destructive-foreground: oklch(98% 0.01 264);
|
||||
|
||||
--color-border: oklch(91% 0.01 264);
|
||||
--color-ring: oklch(14.5% 0.025 264);
|
||||
|
||||
--color-card: oklch(100% 0 0);
|
||||
--color-card-foreground: oklch(14.5% 0.025 264);
|
||||
|
||||
/* Ring offset for focus states */
|
||||
--color-ring-offset: oklch(100% 0 0);
|
||||
|
||||
/* Radius tokens */
|
||||
--radius-sm: 0.25rem;
|
||||
--radius-md: 0.375rem;
|
||||
--radius-lg: 0.5rem;
|
||||
--radius-xl: 0.75rem;
|
||||
|
||||
/* Animation tokens - keyframes inside @theme are output when referenced by --animate-* variables */
|
||||
--animate-fade-in: fade-in 0.2s ease-out;
|
||||
--animate-fade-out: fade-out 0.2s ease-in;
|
||||
--animate-slide-in: slide-in 0.3s ease-out;
|
||||
--animate-slide-out: slide-out 0.3s ease-in;
|
||||
|
||||
@keyframes fade-in {
|
||||
from {
|
||||
opacity: 0;
|
||||
}
|
||||
to {
|
||||
opacity: 1;
|
||||
}
|
||||
}
|
||||
|
||||
@keyframes fade-out {
|
||||
from {
|
||||
opacity: 1;
|
||||
}
|
||||
to {
|
||||
opacity: 0;
|
||||
}
|
||||
}
|
||||
|
||||
@keyframes slide-in {
|
||||
from {
|
||||
transform: translateY(-0.5rem);
|
||||
opacity: 0;
|
||||
}
|
||||
to {
|
||||
transform: translateY(0);
|
||||
opacity: 1;
|
||||
}
|
||||
}
|
||||
|
||||
@keyframes slide-out {
|
||||
from {
|
||||
transform: translateY(0);
|
||||
opacity: 1;
|
||||
}
|
||||
to {
|
||||
transform: translateY(-0.5rem);
|
||||
opacity: 0;
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/* Dark mode variant - use @custom-variant for class-based dark mode */
|
||||
@custom-variant dark (&:where(.dark, .dark *));
|
||||
|
||||
/* Dark mode theme overrides */
|
||||
.dark {
|
||||
--color-background: oklch(14.5% 0.025 264);
|
||||
--color-foreground: oklch(98% 0.01 264);
|
||||
|
||||
--color-primary: oklch(98% 0.01 264);
|
||||
--color-primary-foreground: oklch(14.5% 0.025 264);
|
||||
|
||||
--color-secondary: oklch(22% 0.02 264);
|
||||
--color-secondary-foreground: oklch(98% 0.01 264);
|
||||
|
||||
--color-muted: oklch(22% 0.02 264);
|
||||
--color-muted-foreground: oklch(65% 0.02 264);
|
||||
|
||||
--color-accent: oklch(22% 0.02 264);
|
||||
--color-accent-foreground: oklch(98% 0.01 264);
|
||||
|
||||
--color-destructive: oklch(42% 0.15 27);
|
||||
--color-destructive-foreground: oklch(98% 0.01 264);
|
||||
|
||||
--color-border: oklch(22% 0.02 264);
|
||||
--color-ring: oklch(83% 0.02 264);
|
||||
|
||||
--color-card: oklch(14.5% 0.025 264);
|
||||
--color-card-foreground: oklch(98% 0.01 264);
|
||||
|
||||
--color-ring-offset: oklch(14.5% 0.025 264);
|
||||
}
|
||||
|
||||
/* Base styles */
|
||||
@layer base {
|
||||
* {
|
||||
@apply border-border;
|
||||
}
|
||||
|
||||
body {
|
||||
@apply bg-background text-foreground antialiased;
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Core Concepts
|
||||
|
||||
### 1. Design Token Hierarchy
|
||||
|
||||
```
|
||||
Brand Tokens (abstract)
|
||||
└── Semantic Tokens (purpose)
|
||||
└── Component Tokens (specific)
|
||||
|
||||
Example:
|
||||
oklch(45% 0.2 260) → --color-primary → bg-primary
|
||||
```
|
||||
|
||||
### 2. Component Architecture
|
||||
|
||||
```
|
||||
Base styles → Variants → Sizes → States → Overrides
|
||||
```
|
||||
|
||||
## Patterns
|
||||
|
||||
### Pattern 1: CVA (Class Variance Authority) Components
|
||||
|
||||
```typescript
|
||||
// components/ui/button.tsx
|
||||
import { Slot } from '@radix-ui/react-slot'
|
||||
import { cva, type VariantProps } from 'class-variance-authority'
|
||||
import { cn } from '@/lib/utils'
|
||||
|
||||
const buttonVariants = cva(
|
||||
// Base styles - v4 uses native CSS variables
|
||||
'inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
|
||||
{
|
||||
variants: {
|
||||
variant: {
|
||||
default: 'bg-primary text-primary-foreground hover:bg-primary/90',
|
||||
destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
|
||||
outline: 'border border-border bg-background hover:bg-accent hover:text-accent-foreground',
|
||||
secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
|
||||
ghost: 'hover:bg-accent hover:text-accent-foreground',
|
||||
link: 'text-primary underline-offset-4 hover:underline',
|
||||
},
|
||||
size: {
|
||||
default: 'h-10 px-4 py-2',
|
||||
sm: 'h-9 rounded-md px-3',
|
||||
lg: 'h-11 rounded-md px-8',
|
||||
icon: 'size-10',
|
||||
},
|
||||
},
|
||||
defaultVariants: {
|
||||
variant: 'default',
|
||||
size: 'default',
|
||||
},
|
||||
}
|
||||
)
|
||||
|
||||
export interface ButtonProps
|
||||
extends React.ButtonHTMLAttributes<HTMLButtonElement>,
|
||||
VariantProps<typeof buttonVariants> {
|
||||
asChild?: boolean
|
||||
}
|
||||
|
||||
// React 19: No forwardRef needed
|
||||
export function Button({
|
||||
className,
|
||||
variant,
|
||||
size,
|
||||
asChild = false,
|
||||
ref,
|
||||
...props
|
||||
}: ButtonProps & { ref?: React.Ref<HTMLButtonElement> }) {
|
||||
const Comp = asChild ? Slot : 'button'
|
||||
return (
|
||||
<Comp
|
||||
className={cn(buttonVariants({ variant, size, className }))}
|
||||
ref={ref}
|
||||
{...props}
|
||||
/>
|
||||
)
|
||||
}
|
||||
|
||||
// Usage
|
||||
<Button variant="destructive" size="lg">Delete</Button>
|
||||
<Button variant="outline">Cancel</Button>
|
||||
<Button asChild><Link href="/home">Home</Link></Button>
|
||||
```
|
||||
|
||||
### Pattern 2: Compound Components (React 19)
|
||||
|
||||
```typescript
|
||||
// components/ui/card.tsx
|
||||
import { cn } from '@/lib/utils'
|
||||
|
||||
// React 19: ref is a regular prop, no forwardRef
|
||||
export function Card({
|
||||
className,
|
||||
ref,
|
||||
...props
|
||||
}: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
|
||||
return (
|
||||
<div
|
||||
ref={ref}
|
||||
className={cn(
|
||||
'rounded-lg border border-border bg-card text-card-foreground shadow-sm',
|
||||
className
|
||||
)}
|
||||
{...props}
|
||||
/>
|
||||
)
|
||||
}
|
||||
|
||||
export function CardHeader({
|
||||
className,
|
||||
ref,
|
||||
...props
|
||||
}: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
|
||||
return (
|
||||
<div
|
||||
ref={ref}
|
||||
className={cn('flex flex-col space-y-1.5 p-6', className)}
|
||||
{...props}
|
||||
/>
|
||||
)
|
||||
}
|
||||
|
||||
export function CardTitle({
|
||||
className,
|
||||
ref,
|
||||
...props
|
||||
}: React.HTMLAttributes<HTMLHeadingElement> & { ref?: React.Ref<HTMLHeadingElement> }) {
|
||||
return (
|
||||
<h3
|
||||
ref={ref}
|
||||
className={cn('text-2xl font-semibold leading-none tracking-tight', className)}
|
||||
{...props}
|
||||
/>
|
||||
)
|
||||
}
|
||||
|
||||
export function CardDescription({
|
||||
className,
|
||||
ref,
|
||||
...props
|
||||
}: React.HTMLAttributes<HTMLParagraphElement> & { ref?: React.Ref<HTMLParagraphElement> }) {
|
||||
return (
|
||||
<p
|
||||
ref={ref}
|
||||
className={cn('text-sm text-muted-foreground', className)}
|
||||
{...props}
|
||||
/>
|
||||
)
|
||||
}
|
||||
|
||||
export function CardContent({
|
||||
className,
|
||||
ref,
|
||||
...props
|
||||
}: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
|
||||
return (
|
||||
<div ref={ref} className={cn('p-6 pt-0', className)} {...props} />
|
||||
)
|
||||
}
|
||||
|
||||
export function CardFooter({
|
||||
className,
|
||||
ref,
|
||||
...props
|
||||
}: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
|
||||
return (
|
||||
<div
|
||||
ref={ref}
|
||||
className={cn('flex items-center p-6 pt-0', className)}
|
||||
{...props}
|
||||
/>
|
||||
)
|
||||
}
|
||||
|
||||
// Usage
|
||||
<Card>
|
||||
<CardHeader>
|
||||
<CardTitle>Account</CardTitle>
|
||||
<CardDescription>Manage your account settings</CardDescription>
|
||||
</CardHeader>
|
||||
<CardContent>
|
||||
<form>...</form>
|
||||
</CardContent>
|
||||
<CardFooter>
|
||||
<Button>Save</Button>
|
||||
</CardFooter>
|
||||
</Card>
|
||||
```
|
||||
|
||||
### Pattern 3: Form Components
|
||||
|
||||
```typescript
|
||||
// components/ui/input.tsx
|
||||
import { cn } from '@/lib/utils'
|
||||
|
||||
export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
|
||||
error?: string
|
||||
ref?: React.Ref<HTMLInputElement>
|
||||
}
|
||||
|
||||
export function Input({ className, type, error, ref, ...props }: InputProps) {
|
||||
return (
|
||||
<div className="relative">
|
||||
<input
|
||||
type={type}
|
||||
className={cn(
|
||||
'flex h-10 w-full rounded-md border border-border bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
|
||||
error && 'border-destructive focus-visible:ring-destructive',
|
||||
className
|
||||
)}
|
||||
ref={ref}
|
||||
aria-invalid={!!error}
|
||||
aria-describedby={error ? `${props.id}-error` : undefined}
|
||||
{...props}
|
||||
/>
|
||||
{error && (
|
||||
<p
|
||||
id={`${props.id}-error`}
|
||||
className="mt-1 text-sm text-destructive"
|
||||
role="alert"
|
||||
>
|
||||
{error}
|
||||
</p>
|
||||
)}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
// components/ui/label.tsx
|
||||
import { cva, type VariantProps } from 'class-variance-authority'
|
||||
|
||||
const labelVariants = cva(
|
||||
'text-sm font-medium leading-none peer-disabled:cursor-not-allowed peer-disabled:opacity-70'
|
||||
)
|
||||
|
||||
export function Label({
|
||||
className,
|
||||
ref,
|
||||
...props
|
||||
}: React.LabelHTMLAttributes<HTMLLabelElement> & { ref?: React.Ref<HTMLLabelElement> }) {
|
||||
return (
|
||||
<label ref={ref} className={cn(labelVariants(), className)} {...props} />
|
||||
)
|
||||
}
|
||||
|
||||
// Usage with React Hook Form + Zod
|
||||
import { useForm } from 'react-hook-form'
|
||||
import { zodResolver } from '@hookform/resolvers/zod'
|
||||
import { z } from 'zod'
|
||||
|
||||
const schema = z.object({
|
||||
email: z.string().email('Invalid email address'),
|
||||
password: z.string().min(8, 'Password must be at least 8 characters'),
|
||||
})
|
||||
|
||||
function LoginForm() {
|
||||
const { register, handleSubmit, formState: { errors } } = useForm({
|
||||
resolver: zodResolver(schema),
|
||||
})
|
||||
|
||||
return (
|
||||
<form onSubmit={handleSubmit(onSubmit)} className="space-y-4">
|
||||
<div className="space-y-2">
|
||||
<Label htmlFor="email">Email</Label>
|
||||
<Input
|
||||
id="email"
|
||||
type="email"
|
||||
{...register('email')}
|
||||
error={errors.email?.message}
|
||||
/>
|
||||
</div>
|
||||
<div className="space-y-2">
|
||||
<Label htmlFor="password">Password</Label>
|
||||
<Input
|
||||
id="password"
|
||||
type="password"
|
||||
{...register('password')}
|
||||
error={errors.password?.message}
|
||||
/>
|
||||
</div>
|
||||
<Button type="submit" className="w-full">Sign In</Button>
|
||||
</form>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 4: Responsive Grid System
|
||||
|
||||
```typescript
|
||||
// components/ui/grid.tsx
|
||||
import { cn } from '@/lib/utils'
|
||||
import { cva, type VariantProps } from 'class-variance-authority'
|
||||
|
||||
const gridVariants = cva('grid', {
|
||||
variants: {
|
||||
cols: {
|
||||
1: 'grid-cols-1',
|
||||
2: 'grid-cols-1 sm:grid-cols-2',
|
||||
3: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3',
|
||||
4: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-4',
|
||||
5: 'grid-cols-2 sm:grid-cols-3 lg:grid-cols-5',
|
||||
6: 'grid-cols-2 sm:grid-cols-3 lg:grid-cols-6',
|
||||
},
|
||||
gap: {
|
||||
none: 'gap-0',
|
||||
sm: 'gap-2',
|
||||
md: 'gap-4',
|
||||
lg: 'gap-6',
|
||||
xl: 'gap-8',
|
||||
},
|
||||
},
|
||||
defaultVariants: {
|
||||
cols: 3,
|
||||
gap: 'md',
|
||||
},
|
||||
})
|
||||
|
||||
interface GridProps
|
||||
extends React.HTMLAttributes<HTMLDivElement>,
|
||||
VariantProps<typeof gridVariants> {}
|
||||
|
||||
export function Grid({ className, cols, gap, ...props }: GridProps) {
|
||||
return (
|
||||
<div className={cn(gridVariants({ cols, gap, className }))} {...props} />
|
||||
)
|
||||
}
|
||||
|
||||
// Container component
|
||||
const containerVariants = cva('mx-auto w-full px-4 sm:px-6 lg:px-8', {
|
||||
variants: {
|
||||
size: {
|
||||
sm: 'max-w-screen-sm',
|
||||
md: 'max-w-screen-md',
|
||||
lg: 'max-w-screen-lg',
|
||||
xl: 'max-w-screen-xl',
|
||||
'2xl': 'max-w-screen-2xl',
|
||||
full: 'max-w-full',
|
||||
},
|
||||
},
|
||||
defaultVariants: {
|
||||
size: 'xl',
|
||||
},
|
||||
})
|
||||
|
||||
interface ContainerProps
|
||||
extends React.HTMLAttributes<HTMLDivElement>,
|
||||
VariantProps<typeof containerVariants> {}
|
||||
|
||||
export function Container({ className, size, ...props }: ContainerProps) {
|
||||
return (
|
||||
<div className={cn(containerVariants({ size, className }))} {...props} />
|
||||
)
|
||||
}
|
||||
|
||||
// Usage
|
||||
<Container>
|
||||
<Grid cols={4} gap="lg">
|
||||
{products.map((product) => (
|
||||
<ProductCard key={product.id} product={product} />
|
||||
))}
|
||||
</Grid>
|
||||
</Container>
|
||||
```
|
||||
|
||||
### Pattern 5: Native CSS Animations (v4)
|
||||
|
||||
```css
|
||||
/* In your CSS file - native @starting-style for entry animations */
|
||||
@theme {
|
||||
--animate-dialog-in: dialog-fade-in 0.2s ease-out;
|
||||
--animate-dialog-out: dialog-fade-out 0.15s ease-in;
|
||||
}
|
||||
|
||||
@keyframes dialog-fade-in {
|
||||
from {
|
||||
opacity: 0;
|
||||
transform: scale(0.95) translateY(-0.5rem);
|
||||
}
|
||||
to {
|
||||
opacity: 1;
|
||||
transform: scale(1) translateY(0);
|
||||
}
|
||||
}
|
||||
|
||||
@keyframes dialog-fade-out {
|
||||
from {
|
||||
opacity: 1;
|
||||
transform: scale(1) translateY(0);
|
||||
}
|
||||
to {
|
||||
opacity: 0;
|
||||
transform: scale(0.95) translateY(-0.5rem);
|
||||
}
|
||||
}
|
||||
|
||||
/* Native popover animations using @starting-style */
|
||||
[popover] {
|
||||
transition:
|
||||
opacity 0.2s,
|
||||
transform 0.2s,
|
||||
display 0.2s allow-discrete;
|
||||
opacity: 0;
|
||||
transform: scale(0.95);
|
||||
}
|
||||
|
||||
[popover]:popover-open {
|
||||
opacity: 1;
|
||||
transform: scale(1);
|
||||
}
|
||||
|
||||
@starting-style {
|
||||
[popover]:popover-open {
|
||||
opacity: 0;
|
||||
transform: scale(0.95);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```typescript
|
||||
// components/ui/dialog.tsx - Using native popover API
|
||||
import * as DialogPrimitive from '@radix-ui/react-dialog'
|
||||
import { cn } from '@/lib/utils'
|
||||
|
||||
const DialogPortal = DialogPrimitive.Portal
|
||||
|
||||
export function DialogOverlay({
|
||||
className,
|
||||
ref,
|
||||
...props
|
||||
}: React.ComponentPropsWithoutRef<typeof DialogPrimitive.Overlay> & {
|
||||
ref?: React.Ref<HTMLDivElement>
|
||||
}) {
|
||||
return (
|
||||
<DialogPrimitive.Overlay
|
||||
ref={ref}
|
||||
className={cn(
|
||||
'fixed inset-0 z-50 bg-black/80',
|
||||
'data-[state=open]:animate-fade-in data-[state=closed]:animate-fade-out',
|
||||
className
|
||||
)}
|
||||
{...props}
|
||||
/>
|
||||
)
|
||||
}
|
||||
|
||||
export function DialogContent({
|
||||
className,
|
||||
children,
|
||||
ref,
|
||||
...props
|
||||
}: React.ComponentPropsWithoutRef<typeof DialogPrimitive.Content> & {
|
||||
ref?: React.Ref<HTMLDivElement>
|
||||
}) {
|
||||
return (
|
||||
<DialogPortal>
|
||||
<DialogOverlay />
|
||||
<DialogPrimitive.Content
|
||||
ref={ref}
|
||||
className={cn(
|
||||
'fixed left-1/2 top-1/2 z-50 grid w-full max-w-lg -translate-x-1/2 -translate-y-1/2 gap-4 border border-border bg-background p-6 shadow-lg sm:rounded-lg',
|
||||
'data-[state=open]:animate-dialog-in data-[state=closed]:animate-dialog-out',
|
||||
className
|
||||
)}
|
||||
{...props}
|
||||
>
|
||||
{children}
|
||||
</DialogPrimitive.Content>
|
||||
</DialogPortal>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
### Pattern 6: Dark Mode with CSS (v4)
|
||||
|
||||
```typescript
|
||||
// providers/ThemeProvider.tsx - Simplified for v4
|
||||
'use client'
|
||||
|
||||
import { createContext, useContext, useEffect, useState } from 'react'
|
||||
|
||||
type Theme = 'dark' | 'light' | 'system'
|
||||
|
||||
interface ThemeContextType {
|
||||
theme: Theme
|
||||
setTheme: (theme: Theme) => void
|
||||
resolvedTheme: 'dark' | 'light'
|
||||
}
|
||||
|
||||
const ThemeContext = createContext<ThemeContextType | undefined>(undefined)
|
||||
|
||||
export function ThemeProvider({
|
||||
children,
|
||||
defaultTheme = 'system',
|
||||
storageKey = 'theme',
|
||||
}: {
|
||||
children: React.ReactNode
|
||||
defaultTheme?: Theme
|
||||
storageKey?: string
|
||||
}) {
|
||||
const [theme, setTheme] = useState<Theme>(defaultTheme)
|
||||
const [resolvedTheme, setResolvedTheme] = useState<'dark' | 'light'>('light')
|
||||
|
||||
useEffect(() => {
|
||||
const stored = localStorage.getItem(storageKey) as Theme | null
|
||||
if (stored) setTheme(stored)
|
||||
}, [storageKey])
|
||||
|
||||
useEffect(() => {
|
||||
const root = document.documentElement
|
||||
root.classList.remove('light', 'dark')
|
||||
|
||||
const resolved = theme === 'system'
|
||||
? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
|
||||
: theme
|
||||
|
||||
root.classList.add(resolved)
|
||||
setResolvedTheme(resolved)
|
||||
|
||||
// Update meta theme-color for mobile browsers
|
||||
const metaThemeColor = document.querySelector('meta[name="theme-color"]')
|
||||
if (metaThemeColor) {
|
||||
metaThemeColor.setAttribute('content', resolved === 'dark' ? '#09090b' : '#ffffff')
|
||||
}
|
||||
}, [theme])
|
||||
|
||||
return (
|
||||
<ThemeContext.Provider value={{
|
||||
theme,
|
||||
setTheme: (newTheme) => {
|
||||
localStorage.setItem(storageKey, newTheme)
|
||||
setTheme(newTheme)
|
||||
},
|
||||
resolvedTheme,
|
||||
}}>
|
||||
{children}
|
||||
</ThemeContext.Provider>
|
||||
)
|
||||
}
|
||||
|
||||
export const useTheme = () => {
|
||||
const context = useContext(ThemeContext)
|
||||
if (!context) throw new Error('useTheme must be used within ThemeProvider')
|
||||
return context
|
||||
}
|
||||
|
||||
// components/ThemeToggle.tsx
|
||||
import { Moon, Sun } from 'lucide-react'
|
||||
import { useTheme } from '@/providers/ThemeProvider'
|
||||
|
||||
export function ThemeToggle() {
|
||||
const { resolvedTheme, setTheme } = useTheme()
|
||||
|
||||
return (
|
||||
<Button
|
||||
variant="ghost"
|
||||
size="icon"
|
||||
onClick={() => setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')}
|
||||
>
|
||||
<Sun className="size-5 rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
|
||||
<Moon className="absolute size-5 rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
|
||||
<span className="sr-only">Toggle theme</span>
|
||||
</Button>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Utility Functions
|
||||
|
||||
```typescript
|
||||
// lib/utils.ts
|
||||
import { type ClassValue, clsx } from "clsx";
|
||||
import { twMerge } from "tailwind-merge";
|
||||
|
||||
export function cn(...inputs: ClassValue[]) {
|
||||
return twMerge(clsx(inputs));
|
||||
}
|
||||
|
||||
// Focus ring utility
|
||||
export const focusRing = cn(
|
||||
"focus-visible:outline-none focus-visible:ring-2",
|
||||
"focus-visible:ring-ring focus-visible:ring-offset-2",
|
||||
);
|
||||
|
||||
// Disabled utility
|
||||
export const disabled = "disabled:pointer-events-none disabled:opacity-50";
|
||||
```
|
||||
|
||||
## Advanced v4 Patterns
|
||||
|
||||
### Custom Utilities with `@utility`
|
||||
|
||||
Define reusable custom utilities:
|
||||
|
||||
```css
|
||||
/* Custom utility for decorative lines */
|
||||
@utility line-t {
|
||||
@apply relative before:absolute before:top-0 before:-left-[100vw] before:h-px before:w-[200vw] before:bg-gray-950/5 dark:before:bg-white/10;
|
||||
}
|
||||
|
||||
/* Custom utility for text gradients */
|
||||
@utility text-gradient {
|
||||
@apply bg-gradient-to-r from-primary to-accent bg-clip-text text-transparent;
|
||||
}
|
||||
```
|
||||
|
||||
### Theme Modifiers
|
||||
|
||||
```css
|
||||
/* Use @theme inline when referencing other CSS variables */
|
||||
@theme inline {
|
||||
--font-sans: var(--font-inter), system-ui;
|
||||
}
|
||||
|
||||
/* Use @theme static to always generate CSS variables (even when unused) */
|
||||
@theme static {
|
||||
--color-brand: oklch(65% 0.15 240);
|
||||
}
|
||||
|
||||
/* Import with theme options */
|
||||
@import "tailwindcss" theme(static);
|
||||
```
|
||||
|
||||
### Namespace Overrides
|
||||
|
||||
```css
|
||||
@theme {
|
||||
/* Clear all default colors and define your own */
|
||||
--color-*: initial;
|
||||
--color-white: #fff;
|
||||
--color-black: #000;
|
||||
--color-primary: oklch(45% 0.2 260);
|
||||
--color-secondary: oklch(65% 0.15 200);
|
||||
|
||||
/* Clear ALL defaults for a minimal setup */
|
||||
/* --*: initial; */
|
||||
}
|
||||
```
|
||||
|
||||
### Semi-transparent Color Variants
|
||||
|
||||
```css
|
||||
@theme {
|
||||
/* Use color-mix() for alpha variants */
|
||||
--color-primary-50: color-mix(in oklab, var(--color-primary) 5%, transparent);
|
||||
--color-primary-100: color-mix(
|
||||
in oklab,
|
||||
var(--color-primary) 10%,
|
||||
transparent
|
||||
);
|
||||
--color-primary-200: color-mix(
|
||||
in oklab,
|
||||
var(--color-primary) 20%,
|
||||
transparent
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
### Container Queries
|
||||
|
||||
```css
|
||||
@theme {
|
||||
--container-xs: 20rem;
|
||||
--container-sm: 24rem;
|
||||
--container-md: 28rem;
|
||||
--container-lg: 32rem;
|
||||
}
|
||||
```
|
||||
|
||||
## v3 to v4 Migration Checklist
|
||||
|
||||
- [ ] Replace `tailwind.config.ts` with CSS `@theme` block
|
||||
- [ ] Change `@tailwind base/components/utilities` to `@import "tailwindcss"`
|
||||
- [ ] Move color definitions to `@theme { --color-*: value }`
|
||||
- [ ] Replace `darkMode: "class"` with `@custom-variant dark`
|
||||
- [ ] Move `@keyframes` inside `@theme` blocks (ensures keyframes output with theme)
|
||||
- [ ] Replace `require("tailwindcss-animate")` with native CSS animations
|
||||
- [ ] Update `h-10 w-10` to `size-10` (new utility)
|
||||
- [ ] Remove `forwardRef` (React 19 passes ref as prop)
|
||||
- [ ] Consider OKLCH colors for better color perception
|
||||
- [ ] Replace custom plugins with `@utility` directives
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Do's
|
||||
|
||||
- **Use `@theme` blocks** - CSS-first configuration is v4's core pattern
|
||||
- **Use OKLCH colors** - Better perceptual uniformity than HSL
|
||||
- **Compose with CVA** - Type-safe variants
|
||||
- **Use semantic tokens** - `bg-primary` not `bg-blue-500`
|
||||
- **Use `size-*`** - New shorthand for `w-* h-*`
|
||||
- **Add accessibility** - ARIA attributes, focus states
|
||||
|
||||
### Don'ts
|
||||
|
||||
- **Don't use `tailwind.config.ts`** - Use CSS `@theme` instead
|
||||
- **Don't use `@tailwind` directives** - Use `@import "tailwindcss"`
|
||||
- **Don't use `forwardRef`** - React 19 passes ref as prop
|
||||
- **Don't use arbitrary values** - Extend `@theme` instead
|
||||
- **Don't hardcode colors** - Use semantic tokens
|
||||
- **Don't forget dark mode** - Test both themes
|
||||
|
||||
## Resources
|
||||
|
||||
- [Tailwind CSS v4 Documentation](https://tailwindcss.com/docs)
|
||||
- [Tailwind v4 Beta Announcement](https://tailwindcss.com/blog/tailwindcss-v4-beta)
|
||||
- [CVA Documentation](https://cva.style/docs)
|
||||
- [shadcn/ui](https://ui.shadcn.com/)
|
||||
- [Radix Primitives](https://www.radix-ui.com/primitives)
|
||||
221
axhub-make/skills/third-party/taste-skill/SKILL.md
vendored
Normal file
221
axhub-make/skills/third-party/taste-skill/SKILL.md
vendored
Normal file
@@ -0,0 +1,221 @@
|
||||
# High-Agency Frontend Skill
|
||||
|
||||
## 1. ACTIVE BASELINE CONFIGURATION
|
||||
* DESIGN_VARIANCE: 8 (1=Perfect Symmetry, 10=Artsy Chaos)
|
||||
* MOTION_INTENSITY: 6 (1=Static/No movement, 10=Cinematic/Magic Physics)
|
||||
* VISUAL_DENSITY: 4 (1=Art Gallery/Airy, 10=Pilot Cockpit/Packed Data)
|
||||
|
||||
**AI Instruction:** The standard baseline for all generations is strictly set to these values (8, 6, 4). Do not ask the user to edit this file. Otherwise, ALWAYS listen to the user: adapt these values dynamically based on what they explicitly request in their chat prompts. Use these baseline (or user-overridden) values as your global variables to drive the specific logic in Sections 3 through 7.
|
||||
|
||||
## 2. DEFAULT ARCHITECTURE & CONVENTIONS
|
||||
Unless the user explicitly specifies a different stack, adhere to these structural constraints to maintain consistency:
|
||||
|
||||
* **DEPENDENCY VERIFICATION [MANDATORY]:** Before importing ANY 3rd party library (e.g. `framer-motion`, `lucide-react`, `zustand`), you MUST check `package.json`. If the package is missing, you MUST output the installation command (e.g. `npm install package-name`) before providing the code. **Never** assume a library exists.
|
||||
* **Framework & Interactivity:** React or Next.js. Default to Server Components (`RSC`).
|
||||
* **RSC SAFETY:** Global state works ONLY in Client Components. In Next.js, wrap providers in a `"use client"` component.
|
||||
* **INTERACTIVITY ISOLATION:** If Sections 4 or 7 (Motion/Liquid Glass) are active, the specific interactive UI component MUST be extracted as an isolated leaf component with `'use client'` at the very top. Server Components must exclusively render static layouts.
|
||||
* **State Management:** Use local `useState`/`useReducer` for isolated UI. Use global state strictly for deep prop-drilling avoidance.
|
||||
* **Styling Policy:** Use Tailwind CSS (v3/v4) for 90% of styling.
|
||||
* **TAILWIND VERSION LOCK:** Check `package.json` first. Do not use v4 syntax in v3 projects.
|
||||
* **T4 CONFIG GUARD:** For v4, do NOT use `tailwindcss` plugin in `postcss.config.js`. Use `@tailwindcss/postcss` or the Vite plugin.
|
||||
* **ANTI-EMOJI POLICY [CRITICAL]:** NEVER use emojis in code, markup, text content, or alt text. Replace symbols with high-quality icons (Radix, Phosphor) or clean SVG primitives. Emojis are BANNED.
|
||||
* **Responsiveness & Spacing:**
|
||||
* Standardize breakpoints (`sm`, `md`, `lg`, `xl`).
|
||||
* Contain page layouts using `max-w-[1400px] mx-auto` or `max-w-7xl`.
|
||||
* **Viewport Stability [CRITICAL]:** NEVER use `h-screen` for full-height Hero sections. ALWAYS use `min-h-[100dvh]` to prevent catastrophic layout jumping on mobile browsers (iOS Safari).
|
||||
* **Grid over Flex-Math:** NEVER use complex flexbox percentage math (`w-[calc(33%-1rem)]`). ALWAYS use CSS Grid (`grid grid-cols-1 md:grid-cols-3 gap-6`) for reliable structures.
|
||||
* **Icons:** You MUST use exactly `@phosphor-icons/react` or `@radix-ui/react-icons` as the import paths (check installed version). Standardize `strokeWidth` globally (e.g., exclusively use `1.5` or `2.0`).
|
||||
|
||||
|
||||
## 3. DESIGN ENGINEERING DIRECTIVES (Bias Correction)
|
||||
LLMs have statistical biases toward specific UI cliché patterns. Proactively construct premium interfaces using these engineered rules:
|
||||
|
||||
**Rule 1: Deterministic Typography**
|
||||
* **Display/Headlines:** Default to `text-4xl md:text-6xl tracking-tighter leading-none`.
|
||||
* **ANTI-SLOP:** Discourage `Inter` for "Premium" or "Creative" vibes. Force unique character using `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`.
|
||||
* **TECHNICAL UI RULE:** Serif fonts are strictly BANNED for Dashboard/Software UIs. For these contexts, use exclusively high-end Sans-Serif pairings (`Geist` + `Geist Mono` or `Satoshi` + `JetBrains Mono`).
|
||||
* **Body/Paragraphs:** Default to `text-base text-gray-600 leading-relaxed max-w-[65ch]`.
|
||||
|
||||
**Rule 2: Color Calibration**
|
||||
* **Constraint:** Max 1 Accent Color. Saturation < 80%.
|
||||
* **THE LILA BAN:** The "AI Purple/Blue" aesthetic is strictly BANNED. No purple button glows, no neon gradients. Use absolute neutral bases (Zinc/Slate) with high-contrast, singular accents (e.g. Emerald, Electric Blue, or Deep Rose).
|
||||
* **COLOR CONSISTENCY:** Stick to one palette for the entire output. Do not fluctuate between warm and cool grays within the same project.
|
||||
|
||||
**Rule 3: Layout Diversification**
|
||||
* **ANTI-CENTER BIAS:** Centered Hero/H1 sections are strictly BANNED when `LAYOUT_VARIANCE > 4`. Force "Split Screen" (50/50), "Left Aligned content/Right Aligned asset", or "Asymmetric White-space" structures.
|
||||
|
||||
**Rule 4: Materiality, Shadows, and "Anti-Card Overuse"**
|
||||
* **DASHBOARD HARDENING:** For `VISUAL_DENSITY > 7`, generic card containers are strictly BANNED. Use logic-grouping via `border-t`, `divide-y`, or purely negative space. Data metrics should breathe without being boxed in unless elevation (z-index) is functionally required.
|
||||
* **Execution:** Use cards ONLY when elevation communicates hierarchy. When a shadow is used, tint it to the background hue.
|
||||
|
||||
**Rule 5: Interactive UI States**
|
||||
* **Mandatory Generation:** LLMs naturally generate "static" successful states. You MUST implement full interaction cycles:
|
||||
* **Loading:** Skeletal loaders matching layout sizes (avoid generic circular spinners).
|
||||
* **Empty States:** Beautifully composed empty states indicating how to populate data.
|
||||
* **Error States:** Clear, inline error reporting (e.g., forms).
|
||||
* **Tactile Feedback:** On `:active`, use `-translate-y-[1px]` or `scale-[0.98]` to simulate a physical push indicating success/action.
|
||||
|
||||
**Rule 6: Data & Form Patterns**
|
||||
* **Forms:** Label MUST sit above input. Helper text is optional but should exist in markup. Error text below input. Use a standard `gap-2` for input blocks.
|
||||
|
||||
## 4. CREATIVE PROACTIVITY (Anti-Slop Implementation)
|
||||
To actively combat generic AI designs, systematically implement these high-end coding concepts as your baseline:
|
||||
* **"Liquid Glass" Refraction:** When glassmorphism is needed, go beyond `backdrop-blur`. Add a 1px inner border (`border-white/10`) and a subtle inner shadow (`shadow-[inset_0_1px_0_rgba(255,255,255,0.1)]`) to simulate physical edge refraction.
|
||||
* **Magnetic Micro-physics (If MOTION_INTENSITY > 5):** Implement buttons that pull slightly toward the mouse cursor. **CRITICAL:** NEVER use React `useState` for magnetic hover or continuous animations. Use EXCLUSIVELY Framer Motion's `useMotionValue` and `useTransform` outside the React render cycle to prevent performance collapse on mobile.
|
||||
* **Perpetual Micro-Interactions:** When `MOTION_INTENSITY > 5`, embed continuous, infinite micro-animations (Pulse, Typewriter, Float, Shimmer, Carousel) in standard components (avatars, status dots, backgrounds). Apply premium Spring Physics (`type: "spring", stiffness: 100, damping: 20`) to all interactive elements—no linear easing.
|
||||
* **Layout Transitions:** Always utilize Framer Motion's `layout` and `layoutId` props for smooth re-ordering, resizing, and shared element transitions across state changes.
|
||||
* **Staggered Orchestration:** Do not mount lists or grids instantly. Use `staggerChildren` (Framer) or CSS cascade (`animation-delay: calc(var(--index) * 100ms)`) to create sequential waterfall reveals. **CRITICAL:** For `staggerChildren`, the Parent (`variants`) and Children MUST reside in the identical Client Component tree. If data is fetched asynchronously, pass the data as props into a centralized Parent Motion wrapper.
|
||||
|
||||
## 5. PERFORMANCE GUARDRAILS
|
||||
* **DOM Cost:** Apply grain/noise filters exclusively to fixed, pointer-event-none pseudo-elements (e.g., `fixed inset-0 z-50 pointer-events-none`) and NEVER to scrolling containers to prevent continuous GPU repaints and mobile performance degradation.
|
||||
* **Hardware Acceleration:** Never animate `top`, `left`, `width`, or `height`. Animate exclusively via `transform` and `opacity`.
|
||||
* **Z-Index Restraint:** NEVER spam arbitrary `z-50` or `z-10` unprompted. Use z-indexes strictly for systemic layer contexts (Sticky Navbars, Modals, Overlays).
|
||||
|
||||
## 6. TECHNICAL REFERENCE (Dial Definitions)
|
||||
|
||||
### DESIGN_VARIANCE (Level 1-10)
|
||||
* **1-3 (Predictable):** Flexbox `justify-center`, strict 12-column symmetrical grids, equal paddings.
|
||||
* **4-7 (Offset):** Use `margin-top: -2rem` overlapping, varied image aspect ratios (e.g., 4:3 next to 16:9), left-aligned headers over center-aligned data.
|
||||
* **8-10 (Asymmetric):** Masonry layouts, CSS Grid with fractional units (e.g., `grid-template-columns: 2fr 1fr 1fr`), massive empty zones (`padding-left: 20vw`).
|
||||
* **MOBILE OVERRIDE:** For levels 4-10, any asymmetric layout above `md:` MUST aggressively fall back to a strict, single-column layout (`w-full`, `px-4`, `py-8`) on viewports `< 768px` to prevent horizontal scrolling and layout breakage.
|
||||
|
||||
### MOTION_INTENSITY (Level 1-10)
|
||||
* **1-3 (Static):** No automatic animations. CSS `:hover` and `:active` states only.
|
||||
* **4-7 (Fluid CSS):** Use `transition: all 0.3s cubic-bezier(0.16, 1, 0.3, 1)`. Use `animation-delay` cascades for load-ins. Focus strictly on `transform` and `opacity`. Use `will-change: transform` sparingly.
|
||||
* **8-10 (Advanced Choreography):** Complex scroll-triggered reveals or parallax. Use Framer Motion hooks. NEVER use `window.addEventListener('scroll')`.
|
||||
|
||||
### VISUAL_DENSITY (Level 1-10)
|
||||
* **1-3 (Art Gallery Mode):** Lots of white space. Huge section gaps. Everything feels very expensive and clean.
|
||||
* **4-7 (Daily App Mode):** Normal spacing for standard web apps.
|
||||
* **8-10 (Cockpit Mode):** Tiny paddings. No card boxes; just 1px lines to separate data. Everything is packed. **Mandatory:** Use Monospace (`font-mono`) for all numbers.
|
||||
|
||||
## 7. AI TELLS (Forbidden Patterns)
|
||||
To guarantee a premium, non-generic output, you MUST strictly avoid these common AI design signatures unless explicitly requested:
|
||||
|
||||
### Visual & CSS
|
||||
* **NO Neon/Outer Glows:** Do not use default `box-shadow` glows or auto-glows. Use inner borders or subtle tinted shadows.
|
||||
* **NO Pure Black:** Never use `#000000`. Use Off-Black, Zinc-950, or Charcoal.
|
||||
* **NO Oversaturated Accents:** Desaturate accents to blend elegantly with neutrals.
|
||||
* **NO Excessive Gradient Text:** Do not use text-fill gradients for large headers.
|
||||
* **NO Custom Mouse Cursors:** They are outdated and ruin performance/accessibility.
|
||||
|
||||
### Typography
|
||||
* **NO Inter Font:** Banned. Use `Geist`, `Outfit`, `Cabinet Grotesk`, or `Satoshi`.
|
||||
* **NO Oversized H1s:** The first heading should not scream. Control hierarchy with weight and color, not just massive scale.
|
||||
* **Serif Constraints:** Use Serif fonts ONLY for creative/editorial designs. **NEVER** use Serif on clean Dashboards.
|
||||
|
||||
### Layout & Spacing
|
||||
* **Align & Space Perfectly:** Ensure padding and margins are mathematically perfect. Avoid floating elements with awkward gaps.
|
||||
* **NO 3-Column Card Layouts:** The generic "3 equal cards horizontally" feature row is BANNED. Use a 2-column Zig-Zag, asymmetric grid, or horizontal scrolling approach instead.
|
||||
|
||||
### Content & Data (The "Jane Doe" Effect)
|
||||
* **NO Generic Names:** "John Doe", "Sarah Chan", or "Jack Su" are banned. Use highly creative, realistic-sounding names.
|
||||
* **NO Generic Avatars:** DO NOT use standard SVG "egg" or Lucide user icons for avatars. Use creative, believable photo placeholders or specific styling.
|
||||
* **NO Fake Numbers:** Avoid predictable outputs like `99.99%`, `50%`, or basic phone numbers (`1234567`). Use organic, messy data (`47.2%`, `+1 (312) 847-1928`).
|
||||
* **NO Startup Slop Names:** "Acme", "Nexus", "SmartFlow". Invent premium, contextual brand names.
|
||||
* **NO Filler Words:** Avoid AI copywriting clichés like "Elevate", "Seamless", "Unleash", or "Next-Gen". Use concrete verbs.
|
||||
|
||||
### External Resources & Components
|
||||
* **NO Broken Unsplash Links:** Do not use Unsplash. Use absolute, reliable placeholders like `https://picsum.photos/seed/{random_string}/800/600` or SVG UI Avatars.
|
||||
* **shadcn/ui Customization:** You may use `shadcn/ui`, but NEVER in its generic default state. You MUST customize the radii, colors, and shadows to match the high-end project aesthetic.
|
||||
* **Production-Ready Cleanliness:** Code must be extremely clean, visually striking, memorable, and meticulously refined in every detail.
|
||||
|
||||
## 8. THE CREATIVE ARSENAL (High-End Inspiration)
|
||||
Do not default to generic UI. Pull from this library of advanced concepts to ensure the output is visually striking and memorable. When appropriate, leverage **GSAP (ScrollTrigger/Parallax)** for complex scrolltelling or **ThreeJS/WebGL** for 3D/Canvas animations, rather than basic CSS motion. **CRITICAL:** Never mix GSAP/ThreeJS with Framer Motion in the same component tree. Default to Framer Motion for UI/Bento interactions. Use GSAP/ThreeJS EXCLUSIVELY for isolated full-page scrolltelling or canvas backgrounds, wrapped in strict useEffect cleanup blocks.
|
||||
|
||||
### The Standard Hero Paradigm
|
||||
* Stop doing centered text over a dark image. Try asymmetric Hero sections: Text cleanly aligned to the left or right. The background should feature a high-quality, relevant image with a subtle stylistic fade (darkening or lightening gracefully into the background color depending on if it is Light or Dark mode).
|
||||
|
||||
### Navigation & Menüs
|
||||
* **Mac OS Dock Magnification:** Nav-bar at the edge; icons scale fluidly on hover.
|
||||
* **Magnetic Button:** Buttons that physically pull toward the cursor.
|
||||
* **Gooey Menu:** Sub-items detach from the main button like a viscous liquid.
|
||||
* **Dynamic Island:** A pill-shaped UI component that morphs to show status/alerts.
|
||||
* **Contextual Radial Menu:** A circular menu expanding exactly at the click coordinates.
|
||||
* **Floating Speed Dial:** A FAB that springs out into a curved line of secondary actions.
|
||||
* **Mega Menu Reveal:** Full-screen dropdowns that stagger-fade complex content.
|
||||
|
||||
### Layout & Grids
|
||||
* **Bento Grid:** Asymmetric, tile-based grouping (e.g., Apple Control Center).
|
||||
* **Masonry Layout:** Staggered grid without fixed row heights (e.g., Pinterest).
|
||||
* **Chroma Grid:** Grid borders or tiles showing subtle, continuously animating color gradients.
|
||||
* **Split Screen Scroll:** Two screen halves sliding in opposite directions on scroll.
|
||||
* **Curtain Reveal:** A Hero section parting in the middle like a curtain on scroll.
|
||||
|
||||
### Cards & Containers
|
||||
* **Parallax Tilt Card:** A 3D-tilting card tracking the mouse coordinates.
|
||||
* **Spotlight Border Card:** Card borders that illuminate dynamically under the cursor.
|
||||
* **Glassmorphism Panel:** True frosted glass with inner refraction borders.
|
||||
* **Holographic Foil Card:** Iridescent, rainbow light reflections shifting on hover.
|
||||
* **Tinder Swipe Stack:** A physical stack of cards the user can swipe away.
|
||||
* **Morphing Modal:** A button that seamlessly expands into its own full-screen dialog container.
|
||||
|
||||
### Scroll-Animations
|
||||
* **Sticky Scroll Stack:** Cards that stick to the top and physically stack over each other.
|
||||
* **Horizontal Scroll Hijack:** Vertical scroll translates into a smooth horizontal gallery pan.
|
||||
* **Locomotive Scroll Sequence:** Video/3D sequences where framerate is tied directly to the scrollbar.
|
||||
* **Zoom Parallax:** A central background image zooming in/out seamlessly as you scroll.
|
||||
* **Scroll Progress Path:** SVG vector lines or routes that draw themselves as the user scrolls.
|
||||
* **Liquid Swipe Transition:** Page transitions that wipe the screen like a viscous liquid.
|
||||
|
||||
### Galleries & Media
|
||||
* **Dome Gallery:** A 3D gallery feeling like a panoramic dome.
|
||||
* **Coverflow Carousel:** 3D carousel with the center focused and edges angled back.
|
||||
* **Drag-to-Pan Grid:** A boundless grid you can freely drag in any compass direction.
|
||||
* **Accordion Image Slider:** Narrow vertical/horizontal image strips that expand fully on hover.
|
||||
* **Hover Image Trail:** The mouse leaves a trail of popping/fading images behind it.
|
||||
* **Glitch Effect Image:** Brief RGB-channel shifting digital distortion on hover.
|
||||
|
||||
### Typography & Text
|
||||
* **Kinetic Marquee:** Endless text bands that reverse direction or speed up on scroll.
|
||||
* **Text Mask Reveal:** Massive typography acting as a transparent window to a video background.
|
||||
* **Text Scramble Effect:** Matrix-style character decoding on load or hover.
|
||||
* **Circular Text Path:** Text curved along a spinning circular path.
|
||||
* **Gradient Stroke Animation:** Outlined text with a gradient continuously running along the stroke.
|
||||
* **Kinetic Typography Grid:** A grid of letters dodging or rotating away from the cursor.
|
||||
|
||||
### Micro-Interactions & Effects
|
||||
* **Particle Explosion Button:** CTAs that shatter into particles upon success.
|
||||
* **Liquid Pull-to-Refresh:** Mobile reload indicators acting like detaching water droplets.
|
||||
* **Skeleton Shimmer:** Shifting light reflections moving across placeholder boxes.
|
||||
* **Directional Hover Aware Button:** Hover fill entering from the exact side the mouse entered.
|
||||
* **Ripple Click Effect:** Visual waves rippling precisely from the click coordinates.
|
||||
* **Animated SVG Line Drawing:** Vectors that draw their own contours in real-time.
|
||||
* **Mesh Gradient Background:** Organic, lava-lamp-like animated color blobs.
|
||||
* **Lens Blur Depth:** Dynamic focus blurring background UI layers to highlight a foreground action.
|
||||
|
||||
## 9. THE "MOTION-ENGINE" BENTO PARADIGM
|
||||
When generating modern SaaS dashboards or feature sections, you MUST utilize the following "Bento 2.0" architecture and motion philosophy. This goes beyond static cards and enforces a "Vercel-core meets Dribbble-clean" aesthetic heavily reliant on perpetual physics.
|
||||
|
||||
### A. Core Design Philosophy
|
||||
* **Aesthetic:** High-end, minimal, and functional.
|
||||
* **Palette:** Background in `#f9fafb`. Cards are pure white (`#ffffff`) with a 1px border of `border-slate-200/50`.
|
||||
* **Surfaces:** Use `rounded-[2.5rem]` for all major containers. Apply a "diffusion shadow" (a very light, wide-spreading shadow, e.g., `shadow-[0_20px_40px_-15px_rgba(0,0,0,0.05)]`) to create depth without clutter.
|
||||
* **Typography:** Strict `Geist`, `Satoshi`, or `Cabinet Grotesk` font stack. Use subtle tracking (`tracking-tight`) for headers.
|
||||
* **Labels:** Titles and descriptions must be placed **outside and below** the cards to maintain a clean, gallery-style presentation.
|
||||
* **Pixel-Perfection:** Use generous `p-8` or `p-10` padding inside cards.
|
||||
|
||||
### B. The Animation Engine Specs (Perpetual Motion)
|
||||
All cards must contain **"Perpetual Micro-Interactions."** Use the following Framer Motion principles:
|
||||
* **Spring Physics:** No linear easing. Use `type: "spring", stiffness: 100, damping: 20` for a premium, weighty feel.
|
||||
* **Layout Transitions:** Heavily utilize the `layout` and `layoutId` props to ensure smooth re-ordering, resizing, and shared element state transitions.
|
||||
* **Infinite Loops:** Every card must have an "Active State" that loops infinitely (Pulse, Typewriter, Float, or Carousel) to ensure the dashboard feels "alive".
|
||||
* **Performance:** Wrap dynamic lists in ` ` and optimize for 60fps. **PERFORMANCE CRITICAL:** Any perpetual motion or infinite loop MUST be memoized (React.memo) and completely isolated in its own microscopic Client Component. Never trigger re-renders in the parent layout.
|
||||
|
||||
### C. The 5-Card Archetypes (Micro-Animation Specs)
|
||||
Implement these specific micro-animations when constructing Bento grids (e.g., Row 1: 3 cols | Row 2: 2 cols split 70/30):
|
||||
1. **The Intelligent List:** A vertical stack of items with an infinite auto-sorting loop. Items swap positions using `layoutId`, simulating an AI prioritizing tasks in real-time.
|
||||
2. **The Command Input:** A search/AI bar with a multi-step Typewriter Effect. It cycles through complex prompts, including a blinking cursor and a "processing" state with a shimmering loading gradient.
|
||||
3. **The Live Status:** A scheduling interface with "breathing" status indicators. Include a pop-up notification badge that emerges with an "Overshoot" spring effect, stays for 3 seconds, and vanishes.
|
||||
4. **The Wide Data Stream:** A horizontal "Infinite Carousel" of data cards or metrics. Ensure the loop is seamless (using `x: ["0%", "-100%"]`) with a speed that feels effortless.
|
||||
5. **The Contextual UI (Focus Mode):** A document view that animates a staggered highlight of a text block, followed by a "Float-in" of a floating action toolbar with micro-icons.
|
||||
|
||||
## 10. FINAL PRE-FLIGHT CHECK
|
||||
Evaluate your code against this matrix before outputting. This is the **last** filter you apply to your logic.
|
||||
- [ ] Is global state used appropriately to avoid deep prop-drilling rather than arbitrarily?
|
||||
- [ ] Is mobile layout collapse (`w-full`, `px-4`, `max-w-7xl mx-auto`) guaranteed for high-variance designs?
|
||||
- [ ] Do full-height sections safely use `min-h-[100dvh]` instead of the bugged `h-screen`?
|
||||
- [ ] Do `useEffect` animations contain strict cleanup functions?
|
||||
- [ ] Are empty, loading, and error states provided?
|
||||
- [ ] Are cards omitted in favor of spacing where possible?
|
||||
- [ ] Did you strictly isolate CPU-heavy perpetual animations in their own Client Components?
|
||||
202
axhub-make/skills/third-party/theme-factory/LICENSE.txt
vendored
Normal file
202
axhub-make/skills/third-party/theme-factory/LICENSE.txt
vendored
Normal file
@@ -0,0 +1,202 @@
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
APPENDIX: How to apply the Apache License to your work.
|
||||
|
||||
To apply the Apache License to your work, attach the following
|
||||
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||
replaced with your own identifying information. (Don't include
|
||||
the brackets!) The text should be enclosed in the appropriate
|
||||
comment syntax for the file format. We also recommend that a
|
||||
file or class name and description of purpose be included on the
|
||||
same "printed page" as the copyright notice for easier
|
||||
identification within third-party archives.
|
||||
|
||||
Copyright [yyyy] [name of copyright owner]
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
59
axhub-make/skills/third-party/theme-factory/SKILL.md
vendored
Normal file
59
axhub-make/skills/third-party/theme-factory/SKILL.md
vendored
Normal file
@@ -0,0 +1,59 @@
|
||||
---
|
||||
name: theme-factory
|
||||
description: Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.
|
||||
license: Complete terms in LICENSE.txt
|
||||
---
|
||||
|
||||
|
||||
# Theme Factory Skill
|
||||
|
||||
This skill provides a curated collection of professional font and color themes themes, each with carefully selected color palettes and font pairings. Once a theme is chosen, it can be applied to any artifact.
|
||||
|
||||
## Purpose
|
||||
|
||||
To apply consistent, professional styling to presentation slide decks, use this skill. Each theme includes:
|
||||
- A cohesive color palette with hex codes
|
||||
- Complementary font pairings for headers and body text
|
||||
- A distinct visual identity suitable for different contexts and audiences
|
||||
|
||||
## Usage Instructions
|
||||
|
||||
To apply styling to a slide deck or other artifact:
|
||||
|
||||
1. **Show the theme showcase**: Display the `theme-showcase.pdf` file to allow users to see all available themes visually. Do not make any modifications to it; simply show the file for viewing.
|
||||
2. **Ask for their choice**: Ask which theme to apply to the deck
|
||||
3. **Wait for selection**: Get explicit confirmation about the chosen theme
|
||||
4. **Apply the theme**: Once a theme has been chosen, apply the selected theme's colors and fonts to the deck/artifact
|
||||
|
||||
## Themes Available
|
||||
|
||||
The following 10 themes are available, each showcased in `theme-showcase.pdf`:
|
||||
|
||||
1. **Ocean Depths** - Professional and calming maritime theme
|
||||
2. **Sunset Boulevard** - Warm and vibrant sunset colors
|
||||
3. **Forest Canopy** - Natural and grounded earth tones
|
||||
4. **Modern Minimalist** - Clean and contemporary grayscale
|
||||
5. **Golden Hour** - Rich and warm autumnal palette
|
||||
6. **Arctic Frost** - Cool and crisp winter-inspired theme
|
||||
7. **Desert Rose** - Soft and sophisticated dusty tones
|
||||
8. **Tech Innovation** - Bold and modern tech aesthetic
|
||||
9. **Botanical Garden** - Fresh and organic garden colors
|
||||
10. **Midnight Galaxy** - Dramatic and cosmic deep tones
|
||||
|
||||
## Theme Details
|
||||
|
||||
Each theme is defined in the `themes/` directory with complete specifications including:
|
||||
- Cohesive color palette with hex codes
|
||||
- Complementary font pairings for headers and body text
|
||||
- Distinct visual identity suitable for different contexts and audiences
|
||||
|
||||
## Application Process
|
||||
|
||||
After a preferred theme is selected:
|
||||
1. Read the corresponding theme file from the `themes/` directory
|
||||
2. Apply the specified colors and fonts consistently throughout the deck
|
||||
3. Ensure proper contrast and readability
|
||||
4. Maintain the theme's visual identity across all slides
|
||||
|
||||
## Create your Own Theme
|
||||
To handle cases where none of the existing themes work for an artifact, create a custom theme. Based on provided inputs, generate a new theme similar to the ones above. Give the theme a similar name describing what the font/color combinations represent. Use any basic description provided to choose appropriate colors/fonts. After generating the theme, show it for review and verification. Following that, apply the theme as described above.
|
||||
BIN
axhub-make/skills/third-party/theme-factory/theme-showcase.pdf
vendored
Normal file
BIN
axhub-make/skills/third-party/theme-factory/theme-showcase.pdf
vendored
Normal file
Binary file not shown.
19
axhub-make/skills/third-party/theme-factory/themes/arctic-frost.md
vendored
Normal file
19
axhub-make/skills/third-party/theme-factory/themes/arctic-frost.md
vendored
Normal file
@@ -0,0 +1,19 @@
|
||||
# Arctic Frost
|
||||
|
||||
A cool and crisp winter-inspired theme that conveys clarity, precision, and professionalism.
|
||||
|
||||
## Color Palette
|
||||
|
||||
- **Ice Blue**: `#d4e4f7` - Light backgrounds and highlights
|
||||
- **Steel Blue**: `#4a6fa5` - Primary accent color
|
||||
- **Silver**: `#c0c0c0` - Metallic accent elements
|
||||
- **Crisp White**: `#fafafa` - Clean backgrounds and text
|
||||
|
||||
## Typography
|
||||
|
||||
- **Headers**: DejaVu Sans Bold
|
||||
- **Body Text**: DejaVu Sans
|
||||
|
||||
## Best Used For
|
||||
|
||||
Healthcare presentations, technology solutions, winter sports, clean tech, pharmaceutical content.
|
||||
19
axhub-make/skills/third-party/theme-factory/themes/botanical-garden.md
vendored
Normal file
19
axhub-make/skills/third-party/theme-factory/themes/botanical-garden.md
vendored
Normal file
@@ -0,0 +1,19 @@
|
||||
# Botanical Garden
|
||||
|
||||
A fresh and organic theme featuring vibrant garden-inspired colors for lively presentations.
|
||||
|
||||
## Color Palette
|
||||
|
||||
- **Fern Green**: `#4a7c59` - Rich natural green
|
||||
- **Marigold**: `#f9a620` - Bright floral accent
|
||||
- **Terracotta**: `#b7472a` - Earthy warm tone
|
||||
- **Cream**: `#f5f3ed` - Soft neutral backgrounds
|
||||
|
||||
## Typography
|
||||
|
||||
- **Headers**: DejaVu Serif Bold
|
||||
- **Body Text**: DejaVu Sans
|
||||
|
||||
## Best Used For
|
||||
|
||||
Garden centers, food presentations, farm-to-table content, botanical brands, natural products.
|
||||
19
axhub-make/skills/third-party/theme-factory/themes/desert-rose.md
vendored
Normal file
19
axhub-make/skills/third-party/theme-factory/themes/desert-rose.md
vendored
Normal file
@@ -0,0 +1,19 @@
|
||||
# Desert Rose
|
||||
|
||||
A soft and sophisticated theme with dusty, muted tones perfect for elegant presentations.
|
||||
|
||||
## Color Palette
|
||||
|
||||
- **Dusty Rose**: `#d4a5a5` - Soft primary color
|
||||
- **Clay**: `#b87d6d` - Earthy accent
|
||||
- **Sand**: `#e8d5c4` - Warm neutral backgrounds
|
||||
- **Deep Burgundy**: `#5d2e46` - Rich dark contrast
|
||||
|
||||
## Typography
|
||||
|
||||
- **Headers**: FreeSans Bold
|
||||
- **Body Text**: FreeSans
|
||||
|
||||
## Best Used For
|
||||
|
||||
Fashion presentations, beauty brands, wedding planning, interior design, boutique businesses.
|
||||
19
axhub-make/skills/third-party/theme-factory/themes/forest-canopy.md
vendored
Normal file
19
axhub-make/skills/third-party/theme-factory/themes/forest-canopy.md
vendored
Normal file
@@ -0,0 +1,19 @@
|
||||
# Forest Canopy
|
||||
|
||||
A natural and grounded theme featuring earth tones inspired by dense forest environments.
|
||||
|
||||
## Color Palette
|
||||
|
||||
- **Forest Green**: `#2d4a2b` - Primary dark green
|
||||
- **Sage**: `#7d8471` - Muted green accent
|
||||
- **Olive**: `#a4ac86` - Light accent color
|
||||
- **Ivory**: `#faf9f6` - Backgrounds and text
|
||||
|
||||
## Typography
|
||||
|
||||
- **Headers**: FreeSerif Bold
|
||||
- **Body Text**: FreeSans
|
||||
|
||||
## Best Used For
|
||||
|
||||
Environmental presentations, sustainability reports, outdoor brands, wellness content, organic products.
|
||||
19
axhub-make/skills/third-party/theme-factory/themes/golden-hour.md
vendored
Normal file
19
axhub-make/skills/third-party/theme-factory/themes/golden-hour.md
vendored
Normal file
@@ -0,0 +1,19 @@
|
||||
# Golden Hour
|
||||
|
||||
A rich and warm autumnal palette that creates an inviting and sophisticated atmosphere.
|
||||
|
||||
## Color Palette
|
||||
|
||||
- **Mustard Yellow**: `#f4a900` - Bold primary accent
|
||||
- **Terracotta**: `#c1666b` - Warm secondary color
|
||||
- **Warm Beige**: `#d4b896` - Neutral backgrounds
|
||||
- **Chocolate Brown**: `#4a403a` - Dark text and anchors
|
||||
|
||||
## Typography
|
||||
|
||||
- **Headers**: FreeSans Bold
|
||||
- **Body Text**: FreeSans
|
||||
|
||||
## Best Used For
|
||||
|
||||
Restaurant presentations, hospitality brands, fall campaigns, cozy lifestyle content, artisan products.
|
||||
19
axhub-make/skills/third-party/theme-factory/themes/midnight-galaxy.md
vendored
Normal file
19
axhub-make/skills/third-party/theme-factory/themes/midnight-galaxy.md
vendored
Normal file
@@ -0,0 +1,19 @@
|
||||
# Midnight Galaxy
|
||||
|
||||
A dramatic and cosmic theme with deep purples and mystical tones for impactful presentations.
|
||||
|
||||
## Color Palette
|
||||
|
||||
- **Deep Purple**: `#2b1e3e` - Rich dark base
|
||||
- **Cosmic Blue**: `#4a4e8f` - Mystical mid-tone
|
||||
- **Lavender**: `#a490c2` - Soft accent color
|
||||
- **Silver**: `#e6e6fa` - Light highlights and text
|
||||
|
||||
## Typography
|
||||
|
||||
- **Headers**: FreeSans Bold
|
||||
- **Body Text**: FreeSans
|
||||
|
||||
## Best Used For
|
||||
|
||||
Entertainment industry, gaming presentations, nightlife venues, luxury brands, creative agencies.
|
||||
19
axhub-make/skills/third-party/theme-factory/themes/modern-minimalist.md
vendored
Normal file
19
axhub-make/skills/third-party/theme-factory/themes/modern-minimalist.md
vendored
Normal file
@@ -0,0 +1,19 @@
|
||||
# Modern Minimalist
|
||||
|
||||
A clean and contemporary theme with a sophisticated grayscale palette for maximum versatility.
|
||||
|
||||
## Color Palette
|
||||
|
||||
- **Charcoal**: `#36454f` - Primary dark color
|
||||
- **Slate Gray**: `#708090` - Medium gray for accents
|
||||
- **Light Gray**: `#d3d3d3` - Backgrounds and dividers
|
||||
- **White**: `#ffffff` - Text and clean backgrounds
|
||||
|
||||
## Typography
|
||||
|
||||
- **Headers**: DejaVu Sans Bold
|
||||
- **Body Text**: DejaVu Sans
|
||||
|
||||
## Best Used For
|
||||
|
||||
Tech presentations, architecture portfolios, design showcases, modern business proposals, data visualization.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user