Skill: mrpulorx2025-source/utf8-encoder (version 2.0.0)

--- name: UTF-8发布基础设施 description: 自动处理多平台中文编码问题的发布基础设施，集成防卡顿策略，支持Discord、GitHub等平台，遵循'防止勤务干扰'原则。 read_when: - 在多平台发布内容时遇到编码问题 - 需要自动化处理发布流程中的编码转换 - 希望集成韧性发布机制（重试+备选方案） - 需要将编码处理作为基础设施而非手动任务 metadata: {"clawdbot":{"emoji":"🏛️","requires":{"bins":["node","npm"]}}} allowed-tools: Bash(utf8-encoder:*) --- # UTF-8发布基础设施 (UTF-8 Publishing Infrastructure) ## 概述 **核心定位**：不是手动调用的编码工具，而是**自动运行的发布流程基础设施**。遵循Gemini专业评审建议：作为"底层律令"，防止"勤务干扰"，整合验证机制。 **解决的核心问题**：PowerShell控制台使用GB2312编码显示UTF-8内容，导致控制台输出乱码，误导开发者认为发布失败。实际HTTP数据正确，但显示误导导致重复发布浪费API token。 **Gemini评审核心洞察**： - 🏛️ **作为"底层律令"**：不应把编码转换当作需要思考的任务，应设为强制性后处理器 - 🚫 **防止"勤务干扰"**：禁止将编码转换作为工作成果汇报，处理完后直接汇报主线任务进度 - 🔄 **整合验证机制**：与三次尝试法则结合，形成完整的韧性系统 **基础设施特性**： - ✅ **自动运行**：集成到I/O过滤层，无需手动调用 - ✅ **韧性保障**：内置防卡顿策略，失败时智能切换方案 - ✅ **智能检测**：自动判断是否需要编码处理，提供详细原因 - ✅ **中间件模式**：提供系统级集成接口，易嵌入工作流 **已验证的平台**： - ✅ 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', [REDACTED_SECRET], 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. 邮箱: [REDACTED_SECRET] ### 贡献指南 1. Fork仓库 2. 创建功能分支 3. 提交更改 4. 创建Pull Request ## 许可证 MIT License - 详见LICENSE文件 --- **核心教训**：编码问题反复消耗token实属不该。本工具通过一次性测试+验证+发布流程，避免重复浪费，提高发布成功率。 **丞相谨记**：控制台显示 ≠ 实际数据，必须独立验证网页显示！


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: malicious | SkillSpector: suspicious (CRITICAL)