UTF-8发布基础设施

SKILL.md

---
name: UTF-8发布基础设施
description: 为AI代理和开发者打造的UTF-8发布基础设施，自动处理跨平台编码问题，集成防卡顿策略和韧性保障，防止API token浪费，遵循'防止勤务干扰'原则。
read_when:
  - 在多平台发布内容时遇到编码问题
  - 需要自动化处理发布流程中的编码转换
  - 希望集成韧性发布机制（重试+备选方案）
  - 需要将编码处理作为基础设施而非手动任务
metadata: {"clawdbot":{"emoji":"🏛️","requires":{"bins":["node","npm"]}}}
allowed-tools: Bash(utf8-encoder:*)
---

# UTF-8发布基础设施

> 自动处理多平台中文编码问题的发布基础设施，集成防卡顿策略和韧性保障，防止因编码问题浪费API token。

## 为什么需要这个？

如果你在Windows PowerShell中发布内容到Discord、GitHub等平台，经常遇到：
- **控制台显示乱码**（如"????"），但实际网页正常
- **重复发布浪费token**：因显示误导而重复操作，消耗宝贵API额度
- **平台API编码问题**：原生API不处理编码，导致中文、Emoji显示异常
- **缺乏韧性保障**：发布失败后无自动重试和备选方案

UTF-8发布基础设施将这些痛点转化为自动处理的底层能力，遵循"防止勤务干扰"原则：编码转换不应成为你的思考任务，而是自动运行的基础设施。

## 快速开始

### 最简示例（5行代码）

```javascript
const UTF8Encoder = require('utf8-encoder-tool');
const encoder = new UTF8Encoder();

const text = encoder.ensureUTF8("中文测试 🎯");
console.log(`UTF-8编码完成，字节长度: ${encoder.calculateUTF8ByteLength(text)}`);
```

### 完整发布示例（Discord + GitHub）

```javascript
// 发送到Discord Webhook（自动处理编码）
await encoder.sendToDiscord(process.env.DISCORD_WEBHOOK, '消息内容');

// 创建GitHub Gist（自动UTF-8编码）
await encoder.createGitHubGist(process.env.GITHUB_TOKEN, '# 内容', 'file.md');
```

## 核心特性

### 🏛️ 作为"底层律令"
- **自动运行**：集成到I/O过滤层，无需手动调用
- **防止勤务干扰**：不汇报编码处理细节，直接推进主线任务
- **强制后处理**：所有输出自动确保UTF-8编码

### 🔄 整合验证机制
- **智能检测**：自动判断是否需要编码处理（乱码、中文、Emoji等）
- **独立验证**：通过web_fetch验证实际网页显示，不依赖控制台输出
- **三次尝试法则**：同一方法失败2次即切换备选方案

### 🛡️ 韧性保障
- **防卡顿策略**：集成四层策略框架（预防、检测、恢复、切换）
- **指数退避重试**：内置重试机制，避免平台限流
- **备选方案**：主方案失败时自动切换备用发布渠道

### 🔌 中间件模式
- **系统级集成**：`integrateAsMiddleware()`提供批量发布接口
- **多平台支持**：Discord、GitHub、Reddit（架构就绪）
- **可扩展**：轻松添加新平台支持

**已验证平台**：✅ Discord Webhook ✅ GitHub Gist & Issues ✅ 本地文件读写 🔄 Reddit API（待验证）

## 安装

### 方式一：npm全局安装（推荐）
```bash
npm install -g utf8-encoder-tool
```

### 方式二：本地项目使用
```bash
npm install utf8-encoder-tool
# 或
yarn add utf8-encoder-tool
```

### 方式三：直接使用源码
```bash
git clone https://github.com/mrpulorx2025-source/utf8-encoder-skill
cd utf8-encoder-skill
npm install
```

## 核心功能

### 🏛️ 基础设施模式（推荐）

