tsheep-skills 1.0.0

package/NPM_PUBLISH.md

@@ -0,0 +1,174 @@
+# NPM 发布指南
+
+## 前提条件
+
+1. 拥有 npm 账号（在 https://www.npmjs.com/ 注册）
+2. **必须启用双因素认证（2FA）** - npm 发布包时的强制要求
+3. 本地已登录 npm
+
+### 启用 2FA（必须步骤）
+
+npm 要求发布包时必须启用 2FA 或使用具有 bypass 2fa 权限的 granular access token。这是安全策略，无法绕过。
+
+#### 方法 1：启用 2FA（推荐）
+
+1. 登录 https://www.npmjs.com/
+2. 点击右上角头像 → **Account Settings**
+3. 在左侧菜单找到 **Two-Factor Authentication** 或 **Security**
+4. 点击 **Enable 2FA** 或 **Enable Two-Factor Authentication**
+5. 选择认证方式：
+   - **Authenticator App**（推荐）：使用 Google Authenticator、Authy 等应用
+   - **SMS**：使用手机短信验证
+6. 按照提示完成设置
+7. 保存恢复码（重要！）
+
+设置完成后，重新登录 npm：
+```bash
+npm login
+# 输入用户名、密码和 2FA 验证码
+```
+
+#### 方法 2：使用 Granular Access Token（适合 CI/CD）
+
+如果不想启用 2FA，可以使用 Granular Access Token：
+
+1. 登录 https://www.npmjs.com/
+2. 点击右上角头像 → **Access Tokens**
+3. 点击 **Generate New Token** → **Granular Access Token**
+4. 配置 token：
+   - **Token name**: 例如 "tsheep-skills-publish"
+   - **Expiration**: 选择过期时间
+   - **Permissions**: 选择 **Publish packages**
+   - **Packages**: 选择要发布的包或所有包
+5. 点击 **Generate Token**
+6. **重要**：复制 token（只显示一次）
+
+使用 token 登录：
+```bash
+npm login --auth-type=legacy
+# 输入用户名、密码和 token
+```
+
+或者设置环境变量（适合 CI/CD）：
+```bash
+export NPM_TOKEN=your_token_here
+npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN
+```
+
+### 验证登录状态
+
+```bash
+npm whoami
+# 应该显示你的 npm 用户名
+```
+
+## 发布步骤
+
+### 1. 确保代码已提交
+
+```bash
+git status
+git add .
+git commit -m "Prepare for npm publish"
+git push
+```
+
+### 2. 发布到 npm
+
+```bash
+cd /path/to/tsheep-skills
+npm publish
+```
+
+如果包名已被占用，可以使用 scoped package：
+
+```bash
+# 修改 package.json 中的 name 为 @luo29/tsheep-skills
+npm publish --access public
+```
+
+### 3. 验证发布
+
+发布成功后，用户可以通过以下方式安装：
+
+```bash
+# 如果使用普通包名
+npx tsheep-skills add ab-experiment-cleanup
+
+# 如果使用 scoped 包名
+npx @luo29/tsheep-skills add ab-experiment-cleanup
+```
+
+## 更新版本
+
+当需要发布新版本时：
+
+```bash
+# 更新补丁版本 (1.0.0 -> 1.0.1)
+npm version patch
+
+# 更新次版本 (1.0.0 -> 1.1.0)
+npm version minor
+
+# 更新主版本 (1.0.0 -> 2.0.0)
+npm version major
+
+# 推送标签
+git push --tags
+
+# 发布新版本
+npm publish
+```
+
+## 测试本地包
+
+在发布前，可以先本地测试：
+
+```bash
+# 在项目目录下
+npm link
+
+# 在其他目录测试
+npx tsheep-skills add ab-experiment-cleanup
+```
+
+## 包信息
+
+- **包名**: tsheep-skills (或 @luo29/tsheep-skills)
+- **版本**: 1.0.0
+- **仓库**: https://github.com/luo29/tsheep-skills
+- **主页**: https://github.com/luo29/tsheep-skills#readme
+
+## 常见错误及解决方案
+
+### 错误：403 Forbidden - Two-factor authentication required
+
+**原因**：npm 要求发布包时必须启用 2FA 或使用 granular access token。
+
+**解决方案**：
+1. 按照上面的步骤启用 2FA
+2. 或创建并使用 Granular Access Token
+3. 重新登录：`npm login`
+
+### 错误：包名已被占用
+
+**解决方案**：
+1. 使用 scoped package：修改 `package.json` 中的 `name` 为 `@your-username/tsheep-skills`
+2. 发布时添加 `--access public`：`npm publish --access public`
+
+### 错误：package.json 格式问题
+
+**解决方案**：
+```bash
+npm pkg fix
+# 这会自动修复 package.json 中的格式问题
+```
+
+## 注意事项
+
+1. **必须启用 2FA**：npm 发布包时的强制要求
+2. 确保 package.json 中的信息准确
+3. 检查 .npmignore 文件，避免发布不必要的文件
+4. 首次发布可能需要验证邮箱
+5. 如果包名被占用，考虑使用 scoped package (@username/package-name)
+6. 发布前建议运行 `npm pkg fix` 修复格式问题

