Senparc.Xncf.WeixinManager 0.24.14

Prefix Reserved
.NET 10.0 This package targets .NET 10.0. The package is compatible with this framework or higher. 
dotnet add package Senparc.Xncf.WeixinManager --version 0.24.14
                    


                    

                
NuGet\Install-Package Senparc.Xncf.WeixinManager -Version 0.24.14
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package. 
<PackageReference Include="Senparc.Xncf.WeixinManager" Version="0.24.14" />
For projects that support PackageReference, copy this XML node into the project file to reference the package. 
<PackageVersion Include="Senparc.Xncf.WeixinManager" Version="0.24.14" />
                    


                            Directory.Packages.props
                        

                    

                
<PackageReference Include="Senparc.Xncf.WeixinManager" />
                    


                            Project file
For projects that support Central Package Management (CPM), copy this XML node into the solution Directory.Packages.props file to version the package. 
paket add Senparc.Xncf.WeixinManager --version 0.24.14
                    


                    

                
#r "nuget: Senparc.Xncf.WeixinManager, 0.24.14"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package. 
#:package Senparc.Xncf.WeixinManager@0.24.14
#:package directive can be used in C# file-based apps starting in .NET 10 preview 4. Copy this into a .cs file before any lines of code to reference the package. 
#addin nuget:?package=Senparc.Xncf.WeixinManager&version=0.24.14
                    


                            Install as a Cake Addin
                        

                    

                
#tool nuget:?package=Senparc.Xncf.WeixinManager&version=0.24.14
                    


                            Install as a Cake Tool

Senparc.Xncf.WeixinManager

Senparc.Xncf.WeixinManager is an NCF administration module for managing WeChat public-account configuration, users, tags, message handlers, and reusable notification templates.

Features

  • Persists MpAccount, WeixinUser, and UserTag data with DTOs and service layers.
  • Supports account discovery, user synchronization, tag management, and WeChat-facing message handling.
  • Provides WeixinService, XncfMpMessageHandler, and template base types for module integrations.
  • Uses Senparc.Weixin APIs and NCF's multi-database context conventions.

Personal Weixin Bot

The module also supports the personal Weixin Bot channel used by Tencent's official openclaw-weixin package. It implements the iLink HTTP JSON protocol directly and does not require the OpenClaw runtime.

  • Open /Admin/WeixinManager/WeixinClaw to scan a QR code and connect an account.
  • Polls inbound text messages with a persisted get_updates_buf cursor.
  • Stores message_id + seq receipts for idempotent processing.
  • Protects bot tokens with ASP.NET Data Protection.
  • Exposes IWeixinClawMessageHandler for Admin Chat, NeuBell, or custom routing.
  • Exposes IWeixinClawMessageSender / WeixinClawMessageService.SendTextAsync() for outbound text.
  • Supports outbound images, files, and voice files through getuploadurl, the iLink CDN upload flow, and sendmessage.
  • Downloads inbound image, voice, video, and file media from the iLink CDN, decrypts it, and stores it under the host App_Data/WeixinClawMedia directory for authenticated conversation display.
  • Requests a tenant-scoped private-attachment import through the FileManager Abstractions EventBus contract. The message record keeps the resulting FileManager file ID; if FileManager is unavailable, the original Weixin conversation copy remains usable and the import error is recorded separately.
  • Persists the latest inbound user and protected context_token, so the Admin page can send a reply after the phone sends at least one message. The page reports an actionable error instead of treating a context-less send as delivered.
  • Persists inbound and outbound text records in WeixinManager_WeixinClawMessageRecord; the Admin page provides a polling conversation window and shows sending, sent, and failed states. The window also supports image, file, and voice-file uploads.

Sends require the inbound context_token for the same recipient, preserved without trimming. Completing a poll updates the cursor/running status without clearing the stored inbound sender or context. Replying to a stored inbound record uses that record's sender and context; an invalid reply record is rejected rather than silently sending to a different conversation. Media sends without a reply record only reuse the latest context when its sender matches the recipient.