#### 1.1 作为基础设施集成
```javascript
// 导入基础设施类
const { UTF8Infrastructure } = require('utf8-encoder-tool');
const infrastructure = new UTF8Infrastructure();

// 自动集成中间件，无需手动处理编码
const middleware = infrastructure.integrateAsMiddleware();

// 智能检测是否需要编码处理
const check = infrastructure.shouldProcess("中文测试内容");
if (check.needsProcessing) {
  console.debug('🔄 基础设施自动处理编码问题');
  console.debug(`检测原因: ${check.reasons.join(', ')}`);
  // 遵循"防止勤务干扰"原则：不汇报编码处理细节，直接推进主线任务
}

// 带重试的发送（整合三次尝试法则）
const result = await middleware.sendToDiscordWithRetry(
  process.env.DISCORD_WEBHOOK,
  '消息内容',
  { username: 'UTF8-Infrastructure' }
);

// 批量发布到多个平台
const platforms = [
  {
    type: 'discord',
    url: process.env.DISCORD_WEBHOOK,
    options: { username: 'UTF8-Bot' }
  },
  {
    type: 'github',
    token: process.env.GITHUB_TOKEN,
    filename: 'content.md',
    description: '基础设施发布',
    isPublic: false
  }
];

const results = await middleware.publishToMultiplePlatforms(platforms, '发布内容');
console.log(`发布结果: ${results.filter(r => r.success).length}/${results.length} 成功`);
```

#### 1.2 基础设施特性
- **智能检测**：自动判断是否需要编码处理，提供详细原因（乱码、中文、Emoji等）
- **韧性保障**：内置三次尝试法则，同一方法失败2次即切换方案，支持指数退避重试
- **中间件模式**：提供`integrateAsMiddleware()`系统级集成，支持批量发布
- **防卡顿策略**：集成防卡顿四层策略框架，自动处理发布过程中的阻塞问题
- **备选方案**：支持添加备选发布方案，主方案失败时自动切换
- **状态监控**：提供`getInfrastructureStatus()`实时监控基础设施状态
- **自动恢复**：失败时自动备份内容到本地，防止数据丢失

### 🛠️ 传统工具模式（向后兼容）

#### 2.1 确保UTF-8编码
```javascript
const { UTF8Encoder } = require('utf8-encoder-tool');
const encoder = new UTF8Encoder();

const text = "中文测试 Chinese Test 🎯";
const utf8Text = encoder.ensureUTF8(text);
// 确保文本是有效的UTF-8编码
```

### 2. 计算UTF-8字节长度
```javascript
const byteLength = encoder.calculateUTF8ByteLength(text);
console.log(`字符数: ${text.length}, UTF-8字节数: ${byteLength}`);
// 用于设置HTTP请求的Content-Length头
```

### 3. 读取UTF-8文件
```javascript
const content = encoder.readFileUTF8('./chinese-content.md');
console.log(`文件内容: ${content.substring(0, 100)}...`);
// 自动验证中文字符，统计数量
```

### 4. 创建UTF-8 JSON载荷
```javascript
const payload = encoder.createUTF8JSONPayload({
  message: "中文内容",
  timestamp: new Date().toISOString(),
  author: "丞相"
}, true); // true表示美化输出
```

### 5. 发送到Discord（Webhook）
```javascript
const result = await encoder.sendToDiscord(
  'https://discord.com/api/webhooks/...',
  'Discord消息：中文测试 🎯',
  {
    username: 'UTF8-Bot',
    avatar_url: 'https://example.com/avatar.png'
  }
);

console.log(result.success ? '✅ 发送成功' : '❌ 发送失败');
```

### 6. 创建GitHub Gist
```javascript
const result = await encoder.createGitHubGist(
  'ghp_your_token_here',
  '# GitHub Gist测试\n\n中文内容正常显示测试。',
  'test.md',
  'UTF-8编码测试Gist',
  true // 公开
);

if (result.gistUrl) {
  console.log(`Gist已创建: ${result.gistUrl}`);
}
```