package/README.md

@@ -0,0 +1,80 @@
+# TSheep Skills
+
+A collection of Claude Code agent skills for various development tasks.
+
+## Available Skills
+
+### ab-experiment-cleanup
+
+清理已推全的 A/B 实验代码，生成影响面分析和回测报告
+
+**功能特性：**
+- 自动识别和清理已推全的 A/B 实验代码
+- 生成详细的影响面分析报告
+- 提供回测验证支持
+- 支持多种实验框架
+
+[查看详细文档](./ab-experiment-cleanup/README.md)
+
+## Installation
+
+### Method 1: NPX Install (Recommended) 🚀
+
+Install a specific skill using npx (no installation required):
+
+```bash
+npx tsheep-skills add ab-experiment-cleanup
+```
+
+List all available skills:
+
+```bash
+npx tsheep-skills list
+```
+
+### Method 2: Claude Code CLI
+
+Install using the Claude Code CLI:
+
+```bash
+claude skill install https://github.com/luo29/tsheep-skills.git/ab-experiment-cleanup
+```
+
+### Method 3: Manual Install
+
+1. Clone this repository:
+```bash
+git clone https://github.com/luo29/tsheep-skills.git
+```
+
+2. Create a symlink to the skill you want to use:
+```bash
+ln -s /path/to/tsheep-skills/ab-experiment-cleanup ~/.claude/skills/ab-experiment-cleanup
+```
+
+3. Restart Claude Code or reload skills
+
+## Usage
+
+Once installed, you can invoke the skill in Claude Code:
+
+```
+/ab-experiment-cleanup
+```
+
+Or simply describe what you want to do, and Claude will automatically use the appropriate skill.
+
+## Contributing
+
+Feel free to contribute new skills or improvements to existing ones. Please follow the skill structure:
+
+```
+skill-name/
+├── SKILL.md      # The skill prompt/instructions
+├── README.md     # User-facing documentation
+└── EXAMPLE.md    # (Optional) Usage examples
+```
+
+## License
+
+MIT

package/ab-experiment-cleanup/EXAMPLE.md

