npm - wizz-method - Versions diffs - 1.0.3 → 1.2.0 - Mend

wizz-method 1.0.3 → 1.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (630) hide show

package/src/skills-lib/huashu-design/references/react-setup.md ADDED Viewed

@@ -0,0 +1,276 @@
+# React + Babel 项目规范
+用HTML+React+Babel做原型时必须遵守的技术规范。不遵守会炸。
+## Pinned Script Tags（必须用这些版本）
+在HTML的`<head>`里放这三个script tag，用**固定版本+integrity hash**：
+```html
+<script src="https://unpkg.com/react@18.3.1/umd/react.development.js" integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js" integrity="sha384-u6aeetuaXnQ38mYT8rp6sbXaQe3NL9t+IBXmnYxwkUI2Hw4bsp2Wvmx4yRQF1uAm" crossorigin="anonymous"></script>
+<script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script>
+```
+**不要**用`react@18`或`react@latest`这种unpinned版本——会出现版本漂移/缓存问题。
+**不要**省略`integrity`——CDN一旦被劫持或篡改，这是防线。
+## 文件结构
+```
+项目名/
+├── index.html               # 主HTML
+├── components.jsx           # 组件文件（type="text/babel"加载）
+├── data.js                  # 数据文件
+└── styles.css               # 额外CSS（可选）
+```
+HTML里加载方式：
+```html
+<!-- 先React+Babel -->
+<script src="https://unpkg.com/react@18.3.1/..."></script>
+<script src="https://unpkg.com/react-dom@18.3.1/..."></script>
+<script src="https://unpkg.com/@babel/standalone@7.29.0/..."></script>
+<!-- 然后你的组件文件 -->
+<script type="text/babel" src="components.jsx"></script>
+<script type="text/babel" src="pages.jsx"></script>
+<!-- 最后主入口 -->
+<script type="text/babel">
+  const root = ReactDOM.createRoot(document.getElementById('root'));
+  root.render(<App />);
+</script>
+```
+**不要**用`type="module"`——会和Babel冲突。
+## 三条不可违反的规矩
+### 规矩1：styles 对象必须用唯一命名
+**错误**（多组件时必炸）：
+```jsx
+// components.jsx
+const styles = { button: {...}, card: {...} };
+// pages.jsx  ← 同名覆盖！
+const styles = { container: {...}, header: {...} };
+```
+**正确**：每个组件文件的styles用唯一前缀。
+```jsx
+// terminal.jsx
+const terminalStyles = {
+  screen: {...},
+  line: {...}
+};
+// sidebar.jsx
+const sidebarStyles = {
+  container: {...},
+  item: {...}
+};
+```
+**或者用inline styles**（小组件推荐）：
+```jsx
+<div style={{ padding: 16, background: '#111' }}>...</div>
+```
+这条是**非协商**的。每次写`const styles = {...}`都必须replace成specific命名，否则多组件加载时全栈报错。
+### 规矩2：Scope 不共享，需手动export
+**关键认知**：每个`<script type="text/babel">`被Babel独立编译，它们之间**scope不通**。`components.jsx`里定义的`Terminal`组件，在`pages.jsx`里**默认是undefined**。
+**解决方式**：在每个组件文件末尾，把要共享的组件/工具export到`window`：
+```jsx
+// components.jsx 末尾
+function Terminal(props) { ... }
+function Line(props) { ... }
+const colors = { green: '#...', red: '#...' };
+Object.assign(window, {
+  Terminal, Line, colors,
+  // 所有你要在别处用的都列在这里
+});
+```
+然后`pages.jsx`就能直接用`<Terminal />`，因为JSX会去`window.Terminal`找。
+### 规矩3：不要用 scrollIntoView
+`scrollIntoView`会把整个HTML容器往上推，搞坏web harness的布局。**永远不要用**。
+替代方案：
+```js
+// 滚到容器内某个位置
+container.scrollTop = targetElement.offsetTop;
+// 或者用element.scrollTo
+container.scrollTo({
+  top: targetElement.offsetTop - 100,
+  behavior: 'smooth'
+});
+```
+## 调 Claude API（HTML内）
+部分原生 design-agent 环境（如 Claude.ai Artifacts）有免配置的 `window.claude.complete`，但大部分 agent 环境（Claude Code / Codex / Cursor / Trae / etc.）本地里**没有**。
+如果你的 HTML 原型需要调用 LLM 做 demo（比如做个聊天 interface），两个选项：
+### 选项A：不真调，用mock
+Demo场景推荐。写一个假helper，返回预设的response：
+```jsx
+window.claude = {
+  async complete(prompt) {
+    await new Promise(r => setTimeout(r, 800)); // 模拟延迟
+    return "这是一个mock响应。真部署时请替换为真API。";
+  }
+};
+```
+### 选项B：真调Anthropic API
+需要API key，用户必须在HTML里填入自己的key才能跑。**永远不要把key硬编码在HTML里**。
+```html
+<input id="api-key" placeholder="粘贴你的Anthropic API key" />
+<script>
+window.claude = {
+  async complete(prompt) {
+    const key = document.getElementById('api-key').value;
+    const res = await fetch('https://api.anthropic.com/v1/messages', {
+      method: 'POST',
+      headers: {
+        'x-api-key': key,
+        'anthropic-version': '2023-06-01',
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify({
+        model: 'claude-haiku-4-5',
+        max_tokens: 1024,
+        messages: [{ role: 'user', content: prompt }]
+      })
+    });
+    const data = await res.json();
+    return data.content[0].text;
+  }
+};
+</script>
+```
+**注意**：浏览器直接调Anthropic API会遇到CORS问题。如果用户给你的预览环境不支持CORS bypass，这条路不通。这时候用选项A mock，或者告诉用户需要一个proxy后端。
+### 选项 C：用 agent 侧的 LLM 能力生成 mock 数据
+如果只是本地演示用，可以在当前 agent 会话里临时调用该 agent 的 LLM 能力（或用户装的 multi-model 类 skill）先生成 mock 响应数据，再硬编码写进 HTML。这样 HTML 运行时完全不依赖任何 API。
+## 典型 HTML 起手模板
+拷贝这个模板作为React原型的骨架：
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Your Prototype Name</title>
+  <!-- React + Babel pinned -->
+  <script src="https://unpkg.com/react@18.3.1/umd/react.development.js" integrity="sha384-hD6/rw4ppMLGNu3tX5cjIb+uRZ7UkRJ6BPkLpg4hAu/6onKUg4lLsHAs9EBPT82L" crossorigin="anonymous"></script>
+  <script src="https://unpkg.com/react-dom@18.3.1/umd/react-dom.development.js" integrity="sha384-u6aeetuaXnQ38mYT8rp6sbXaQe3NL9t+IBXmnYxwkUI2Hw4bsp2Wvmx4yRQF1uAm" crossorigin="anonymous"></script>
+  <script src="https://unpkg.com/@babel/standalone@7.29.0/babel.min.js" integrity="sha384-m08KidiNqLdpJqLq95G/LEi8Qvjl/xUYll3QILypMoQ65QorJ9Lvtp2RXYGBFj1y" crossorigin="anonymous"></script>
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    html, body { height: 100%; width: 100%; }
+    body {
+      font-family: -apple-system, 'SF Pro Text', sans-serif;
+      background: #FAFAFA;
+      color: #1A1A1A;
+    }
+    #root { min-height: 100vh; }
+  </style>
+</head>
+<body>
+  <div id="root"></div>
+  <!-- 你的组件文件 -->
+  <script type="text/babel" src="components.jsx"></script>
+  <!-- 主入口 -->
+  <script type="text/babel">
+    const { useState, useEffect } = React;
+    function App() {
+      return (
+        <div style={{padding: 40}}>
+          <h1>Hello</h1>
+        </div>
+      );
+    }
+    const root = ReactDOM.createRoot(document.getElementById('root'));
+    root.render(<App />);
+  </script>
+</body>
+</html>
+```
+## 常见报错及解决
+**`styles is not defined` 或 `Cannot read property 'button' of undefined`**
+→ 你在一个文件里定义了`const styles`，另一个文件覆盖了。给每个改成specific命名。
+**`Terminal is not defined`**
+→ 跨文件引用时scope不通。在定义Terminal的文件末尾加`Object.assign(window, {Terminal})`。
+**整个页面白屏，控制台没错误**
+→ 多半是JSX语法错误但Babel没报在控制台。把`babel.min.js`临时换成`babel.js`非压缩版，错误信息更清晰。
+**ReactDOM.createRoot is not a function**
+→ 版本不对。确认用了react-dom@18.3.1（而不是17或其他）。
+**`Objects are not valid as a React child`**
+→ 你渲染了一个对象而不是JSX/字符串。通常是`{someObj}`写成了`{someObj.name}`。
+## 大项目怎么拆文件
+**>1000行的单文件**难维护。分拆思路：
+```
+项目/
+├── index.html
+├── src/
+│   ├── primitives.jsx      # 基础元素：Button、Card、Badge...
+│   ├── components.jsx      # 业务组件：UserCard、PostList...
+│   ├── pages/
+│   │   ├── home.jsx        # 首页
+│   │   ├── detail.jsx      # 详情页
+│   │   └── settings.jsx    # 设置页
+│   ├── router.jsx          # 简单路由（React state切换）
+│   └── app.jsx             # 入口组件
+└── data.js                 # mock data
+```
+HTML里按顺序加载：
+```html
+<script type="text/babel" src="src/primitives.jsx"></script>
+<script type="text/babel" src="src/components.jsx"></script>
+<script type="text/babel" src="src/pages/home.jsx"></script>
+<script type="text/babel" src="src/pages/detail.jsx"></script>
+<script type="text/babel" src="src/pages/settings.jsx"></script>
+<script type="text/babel" src="src/router.jsx"></script>
+<script type="text/babel" src="src/app.jsx"></script>
+```
+**每个文件末尾**都要`Object.assign(window, {...})`导出要共享的东西。

package/src/skills-lib/huashu-design/references/scene-templates.md ADDED Viewed

@@ -0,0 +1,262 @@
+# 场景模板库：按输出类型组织
+> 与 design-styles.md 的「提示词DNA」组合使用。
+> 公式：`[风格提示词DNA] + [场景模板] + [具体内容描述]`
+---
+## 1. 公众号封面 / 文章题图
+**规格**：
+- 封面图：2.35:1（900×383px 或 1200×510px）
+- 正文插图：16:9（1200×675px）或 4:3（1200×900px）
+**关键设计要素**：
+- 视觉冲击力优先（用户在信息流中快速扫过）
+- 文字极少或无文字（公众号标题会覆盖在上面）
+- 色彩饱和度适中（微信阅读环境偏白）
+- 避免过度细节（缩略图也要可辨识）
+**推荐风格**：01 Pentagram / 11 Build / 12 Sagmeister / 18 Kenya Hara / 07 Field.io
+**场景提示词模板**：
+```
+[风格DNA插入此处]
+- Article cover image for WeChat subscription
+- Landscape format, 2.35:1 aspect ratio
+- Bold visual impact, minimal or no text
+- Moderate color saturation for white reading environment
+- Must remain recognizable as thumbnail
+- Clean composition with clear focal point
+```
+---
+## 2. 正文配图 / 概念插画
+**规格**：
+- 16:9（1200×675px）最通用
+- 1:1（800×800px）适合强调
+- 4:3（1200×900px）适合信息密集
+**关键设计要素**：
+- 服务于文章论点，不是装饰
+- 与上下文形成视觉节奏
+- 简洁表达一个核心概念
+- AI生成优先，HTML截图仅在精确数据表格时用
+**推荐风格**：根据文章调性选择，常用 01/04/10/17/18
+**场景提示词模板**：
+```
+[风格DNA插入此处]
+- Article illustration, concept visualization
+- [16:9 / 1:1 / 4:3] aspect ratio
+- Single clear concept: [描述核心概念]
+- Serve the argument, not decoration
+- [Light/Dark] background to match article tone
+```
+---
+## 3. 信息图 / 数据可视化
+**规格**：
+- 竖版长图：1080×1920px（手机阅读）
+- 横版：1920×1080px（文章内嵌）
+- 方形：1080×1080px（社交媒体）
+**关键设计要素**：
+- 信息层级清晰（标题 → 核心数据 → 细节）
+- 数据准确，不编造
+- 视觉引导线（用户阅读路径）
+- 适当使用图标/图表辅助理解
+**推荐风格**：04 Fathom / 10 Müller-Brockmann / 02 Stamen / 17 Takram
+**场景提示词模板**：
+```
+[风格DNA插入此处]
+- Infographic / data visualization
+- [Vertical 1080x1920 / Horizontal 1920x1080 / Square 1080x1080]
+- Clear information hierarchy: title → key data → details
+- Visual flow guiding reader's eye path
+- Icons and charts for comprehension
+- Data-accurate, no decorative distortion
+```
+---
+## 4. PPT / Keynote 演示
+**规格**：
+- 标准：16:9（1920×1080px）
+- 宽屏：16:10（1920×1200px）
+**关键设计要素**：
+- 每页一个核心信息（不堆砌）
+- 字号层级明确（标题40pt+ / 正文24pt+ / 注释16pt+）
+- 大量留白，投影时更清晰
+- 图文比例至少 60:40
+- 一致的视觉系统（颜色、字体、间距）
+**推荐风格**：01 Pentagram / 10 Müller-Brockmann / 11 Build / 18 Kenya Hara / 04 Fathom
+**场景提示词模板**：
+```
+[风格DNA插入此处]
+- Presentation slide design, 16:9
+- One core message per slide
+- Clear type hierarchy (title 40pt+, body 24pt+)
+- Generous whitespace for projection clarity
+- Consistent visual system throughout
+- [Light/Dark] theme
+```
+---
+## 5. PDF 白皮书 / 技术报告
+**规格**：
+- A4 纵向（210×297mm / 595×842pt）
+- Letter 纵向（216×279mm / 612×792pt）
+**关键设计要素**：
+- 长文阅读优化（行宽66字符、行高1.5-1.8）
+- 清晰的章节导航系统
+- 页眉/页脚/页码的统一设计
+- 图表与正文的优雅共存
+- 引用/注释系统
+- 封面页设计精致
+**推荐风格**：10 Müller-Brockmann / 04 Fathom / 03 Information Architects / 17 Takram / 19 Irma Boom
+**场景提示词模板**：
+```
+[风格DNA插入此处]
+- PDF document / white paper design
+- A4 portrait format (210×297mm)
+- Long-form reading optimized (66 char line width, 1.5 line height)
+- Clear chapter navigation system
+- Elegant header/footer/page number design
+- Charts integrated with body text
+- Professional cover page
+```
+---
+## 6. 落地页 / 产品官网
+**规格**：
+- Desktop: 1440px 宽度设计（响应至320px）
+- 首屏高度：100vh
+**关键设计要素**：
+- 首屏5秒内传达核心价值
+- 清晰的CTA（行动按钮）
+- 滚动叙事结构（问题→方案→证明→行动）
+- 移动端适配
+- 加载速度
+**推荐风格**：05 Locomotive / 01 Pentagram / 11 Build / 08 Resn / 06 Active Theory
+**场景提示词模板**：
+```
+[风格DNA插入此处]
+- Landing page / product website
+- Desktop 1440px width, responsive
+- Hero section 100vh, core value in 5 seconds
+- Clear CTA button design
+- Scroll narrative: problem → solution → proof → action
+- Modern web aesthetic
+```
+---
+## 7. App UI / 原型界面
+**规格**：
+- iOS: 390×844pt（iPhone 15）
+- Android: 360×800dp
+- 平板: 1024×1366pt（iPad Pro）
+**关键设计要素**：
+- 触摸友好（最小点击区44×44pt）
+- 系统设计语言一致性
+- 状态栏/导航栏/Tab栏的标准处理
+- 信息密度适中（移动端不宜过密）
+**推荐风格**：17 Takram / 11 Build / 03 Information Architects / 01 Pentagram
+**场景提示词模板**：
+```
+[风格DNA插入此处]
+- Mobile app UI design
+- iOS [390×844pt] / Android [360×800dp]
+- Touch-friendly (44pt minimum tap targets)
+- Consistent design system
+- Standard status bar / navigation / tab bar
+- Moderate information density
+```
+---
+## 8. 小红书配图
+**规格**：
+- 竖版：3:4（1080×1440px）最佳
+- 方形：1:1（1080×1080px）
+- 首图决定点击率
+**关键设计要素**：
+- 视觉吸引力第一（在瀑布流中竞争）
+- 可以有少量文字（但不超过画面20%）
+- 色彩鲜明但不俗
+- 生活感/质感/氛围感
+**推荐风格**：12 Sagmeister / 11 Build / 20 Neo Shen / 09 Experimental Jetset
+**场景提示词模板**：
+```
+[风格DNA插入此处]
+- Social media image for Xiaohongshu (RED)
+- Vertical 3:4 (1080×1440px)
+- Eye-catching in waterfall feed
+- Minimal text overlay (under 20% of area)
+- Vivid but tasteful colors
+- Lifestyle/texture/atmosphere feel
+```
+---
+## 组合示例
+**场景**：公众号封面，介绍一款AI编程工具，想要专业但有温度
+**Step 1**：选风格 → 17 Takram（专业+温度）
+**Step 2**：取Takram提示词DNA + 公众号封面模板
+```
+Takram Japanese speculative design:
+- Elegant concept prototypes and diagrams
+- Soft tech aesthetic (rounded corners, gentle shadows)
+- Charts and diagrams as art pieces
+- Modest sophistication
+- Neutral natural colors (beige, soft gray, muted green)
+- Design as philosophical inquiry
+Article cover image for WeChat subscription
+- Landscape format, 2.35:1 aspect ratio (1200×510px)
+- Bold visual impact, minimal text
+- Moderate color saturation for white reading environment
+- Must remain recognizable as thumbnail
+- Clean composition with clear focal point
+Content: An AI coding assistant tool, showing the concept of human-AI collaboration
+in software development, warm and professional atmosphere
+```
+---
+**版本**：v1.0
+**更新日期**：2026-02-13