Senparc.Xncf.WeixinManager 0.25.1

Prefix Reserved
dotnet add package Senparc.Xncf.WeixinManager --version 0.25.1
                    
NuGet\Install-Package Senparc.Xncf.WeixinManager -Version 0.25.1
                    
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.25.1" />
                    
For projects that support PackageReference, copy this XML node into the project file to reference the package.
<PackageVersion Include="Senparc.Xncf.WeixinManager" Version="0.25.1" />
                    
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.25.1
                    
#r "nuget: Senparc.Xncf.WeixinManager, 0.25.1"
                    
#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.25.1
                    
#: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.25.1
                    
Install as a Cake Addin
#tool nuget:?package=Senparc.Xncf.WeixinManager&version=0.25.1
                    
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.25.1 0 11/19/2026
0.25.0 95 11/11/2026
0.24.18 63 11/5/2026
0.24.17 75 11/2/2026
0.24.15 74 10/10/2026
0.24.14 95 10/5/2026
0.24.13 93 10/4/2026
0.24.8 101 9/18/2026
0.24.7 85 9/16/2026
0.24.6 93 9/15/2026
0.24.5 169 8/29/2026
0.24.4 239 8/23/2026
0.24.4-preview9 136 8/14/2026
0.24.3-preview8 119 8/12/2026
0.24.2-preview7 125 8/8/2026
0.24.1-preview6 133 8/3/2026
0.24.0-preview5 123 7/31/2026
0.23.1-preview4 122 7/28/2026
0.23.0-preview3 123 7/26/2026
0.18.1-preview.5 71 9/15/2026
Loading failed

[2024-09-13] v0.16.4-preview1 upgrade
       [2024-10-09] v0.16.5-preview1 Updated module behavior and related support.
       [2024-12-07] v0.16.6-preview1 Updated module behavior and related support.
       [2025-01-10] v0.17.0-preview1 Updated module behavior and related support.
       [2025-05-29] v0.18.0-preview.1 Updated module behavior and related support.
       v0.1 initial release
       v0.2 Updated module behavior and related support.
       v0.3 Updated module behavior and related support.
       v0.4.1 Updated module behavior and related support.
       v0.6.100 support .NET 5
       v0.6.300 add Swagger Api
       v0.6.359 add FindWeixinApi interface
       v0.6.400 Updated module behavior and related support.
       v0.6.500 Updated module behavior and related support.
       v0.7.0 support PostgreSQL
       v0.8.0 Updated module behavior and related support.
       v0.9.0 Updated module behavior and related support.
       v0.9.2 Updated module behavior and related support.
       v0.9.3 Updated module behavior and related support.
       v0.11.0 Updated module behavior and related support.
       v0.12.0 support PromptRange
       v0.13.0 Updated module behavior and related support.
       v0.15.0 Updated module behavior and related support.
       v0.16.1 Updated module behavior and related support.
       v0.16.2 Updated module behavior and related support.
       [2025-07-12] v0.18.1-preview.3 Updated module behavior and related support.
       [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
       [2025-11-01] update basic libraries, including Senparc.AI
       [2026-03-24] v0.21.5-preview.1 update Senparc.AI.Kernel to v0.28.0 and Senparc.Weixin.MP to v16.24.2
       [2026-07-02] v0.22.2-preview1 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       [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. Updated module behavior and related support.
       [2026-07-17] v0.23.0-preview3 Updated module behavior and related support.
       1. integrateshared resource-localization mechanism, supportmodulefeature textdisplay dynamically according to the current culture
       2. Updated module behavior and related support.
       3. Updated module behavior and related support.
       4. Updated module behavior and related support.
       5. Updated module behavior and related support.
       [2026-07-29] v0.23.1-preview4 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       [2026-07-31] v0.24.0-preview5 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       3. Updated module behavior and related support.
       [2026-08-04] v0.24.1-preview6 Updated module behavior and related support.
       1. Updated module behavior and related support.
       [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. Updated module behavior and related support.
       [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 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       [2026-09-16] v0.24.7 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       [2026-09-17] v0.24.8 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       [2026-09-26] v0.24.9 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       3. Updated module behavior and related support.
       4. Updated module behavior and related support.
       [2026-10-01] invocationaccountservice Repository , unifydelete
       [2026-10-01] v0.24.9 integrate FileManager privateattachmentimport
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       [2026-10-02] unify, improvetaskcancel
       [2026-10-03] v0.24.12 Updated module behavior and related support.
       [2026-10-04] v0.24.13 Updated module behavior and related support.
       [2026-10-05] v0.24.14 Updated module behavior and related support.
       [2026-10-09] v0.24.15 Dependency update from Senparc.Xncf.PromptRange to 0.19.8
       [2026-11-03] v0.24.16 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. adapt Senparc.AI.AgentKernel 0.1.15-preview2
       3. Updated module behavior and related support.
       4. Updated module behavior and related support.
       5. Dependency update from Senparc.Ncf.Database.PostgreSQL to 0.13.11
       6. Dependency update from Senparc.Ncf.Database.Sqlite to 0.20.11
       7. Dependency update from Senparc.Ncf.Database to 0.21.11
       8. Dependency update from Senparc.Ncf.Mvc.UI to 0.22.6-preview10
       [2026-11-03] Add shared documentation help to the official-account edit form.
       [2026-11-03] v0.24.18 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Dependency update from Senparc.Ncf.AreaBase to 0.23.10
       3. Dependency update from Senparc.Ncf.Core to 0.30.4-preview10
       4. Dependency update from Senparc.Ncf.Database.PostgreSQL to 0.13.12
       5. Dependency update from Senparc.Ncf.Database.Sqlite to 0.20.12
       6. Dependency update from Senparc.Ncf.Database to 0.21.12
       7. Dependency update from Senparc.Ncf.Mvc.UI to 0.22.7-preview11
       8. Dependency update from Senparc.Ncf.Repository to 0.20.11-preview10
       9. Dependency update from Senparc.Ncf.Service to 0.23.11-preview10
       10. Dependency update from Senparc.Ncf.XncfBase to 0.28.2
       11. Dependency update from Senparc.Xncf.PromptRange to 0.20.14
       12. Dependency update from Senparc.Xncf.Swagger to 0.20.10
       [2026-11-11] v0.24.18 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       3. Updated module behavior and related support.
       4. Updated module behavior and related support.
       [2026-11-12] v0.25.0 Updated module behavior and related support.
       1. Updated module behavior and related support.
       2. Updated module behavior and related support.
       [2026-11-19] v0.25.1 Localized Weixin account and administration surfaces
       1. Updated localized labels, resource fallbacks, and user-facing messages across affected surfaces.
       2. Kept runtime behavior and module integration aligned with the affected service and registration changes.