@@ -0,0 +1,448 @@
+# A/B 实验清理示例
+
+## 场景描述
+
+假设我们有一个电商网站，之前做了一个新结账流程的 A/B 实验。实验字段为 `enableNewCheckout`，现在实验已经推全，全量值为 `true`，需要清理旧的结账流程代码（`enableNewCheckout === false` 的分支）。
+
+## 使用命令
+
+```
+/ab-experiment-cleanup
+
+enableNewCheckout 实验字段对应的实验已经推全，enableNewCheckout 字段全量为 true，
+请下掉走到 enableNewCheckout 为 false 的业务逻辑代码，
+并产出影响面分析和业务回测报告
+```
+
+## 预期输出示例
+
+### 1. 信息确认
+
+```
+我理解您的需求：
+- 实验字段：enableNewCheckout
+- 全量值：true
+- 需要删除：enableNewCheckout 为 false 的代码分支
+- 需要保留：enableNewCheckout 为 true 的代码分支
+
+开始扫描代码库...
+```
+
+### 2. 代码扫描结果
+
+```
+找到 8 个文件包含 enableNewCheckout 引用：
+
+业务逻辑文件：
+- src/pages/Checkout.tsx
+- src/components/PaymentForm.tsx
+- src/components/OrderSummary.tsx
+- src/hooks/useCheckout.ts
+
+配置文件：
+- src/config/experiments.ts
+- src/config/featureFlags.json
+
+类型定义：
+- src/types/experiments.ts
+
+测试文件：
+- src/pages/__tests__/Checkout.test.tsx
+```
+
+### 3. 清理计划
+
+```markdown
+## 代码清理计划
+
+### src/pages/Checkout.tsx
+
+**当前代码（第 45-89 行）：**
+```typescript
+const CheckoutPage = () => {
+  const { enableNewCheckout } = useExperiments();
+
+  if (enableNewCheckout) {
+    // 新结账流程
+    return (
+      <div className="new-checkout">
+        <CheckoutSteps />
+        <PaymentForm />
+        <OrderSummary />
+      </div>
+    );
+  } else {
+    // 旧结账流程 - 需要删除
+    return (
+      <div className="old-checkout">
+        <LegacyCheckoutForm />
+      </div>
+    );
+  }
+};
+```
+
+**清理后代码：**
+```typescript
+const CheckoutPage = () => {
+  return (
+    <div className="new-checkout">
+      <CheckoutSteps />
+      <PaymentForm />
+      <OrderSummary />
+    </div>
+  );
+};
+```
+
+**操作：**
+- ✂️ 删除第 46 行：`const { enableNewCheckout } = useExperiments();`
+- ✂️ 删除第 48-58 行：整个 if-else 条件判断
+- ✂️ 删除第 59-63 行：旧结账流程代码
+- ✅ 保留第 50-56 行：新结账流程代码，提升到函数顶层
+
+---
+
+### src/config/experiments.ts
+
+**当前代码（第 12-16 行）：**
+```typescript
+export const experiments = {
+  enableNewCheckout: {
+    name: 'New Checkout Flow',
+    defaultValue: true,
+  },
+  // ... 其他实验
+};
+```
+
+**操作：**
+- ✂️ 删除第 12-15 行：整个 enableNewCheckout 配置
+
+---
+
+### src/types/experiments.ts
+
+**当前代码（第 5-8 行）：**
+```typescript
+export interface ExperimentFlags {
+  enableNewCheckout: boolean;
+  // ... 其他实验
+}
+```
+
+**操作：**
+- ✂️ 删除第 6 行：`enableNewCheckout: boolean;`
+
+---
+
+（其他文件的清理计划类似...）
+```
+
+### 4. 影响面分析报告
+
+```markdown
+# 影响面分析报告
+
+## 1. 受影响文件清单
+
+| 文件类型 | 文件路径 | 修改类型 | 影响程度 |
+|---------|---------|---------|---------|
+| 业务逻辑 | src/pages/Checkout.tsx | 删除旧逻辑，简化条件 | 🔴 重大 |
+| 业务逻辑 | src/components/PaymentForm.tsx | 删除条件判断 | 🟡 中等 |
+| 业务逻辑 | src/components/OrderSummary.tsx | 删除条件判断 | 🟡 中等 |
+| 业务逻辑 | src/hooks/useCheckout.ts | 简化逻辑 | 🟢 轻微 |
+| 配置文件 | src/config/experiments.ts | 删除实验配置 | 🟢 轻微 |
+| 配置文件 | src/config/featureFlags.json | 删除 flag | 🟢 轻微 |
+| 类型定义 | src/types/experiments.ts | 删除类型定义 | 🟢 轻微 |
+| 测试文件 | src/pages/__tests__/Checkout.test.tsx | 更新测试用例 | 🟡 中等 |
+
+**统计：**
+- 总文件数：8
+- 重大影响：1
+- 中等影响：3
+- 轻微影响：4
+
+## 2. 功能模块影响
+
+### 结账流程（核心功能）
+- **影响程度**：🔴 重大
+- **涉及文件**：Checkout.tsx, PaymentForm.tsx, OrderSummary.tsx
+- **变更说明**：删除旧结账流程，保留新流程
+- **风险点**：这是核心业务流程，需要充分测试
+
+### 实验配置系统
+- **影响程度**：🟢 轻微
+- **涉及文件**：experiments.ts, featureFlags.json
+- **变更说明**：清理实验配置
+- **风险点**：无
+
+### 类型系统
+- **影响程度**：🟢 轻微
+- **涉及文件**：experiments.ts
+- **变更说明**：删除不再使用的类型定义
+- **风险点**：需要确保没有其他地方引用该类型
+
+## 3. 依赖关系分析
+
+```
+enableNewCheckout (实验字段)
+├── src/pages/Checkout.tsx (主要使用)
+│   └── 依赖 useExperiments hook
+├── src/components/PaymentForm.tsx
+│   └── 依赖 useExperiments hook
+├── src/components/OrderSummary.tsx
+│   └── 依赖 useExperiments hook
+└── src/hooks/useCheckout.ts
+    └── 依赖 experiments config
+```
+
+**关键发现：**
+- ✅ 没有发现其他实验依赖 enableNewCheckout
+- ✅ 删除后不会影响其他功能
+- ⚠️ 需要确认 useExperiments hook 在删除后仍然正常工作
+
+## 4. 风险评估
+
+### 总体风险等级：🟡 中等
+
+**风险因素：**
+1. **核心功能修改**：结账流程是核心业务，任何问题都会直接影响收入
+2. **代码覆盖面广**：涉及 8 个文件，需要仔细审查每个变更
+3. **测试依赖**：需要更新测试用例，确保测试覆盖
+
+**降低风险的措施：**
+1. ✅ 充分的回测（见回测报告）
+2. ✅ 灰度发布策略
+3. ✅ 实时监控关键指标
+4. ✅ 准备快速回滚方案
+
+## 5. 建议的发布策略
+
+1. **阶段 1**：在测试环境完整回测（1-2 天）
+2. **阶段 2**：灰度 5% 用户，监控 24 小时
+3. **阶段 3**：灰度 25% 用户，监控 24 小时
+4. **阶段 4**：灰度 50% 用户，监控 24 小时
+5. **阶段 5**：全量发布
+
+**监控指标：**
+- 结账成功率
+- 支付成功率
+- 页面加载时间
+- JavaScript 错误率
+```
+
+### 5. 回测报告
+
+```markdown
+# 业务回测报告
+
+## 1. 回测检查清单
+
+### 功能模块：结账流程
+
+#### 基础流程测试
+- [ ] 新用户首次结账
+- [ ] 老用户重复购买
+- [ ] 购物车为空时的处理
+- [ ] 购物车有多个商品
+- [ ] 购物车有单个商品
+
+#### 支付相关
+- [ ] 信用卡支付
+- [ ] 借记卡支付
+- [ ] 第三方支付（支付宝、微信）
+- [ ] 支付失败的错误处理
+- [ ] 支付超时的处理
+
+#### 优惠和折扣
+- [ ] 应用优惠券
+- [ ] 应用促销码
+- [ ] 会员折扣
+- [ ] 多重优惠叠加
+
+#### 订单确认
+- [ ] 订单摘要显示正确
+- [ ] 价格计算准确
+- [ ] 订单确认邮件发送
+- [ ] 订单状态更新
+
+#### 异常场景
+- [ ] 网络中断时的处理
+- [ ] 库存不足的提示
+- [ ] 地址信息不完整
+- [ ] 支付信息验证失败
+
+### 功能模块：实验配置系统
+
+- [ ] 其他实验仍然正常工作
+- [ ] useExperiments hook 正常返回
+- [ ] 实验配置加载正常
+
+## 2. 自动化测试建议
+
+### 需要执行的现有测试
+```bash
+# 运行所有结账相关的测试
+npm test -- Checkout
+npm test -- PaymentForm
+npm test -- OrderSummary
+
+# 运行集成测试
+npm test -- e2e/checkout
+```
+
+### 需要新增的测试用例
+
+**src/pages/__tests__/Checkout.test.tsx**
+```typescript
+describe('Checkout - After experiment cleanup', () => {
+  it('should render new checkout flow without experiment flag', () => {
+    render(<CheckoutPage />);
+    expect(screen.getByTestId('new-checkout')).toBeInTheDocument();
+    expect(screen.queryByTestId('old-checkout')).not.toBeInTheDocument();
+  });
+
+  it('should not depend on useExperiments hook', () => {
+    // 确保不再依赖实验配置
+    const { container } = render(<CheckoutPage />);
+    expect(container).toMatchSnapshot();
+  });
+});
+```
+
+### 需要更新的测试用例
+
+**需要删除的测试：**
+- 所有测试旧结账流程的用例
+- 所有测试实验分支切换的用例
+
+**需要更新的测试：**
+- 将测试新结账流程的用例改为默认测试
+- 移除 mock useExperiments 的代码
+
+## 3. 手动测试场景
+
+### 高优先级（必须测试）
+
+1. **完整结账流程**
+   - 从购物车到支付成功的完整流程
+   - 测试环境：Chrome, Safari, Firefox
+   - 测试设备：Desktop, Mobile
+
+2. **支付成功场景**
+   - 使用测试信用卡完成支付
+   - 验证订单创建成功
+   - 验证邮件发送
+
+3. **错误处理**
+   - 支付失败的提示
+   - 网络错误的处理
+   - 表单验证
+
+### 中优先级（建议测试）
+
+1. **不同用户状态**
+   - 未登录用户
+   - 已登录用户
+   - VIP 用户
+
+2. **不同商品类型**
+   - 实体商品
+   - 虚拟商品
+   - 预售商品
+
+### 低优先级（可选测试）
+
+1. **边界情况**
+   - 极大金额订单
+   - 极小金额订单
+   - 特殊字符处理
+
+## 4. 数据验证建议
+
+### 关键指标监控
+
+| 指标 | 当前基线 | 预期范围 | 告警阈值 |
+|-----|---------|---------|---------|
+| 结账成功率 | 85% | 83-87% | < 80% |
+| 支付成功率 | 92% | 90-94% | < 88% |
+| 页面加载时间 | 1.2s | < 1.5s | > 2.0s |
+| JavaScript 错误率 | 0.5% | < 1% | > 2% |
+| 订单转化率 | 12% | 11-13% | < 10% |
+
+### 监控时间表
+
+- **第 1 天**：每小时检查一次
+- **第 2-3 天**：每 4 小时检查一次
+- **第 4-7 天**：每天检查一次
+- **第 2 周后**：恢复正常监控频率
+
+### 数据对比分析
+
+对比以下时间段的数据：
+- 清理前 7 天 vs 清理后 7 天
+- 同比去年同期
+- 环比上周同期
+
+## 5. 回滚预案
+
+### 回滚触发条件
+
+满足以下任一条件立即回滚：
+- 结账成功率下降超过 5%
+- 支付成功率下降超过 3%
+- JavaScript 错误率上升超过 1%
+- 收到 3 个以上用户投诉
+
+### 回滚步骤
+
+1. **立即回滚代码**
+   ```bash
+   git revert <commit-hash>
+   git push origin main
+   ```
+
+2. **触发紧急发布**
+   - 跳过灰度，直接全量
+   - 通知相关团队
+
+3. **验证回滚效果**
+   - 检查关键指标是否恢复
+   - 执行冒烟测试
+
+4. **事后分析**
+   - 分析回滚原因
+   - 制定改进方案
+
+## 6. 后续行动项
+
+### 发布前
+- [ ] 代码 Review（至少 2 人）
+- [ ] 执行所有自动化测试
+- [ ] 完成手动回测
+- [ ] 准备监控 Dashboard
+- [ ] 准备回滚脚本
+
+### 发布中
+- [ ] 按灰度策略发布
+- [ ] 实时监控关键指标
+- [ ] 准备随时回滚
+
+### 发布后
+- [ ] 持续监控 7 天
+- [ ] 收集用户反馈
+- [ ] 数据对比分析
+- [ ] 总结经验教训
+```
+
+## 总结
+
+这个示例展示了 skill 的完整输出，包括：
+
+1. ✅ 详细的代码清理计划
+2. ✅ 全面的影响面分析
+3. ✅ 完整的回测报告
+4. ✅ 清晰的后续行动项
+
+使用这个 skill 可以大大提高 A/B 实验代码清理的效率和安全性。