An HTTP success with ret=0 means the API accepted the request, not that the phone displayed it. The official response's message_id is optional: its absence does not make an accepted request fail. The official ret field is also optional; as in Tencent's sender, a supplied nonzero ret is a business failure, while an omitted ret is preserved as absent rather than fabricated as zero. The existing sent state means API submission, not a read/delivery receipt. Business errors still produce a failed record. Native voice sends support SILK and MP3 encoding declarations only; other audio formats must be sent as files. Outbound audio is not transcoded, and the module does not invent sample rate, bit depth, or duration metadata.

Conversation media playback

  • Incoming video_item (item type 5) is downloaded/decrypted and stored as MP4 rather than ignored. Video and audio responses support HTTP Range requests for browser seeking.
  • SILK voice recordings, including old .bin files, are detected from their actual header. The authenticated playback endpoint decodes them to 24-kHz, mono, signed 16-bit PCM WAV on demand. A .playback.wav sidecar is cached; the original recording and its download URL are preserved.
  • Decoding reuses the existing DrAbc.SilkSharp 2.0.8 dependency. It deliberately uses the file-based codec API: the package's POSIX buffer API incorrectly reads an output-only open_memstream, causing empty or corrupt output. Calls are serialized, input framing is validated, and temporary snapshots/PCM files are removed after conversion. No recording is uploaded to a decoding service.
  • The legacy native decoder requires at least three packets (normally 60 ms). Short/truncated input, packets exceeding its 5-KB bound, and input/estimated or actual PCM above 50 MB are explicitly rejected before playback instead of invoking unsafe native paths or exhausting memory.
  • Deploy the package's native runtime assets alongside the application. Supported bundled targets include Windows x86/x64, Linux x86/x64/ARM/ARM64, and macOS ARM64; unsupported targets produce an explicit playback error. The existing codec dependency is GPL-3.0-or-later.
  • Browser-compatible MP4 video is played directly, not transcoded. H.264/AAC has been verified; other codecs still require browser support. The original download remains available if playback fails.
  • Videos discarded by older versions cannot be reconstructed from an already-advanced poll cursor; resend them after deploying this update.

The page refreshes connection state immediately when opened and continues periodic refreshes. Initial server-rendered account data uses camelCase, matching the AJAX response. Only the conversation composer remains; the duplicate bottom send form and its visibility/manual-context state have been removed.

Playback tests cover generated SILK, malformed framing, cancellation, cached conversion, video decryption, and Range-enabled media results. Set WEIXINCLAW_VOICE_SAMPLE to the provided 4.2-second local fixture when running its opt-in regression test; private recordings are not committed as test assets.

Protocol verification (2026-10-03)