### 7. 乱码检测
```javascript
const validation = encoder.validateNoGarbledChars(text);
if (validation.valid) {
  console.log('✅ 文本无乱码字符');
} else {
  console.log(`❌ 发现${validation.garbledCount}个乱码字符`);
  console.log('乱码字符:', validation.garbledChars);
}
```

## 实战示例

### 示例1：发布调研到多个平台
```javascript
const UTF8Encoder = require('utf8-encoder-tool');
const encoder = new UTF8Encoder();
const fs = require('fs');

async function publishResearch() {
  // 1. 读取调研内容
  const researchContent = encoder.readFileUTF8('./research.md');
  
  // 2. 验证内容
  const validation = encoder.validateNoGarbledChars(researchContent);
  if (!validation.valid) {
    throw new Error(`调研内容包含乱码: ${validation.garbledChars.join(', ')}`);
  }
  
  // 3. 发送到Discord（拆分长消息）
  const discordResult = await encoder.sendToDiscord(
    process.env.DISCORD_WEBHOOK,
    researchContent.substring(0, 1900) // Discord消息限制
  );
  
  // 4. 创建GitHub Gist
  const gistResult = await encoder.createGitHubGist(
    process.env.GITHUB_TOKEN,
    researchContent,
    'research.md',
    '用户调研 - UTF-8测试',
    true
  );
  
  // 5. 生成报告
  const report = encoder.generateTestReport([discordResult, gistResult]);
  fs.writeFileSync('./publish-report.md', report, 'utf8');
  
  console.log('🎉 调研发布完成！');
}

publishResearch().catch(console.error);
```

### 示例2：PowerShell中调用Node.js模块
```powershell
# PowerShell脚本：通过Node.js确保UTF-8编码
$nodeScript = @'
const UTF8Encoder = require('utf8-encoder-tool');
const encoder = new UTF8Encoder();

const text = process.argv[2];
const utf8Text = encoder.ensureUTF8(text);
console.log(utf8Text);
'@

# 保存临时脚本
$nodeScript | Out-File -FilePath "temp-utf8.js" -Encoding UTF8

# 执行并获取结果
$inputText = "PowerShell中的中文测试"
$result = node temp-utf8.js "$inputText"
Write-Host "UTF-8编码结果: $result"

# 清理
Remove-Item "temp-utf8.js"
```

### 示例3：API服务器中间件
```javascript
// Express.js中间件：确保请求体UTF-8编码
const UTF8Encoder = require('utf8-encoder-tool');
const encoder = new UTF8Encoder();

function utf8Middleware(req, res, next) {
  // 确保请求体文本是UTF-8编码
  if (req.body && typeof req.body.text === 'string') {
    req.body.text = encoder.ensureUTF8(req.body.text);
    
    // 验证无乱码
    const validation = encoder.validateNoGarbledChars(req.body.text);
    if (!validation.valid) {
      return res.status(400).json({
        error: '请求包含乱码字符',
        garbledChars: validation.garbledChars
      });
    }
  }
  
  // 设置响应头
  res.setHeader('Content-Type', 'application/json; charset=utf-8');
  next();
}

// 使用中间件
app.use(express.json());
app.use(utf8Middleware);
```

## 技术原理

### 问题根源
1. **PowerShell编码问题**：PowerShell控制台默认使用系统活动代码页（如GB2312）显示文本
2. **编码不一致**：控制台显示编码 ≠ HTTP传输编码 ≠ 文件保存编码
3. **验证缺失**：依赖控制台输出判断，未独立验证实际网页显示

### 解决方案
1. **统一使用Node.js**：Node.js默认使用UTF-8编码，端到端一致性
2. **显式指定编码**：所有文件操作、Buffer转换都明确使用`'utf8'`
3. **独立验证**：通过web_fetch或实际访问验证网页显示
4. **字节长度计算**：使用`Buffer.byteLength(text, 'utf8')`而非`text.length`

