Initial commit: OneOS prototype workspace baseline.
Include weekly report and other prototype sources with project tooling config. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
王冕
109
rules/ai-studio-project-converter.md
Normal file
109
rules/ai-studio-project-converter.md
Normal file
@@ -0,0 +1,109 @@
|
||||
# AI Studio 项目转换规则
|
||||
|
||||
用于将 Google AI Studio 生成的 React 项目转换为本项目原型页面，保持视觉和功能，并符合 `rules/prototype-development-guide.md`。
|
||||
|
||||
## 目标
|
||||
|
||||
- 移除 AI Studio 特定入口与 HTML 模板。
|
||||
- 将 Import Map / CDN 依赖转为 npm 依赖。
|
||||
- 产出可在 `src/prototypes/<name>/` 中运行的 React 页面。
|
||||
|
||||
## 预处理
|
||||
|
||||
```bash
|
||||
node scripts/ai-studio-converter.mjs <ai-studio-project-dir> [output-name]
|
||||
```
|
||||
|
||||
脚本位于客户端项目 `scripts/` 目录。它会复制项目、分析 Import Map、样式、依赖和环境变量，并生成任务文档与分析 JSON。脚本不直接修改业务代码。
|
||||
|
||||
## 典型结构
|
||||
|
||||
```text
|
||||
ai-studio-project/
|
||||
├── assets/
|
||||
├── components/
|
||||
├── App.tsx
|
||||
├── index.tsx
|
||||
├── index.html
|
||||
├── constants.ts
|
||||
├── types.ts
|
||||
├── vite.config.ts
|
||||
└── metadata.json
|
||||
```
|
||||
|
||||
重点处理：
|
||||
|
||||
- `App.tsx`：转换为本项目 `index.tsx` 入口组件。
|
||||
- `index.html`：提取 Import Map、Tailwind CDN、自定义样式和字体后删除。
|
||||
- `index.tsx`：本项目已有挂载入口，删除。
|
||||
|
||||
## 默认页面格式
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* @name 页面名称
|
||||
*
|
||||
* 参考资料：
|
||||
* - /rules/prototype-development-guide.md
|
||||
*/
|
||||
|
||||
import './style.css';
|
||||
import React from 'react';
|
||||
|
||||
export default function PageName() {
|
||||
return (
|
||||
<div />
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
默认保持普通 React 组件；只有明确需要外部接管、配置、数据、事件或动作时，才参考 `rules/axure-api-guide.md` 接入 Axure API。
|
||||
|
||||
## 样式迁移
|
||||
|
||||
从 `index.html` 提取 `<style>` 和外部字体，写入 `style.css`：
|
||||
|
||||
```css
|
||||
@import "tailwindcss";
|
||||
@import url('https://fonts.googleapis.com/css2?family=...');
|
||||
```
|
||||
|
||||
保留原有 Tailwind 类名、自定义动画和 CSS 变量。
|
||||
|
||||
## Import Map 转换
|
||||
|
||||
将 CDN 依赖转换为 npm 包：
|
||||
|
||||
| Import Map | npm 包 |
|
||||
|------------|--------|
|
||||
| `https://esm.sh/lucide-react` | `lucide-react` |
|
||||
| `https://esm.sh/framer-motion` | `framer-motion` |
|
||||
| `https://esm.sh/@google/genai` | `@google/genai` |
|
||||
|
||||
排除 `react` 和 `react-dom`，本项目已提供。
|
||||
|
||||
## 环境变量
|
||||
|
||||
将 `process.env.*` 改为 `import.meta.env.VITE_*`，并告知用户需要配置的 `.env.local` 项。
|
||||
|
||||
## 移除文件
|
||||
|
||||
完成迁移后移除：
|
||||
|
||||
- `index.html`
|
||||
- `index.tsx`
|
||||
- `metadata.json`（可保留为参考，但不作为运行入口）
|
||||
|
||||
## 验收
|
||||
|
||||
```bash
|
||||
node scripts/check-app-ready.mjs /prototypes/[页面名]
|
||||
```
|
||||
|
||||
要求：
|
||||
|
||||
- 状态为 `READY`。
|
||||
- 页面正常渲染。
|
||||
- 无控制台错误。
|
||||
- 关键交互正常。
|
||||
- 样式显示正确。
|
||||
183
rules/axure-api-guide.md
Normal file
183
rules/axure-api-guide.md
Normal file
@@ -0,0 +1,183 @@
|
||||
# Axure API 指南
|
||||
|
||||
本文说明何时以及如何在原型中接入 Axure API。默认保持普通 React 组件；只有明确需要外部接管、配置、数据、事件或动作时才接入。
|
||||
|
||||
## 何时使用
|
||||
|
||||
使用场景：
|
||||
|
||||
- 需要与 Axure 原型交互。
|
||||
- 需要配置面板。
|
||||
- 需要接收外部数据源。
|
||||
- 需要触发事件或响应动作。
|
||||
- 需要向外暴露变量。
|
||||
|
||||
不使用场景：
|
||||
|
||||
- 纯展示型页面。
|
||||
- 不需要外部交互的普通原型。
|
||||
- 标准 React 组件即可满足需求。
|
||||
|
||||
## 组件结构
|
||||
|
||||
```typescript
|
||||
import React, { forwardRef, useImperativeHandle } from 'react';
|
||||
import type { AxureHandle, AxureProps } from '../../common/axure-types';
|
||||
|
||||
const Component = forwardRef(function MyComponent(
|
||||
innerProps: AxureProps,
|
||||
ref: React.ForwardedRef<AxureHandle>,
|
||||
) {
|
||||
useImperativeHandle(ref, function () {
|
||||
return {
|
||||
getVar: function (name: string) {
|
||||
return undefined;
|
||||
},
|
||||
fireAction: function (name: string, params?: string) {
|
||||
return undefined;
|
||||
},
|
||||
eventList: EVENT_LIST,
|
||||
actionList: ACTION_LIST,
|
||||
varList: VAR_LIST,
|
||||
configList: CONFIG_LIST,
|
||||
dataList: DATA_LIST,
|
||||
};
|
||||
}, []);
|
||||
|
||||
return <div />;
|
||||
});
|
||||
|
||||
export default Component;
|
||||
```
|
||||
|
||||
## Props 处理
|
||||
|
||||
```typescript
|
||||
const dataSource = innerProps && innerProps.data ? innerProps.data : {};
|
||||
const configSource = innerProps && innerProps.config ? innerProps.config : {};
|
||||
const onEventHandler = typeof innerProps.onEvent === 'function'
|
||||
? innerProps.onEvent
|
||||
: function () { return undefined; };
|
||||
|
||||
const title = typeof configSource.title === 'string' && configSource.title
|
||||
? configSource.title
|
||||
: '默认标题';
|
||||
```
|
||||
|
||||
避免用 `||` 覆盖合法的空值、`0` 或 `false`。
|
||||
|
||||
## 事件
|
||||
|
||||
事件 payload 必须是字符串。复杂数据使用 `JSON.stringify()`。
|
||||
|
||||
```typescript
|
||||
import type { EventItem } from '../../common/axure-types';
|
||||
|
||||
const EVENT_LIST: EventItem[] = [
|
||||
{ name: 'onClick', desc: '点击按钮时触发' },
|
||||
{ name: 'onChange', desc: '值改变时触发，payload 为 JSON 字符串' },
|
||||
];
|
||||
|
||||
function emitEvent(eventName: string, payload?: string) {
|
||||
try {
|
||||
onEventHandler(eventName, payload);
|
||||
} catch (error) {
|
||||
console.warn('事件触发失败:', eventName, error);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 动作
|
||||
|
||||
动作 `params` 必须是字符串。复杂参数使用 JSON 字符串，并在 `desc` 中说明格式。
|
||||
|
||||
```typescript
|
||||
import type { Action } from '../../common/axure-types';
|
||||
|
||||
const ACTION_LIST: Action[] = [
|
||||
{ name: 'reset', desc: '重置到初始状态' },
|
||||
{ name: 'setValue', desc: '设置值，参数格式：JSON 字符串 {"value":"新值"}', params: 'JSON string' },
|
||||
];
|
||||
|
||||
function fireActionHandler(name: string, params?: string) {
|
||||
switch (name) {
|
||||
case 'reset':
|
||||
break;
|
||||
case 'setValue':
|
||||
if (!params) return;
|
||||
try {
|
||||
const parsed = JSON.parse(params);
|
||||
console.log(parsed.value);
|
||||
} catch (error) {
|
||||
console.warn('参数解析失败:', error);
|
||||
}
|
||||
break;
|
||||
default:
|
||||
console.warn('未知动作:', name);
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## 变量
|
||||
|
||||
变量名使用 snake_case。
|
||||
|
||||
```typescript
|
||||
import type { KeyDesc } from '../../common/axure-types';
|
||||
|
||||
const VAR_LIST: KeyDesc[] = [
|
||||
{ name: 'value', desc: '当前值' },
|
||||
{ name: 'is_valid', desc: '是否有效' },
|
||||
];
|
||||
```
|
||||
|
||||
`getVar(name)` 返回值必须与 `VAR_LIST` 中的命名一致。
|
||||
|
||||
## 配置项
|
||||
|
||||
```typescript
|
||||
import type { ConfigItem } from '../../common/axure-types';
|
||||
|
||||
const CONFIG_LIST: ConfigItem[] = [
|
||||
{
|
||||
type: 'input',
|
||||
attributeId: 'title',
|
||||
displayName: '标题',
|
||||
info: '组件顶部显示的标题文本',
|
||||
initialValue: '默认标题',
|
||||
},
|
||||
{
|
||||
type: 'switch',
|
||||
attributeId: 'disabled',
|
||||
displayName: '禁用',
|
||||
info: '是否禁用组件',
|
||||
initialValue: false,
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
常见类型包括 `input`、`inputNumber`、`switch`、`select`、`color`。更多类型参考 `src/common/config-panel-types.ts`。
|
||||
|
||||
## 数据项
|
||||
|
||||
```typescript
|
||||
import type { DataDesc } from '../../common/axure-types';
|
||||
|
||||
const DATA_LIST: DataDesc[] = [
|
||||
{
|
||||
name: 'users',
|
||||
desc: '用户列表',
|
||||
keys: [
|
||||
{ name: 'id', desc: '用户唯一标识' },
|
||||
{ name: 'name', desc: '用户姓名' },
|
||||
],
|
||||
},
|
||||
];
|
||||
```
|
||||
|
||||
## 自检
|
||||
|
||||
- `eventList` / `actionList` / `varList` / `configList` / `dataList` 与实际实现一致。
|
||||
- 事件 payload 和动作 params 都是字符串。
|
||||
- 变量名使用 snake_case。
|
||||
- 仅在明确需要 Axure API 时引入 `forwardRef` 和 `useImperativeHandle`。
|
||||
74
rules/axure-export-workflow.md
Normal file
74
rules/axure-export-workflow.md
Normal file
@@ -0,0 +1,74 @@
|
||||
# Axure 导出修复规则
|
||||
|
||||
用于“导出到 Axure”前的代码检查失败场景，处理规范问题、补齐 `@mode axure`，并让目标文件通过当前检测链路。
|
||||
|
||||
## 适用场景
|
||||
|
||||
- 用户在导出到 Axure 前触发 code-review 失败。
|
||||
- 需要快速修复当前导出检测错误。
|
||||
- 需要补齐 Axure 模式头注释。
|
||||
|
||||
## 目标
|
||||
|
||||
1. 优先修复 `error`，再评估 `warning`。
|
||||
2. 不改变现有业务功能、交互和视觉表现。
|
||||
3. 让目标文件通过当前导出前检查。
|
||||
|
||||
## 固定流程
|
||||
|
||||
### 1. 锁定修改范围
|
||||
|
||||
- 只修改报错目标文件，通常是 `src/prototypes/<name>/index.tsx`。
|
||||
- 不主动重构无关代码。
|
||||
- 不处理 Figma 等第三方导出链路。
|
||||
|
||||
### 2. 按优先级修复检查项
|
||||
|
||||
- `error` 必须修复。
|
||||
- `warning` 尽量修复；无法安全修复时在交付说明中说明。
|
||||
- 每项改动都保持原有行为一致。
|
||||
|
||||
### 3. 补齐头部注释
|
||||
|
||||
用于 Axure 导出的文件头建议包含：
|
||||
|
||||
- `@name`
|
||||
- `@mode axure`
|
||||
- `rules/axure-export-workflow.md`
|
||||
- `rules/prototype-development-guide.md`
|
||||
- `rules/axure-api-guide.md`（需要 Axure API 时）
|
||||
|
||||
模板：
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* @name 组件或页面名称
|
||||
* @mode axure
|
||||
*
|
||||
* 参考资料：
|
||||
* - /rules/axure-export-workflow.md
|
||||
* - /rules/prototype-development-guide.md
|
||||
* - /rules/axure-api-guide.md
|
||||
*/
|
||||
```
|
||||
|
||||
导出组件名必须满足当前检测要求；Axure 导出模式下默认使用 `Component` 并 `export default Component`。
|
||||
|
||||
### 4. Axure API 处理策略
|
||||
|
||||
- Axure API 是可选项。
|
||||
- 不为了“通过导出检测”强行引入 `forwardRef<AxureHandle, AxureProps>`。
|
||||
- 只有明确需要配置面板、外部数据源、事件回调或动作触发时，才按 `rules/axure-api-guide.md` 集成。
|
||||
|
||||
### 5. 交付前自检
|
||||
|
||||
- 全部阻断错误已修复。
|
||||
- warning 已评估并尽量处理。
|
||||
- 文件头包含 `@mode axure` 和相关 rules 路径。
|
||||
- 默认导出符合当前导出检查逻辑。
|
||||
|
||||
## 非目标
|
||||
|
||||
- 不扩展到 Figma 或其他导出链路。
|
||||
- 不修改构建插件和检查规则策略。
|
||||
- 不进行大规模样式重写或架构重构。
|
||||
109
rules/prototype-development-guide.md
Normal file
109
rules/prototype-development-guide.md
Normal file
@@ -0,0 +1,109 @@
|
||||
# 原型开发与验收指南
|
||||
|
||||
用于 `src/prototypes/<name>/` 下的原型实现、局部修改、多页面组织和预览验收。主题创建、派生和主题页验收优先看 `rules/theme-guide.md`。
|
||||
|
||||
开发流程：
|
||||
|
||||
```text
|
||||
读取已确认需求和设计决策 -> 修改原型目录内代码 -> 运行验收脚本 -> 按错误信息修复 -> 重新验收
|
||||
```
|
||||
|
||||
## 实现边界
|
||||
|
||||
- 一个原型目录就是主要隔离边界，页面组件、样式和素材优先留在对应原型目录内。
|
||||
- 不为单个原型随意修改 `src/common/`、全局主题或共享工具。
|
||||
- 多步骤或高风险修改先拆成短任务，逐项处理并维护当前状态。
|
||||
- 一次只处理一个明确问题；遇到构建、运行或验收失败，先定位原因再继续。
|
||||
- 完成后必须通过预览验收；纯视觉、文案、布局和素材调整不要求测试驱动。
|
||||
|
||||
## 文件结构与命名
|
||||
|
||||
```text
|
||||
src/prototypes/<name>/
|
||||
├── index.tsx # 必需
|
||||
├── style.css # 可选
|
||||
├── components/ # 可选：原型内部共享组件
|
||||
├── pages/ # 可选：多页面原型页面组件
|
||||
└── assets/ # 可选：原型专属素材
|
||||
```
|
||||
|
||||
- 原型入口文件必须是 `index.tsx`。
|
||||
- 原型目录名使用小写字母、数字、连字符，如 `order-review`。
|
||||
- 当目录名为 `untitled`、`untitled-*` 或显示名为「未命名」时，开始生成实际内容前应更新为有意义的目录名和 `@name`。
|
||||
- 本项目当前不产出独立 `components` 资源；原型内部组件放在对应原型目录下的 `components/`。
|
||||
|
||||
每个原型的 `index.tsx` 顶部建议包含面向用户的中文 `@name`，用于预览列表展示名：
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* @name 评审工作台
|
||||
*/
|
||||
```
|
||||
|
||||
## 多页面原型
|
||||
|
||||
单个原型可以包含多个页面，通过 URL hash 参数 `#page=<pageId>` 定位：
|
||||
|
||||
```text
|
||||
/prototypes/express-app/#page=home
|
||||
/prototypes/express-app/#page=detail
|
||||
```
|
||||
|
||||
多页面仍属于同一个原型目录；页面组件放在原型内部的 `pages/`，跨页面共享组件放在原型内部的 `components/`。
|
||||
|
||||
使用公共 hook `src/common/useHashPage.ts`：
|
||||
|
||||
```typescript
|
||||
import { useHashPage } from '../../common/useHashPage';
|
||||
|
||||
export default function MyApp() {
|
||||
const { page, setPage } = useHashPage('home');
|
||||
// page === 'home' | 'detail' | ...
|
||||
}
|
||||
```
|
||||
|
||||
- `pageId` 命名使用小写字母、数字、连字符。
|
||||
- 不带 `#page=` 时自动使用 `defaultPage`。
|
||||
- 此路由完全在原型内部，不影响构建。
|
||||
|
||||
参考实现：`src/prototypes/ref-app-home/index.tsx`。
|
||||
|
||||
## 依赖与样式
|
||||
|
||||
- React 与 Hooks 直接从 `react` 导入。
|
||||
- 第三方库按需导入，新增依赖必须同步更新 `package.json`。
|
||||
- 使用 Tailwind CSS V4 时，入口样式文件需包含：
|
||||
|
||||
```css
|
||||
@import "tailwindcss";
|
||||
```
|
||||
|
||||
- 使用主题 CSS Variables 时，按所选 `DESIGN.md` 和主题规则引入，不复制另一套 token。
|
||||
|
||||
## 验收流程
|
||||
|
||||
运行原型验收脚本：
|
||||
|
||||
```bash
|
||||
node scripts/check-app-ready.mjs /prototypes/[原型目录]
|
||||
```
|
||||
|
||||
关键返回字段：
|
||||
|
||||
- `status`: `READY` / `ERROR` / `TIMEOUT`。
|
||||
- `targetUrl`: 本次验收目标地址。
|
||||
- `errors`: 构建、运行时或页面加载错误列表。
|
||||
|
||||
错误处理：
|
||||
|
||||
- `ERROR`：按 `errors` 修复后重新执行验收脚本，直到通过。
|
||||
- `TIMEOUT`：优先排查 dev server 启动、端口、长任务和运行时阻塞。
|
||||
- 修复时先处理构建、启动和运行时报错，再处理交互与视觉问题；一次只修一个明确问题，修完重新验收。
|
||||
|
||||
## 最小清单
|
||||
|
||||
- [ ] `index.tsx` 完整存在。
|
||||
- [ ] `index.tsx` 顶部有清晰的 `@name`。
|
||||
- [ ] 占位原型已更新为有意义的目录名和显示名。
|
||||
- [ ] 新增依赖已写入 `package.json`。
|
||||
- [ ] `check-app-ready.mjs` 原型验收通过。
|
||||
151
rules/prototype-review-guide.md
Normal file
151
rules/prototype-review-guide.md
Normal file
@@ -0,0 +1,151 @@
|
||||
# 原型 Review 指导
|
||||
|
||||
用于审查 Axhub Make client 原型的业务完整性、项目对齐、逻辑连贯性、数据一致性、状态、异常、边界条件和恢复路径。
|
||||
|
||||
本规则关注“这个原型表达的业务是否成立”。视觉美观、品牌一致性、响应式和可访问性问题按 `rules/ui-review-guide.md` 处理。
|
||||
|
||||
## 审查入口
|
||||
|
||||
当用户说「原型评审」「需求评审」「业务逻辑评审」「看看缺漏」「检查状态和错误处理」「帮我从业务角度挑问题」时，读取本规则并输出 Markdown 评审结论。
|
||||
|
||||
不要输出 JSON，不要写 JSON 文件。
|
||||
|
||||
## 审查依据
|
||||
|
||||
审查依据按以下优先级使用：
|
||||
|
||||
1. 用户当前说明、附件、链接、截图、需求文档、PRD、会议纪要、业务规则、字段表、数据样例等用户提供的信息源。用户提供的信息源权重最高。
|
||||
2. `src/prototypes/<prototype-id>/.spec/` 中最近的决策、规格或计划 Markdown。排除 `ui-review.md`、`prototype-review.md` 和其他 review 结果。
|
||||
3. `src/resources/` 中与当前原型相关的需求、业务资料、字段清单、流程记录和数据样例。
|
||||
4. 当前原型源码、`canvas.excalidraw`、`annotation-source.json`、路由、页面配置和局部状态实现。
|
||||
5. `.axhub/make/project.json` 等 metadata 只作为项目资源、入口和命名关系证据。
|
||||
|
||||
如果用户提供的信息源与 `.spec`、`src/resources/` 或原型实现冲突，以用户提供的信息源为准，并在评审中标记为「资料冲突/待确认」。不要用项目旧文件覆盖用户最新资料。
|
||||
|
||||
## 明确不审
|
||||
|
||||
- 不评价视觉美观、品牌一致性、响应式布局、可访问性细节或是否符合 `DESIGN.md`。
|
||||
- 不把配色、圆角、间距、字体、图标风格作为原型 Review 问题。
|
||||
- 只有当 UI 缺失直接导致业务状态、错误、流程或字段无法表达时，才作为业务完整性问题记录。
|
||||
|
||||
## 推荐审查流程
|
||||
|
||||
1. **确定目标**
|
||||
- 原型：`src/prototypes/<prototype-id>/`
|
||||
- 原型内页面：保留 `pageId`
|
||||
- 目标不清时，先问用户确认
|
||||
|
||||
2. **读取资料**
|
||||
- 先读取用户本轮提供的信息源
|
||||
- 再读取当前原型 `.spec` 中最新决策
|
||||
- 再读取相关 `src/resources/` 资料
|
||||
- 最后读取原型源码、画布和 metadata
|
||||
|
||||
3. **建立业务基线**
|
||||
- 确认核心用户、业务目标、主流程、关键对象和成功标准
|
||||
- 记录明确范围和不做范围
|
||||
- 标记资料冲突、缺失资料和需要用户确认的问题
|
||||
|
||||
4. **审查完整性和连贯性**
|
||||
- 检查主流程入口、出口、成功路径和必要分支
|
||||
- 检查空、加载、成功、失败、权限不足、无数据、部分成功等状态
|
||||
- 检查数据模型、字段名称、枚举值、状态值和业务口径是否一致
|
||||
|
||||
5. **审查边界和恢复**
|
||||
- 输入校验、范围上下限、空值、重复值、非法格式
|
||||
- 网络、系统、权限、资源不存在、会话过期、外部集成失败
|
||||
- 重复点击、并发编辑、数据过期、跨页面返回、流程中断
|
||||
- 每个重要错误都要有恢复路径，而不只是报错
|
||||
|
||||
6. **写入 `.spec`**
|
||||
- 原型级：`src/prototypes/<prototype-id>/.spec/prototype-review.md`
|
||||
- 页面级如后续需要：`src/prototypes/<prototype-id>/.spec/<page-id>/prototype-review.md`
|
||||
|
||||
## 核心审查维度
|
||||
|
||||
- **原型完整性**：核心用户、主流程、入口、出口、空/加载/成功/失败状态是否覆盖。
|
||||
- **项目上下文一致性**：是否与用户资料、最新 `.spec` 决策、资源文档、项目 metadata、已有原型命名和范围一致。
|
||||
- **业务逻辑连贯性**：流程顺序、状态迁移、角色权限、操作前置条件、数据生命周期是否自洽。
|
||||
- **数据模型一致性**：实体、字段名、枚举、状态值、单位、时间/金额/数量口径是否在用户资料、资源、规格和原型中一致。
|
||||
- **Edge cases**：输入校验、边界条件、系统/网络失败、权限失败、并发/重复操作、集成失败、恢复路径。
|
||||
|
||||
## Markdown 模板
|
||||
|
||||
```markdown
|
||||
# Prototype Review
|
||||
|
||||
- 审查目标：src/prototypes/<prototype-id>
|
||||
- 用户资料/参考资料：列出本次使用的用户资料、.spec、resources、源码或 metadata
|
||||
- 生成时间：2026-05-22 00:00
|
||||
|
||||
## 总体点评
|
||||
|
||||
用 1-3 段总结原型在业务完整性、项目对齐、逻辑连贯性和风险覆盖上的整体质量。先说最影响业务成立的问题，再说可以保留的有效表达。
|
||||
|
||||
## P0-P3 优先级问题
|
||||
|
||||
### P1 - Finding title
|
||||
|
||||
- 证据：说明来自用户资料、.spec、resources、源码、画布或 metadata 的具体线索。
|
||||
- 影响：说明对业务流程、数据口径、用户任务、状态理解或后续实现/测试的影响。
|
||||
- 修复方向：给出可执行的需求、原型或资料补充建议。
|
||||
|
||||
## 完整性与项目对齐
|
||||
|
||||
说明核心用户、主流程、入口出口、范围边界、资料冲突、最新决策和项目资源是否对齐。
|
||||
|
||||
## 业务逻辑连贯性
|
||||
|
||||
说明流程顺序、状态迁移、角色权限、操作前置条件、数据生命周期和跨页面一致性。
|
||||
|
||||
## 状态、异常、边界与恢复
|
||||
|
||||
按输入校验、边界条件、错误状态、并发/重复操作、集成失败和恢复路径整理发现。没有明显问题时也要说明已检查。
|
||||
|
||||
## 证据与评估说明
|
||||
|
||||
- 用户资料优先级：说明是否存在用户资料，以及是否与项目内资料冲突。
|
||||
- 读取范围：说明读取了哪些 .spec、resources、源码、画布或 metadata。
|
||||
- 独立评估：full 或 degraded，并说明原因。
|
||||
```
|
||||
|
||||
## 分组要求
|
||||
|
||||
前三组固定且顺序不可变：
|
||||
|
||||
1. `总体点评`
|
||||
2. `P0-P3 优先级问题`，最多 5 条
|
||||
3. `完整性与项目对齐`
|
||||
|
||||
可以追加额外分组，例如 `业务逻辑连贯性`、`状态、异常、边界与恢复`、`证据与评估说明`，但必须放在前三组之后。
|
||||
|
||||
## 优先级
|
||||
|
||||
- `P0`：核心业务流程无法成立，或与用户提供的明确需求/最新决策冲突。
|
||||
- `P1`：主要流程、关键状态、权限或数据口径存在严重缺漏。
|
||||
- `P2`：明显业务摩擦或边界缺失，但存在可用绕行。
|
||||
- `P3`：低风险补充项，后续完善后会提升业务表达或测试覆盖。
|
||||
|
||||
不要使用 `P4` 或更低优先级。
|
||||
|
||||
## 子代理与独立评估
|
||||
|
||||
有子代理能力时，优先拆成两个独立评估：
|
||||
|
||||
- 业务完整性评估：只看用户资料、`.spec`、`src/resources/` 和 metadata，先判断业务基线。
|
||||
- 原型证据评估：看源码、画布、路由、状态和页面实现，判断原型是否表达了业务基线。
|
||||
|
||||
两个评估完成前不要互相暴露结论。没有子代理时，先完成业务完整性笔记，再看原型证据，并在 `证据与评估说明` 中标记独立评估为 `degraded`。
|
||||
|
||||
当审查 3 个以上独立页面或业务流程时，优先按流程或页面拆分并行审查，最后统一综合成 `.spec/prototype-review.md`。
|
||||
|
||||
## 交付说明
|
||||
|
||||
最终回复至少包含：
|
||||
|
||||
- 审查目标
|
||||
- 写入的 `.spec/prototype-review.md` 路径
|
||||
- 使用的用户资料和项目资料
|
||||
- P0-P3 数量
|
||||
- 是否发现资料冲突/待确认项
|
||||
- 独立评估是否完整
|
||||
109
rules/requirements-alignment-guide.md
Normal file
109
rules/requirements-alignment-guide.md
Normal file
@@ -0,0 +1,109 @@
|
||||
# 需求与设计对齐指南
|
||||
|
||||
用于新建或明显更新原型、主题、项目文档等资源时，先收敛产品需求，再确认设计方案。对齐贯穿全过程：读取资料、生成规格、计划实施和验收时，只要发现会改变方向、范围、成本或验收标准的问题，都应回到相应阶段继续确认。
|
||||
|
||||
核心流程：
|
||||
|
||||
```text
|
||||
读取上下文 -> 产品需求对齐 -> 产品需求确认 -> DESIGN.md 候选确认 -> 设计方案对齐 -> 设计决策确认 -> 规格/计划 -> 实施验证
|
||||
```
|
||||
|
||||
## 何时触发
|
||||
|
||||
- 新建原型页面、主题或项目文档。
|
||||
- 明显重构信息架构、核心交互、页面流程或视觉方向。
|
||||
- 用户需求模糊，例如只说“生成一个健身 APP”。
|
||||
- 存在多种合理功能范围、布局方式、交互路径、内容组织或视觉方案。
|
||||
- 用户明确要求先看方向、先出方案、先写规格或先出计划。
|
||||
- 资料、主题、现有原型或资源目录之间有冲突，且会改变产出方向。
|
||||
|
||||
局部文案、样式、素材替换、明确 bug 修复等不改变产品范围、信息架构和视觉骨架的任务，可以跳过正式对齐；但仍要记录采用的假设，并在发现关键缺口时回到对齐流程。
|
||||
|
||||
## 上下文读取
|
||||
|
||||
提问前先读取可获得的信息，不把项目里能找到的问题抛给用户。
|
||||
|
||||
优先级：
|
||||
|
||||
1. 用户当前消息、附件、截图、链接和已给出的约束。
|
||||
2. 当前目录最近的 `AGENTS.md`、`README.md` 和相关 `rules/`。
|
||||
3. 关联原型：目录结构、入口文件、必要样式和已有交互。
|
||||
4. 资源目录：只做目录级扫描，了解已有原型、主题、文档和资产。
|
||||
5. 相关文件：只读取会影响本次判断的文件，不批量展开无关文件。
|
||||
|
||||
重点看：
|
||||
|
||||
- `src/prototypes/`：是否已有同类原型、参考页或可复用页面结构。
|
||||
- `src/themes/`：是否已有相近主题或设计系统。
|
||||
- `src/resources/`：是否已有业务说明、字段、流程资料或素材。
|
||||
- 原型内 `assets/`、`canvas-assets/`：是否有用户提供或历史沉淀的素材。
|
||||
|
||||
## 产品需求对齐
|
||||
|
||||
产品需求阶段负责回答“做什么”，方向应以收敛为主。通常需要明确：
|
||||
|
||||
- 目标用户和核心任务。
|
||||
- 本次范围、功能清单和不做什么。
|
||||
- 页面或资源的核心内容、数据来源和素材来源。
|
||||
- 关键状态、核心路径和必要交互。
|
||||
- 用户最终如何判断结果可用。
|
||||
|
||||
只问会影响范围、成本或验收的问题。能从上下文推断的内容直接记为假设继续；如果缺失信息会导致不同功能范围、不同页面结构或不同验收标准，必须先问。
|
||||
|
||||
## 设计方案对齐
|
||||
|
||||
设计方案阶段负责回答“怎么表达”。进入视觉、主题或明显 UI 改版前，必须先让用户确认一个 `DESIGN.md` 作为设计基底：
|
||||
|
||||
1. 如果用户已指定 `DESIGN.md` 或主题，直接采用。
|
||||
2. 如果用户未指定，先从项目默认主题、已有同类原型和 `src/themes/` 中整理 3-4 个最匹配候选，让用户选择。
|
||||
3. 候选说明只写适用理由、主要风格、取舍和预览链接，不替用户决定最终基底。
|
||||
4. 不自行新建 `DESIGN.md`；没有合适候选时，停止并请用户提供设计基底或主题方向。
|
||||
|
||||
整理候选时优先读取主题 `theme.json`，用 `tags.*`、`display.distributionTags`、`identity.title*/description*` 和 `display.variant` 做检索与候选说明；用 `identity.slug` 和 `assets.designMd.path` 校验目录与 `DESIGN.md` 路径。
|
||||
|
||||
候选必须提供可打开的主题预览链接。优先使用资源 metadata 里的 `clientUrl` / `previewUrl`；没有时使用 `/themes/<theme-slug>`。同时标出对应 `DESIGN.md` 路径，便于用户核对。
|
||||
|
||||
`DESIGN.md` 确定后，用户零散提出的颜色、字体、布局、动效、组件形态等需求，都作为基于该设计基底的调整处理，不另起一套视觉系统。
|
||||
|
||||
新建页面、大面积 UI 改版或模糊需求，设计阶段至少覆盖 5 个设计问题或设计决策变量；局部微调、明确 bug 修复或用户已给出完整设计约束时不受此下限限制。
|
||||
|
||||
常见设计问题包括：
|
||||
|
||||
- 首屏目标：主操作、信息概览、品牌表达或引导转化。
|
||||
- 信息层级：哪些内容必须突出，哪些可以折叠或延后。
|
||||
- 布局模式：看板、列表详情、仪表盘、向导、沉浸页或多步骤流程。
|
||||
- 交互路径：高频用户效率优先，还是首次用户理解优先。
|
||||
- 数据呈现：真实数据、文档推断、临时示例数据或空状态优先。
|
||||
- 视觉语气：严格继承 `DESIGN.md`，还是在其基础上加强某种风格倾向。
|
||||
|
||||
落地时优先复用所选 `DESIGN.md` 对应的 CSS Variables、tokens 和组件习惯；缺少 token 时贴近所选基底的视觉语言，并在方案或交付说明中写明假设。
|
||||
|
||||
## 提问规则
|
||||
|
||||
- 先读上下文，能推断就不问。
|
||||
- 默认一次只问一个决策点；同一主题下强相关的 2-3 个参数可以合并为一问。
|
||||
- 尽量给出 2-3 个互斥选项，并标出推荐答案。
|
||||
- 推荐答案要说明取舍，不只表达偏好。
|
||||
- 不为了补齐形式追问已能从上下文判断的问题。
|
||||
- 用户回答后继续收敛；如果出现新分支，再追加提问。
|
||||
|
||||
## 确认与记录
|
||||
|
||||
进入实现前必须让用户确认产品需求和设计方案。确认产物可以是中文规格文档、执行计划或方案摘要，但至少包含：
|
||||
|
||||
- 产品需求：目标用户、核心任务、范围、功能清单、内容/数据来源、验收重点。
|
||||
- 设计方案：采用的 `DESIGN.md`、整体设计方向、关键设计决策、设计假设。
|
||||
- 实施边界：本轮会做什么，不会做什么。
|
||||
|
||||
确认过的方案或规格需要归档为当时决策快照；未确认的不归档。
|
||||
|
||||
- 保存位置：原型相关内容保存到 `src/prototypes/<prototype-name>/.spec/`。
|
||||
- 文件命名：文件名必须包含日期，建议使用 `YYYY-MM-DD-<topic>.md`。
|
||||
- 归档内容：只记录已确认的需求问题、设计问题、用户选择和最终设计决策。
|
||||
- 归档性质：只表示当下决策，不要求跟随后续实现继续同步变化。
|
||||
|
||||
触发过对齐时，本轮交付说明或确认产物中只需补充：
|
||||
|
||||
- 问题。
|
||||
- 用户选择。
|
||||
- 最终设计决策。
|
||||
11
rules/resource-management-guide.md
Normal file
11
rules/resource-management-guide.md
Normal file
@@ -0,0 +1,11 @@
|
||||
# 资源指南
|
||||
|
||||
`src/resources/` 用于存放项目资料、需求说明和原型讨论中需要长期保留的上下文，方便后续生成、修改和复盘原型时读取。
|
||||
|
||||
常见内容包括：
|
||||
|
||||
- Markdown 文档，如需求说明、页面说明、调研记录、会议纪要
|
||||
- 数据样例，如 JSON、CSV、TSV、表格导出文件
|
||||
- 设计或业务附件，如 PDF、Office 文档、压缩包等
|
||||
|
||||
图片、截图、参考图等素材只在需要长期保留为项目资料时放入 `src/resources/`。原型页面素材、主题素材和画布截图按对应规则放到原型、主题或画布目录内。
|
||||
148
rules/theme-guide.md
Normal file
148
rules/theme-guide.md
Normal file
@@ -0,0 +1,148 @@
|
||||
# 主题创建与验收指南
|
||||
|
||||
本文档约束 `make-client` 中主题资源的创建、更新、派生与验收。主题只面向当前标准结构。
|
||||
|
||||
## 核心原则
|
||||
|
||||
- `DESIGN.md` 是主题事实源：品牌定位、设计原则、色彩、字体、圆角、间距、边框、阴影、组件规则和禁用做法，均优先按它判断。
|
||||
- `theme.json` 是运行时与管理端消费的结构化摘要；`assets/tokens.json` 是轻量 token 快照；`style.css` 是演示页可见样式。三者必须与 `DESIGN.md` 保持一致。
|
||||
- 用户当前消息或附件的优先级高于已有文件；若用户要求与 `DESIGN.md` 冲突，先更新 `DESIGN.md`，再同步派生文件。
|
||||
- 不根据截图、元数据或自动推断结果覆盖明确写在 `DESIGN.md` 中的规则；只能在 `DESIGN.md` 缺失信息时补充合理假设，并在文档或交付说明中写清楚。
|
||||
- 主题代码、CSS 和 `theme.json` 中的本地资源引用必须使用主题内相对路径，禁止根路径、本机绝对路径或 `../` 逃逸到其他目录。
|
||||
- 主题演示页不得引入与该主题无关的 UI 库，避免污染视觉表达。
|
||||
|
||||
## 标准参考主题
|
||||
|
||||
当前标准参考主题是 `src/themes/linear/`。新建或重做主题时，参考它的目录结构、`theme.json` 字段组织、`index.tsx` 接入方式和预览资源引用方式。
|
||||
|
||||
参考范围：
|
||||
|
||||
- `index.tsx`：引入 `./style.css`、读取 `./theme.json`、将 `display` 映射为 `DesignMdBatchShowcase` 配置，并静态 import 本地预览资源。
|
||||
- `theme.json`：包含 `schemaVersion`、`source`、`identity`、`tags`、`assets`、`tokens`、`previewImages`、`display`。
|
||||
- `style.css`：以 `@import "tailwindcss";` 开头，在 `.dmb-page` 中写入 `--dmb-*` CSS Variables。
|
||||
- `assets/`：至少包含 `tokens.json` 和一个稳定预览图，例如 `official-homepage.webp`、`cover.webp` 或 `source-preview.webp`。
|
||||
|
||||
不要复制参考主题的品牌内容、视觉风格、文案或临时生成注释。新主题必须用自己的 `DESIGN.md` 派生真实 token、展示字段和预览资源。
|
||||
|
||||
## 推荐来源与导入路径
|
||||
|
||||
用户查找和导入主题时，优先走这两类来源：
|
||||
|
||||
- `getdesign.md`：主流 Design.md 主题的优先来源，适合先找品牌主线和标准主题。
|
||||
- `styles.refero.design`：补缺优先来源，适合找行业、场景、字体、颜色和 token 更丰富的主题。
|
||||
|
||||
当前只推荐这两类 active source；旧来源不作为默认导入入口。
|
||||
|
||||
推荐的导入路径按这个顺序走：
|
||||
|
||||
```bash
|
||||
node scripts/collect-design-md-batch.mjs
|
||||
node scripts/generate-design-md-theme-pages.mjs
|
||||
node scripts/review-design-md-theme-pages.mjs
|
||||
```
|
||||
|
||||
对应的本地产物和主题落点分别是：
|
||||
|
||||
- `.local/design-md-batch/manifest.json`
|
||||
- `client/src/themes/<slug>/`
|
||||
|
||||
如果用户已经提供了 Design.md 线索、品牌名或详情页链接，就先按上面两类来源定位，再进入采集、生成和复查。
|
||||
|
||||
## 标准交付物
|
||||
|
||||
每个主题目录使用 `kebab-case` 命名，例如 `stripe`、`longcipher-design`：
|
||||
|
||||
```text
|
||||
src/themes/<theme-key>/
|
||||
├── DESIGN.md # 必需，主题事实依据
|
||||
├── theme.json # 必需，结构化主题元数据与展示配置
|
||||
├── assets/
|
||||
│ ├── tokens.json # 必需，轻量 token 快照
|
||||
│ └── ... # 预览图、官网截图、字体、preview.html 等主题私有资源
|
||||
├── style.css # 必需，主题演示页样式变量
|
||||
├── tw.css # 必需，Tailwind v4 主题片段或最小可用片段
|
||||
└── index.tsx # 必需，主题演示页入口，必须 export default Component
|
||||
```
|
||||
|
||||
## `DESIGN.md` 编写规范
|
||||
|
||||
`DESIGN.md` 应写成可执行的设计规范，而不是氛围描述。信息充分时至少覆盖：
|
||||
|
||||
- 主题身份：品牌/产品背景、适用场景、不适用场景、关键词。
|
||||
- 视觉原则：信息密度、页面气质、品牌表达边界、动效或图片使用原则。
|
||||
- 色彩系统：主色、背景、表面、文本、边框、状态色、CTA 或限制色的使用边界。
|
||||
- 字体系统：display/body/mono 角色、字号层级、字重和 fallback。
|
||||
- 尺寸系统：间距、圆角、边框、阴影、卡片、表单、按钮、导航、表格等基础组件规则。
|
||||
- 使用约束：明确的 Do/Don't，尤其是禁用的大面积颜色、错误圆角、过度阴影、无关行业布局等。
|
||||
|
||||
生成或更新 `DESIGN.md` 时，优先使用用户提供的规范、原始 Design.md、官方设计资料和当前主题已有内容。截图和元数据只能用于补缺，不能覆盖明确规则。
|
||||
|
||||
## 派生文件规范
|
||||
|
||||
`theme.json` 必须承载管理端和演示页需要的结构化信息：
|
||||
|
||||
- `identity.slug` 必须与主题目录名一致；`titleZh`、`descriptionZh` 面向管理端展示。
|
||||
- `tokens.palette`、`tokens.typography`、`tokens.radius`、`tokens.spacing` 等必须从 `DESIGN.md` 抽取或由用户确认。
|
||||
- `display.palette`、`display.typography`、`display.radius`、`display.spacing`、`display.borders`、`display.shadows`、`display.usageGuidance` 应服务于演示页展示，并与 `tokens` 同源。
|
||||
- `assets` 和 `previewImages` 只引用当前主题目录内资源，不引用本机绝对路径或其他主题资源。
|
||||
|
||||
`assets/tokens.json` 只保存轻量 token 快照：
|
||||
|
||||
- 至少包含 `palette`、`typography`；若 `DESIGN.md` 提供圆角、间距、边框或阴影，也应保留对应字段。
|
||||
- 与 `theme.json.tokens` 保持一致，不额外发明另一套命名或语义。
|
||||
|
||||
`style.css` 用于让演示页真实体现主题：
|
||||
|
||||
- 必须 `@import "tailwindcss";`。
|
||||
- 使用 `.dmb-page` 写入 `--dmb-*` CSS Variables，包括 accent、link、muted、background、font、radius、spacing、border 等可见变量。
|
||||
- 变量值必须来自 `DESIGN.md` 或 `theme.json.tokens`，不能为了好看临时换色。
|
||||
|
||||
`tw.css` 用于保留 Tailwind v4 主题片段：
|
||||
|
||||
- 若来源提供 Tailwind/CSS 变量，应尽量原样保留并补齐 `@import "tailwindcss";`。
|
||||
- 若暂无可用内容，可保持最小可用片段，但不得替代 `DESIGN.md` 成为事实源。
|
||||
|
||||
## 演示页规范
|
||||
|
||||
`index.tsx` 是主题预览入口，必须：
|
||||
|
||||
- `export default Component`。
|
||||
- 引入 `./style.css`，读取 `./theme.json`，并把 `display` 配置传入 `DesignMdBatchShowcase`。
|
||||
- 通过静态 import 引入本地预览资源，例如 `./assets/official-homepage.webp?url`。
|
||||
- 展示颜色、字体、圆角、间距、边框/阴影、使用建议和典型场景。
|
||||
- 不展示内部采集过程、脚本状态、TODO、占位文案或无关营销内容。
|
||||
|
||||
可以复用 `DesignMdBatchShowcase` 的结构，但主题内容、标签、色板、使用建议和预览图必须来自当前 `DESIGN.md`。
|
||||
|
||||
## 更新工作流
|
||||
|
||||
1. 先读用户要求、当前主题 `DESIGN.md`、`theme.json`、`assets/tokens.json`、`style.css`、`tw.css`、`index.tsx` 和相关资源。
|
||||
2. 判断冲突：用户明确修改意图优先；否则以 `DESIGN.md` 为准，修正派生文件。
|
||||
3. 修改事实源：新增或修正设计规则时先改 `DESIGN.md`。
|
||||
4. 同步派生：更新 `theme.json.tokens/display`、`assets/tokens.json`、`style.css`、`tw.css` 和预览资源引用。
|
||||
5. 检查一致性：主色是否来自 `DESIGN.md`，字体角色是否完整，圆角/间距/边框/阴影是否没有丢失，使用建议是否非泛化。
|
||||
6. 查找和导入：优先从 `getdesign.md` 和 `styles.refero.design` 定位主题，再用 `collect`、`generate`、`review` 三个脚本串起导入流程。
|
||||
7. 验收预览：运行主题 ready 检查并打开目标页面做视觉回归，确认字体、颜色、间距、建议项和预览图都能完整渲染。
|
||||
|
||||
输入来源优先级：
|
||||
|
||||
1. 用户当前明确要求、附件、截图和链接。
|
||||
2. 当前主题 `DESIGN.md`。
|
||||
3. 当前主题 `theme.json`、`assets/tokens.json`、`style.css`、`tw.css`、`index.tsx`。
|
||||
4. 官方设计资料或原始 Design.md 来源。
|
||||
5. 标准参考主题 `src/themes/linear/` 和同类主题。
|
||||
|
||||
## 验收流程
|
||||
|
||||
基础检查：
|
||||
|
||||
```bash
|
||||
node scripts/check-app-ready.mjs /themes/[主题名]
|
||||
```
|
||||
|
||||
验收重点：
|
||||
|
||||
- `READY` 后访问目标页面，检查预览图、色板、字体、圆角、间距、边框、阴影和使用建议是否与 `DESIGN.md` 一致。
|
||||
- 若出现 `ERROR`，优先修复入口、资源路径、JSON 结构和 CSS 导入。
|
||||
- 若出现 `TIMEOUT`，排查 dev server、依赖安装、构建缓存或长任务。
|
||||
- 视觉问题按 `DESIGN.md`、用户要求、`rules/requirements-alignment-guide.md` 的顺序判断，不以自动生成结果为准。
|
||||
164
rules/ui-review-guide.md
Normal file
164
rules/ui-review-guide.md
Normal file
@@ -0,0 +1,164 @@
|
||||
# UI Review 指导
|
||||
|
||||
用于审查 Axhub Make client 原型页面的 UI 质量、设计一致性、响应式、可访问性和核心元件表现。
|
||||
|
||||
## 审查入口
|
||||
|
||||
优先使用官方 Impeccable 技能的 critique 流程：
|
||||
|
||||
```text
|
||||
/impeccable critique <target>
|
||||
```
|
||||
|
||||
`<target>` 应明确到原型或页面，例如：
|
||||
|
||||
```text
|
||||
/impeccable critique src/prototypes/beginner-guide
|
||||
/impeccable critique beginner-guide/install-agent
|
||||
```
|
||||
|
||||
如果用户说「UI review」「审查这个页面」「检查设计质量」「帮我挑一下 UI 问题」，按本规则约束 `/impeccable critique` 的产物，不另起一套审查流程。
|
||||
|
||||
## 审查依据
|
||||
|
||||
审查依据只允许是一个 `DESIGN.md`：
|
||||
|
||||
1. 用户明确指定的 `DESIGN.md` 或主题目录下的 `DESIGN.md`
|
||||
2. 用户未指定时，使用项目默认设计的 `DESIGN.md`
|
||||
3. 如果没有用户指定或项目默认的 `DESIGN.md`，必须停止，要求用户提供
|
||||
|
||||
禁止把以下内容作为审查依据：
|
||||
|
||||
- `PRODUCT.md`
|
||||
- `theme.json`
|
||||
- `tokens.json`
|
||||
- CSS 变量文件
|
||||
- 截图
|
||||
- README 或其他说明文档
|
||||
|
||||
这些文件可以作为证据或实现参考，但不能替代 `DESIGN.md` 的规范地位。
|
||||
|
||||
## Impeccable 使用约束
|
||||
|
||||
使用 `/impeccable critique` 时，必须在执行前附加或内化以下约束：
|
||||
|
||||
```text
|
||||
Use /impeccable critique as the review method, but follow Axhub rules:
|
||||
1. Use only the selected DESIGN.md as the design basis.
|
||||
2. Ignore PRODUCT.md and all other design files as normative criteria.
|
||||
3. If no DESIGN.md is available, stop and ask for one.
|
||||
4. Do not write .impeccable critique artifacts as the deliverable.
|
||||
5. Produce a Markdown report, not JSON.
|
||||
6. Write the result to the target prototype .spec directory.
|
||||
7. Include sections in order: 总体点评, P0-P3 优先级问题, 核心元件.
|
||||
8. Priorities must contain at most 5 P0-P3 findings.
|
||||
```
|
||||
|
||||
如果 Impeccable 的原始流程要求 `PRODUCT.md`、`.impeccable/critique` 或额外上下文，与本规则冲突时，以本规则为准。
|
||||
|
||||
## 推荐审查流程
|
||||
|
||||
1. **确定目标**
|
||||
- 原型：`src/prototypes/<prototype-id>/`
|
||||
- 原型内页面：保留 `pageId`
|
||||
- 目标不清时，先问用户确认
|
||||
|
||||
2. **确定 DESIGN.md**
|
||||
- 用户指定主题时，读取 `src/themes/<theme-id>/DESIGN.md`
|
||||
- 用户指定路径时，只读取该 `DESIGN.md`
|
||||
- 未指定且项目默认不存在时，停止
|
||||
|
||||
3. **执行 Impeccable critique**
|
||||
- 读取目标源码和本地样式
|
||||
- 有预览环境时检查桌面和移动端
|
||||
- 可用浏览器时保留截图证据
|
||||
- 允许使用 Impeccable detector 作为辅助证据，但不要让 detector 输出先污染设计判断
|
||||
|
||||
4. **综合结论**
|
||||
- 不直接拼接 Impeccable 原报告
|
||||
- 按 Axhub Markdown 模板重组
|
||||
- P0-P3 问题最多 5 条
|
||||
- 必须包含核心元件或关键 UI 区块点评
|
||||
|
||||
5. **写入 `.spec`**
|
||||
- 原型级：`src/prototypes/<prototype-id>/.spec/ui-review.md`
|
||||
- 页面级如后续需要：`src/prototypes/<prototype-id>/.spec/<page-id>/ui-review.md`
|
||||
|
||||
## Markdown 模板
|
||||
|
||||
```markdown
|
||||
# UI Review
|
||||
|
||||
- 审查目标：src/prototypes/<prototype-id>
|
||||
- 使用设计依据：src/themes/<theme-id>/DESIGN.md
|
||||
- 生成时间：2026-05-22 00:00
|
||||
|
||||
## 总体点评
|
||||
|
||||
用 1-3 段总结整体设计质量、与 DESIGN.md 的一致性、主要风险和最值得保留的亮点。
|
||||
|
||||
## P0-P3 优先级问题
|
||||
|
||||
### P1 - Finding title
|
||||
|
||||
- 证据：说明出现位置、截图/预览观察或源码线索。
|
||||
- 影响：说明对用户任务、理解、可访问性或品牌一致性的影响。
|
||||
- 修复方向：给出可执行的设计或实现建议。
|
||||
|
||||
## 核心元件
|
||||
|
||||
### Hero / Header / Form / Navigation
|
||||
|
||||
按关键 UI 区块点评是否符合 DESIGN.md，指出保留点和调整点。
|
||||
|
||||
## 响应式与可访问性
|
||||
|
||||
记录桌面/移动端差异、键盘/语义/对比度等发现。没有明显问题时也要说明已检查。
|
||||
|
||||
## 证据与评估说明
|
||||
|
||||
- 浏览器/截图：说明是否使用。
|
||||
- Scanner：说明是否使用。
|
||||
- 独立评估：full 或 degraded，并说明原因。
|
||||
```
|
||||
|
||||
## 分组要求
|
||||
|
||||
前三组固定且顺序不可变：
|
||||
|
||||
1. `总体点评`
|
||||
2. `P0-P3 优先级问题`，最多 5 条
|
||||
3. `核心元件`
|
||||
|
||||
可以追加额外分组，例如 `响应式与可访问性`、`证据与评估说明`，但必须放在前三组之后。
|
||||
|
||||
## 优先级
|
||||
|
||||
- `P0`：阻断核心任务完成，或违反 `DESIGN.md` 中强制规则
|
||||
- `P1`：显著增加用户完成任务的难度，或造成 WCAG AA 级别可访问性问题
|
||||
- `P2`：明显体验摩擦，但存在可用绕行
|
||||
- `P3`：低影响 polish，修复后更好但不影响主要任务
|
||||
|
||||
不要使用 `P4` 或更低优先级。
|
||||
|
||||
## 子代理与独立评估
|
||||
|
||||
有子代理能力时，优先拆成两个独立评估：
|
||||
|
||||
- 设计评估：只看目标、`DESIGN.md`、截图/预览和源码
|
||||
- 证据评估：看 scanner、响应式、可访问性和实现风险
|
||||
|
||||
两个评估完成前不要互相暴露结论。没有子代理时，先完成设计评估笔记，再看 scanner/证据，并在 `证据与评估说明` 中标记独立评估为 `degraded`。
|
||||
|
||||
当审查 3 个以上独立页面或组件时，优先按目标拆分并行审查，最后统一综合成 `.spec/ui-review.md`。
|
||||
|
||||
## 交付说明
|
||||
|
||||
最终回复至少包含：
|
||||
|
||||
- 审查目标
|
||||
- 使用的 `DESIGN.md`
|
||||
- 写入的 `.spec/ui-review.md` 路径
|
||||
- P0-P3 数量
|
||||
- 是否使用浏览器/截图/scanner
|
||||
- 独立评估是否完整
|
||||
113
rules/v0-project-converter.md
Normal file
113
rules/v0-project-converter.md
Normal file
@@ -0,0 +1,113 @@
|
||||
# V0 项目转换规则
|
||||
|
||||
用于将 V0 生成的 Next.js 项目转换为本项目原型页面，保持视觉和功能，并符合 `rules/prototype-development-guide.md`。
|
||||
|
||||
## 目标
|
||||
|
||||
- 保持页面视觉一致性。
|
||||
- 移除 Next.js 特有实现。
|
||||
- 产出可在 `src/prototypes/<name>/` 中运行的 React 页面。
|
||||
|
||||
## 预处理
|
||||
|
||||
```bash
|
||||
node scripts/v0-converter.mjs <v0-project-dir> [output-name]
|
||||
```
|
||||
|
||||
脚本位于客户端项目 `scripts/` 目录。它会复制项目、分析路径别名和依赖，并生成任务文档与分析 JSON。脚本不直接修改业务代码。
|
||||
|
||||
## 默认页面格式
|
||||
|
||||
默认转换为普通 React 页面。只有明确需要 Axhub / Axure 接管时才接入 Axure API。
|
||||
|
||||
```typescript
|
||||
/**
|
||||
* @name 页面名称
|
||||
*
|
||||
* 参考资料：
|
||||
* - /rules/prototype-development-guide.md
|
||||
*/
|
||||
|
||||
import './style.css';
|
||||
import React from 'react';
|
||||
|
||||
export default function PageName() {
|
||||
return (
|
||||
<div />
|
||||
);
|
||||
}
|
||||
```
|
||||
|
||||
需要 Axure API 时，再参考 `rules/axure-api-guide.md`。
|
||||
|
||||
## 移除 Next.js 代码
|
||||
|
||||
移除或替换：
|
||||
|
||||
- `"use client"`：删除。
|
||||
- `next/navigation`：删除或改为组件内状态/普通链接。
|
||||
- `next/image`：改为 `<img>`。
|
||||
- `next/link`：改为 `<a>`。
|
||||
- `Metadata`、`@vercel/*`：删除。
|
||||
|
||||
## 路径别名
|
||||
|
||||
将 `@/` 转换为相对路径：
|
||||
|
||||
```typescript
|
||||
// V0
|
||||
import { cn } from "@/lib/utils";
|
||||
|
||||
// 转换后
|
||||
import { cn } from "../lib/utils";
|
||||
```
|
||||
|
||||
以脚本生成的分析表为准逐项检查。
|
||||
|
||||
## 样式
|
||||
|
||||
`style.css` 以 Tailwind V4 入口开头：
|
||||
|
||||
```css
|
||||
@import "tailwindcss";
|
||||
```
|
||||
|
||||
随后合并源项目全局样式文件、主题变量和自定义样式。
|
||||
|
||||
## 依赖
|
||||
|
||||
排除：
|
||||
|
||||
- `next` 和 `next-*`
|
||||
- `@vercel/*`
|
||||
- `react` 和 `react-dom`
|
||||
|
||||
保留并按需安装：
|
||||
|
||||
- `class-variance-authority`
|
||||
- `clsx`
|
||||
- `tailwind-merge`
|
||||
- `@radix-ui/*`
|
||||
- `lucide-react`
|
||||
- `recharts`
|
||||
- `date-fns`
|
||||
|
||||
新增依赖优先使用 npm，便于生成项目在没有 pnpm 的用户环境中继续运行：
|
||||
|
||||
```bash
|
||||
npm install <package-name>
|
||||
```
|
||||
|
||||
## 验收
|
||||
|
||||
```bash
|
||||
node scripts/check-app-ready.mjs /prototypes/[页面名]
|
||||
```
|
||||
|
||||
要求：
|
||||
|
||||
- 状态为 `READY`。
|
||||
- 页面正常渲染。
|
||||
- 无控制台错误。
|
||||
- 关键交互正常。
|
||||
- 样式显示正确。
|
||||
Reference in New Issue
Block a user