# NPM 发布认证设置指南

## 问题诊断

当前CI发布失败的错误信息：
```
npm error code ENEEDAUTH
npm error need auth This command requires you to be logged in to https://registry.npmjs.org/
npm error need auth You need to authorize this machine using `npm adduser`
```

## 解决方案

### 1. 获取NPM Access Token

#### 步骤1：登录NPM
访问 [https://www.npmjs.com/](https://www.npmjs.com/) 并登录您的账户

#### 步骤2：生成Access Token
1. 点击右上角头像 → "Access Tokens"
2. 点击 "Generate New Token"
3. 选择 "Automation" 类型（用于CI/CD）
4. 复制生成的token（格式类似：`npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`）

### 2. 配置GitHub Secrets

#### 步骤1：访问仓库设置
访问：https://github.com/Deepractice/PromptX/settings/secrets/actions

#### 步骤2：添加ORG_NPM_TOKEN（组织级）
1. 访问组织设置：https://github.com/organizations/Deepractice/settings/secrets/actions
2. 点击 "New organization secret"
3. Name: `ORG_NPM_TOKEN`
4. Secret: 粘贴上一步获取的npm token
5. Repository access: 选择适当的访问权限
6. 点击 "Add secret"

或者添加仓库级的NPM_TOKEN：
1. 点击 "New repository secret"
2. Name: `NPM_TOKEN`
3. Secret: 粘贴上一步获取的npm token
4. 点击 "Add secret"

### 3. 验证配置

#### 本地测试（可选）
```bash
# 设置临时环境变量
export NPM_TOKEN=npm_your_token_here

# 测试认证
./scripts/test-npm-auth.sh
```

#### CI测试
推送代码到develop分支，观察CI日志中的发布结果

### 4. 包权限检查

#### 确保包名可用
```bash
npm view dpml-prompt
```

如果包不存在或您没有发布权限，可能需要：
1. 更改包名
2. 请求包的发布权限
3. 或者发布为scoped包（如：`@deepractice/dpml-prompt`）

### 5. 常见问题排查

#### 问题1：Token无效
- 确保token类型是 "Automation"
- 确保token没有过期
- 重新生成token并更新GitHub Secret

#### 问题2：权限不足
- 确保您的npm账户有发布权限
- 如果是组织包，确保您是组织成员并有发布权限

#### 问题3：包名冲突
- 检查包名是否已存在：`npm view dpml-prompt`
- 考虑使用scoped包名：`@deepractice/dpml-prompt`

#### 问题4：2FA认证
如果启用了2FA，需要：
1. 使用Automation token（不需要2FA）
2. 或在token设置中配置适当的权限

### 6. 最佳实践

#### Token安全
- 永远不要在代码中硬编码token
- 定期轮换token
- 使用最小权限原则

#### CI配置
- 使用`NODE_AUTH_TOKEN`环境变量
- 配置正确的registry URL
- 使用`--no-git-checks`标志避免git相关检查

#### 监控
- 监控发布日志
- 设置发布成功/失败通知
- 定期检查已发布的版本

### 7. 参考DPML项目

DPML项目（https://github.com/Deepractice/dpml）也使用类似的发布流程，可以参考其配置：
- 使用pnpm发布
- 配置NODE_AUTH_TOKEN
- 使用actions/setup-node的registry-url配置

### 8. 当前修复状态

已修复的配置：
- ✅ 添加了NODE_AUTH_TOKEN环境变量
- ✅ 配置了registry-url
- ✅ 使用pnpm发布（与DPML项目一致）
- ✅ 移除了手动.npmrc配置（使用actions/setup-node自动配置）

已更新配置：
- ✅ 使用组织级ORG_NPM_TOKEN
- ✅ CI配置已更新为使用组织token

待验证：
- 🔍 组织token的访问权限设置
- 🔍 npm账户的包发布权限