### 核心代码片段
```javascript
// 关键：Buffer.byteLength计算UTF-8字节长度
const postData = JSON.stringify(payload);
const contentLength = Buffer.byteLength(postData, 'utf8');

// 关键：设置正确的Content-Type头
headers['Content-Type'] = 'application/json; charset=utf-8';
headers['Content-Length'] = contentLength;
```

## 常见问题与解决

### Q1：为什么控制台显示乱码但网页正常？
**A**：控制台使用GB2312编码显示UTF-8内容。解决方案：不依赖控制台输出，通过`web_fetch`工具验证实际网页显示。

### Q2：如何验证编码是否正确？
**A**：使用`encoder.validateNoGarbledChars(text)`检测乱码字符，或直接访问生成的Gist/Issue查看实际显示。

### Q3：支持哪些特殊字符？
**A**：支持中文、日文、韩文、Emoji、特殊符号。使用正则表达式`/[\u4e00-\u9fa5]/`检测中文字符。

### Q4：与平台原生API有什么区别？
**A**：平台API可能不处理编码问题。本工具确保：
1. 请求体正确UTF-8编码
2. Content-Length头准确
3. Content-Type包含charset=utf-8
4. 响应体正确解码

### Q5：性能影响大吗？
**A**：极小。主要开销是`Buffer.byteLength`计算，对于普通文本（<10KB）可忽略不计。

## 最佳实践

### 开发阶段
1. **先验证后发布**：创建测试Gist/Issue验证编码，确认无误后再正式发布
2. **使用环境变量**：将API Token、Webhook URL存储在环境变量中
3. **记录验证日志**：保存每次发布的验证结果，便于排查问题

### 生产环境
1. **错误处理**：所有API调用都要有try-catch和重试机制
2. **速率限制**：遵守平台API速率限制，添加适当的延迟
3. **监控告警**：监控发布成功率，失败时发送告警

### 测试策略
1. **单元测试**：测试`ensureUTF8`、`calculateUTF8ByteLength`等核心函数
2. **集成测试**：使用测试Webhook和测试Token进行真实API测试
3. **回归测试**：每次更新后验证所有平台兼容性

## 平台扩展指南

### 添加新平台支持
1. 在`UTF8Encoder`类中添加新方法（如`sendToReddit`）
2. 实现平台特定的参数处理和错误处理
3. 添加平台测试用例
4. 更新文档和示例

### Reddit API示例框架
```javascript
async sendToReddit(token, subreddit, title, content, options = {}) {
  const payload = {
    title: this.ensureUTF8(title),
    text: this.ensureUTF8(content),
    sr: subreddit,
    kind: 'self',
    ...options
  };
  
  // Reddit API特定的头和处理逻辑
  // ...
}
```

## 更新日志

### v1.0.0 (2026-03-15)
- ✅ 核心UTF-8编码保障功能
- ✅ Discord Webhook支持
- ✅ GitHub Gist & Issues支持  
- ✅ 乱码检测与验证
- ✅ 字节长度计算
- ✅ 完整文档和示例

### 计划功能
- 🔄 Reddit API支持
- 🔄 Telegram Bot支持
- 🔄 微信公众平台支持
- 🔄 编码转换工具（GB2312 ↔ UTF-8）
- 🔄 批量处理工具

## 贡献与反馈

### 问题反馈
1. GitHub Issues: https://github.com/mrpulorx2025-source/utf8-encoder-skill/issues
2. 邮箱: mrpulorx2025@gmail.com

### 贡献指南
1. Fork仓库
2. 创建功能分支
3. 提交更改
4. 创建Pull Request

## 许可证
MIT License - 详见LICENSE文件

---

**核心教训**：编码问题反复消耗token实属不该。本工具通过一次性测试+验证+发布流程，避免重复浪费，提高发布成功率。

**丞相谨记**：控制台显示 ≠ 实际数据，必须独立验证网页显示！