svharness 0.8.0 → 0.13.2

package/templates/web-react/skeleton/agent-env/skills/harness-state-management/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: harness-state-management
+description: React 状态管理模式。覆盖 useState/useReducer、Context、Zustand、Redux Toolkit 的选择与使用。
+---
+
+# 状态管理
+
+## 概述
+
+根据状态的作用域与复杂度选择合适的管理方式。避免过度工程，也避免状态混乱。
+
+---
+
+## 状态分类
+
+| 状态类型 | 作用域 | 推荐方案 |
+|----------|--------|---------|
+| **本地 UI 状态** | 单个组件 | `useState` |
+| **跨组件状态** | 组件树局部 | `useReducer` + Context |
+| **全局共享状态** | 全应用 | Zustand / Redux Toolkit |
+| **服务端状态** | 远程数据 | React Query / SWR |
+| **URL 状态** | 路由参数 | React Router / URL SearchParams |
+
+## 本地状态：useState
+
+```tsx
+function Counter() {
+  const [count, setCount] = useState(0);
+  return <button onClick={() => setCount(c => c + 1)}>{count}</button>;
+}
+```
+
+## 复杂状态：useReducer
+
+```tsx
+type Action =
+  | { type: 'INCREMENT'; payload: number }
+  | { type: 'DECREMENT'; payload: number }
+  | { type: 'RESET' };
+
+function counterReducer(state: number, action: Action): number {
+  switch (action.type) {
+    case 'INCREMENT': return state + action.payload;
+    case 'DECREMENT': return state - action.payload;
+    case 'RESET': return 0;
+  }
+}
+
+function Counter() {
+  const [count, dispatch] = useReducer(counterReducer, 0);
+  return (
+    <>
+      <p>{count}</p>
+      <button onClick={() => dispatch({ type: 'INCREMENT', payload: 1 })}>+</button>
+      <button onClick={() => dispatch({ type: 'RESET' })}>Reset</button>
+    </>
+  );
+}
+```
+
+## 跨组件状态：Context
+
+```tsx
+import { createContext, useContext, useReducer, type ReactNode } from 'react';
+
+// 1. 定义状态与 Action
+interface AuthState { user: User | null; token: string | null; }
+type AuthAction =
+  | { type: 'LOGIN'; user: User; token: string }
+  | { type: 'LOGOUT' };
+
+// 2. 创建 Context
+interface AuthContextType {
+  state: AuthState;
+  login: (user: User, token: string) => void;
+  logout: () => void;
+}
+
+const AuthContext = createContext<AuthContextType | null>(null);
+
+// 3. Provider
+function AuthProvider({ children }: { children: ReactNode }) {
+  const [state, dispatch] = useReducer(authReducer, initialState);
+
+  const login = (user: User, token: string) =>
+    dispatch({ type: 'LOGIN', user, token });
+
+  const logout = () => dispatch({ type: 'LOGOUT' });
+
+  return (
+    <AuthContext.Provider value={{ state, login, logout }}>
+      {children}
+    </AuthContext.Provider>
+  );
+}
+
+// 4. 自定义 Hook
+function useAuth(): AuthContextType {
+  const ctx = useContext(AuthContext);
+  if (!ctx) throw new Error('useAuth must be used within AuthProvider');
+  return ctx;
+}
+```
+
+## 全局状态：Zustand
+
+```tsx
+import { create } from 'zustand';
+
+interface CartStore {
+  items: CartItem[];
+  total: number;
+  addItem: (item: CartItem) => void;
+  removeItem: (id: string) => void;
+  clearCart: () => void;
+}
+
+const useCartStore = create<CartStore>((set, get) => ({
+  items: [],
+  total: 0,
+  addItem: (item) => set((state) => ({
+    items: [...state.items, item],
+    total: state.total + item.price * item.quantity,
+  })),
+  removeItem: (id) => set((state) => {
+    const items = state.items.filter((i) => i.id !== id);
+    const total = items.reduce((sum, i) => sum + i.price * i.quantity, 0);
+    return { items, total };
+  }),
+  clearCart: () => set({ items: [], total: 0 }),
+}));
+
+// 使用（组件内）
+function CartSummary() {
+  const total = useCartStore((state) => state.total);
+  const items = useCartStore((state) => state.items);
+  const addItem = useCartStore((state) => state.addItem);
+  // ...
+}
+```
+
+## 服务端状态：React Query (TanStack Query)
+
+```tsx
+import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';
+
+// 获取数据
+function useUsers() {
+  return useQuery({
+    queryKey: ['users'],
+    queryFn: () => fetch('/api/users').then(r => r.json()),
+    staleTime: 5 * 60 * 1000, // 5 分钟内不过期
+  });
+}
+
+// 变更数据
+function useCreateUser() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (newUser: NewUser) =>
+      fetch('/api/users', { method: 'POST', body: JSON.stringify(newUser) }),
+    onSuccess: () => {
+      queryClient.invalidateQueries({ queryKey: ['users'] });
+    },
+  });
+}
+```
+
+## 状态管理决策树
+
+```
+这个状态是...
+├── 服务端数据（来自 API）? → React Query / SWR
+├── URL 参数?              → React Router / useSearchParams
+├── 仅一个组件使用?         → useState
+├── 组件树局部（2-3 层）?    → useState + Props
+├── 组件树局部（3+ 层透传）?  → useReducer + Context（禁止 prop drilling）
+└── 全局共享（主题、用户、购物车）?
+    ├── 少量状态，简单逻辑 → Zustand
+    └── 大量状态，复杂逻辑 → Redux Toolkit
+```
+
+---
+
+## 相关规则
+
+- `seed-no-props-drilling` — 禁止超 2 层 props drilling
+- `seed-hook-rules` — Hook 调用铁律

package/templates/_shared/skeleton/assets/baseline/code/.gitkeep

@@ -1 +0,0 @@
-# placeholder — reference code snapshots (~20 key files), NOT full src copy

package/templates/_shared/skeleton/assets/baseline/wiki/.gitkeep

@@ -1 +0,0 @@
-# placeholder — repowiki pages rendered by harness-knowledge-builder skill

package/templates/_shared/skeleton/assets/raw/.gitkeep

@@ -1 +0,0 @@
-# placeholder — populated during harness build (manual requirement docs)

package/templates/_shared/skeleton/assets/requirements/.gitkeep

@@ -1 +0,0 @@
-# placeholder — populated during harness build (parsed/structured requirements)