The Weixin Open Documentation ClawBot page documents the /api/v1/wechat/* login/channel wrapper, not the full direct iLink sendmessage contract. The direct protocol was cross-checked against Tencent's published @tencent-weixin/openclaw-weixin 2.4.9 source, particularly src/api/types.ts, src/api/api.ts, src/messaging/send.ts, and src/cdn/upload.ts.

  • JSON property names are case-sensitive on output: type, text_item.text, image_item.media, voice_item.media, and file_item.media / file_item.len must not use C# property casing.
  • Text, image, voice, and file messages all use message_type: 2 (BOT) and message_state: 2 (FINISH). The content type is item_list[].type: text=1, image=2, voice=3, file=4.
  • Outbound msg includes from_user_id: "", the recipient, client_id, message type/state, items, and context; run_id is optional. Server-only inbound fields and null payload branches are omitted.
  • JSON POSTs use AuthorizationType: ilink_bot_token, Authorization: Bearer <bot_token>, a random uint32 decimal string encoded as base64 in X-WECHAT-UIN, and Content-Type: application/json. App headers are iLink-App-Id: bot and iLink-App-ClientVersion: 132105; base_info.channel_version is 2.4.9, with NCF identified by bot_agent. QR creation is a token-less POST; status polling is GET.
  • Upload requests use rawsize / rawfilemd5 for plaintext, filesize for PKCS7-padded AES-128-ECB ciphertext, and a lowercase hex aeskey. Following the official sender, the outgoing media aes_key is base64 of that hex string; file len is plaintext size as a string.
  • Contract tests compare complete parsed JSON objects (including field names and value types), authenticated request headers, business-error handling, optional response fields, and uint64 IDs. Pipeline tests exercise the actual send services, decrypt their uploaded ciphertext to verify plaintext/MD5/sizes/key encoding, and confirm that polling preserves a usable reply context.

After the first successful inbound message, the account and Admin binding persist the latest recipient and protected conversation context. This lets Admin Chat and NeuBell continue sending after a page reload or process restart when the WeChat-side context is still valid. The Admin integration also performs one startup NeuBell reconciliation and stores per-provider snapshot fingerprints to avoid duplicate recovery messages. Apply the Admin module's latest database migration before enabling this behavior in production, and persist ASP.NET Data Protection keys across deployments; otherwise encrypted bot/context tokens cannot be recovered.

If the WeChat-side context has expired or the Data Protection keys were replaced, send a fresh message from the phone to establish a new context. Verify that the actual phone displays the text and media; unit tests and ret=0 alone cannot prove delivery.

Concrete Admin Chat, NeuBell, Workflow, and Harness routing is implemented by the upper-layer Admin integration rather than this channel module.

Hosted-service tuning

The background WeixinClaw poller can be tuned with the SenparcXncfWeixinManager:WeixinClaw:HostedService configuration section:

  • ScanIntervalSeconds - account discovery interval, clamped to 1-300 seconds.
  • ErrorRetryDelaySeconds - delay after getupdates returns a business error, clamped to 1-300 seconds.
  • ShutdownWaitSeconds - host shutdown grace period for in-flight poll tasks, clamped to 1-60 seconds.
  • NotifyStopTimeoutSeconds - timeout for the best-effort notifystop call, clamped to 1-30 seconds.

Installation

<PackageReference Include="Senparc.Xncf.WeixinManager" Version="0.24.14" />

Key API

  • MpAccountService manages account configuration and MpAccount records.
  • WeixinService provides module-level WeChat operations.
  • WeixinUser/WeixinUserDto and UserTag/UserTag_WeixinUserDto represent synchronized user and tag data.
  • MpMessageHandlerAttribute and XncfMpMessageHandler connect incoming WeChat messages to NCF handlers.
  • WeixinTemplateBase and the WeixinTemplate_* types support reusable template messages.
  • FindWeixinApiController exposes API discovery/management endpoints.

Store AppSecret, access tokens, and encryption keys in secure configuration. Validate WeChat signatures, scope account access by tenant/administrator, and treat synchronized user data as personal information.

Product Compatible and additional computed target framework versions.
.NET net10.0 is compatible.  net10.0-android was computed.  net10.0-browser was computed.  net10.0-ios was computed.  net10.0-maccatalyst was computed.  net10.0-macos was computed.  net10.0-tvos was computed.  net10.0-windows was computed. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

NuGet packages (1)

Showing the top 1 NuGet packages that depend on Senparc.Xncf.WeixinManager:

Package Downloads
Senparc.Xncf.OpenAI

OpenAI 和 ChatGPT 接口

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last Updated
0.24.14 58 10/5/2026
0.24.13 64 10/4/2026
0.24.8 82 9/18/2026
0.24.7 68 9/16/2026
0.24.6 69 9/15/2026
0.24.5 153 8/29/2026
0.24.4 200 8/23/2026
0.24.4-preview9 123 8/14/2026
0.24.3-preview8 105 8/12/2026
0.24.2-preview7 112 8/8/2026
0.24.1-preview6 117 8/3/2026
0.24.0-preview5 110 7/31/2026
0.23.1-preview4 112 7/28/2026
0.23.0-preview3 105 7/26/2026
0.22.3-preview2 82 7/15/2026
0.22.2-preview1 80 7/3/2026
0.22.1-preview1 101 6/17/2026
0.21.6.1-preview 180 5/9/2026
0.21.2-preview 84 6/16/2026
0.18.1-preview.5 52 9/15/2026
Loading failed

[2026-10-05] v0.24.14 持久化微信 Claw 会话上下文，支持 NeuBell 重启补偿推送并记录去重状态
[2026-10-04] v0.24.13 支持微信 SILK 语音缓存解码和视频播放、Range 请求，修复首屏连接状态加载并移除重复发送面板
[2026-10-03] v0.24.12 修复微信 Claw 下行 JSON 字段大小写、可选响应字段、媒体密钥编码及轮询会话上下文丢失，按官方 2.4.9 协议补充契约和发送链路测试
[2026-10-02] 微信后台轮询复用统一租户作用域，移除反射及重复上下文设置并完善任务取消释放
[2026-10-01] 个人微信后台按租户作用域调用账号服务和现有 Repository 查询，保留统一软删除过滤
v0.1 创世
v0.2 完成公众号管理、用户管理等功能
v0.3 优化UI，匹配新版本NCF
v0.4.1 移植WeixinFace
v0.6.100 支持 .NET 5
v0.6.300 添加 Swagger Api
v0.6.359 添加 FindWeixinApi 接口
v0.6.400 更新基础接口，优化 WebApi
v0.6.500 使用新的 FunctionRender 版本
v0.7.0 支持 PostgreSQL
v0.8.0 中间件添加 MpAccountDto 参数
v0.9.0 优化多租户机制，解决添加新帐号后需要重启才能使用中间件的问题
v0.9.2 优化多租户机制，解决中间件启动问题
v0.9.3 解决中间件访问问题
v0.11.0 支持微信 MessageHandler 自定义上下文（MessageContext）
v0.12.0 支持 PromptRange
v0.13.0 支持最新 Senparc.AI
v0.15.0 支持最新 Senparc.AI
v0.16.1 支持基础新架构
v0.16.2 更新基础库
[2024-09-13] v0.16.4-preview1 升级基础库
[2024-10-09] v0.16.5-preview1 升级基础库
[2024-12-07] v0.16.6-preview1 更新基础库
[2025-01-10] v0.17.0-preview1 添加达梦（DM）和 Oracle 数据库支持
[2025-05-29] v0.18.0-preview.1 升级基础库
[2025-07-12] v0.18.1-preview.3 fix: SqlServerDatabaseConfiguration 命名统一
[2025-07-12] v0.19.0-preview.1 migratie Senparc.Xncf.WeixinManager to NcfPackageResource repository
[2025-07-13] v0.20.0-preview.1 upgrade MpAccount loading progress in UseXncfModule
[2025-07-13] v0.20.1-preview.1 upgrade MpAccount loading progress in UseXncfModule
[2025-07-26] v0.20.2-preview.1 update Weixin(WeChat) API search function
[2025-08-18] v0.21.0-preview.1 feat: support for McpRouter of Weixin
[2025-08-19] v0.21.1-preview.1 fix: Set ApiBind DefaultRequestMethod to GET
[2026-03-24] v0.21.5-preview.1 update Senparc.AI.Kernel to v0.28.0 and Senparc.Weixin.MP to v16.24.2
[2025-11-01] update basic libraries, including Senparc.AI
[2026-07-02] v0.22.2-preview1 支持流式输出并优化交互体验，新增 PromptRange 与 AgentsManager 使用记录能力
1、支持流式输出并优化交互体验
2、新增 PromptRange 与 AgentsManager 使用记录能力
[2026-07-07] v0.22.3-preview2 Dependency updates from upstream modules
1、Dependency update from Senparc.Xncf.PromptRange to 0.16.5-preview4
2、升级 Senparc.AI 至 0.27.3、Senparc.AI.AgentKernel 至 0.1.10
[2026-07-17] v0.23.0-preview3 为 WeixinManager 模块接入统一资源本地化并优化功能文案
1、接入统一资源本地化机制，支持模块功能文案按当前文化动态显示
2、统一模块注册信息、菜单名称与功能描述的本地化输出
3、同步管理页面与前端交互文案的多语言显示
4、补充并统一多语言资源键及资源文件
5、调整公众号账号页面链接导航处理，兼容桌面内嵌 WebView
[2026-07-29] v0.23.1-preview4 限制微信管理模块的敏感日志和外部接口暴露
1、详细 API 日志仅在开发环境启用，降低密钥和令牌泄露风险
2、生成 SDK 接口默认禁止外部访问，避免未经授权的公网暴露
[2026-07-31] v0.24.0-preview5 完善 WeixinManager 管理功能多语言并升级兼容依赖
1、补齐公众号账户、用户、异常与 Swagger 交互文案的多语言资源
2、修复账户保存提示乱码并保留英文回退文案
3、升级 Senparc.AI 组件、CO2NET WebApi 2.1.9-preview 与 TenPay 1.20.0
[2026-08-04] v0.24.1-preview6 统一微信模块多数据库设计时配置
1、为 Dm、MySql、Oracle、PostgreSQL、SqlServer 与 Sqlite 统一设计时 DbContext 配置
[2026-08-08] v0.24.2-preview7 Dependency updates from upstream projects
1、Dependency update from Senparc.Ncf.AreaBase to 0.23.2-preview6
2、Dependency update from Senparc.Ncf.Core to 0.28.1-preview6
3、Dependency update from Senparc.Ncf.Database.PostgreSQL to 0.13.6-preview6
4、Dependency update from Senparc.Ncf.Database.Sqlite to 0.20.6-preview6
5、Dependency update from Senparc.Ncf.Database to 0.21.6-preview6
6、Dependency update from Senparc.Ncf.Mvc.UI to 0.22.2-preview6
7、Dependency update from Senparc.Ncf.Repository to 0.20.6-preview6
8、Dependency update from Senparc.Ncf.Service to 0.23.6-preview6
9、Dependency update from Senparc.Ncf.XncfBase to 0.24.1-preview6
10、Dependency update from Senparc.Xncf.PromptRange to 0.19.1-preview9
[2026-08-13] v0.24.3-preview8 Dependency update from Senparc.Ncf.AreaBase to 0.23.3-preview7; Senparc.Ncf.Core to 0.28.2-preview7; Senparc.Ncf.XncfBase to 0.25.0-preview7; Senparc.Xncf.PromptRange to 0.19.2-preview10; Senparc.Xncf.Swagger to 0.20.3-preview7
[2026-08-15] v0.24.4 Dependency update from Senparc.Ncf.Core to 0.29.0-preview8
1、Dependency update from Senparc.Xncf.PromptRange to 0.19.3
2、补充本地数据库配置文件并同步当前基础服务与 AgentsManager 依赖版本
[2026-08-29] v0.24.5 Dependency updates from Senparc.Ncf.Core to 0.30.0-preview9
1、Dependency update from Senparc.Ncf.Core to 0.30.0-preview9
[2026-09-15] v0.24.6 适配共享 AI 依赖与 Harness 版本
1、同步 AgentKernel 及 Microsoft Agents AI Harness 依赖
2、保持微信管理模块宿主集成兼容
[2026-09-16] v0.24.7 升级微信相关组件至当前兼容版本
1、同步 Senparc.Weixin.AspNet、MP、Open、TenPay、Work 与 WxOpen 等组件版本
2、保持微信管理模块在当前 .NET 10 宿主中的运行兼容
[2026-09-17] v0.24.8 适配共享 AgentKernel 预览依赖版本
1、同步 Senparc.AI.AgentKernel 至 0.1.14-preview5
2、保持微信管理模块宿主集成兼容
[2026-10-01] v0.24.9 接入 FileManager 私有附件导入
1、Weixin Bot 收到媒体文件后通过 Abstractions EventBus 请求保存到 FileManager
2、修复后台轮询在多租户模式下的账号发现和租户上下文传播