commit 221951261bc3e5d71d02be917f8b3066ceef8431
Author: starry <115192496+sky22333@users.noreply.github.com>
Date: Tue Mar 17 13:22:56 2026 +0000
add
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..a3478c6
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,3 @@
+*.toml
+*.exe
+/data/
diff --git a/LICENSE b/LICENSE
new file mode 100644
index 0000000..f288702
--- /dev/null
+++ b/LICENSE
@@ -0,0 +1,674 @@
+ GNU GENERAL PUBLIC LICENSE
+ Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc.
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ Preamble
+
+ The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+ The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works. By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users. We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors. You can apply it to
+your programs, too.
+
+ When we speak of free software, we are referring to freedom, not
+price. Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+ To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights. Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+ For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received. You must make sure that they, too, receive
+or can get the source code. And you must show them these terms so they
+know their rights.
+
+ Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+ For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software. For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+ Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so. This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software. The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable. Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products. If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+ Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary. To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+ The precise terms and conditions for copying, distribution and
+modification follow.
+
+ TERMS AND CONDITIONS
+
+ 0. Definitions.
+
+ "This License" refers to version 3 of the GNU General Public License.
+
+ "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+ "The Program" refers to any copyrightable work licensed under this
+License. Each licensee is addressed as "you". "Licensees" and
+"recipients" may be individuals or organizations.
+
+ To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy. The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+ A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+ To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy. Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+ To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies. Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+ An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License. If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+ 1. Source Code.
+
+ The "source code" for a work means the preferred form of the work
+for making modifications to it. "Object code" means any non-source
+form of a work.
+
+ A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+ The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form. A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+ The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities. However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work. For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+ The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+ The Corresponding Source for a work in source code form is that
+same work.
+
+ 2. Basic Permissions.
+
+ All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met. This License explicitly affirms your unlimited
+permission to run the unmodified Program. The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work. This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+ You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force. You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright. Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+ Conveying under any other circumstances is permitted solely under
+the conditions stated below. Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+ 3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+ No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+ When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+ 4. Conveying Verbatim Copies.
+
+ You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+ You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+ 5. Conveying Modified Source Versions.
+
+ You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+ a) The work must carry prominent notices stating that you modified
+ it, and giving a relevant date.
+
+ b) The work must carry prominent notices stating that it is
+ released under this License and any conditions added under section
+ 7. This requirement modifies the requirement in section 4 to
+ "keep intact all notices".
+
+ c) You must license the entire work, as a whole, under this
+ License to anyone who comes into possession of a copy. This
+ License will therefore apply, along with any applicable section 7
+ additional terms, to the whole of the work, and all its parts,
+ regardless of how they are packaged. This License gives no
+ permission to license the work in any other way, but it does not
+ invalidate such permission if you have separately received it.
+
+ d) If the work has interactive user interfaces, each must display
+ Appropriate Legal Notices; however, if the Program has interactive
+ interfaces that do not display Appropriate Legal Notices, your
+ work need not make them do so.
+
+ A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit. Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+ 6. Conveying Non-Source Forms.
+
+ You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+ a) Convey the object code in, or embodied in, a physical product
+ (including a physical distribution medium), accompanied by the
+ Corresponding Source fixed on a durable physical medium
+ customarily used for software interchange.
+
+ b) Convey the object code in, or embodied in, a physical product
+ (including a physical distribution medium), accompanied by a
+ written offer, valid for at least three years and valid for as
+ long as you offer spare parts or customer support for that product
+ model, to give anyone who possesses the object code either (1) a
+ copy of the Corresponding Source for all the software in the
+ product that is covered by this License, on a durable physical
+ medium customarily used for software interchange, for a price no
+ more than your reasonable cost of physically performing this
+ conveying of source, or (2) access to copy the
+ Corresponding Source from a network server at no charge.
+
+ c) Convey individual copies of the object code with a copy of the
+ written offer to provide the Corresponding Source. This
+ alternative is allowed only occasionally and noncommercially, and
+ only if you received the object code with such an offer, in accord
+ with subsection 6b.
+
+ d) Convey the object code by offering access from a designated
+ place (gratis or for a charge), and offer equivalent access to the
+ Corresponding Source in the same way through the same place at no
+ further charge. You need not require recipients to copy the
+ Corresponding Source along with the object code. If the place to
+ copy the object code is a network server, the Corresponding Source
+ may be on a different server (operated by you or a third party)
+ that supports equivalent copying facilities, provided you maintain
+ clear directions next to the object code saying where to find the
+ Corresponding Source. Regardless of what server hosts the
+ Corresponding Source, you remain obligated to ensure that it is
+ available for as long as needed to satisfy these requirements.
+
+ e) Convey the object code using peer-to-peer transmission, provided
+ you inform other peers where the object code and Corresponding
+ Source of the work are being offered to the general public at no
+ charge under subsection 6d.
+
+ A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+ A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling. In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage. For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product. A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+ "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source. The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+ If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information. But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+ The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed. Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+ Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+ 7. Additional Terms.
+
+ "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law. If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+ When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it. (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.) You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+ Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+ a) Disclaiming warranty or limiting liability differently from the
+ terms of sections 15 and 16 of this License; or
+
+ b) Requiring preservation of specified reasonable legal notices or
+ author attributions in that material or in the Appropriate Legal
+ Notices displayed by works containing it; or
+
+ c) Prohibiting misrepresentation of the origin of that material, or
+ requiring that modified versions of such material be marked in
+ reasonable ways as different from the original version; or
+
+ d) Limiting the use for publicity purposes of names of licensors or
+ authors of the material; or
+
+ e) Declining to grant rights under trademark law for use of some
+ trade names, trademarks, or service marks; or
+
+ f) Requiring indemnification of licensors and authors of that
+ material by anyone who conveys the material (or modified versions of
+ it) with contractual assumptions of liability to the recipient, for
+ any liability that these contractual assumptions directly impose on
+ those licensors and authors.
+
+ All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10. If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term. If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+ If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+ Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+ 8. Termination.
+
+ You may not propagate or modify a covered work except as expressly
+provided under this License. Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+ However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+ Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+ Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License. If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+ 9. Acceptance Not Required for Having Copies.
+
+ You are not required to accept this License in order to receive or
+run a copy of the Program. Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance. However,
+nothing other than this License grants you permission to propagate or
+modify any covered work. These actions infringe copyright if you do
+not accept this License. Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+ 10. Automatic Licensing of Downstream Recipients.
+
+ Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License. You are not responsible
+for enforcing compliance by third parties with this License.
+
+ An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations. If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+ You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License. For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+ 11. Patents.
+
+ A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based. The
+work thus licensed is called the contributor's "contributor version".
+
+ A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version. For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+ Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+ In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement). To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+ If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients. "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+ If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+ A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License. You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+ Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+ 12. No Surrender of Others' Freedom.
+
+ If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License. If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all. For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+ 13. Use with the GNU Affero General Public License.
+
+ Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work. The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+ 14. Revised Versions of this License.
+
+ The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time. Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+ Each version is given a distinguishing version number. If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation. If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+ If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+ Later license versions may give you additional or different
+permissions. However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+ 15. Disclaimer of Warranty.
+
+ THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+ 16. Limitation of Liability.
+
+ IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+ 17. Interpretation of Sections 15 and 16.
+
+ If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+ END OF TERMS AND CONDITIONS
+
+ How to Apply These Terms to Your New Programs
+
+ If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+ To do so, attach the following notices to the program. It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+
+ Copyright (C)
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License
+ along with this program. If not, see .
+
+Also add information on how to contact you by electronic and paper mail.
+
+ If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+ Copyright (C)
+ This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+ This is free software, and you are welcome to redistribute it
+ under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License. Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+ You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+.
+
+ The GNU General Public License does not permit incorporating your program
+into proprietary programs. If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library. If this is what you want to do, use the GNU Lesser General
+Public License instead of this License. But first, please read
+.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..c49ba87
--- /dev/null
+++ b/README.md
@@ -0,0 +1,140 @@
+# qqbot
+
+轻量级 QQ 通知机器人（单账户），支持 HTTP 服务与 Go SDK 两种使用方式。
+
+## 1. 快速开始
+
+- Go 1.26+
+- 已开通 QQ 机器人并拿到 `app_id`、`client_secret`
+- 开通地址：https://q.qq.com/qqbot/openclaw/login.html
+
+编辑 `configs/config.toml`：
+
+```toml
+[qqbot]
+app_id = "你的AppID"
+client_secret = "你的ClientSecret"
+token_url = "https://bots.qq.com/app/getAppAccessToken"
+api_base = "https://api.sgroup.qq.com"
+request_timeout = "10s"
+markdown = false
+
+[server]
+listen_addr = ":8080"
+api_token = "强密码token"
+```
+
+## 2. HTTP 调用方式
+
+除健康检查外，业务接口都需要鉴权：
+
+```http
+Authorization: Bearer 你的api_token
+Content-Type: application/json
+```
+
+### 2.1 同步发送 `POST /api/v1/messages/send`
+
+```json
+{
+ "target_type": "c2c",
+ "content": "这是一条通知"
+}
+```
+
+`target_id` 可选；不传时自动使用最近采集目标。
+`target_type` 也可选；不传时自动使用最近采集目标的类型与 ID。
+
+### 2.2 异步入队 `POST /api/v1/messages`
+
+```json
+{
+ "target_type": "group",
+ "content": "这是一条群通知"
+}
+```
+
+`target_id` 可选；不传时自动使用最近采集目标。
+
+### 2.3 查询状态 `GET /api/v1/messages/{request_id}`
+
+### 2.4 查询目标 `GET /api/v1/targets`
+
+可选参数：`target_type=c2c|group|channel`
+
+### 2.5 健康检查（无需鉴权）
+
+- `GET /healthz`
+- `GET /readyz`
+
+## 3. SDK 调用方式
+
+```go
+package main
+
+import (
+ "context"
+ "log"
+ "time"
+
+ "github.com/sky22333/qqbot"
+)
+
+func main() {
+ client, err := qqbot.NewFromConfigFile("configs/config.toml")
+ if err != nil {
+ log.Fatal(err)
+ }
+ defer client.Close()
+
+ ctx, cancel := context.WithTimeout(context.Background(), 20*time.Second)
+ defer cancel()
+
+ _, err = client.Send(ctx, qqbot.PushRequest{
+ TargetType: qqbot.TargetC2C,
+ Content: "SDK通知消息",
+ })
+ if err != nil {
+ log.Fatal(err)
+ }
+}
+```
+
+## 4. 目标采集
+
+启动服务后，用自己的 QQ 给机器人发消息，系统会自动采集目标并写入 `data/known_targets.json`。
+可通过 `GET /api/v1/targets` 查看。
+
+## 5. 常用命令
+
+```bash
+# 运行测试
+go test ./...
+
+# 静态检查
+go vet ./...
+
+# 直接运行
+go run ./cmd/qqbotd -config configs/config.toml
+
+# 构建
+go build ./cmd/qqbotd
+
+# 生产环境构建
+go build -trimpath -ldflags "-s -w -buildid=" -o qqbotd ./cmd/qqbotd
+```
+
+## 推送测试
+```
+# 异步推送
+curl -X POST "http://127.0.0.1:8080/api/v1/messages" \
+ -H "Authorization: Bearer 接口鉴权token" \
+ -H "Content-Type: application/json; charset=utf-8" \
+ -d '{"content":"这是一条异步推送测试"}'
+
+# 同步推送
+curl -X POST "http://127.0.0.1:8080/api/v1/messages/send" \
+ -H "Authorization: Bearer 接口鉴权token" \
+ -H "Content-Type: application/json; charset=utf-8" \
+ -d '{"content":"这是一条同步推送测试"}'
+```
\ No newline at end of file
diff --git a/cmd/qqbotd/main.go b/cmd/qqbotd/main.go
new file mode 100644
index 0000000..f139910
--- /dev/null
+++ b/cmd/qqbotd/main.go
@@ -0,0 +1,90 @@
+package main
+
+import (
+ "context"
+ "flag"
+ "log/slog"
+ "net/http"
+ "os"
+ "os/signal"
+ "syscall"
+
+ "github.com/sky22333/qqbot/config"
+ "github.com/sky22333/qqbot/internal/collector"
+ "github.com/sky22333/qqbot/internal/httpserver"
+ "github.com/sky22333/qqbot/internal/notifier"
+ "github.com/sky22333/qqbot/internal/targets"
+)
+
+func main() {
+ configPath := flag.String("config", "configs/config.toml", "配置文件路径")
+ flag.Parse()
+
+ cfg, err := config.Load(*configPath)
+ if err != nil {
+ panic(err)
+ }
+
+ logLevel := slog.LevelInfo
+ if cfg.App.LogLevel == "debug" {
+ logLevel = slog.LevelDebug
+ }
+ logger := slog.New(slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{Level: logLevel}))
+
+ flushInterval, err := cfg.TargetsFlushInterval()
+ if err != nil {
+ panic(err)
+ }
+ targetStore, err := targets.NewStore(cfg.Targets.FilePath, cfg.Targets.MaxRecords, flushInterval)
+ if err != nil {
+ panic(err)
+ }
+
+ targetCollector, err := collector.New(cfg, logger, targetStore)
+ if err != nil {
+ panic(err)
+ }
+
+ targetCollector.Start()
+ logger.Info("采集器已启动")
+
+ n, err := notifier.New(cfg, logger)
+ if err != nil {
+ panic(err)
+ }
+ n.SetTargetStore(targetStore)
+
+ server, err := httpserver.New(cfg, logger, n, targetStore)
+ if err != nil {
+ panic(err)
+ }
+
+ errCh := make(chan error, 1)
+ go func() {
+ errCh <- server.Start()
+ }()
+
+ stopCh := make(chan os.Signal, 1)
+ signal.Notify(stopCh, syscall.SIGTERM, syscall.SIGINT)
+
+ select {
+ case sig := <-stopCh:
+ logger.Info("收到退出信号，停止程序", "signal", sig.String())
+ case err := <-errCh:
+ if err != nil && err != http.ErrServerClosed {
+ logger.Error("服务异常退出", "error", err)
+ }
+ }
+
+ shutdownTimeout, err := cfg.ShutdownTimeout()
+ if err != nil {
+ shutdownTimeout = 10
+ }
+ ctx, cancel := context.WithTimeout(context.Background(), shutdownTimeout)
+ defer cancel()
+ _ = server.Shutdown(ctx)
+ targetCollector.Stop()
+ n.Close()
+ _ = targetStore.Close()
+ logger.Info("服务已退出")
+}
diff --git a/config/config.go b/config/config.go
new file mode 100644
index 0000000..2c24c11
--- /dev/null
+++ b/config/config.go
@@ -0,0 +1,201 @@
+package config
+
+import (
+ "errors"
+ "fmt"
+ "strings"
+ "time"
+
+ "github.com/BurntSushi/toml"
+)
+
+type Config struct {
+ App AppConfig `toml:"app"`
+ QQBot QQBotConfig `toml:"qqbot"`
+ Server ServerConfig `toml:"server"`
+ Dispatch DispatchConfig `toml:"dispatch"`
+ Runtime RuntimeConfig `toml:"runtime"`
+ Collector CollectorConfig `toml:"collector"`
+ Targets TargetsConfig `toml:"targets"`
+}
+
+type AppConfig struct {
+ LogLevel string `toml:"log_level"`
+}
+
+type QQBotConfig struct {
+ AppID string `toml:"app_id"`
+ ClientSecret string `toml:"client_secret"`
+ TokenURL string `toml:"token_url"`
+ APIBase string `toml:"api_base"`
+ RequestTimout string `toml:"request_timeout"`
+ Markdown bool `toml:"markdown"`
+}
+
+type ServerConfig struct {
+ ListenAddr string `toml:"listen_addr"`
+ APIToken string `toml:"api_token"`
+ ReadTimeout string `toml:"read_timeout"`
+ WriteTimeout string `toml:"write_timeout"`
+ ShutdownTimeout string `toml:"shutdown_timeout"`
+ MaxBodyBytes int64 `toml:"max_body_bytes"`
+}
+
+type DispatchConfig struct {
+ QueueSize int `toml:"queue_size"`
+ Workers int `toml:"workers"`
+ RetryMax int `toml:"retry_max"`
+ RetryBackoffMS int `toml:"retry_backoff_ms"`
+ EnqueueTimeout string `toml:"enqueue_timeout"`
+}
+
+type RuntimeConfig struct {
+ StatusTTLSeconds int `toml:"status_ttl_seconds"`
+ IdempotencyTTLSeconds int `toml:"idempotency_ttl_seconds"`
+ CleanupIntervalSec int `toml:"cleanup_interval_seconds"`
+}
+
+type CollectorConfig struct {
+ ReconnectDelay string `toml:"reconnect_delay"`
+}
+
+type TargetsConfig struct {
+ FilePath string `toml:"file_path"`
+ MaxRecords int `toml:"max_records"`
+ FlushInterval string `toml:"flush_interval"`
+}
+
+func Default() Config {
+ return Config{
+ App: AppConfig{
+ LogLevel: "info",
+ },
+ QQBot: QQBotConfig{
+ TokenURL: "https://bots.qq.com/app/getAppAccessToken",
+ APIBase: "https://api.sgroup.qq.com",
+ RequestTimout: "10s",
+ Markdown: false,
+ },
+ Server: ServerConfig{
+ ListenAddr: ":8080",
+ ReadTimeout: "10s",
+ WriteTimeout: "15s",
+ ShutdownTimeout: "10s",
+ MaxBodyBytes: 1 << 20,
+ },
+ Dispatch: DispatchConfig{
+ QueueSize: 2048,
+ Workers: 8,
+ RetryMax: 3,
+ RetryBackoffMS: 200,
+ EnqueueTimeout: "3s",
+ },
+ Runtime: RuntimeConfig{
+ StatusTTLSeconds: 86400,
+ IdempotencyTTLSeconds: 3600,
+ CleanupIntervalSec: 60,
+ },
+ Collector: CollectorConfig{
+ ReconnectDelay: "3s",
+ },
+ Targets: TargetsConfig{
+ FilePath: "data/targets.json",
+ MaxRecords: 1000,
+ FlushInterval: "2s",
+ },
+ }
+}
+
+func Load(path string) (Config, error) {
+ cfg := Default()
+ if _, err := toml.DecodeFile(path, &cfg); err != nil {
+ return Config{}, err
+ }
+ if err := cfg.Validate(); err != nil {
+ return Config{}, err
+ }
+ return cfg, nil
+}
+
+func (c Config) Validate() error {
+ if strings.TrimSpace(c.QQBot.AppID) == "" {
+ return errors.New("qqbot.app_id 不能为空")
+ }
+ if strings.TrimSpace(c.QQBot.ClientSecret) == "" {
+ return errors.New("qqbot.client_secret 不能为空")
+ }
+ if strings.TrimSpace(c.Server.ListenAddr) == "" {
+ return errors.New("server.listen_addr 不能为空")
+ }
+ if c.Dispatch.QueueSize <= 0 {
+ return errors.New("dispatch.queue_size 必须大于 0")
+ }
+ if c.Dispatch.Workers <= 0 {
+ return errors.New("dispatch.workers 必须大于 0")
+ }
+ if c.Dispatch.RetryMax < 0 {
+ return errors.New("dispatch.retry_max 不能小于 0")
+ }
+ if c.Dispatch.RetryBackoffMS <= 0 {
+ return errors.New("dispatch.retry_backoff_ms 必须大于 0")
+ }
+ if c.Server.MaxBodyBytes <= 0 {
+ return errors.New("server.max_body_bytes 必须大于 0")
+ }
+ if _, err := c.RequestTimeout(); err != nil {
+ return fmt.Errorf("qqbot.request_timeout 无效: %w", err)
+ }
+ if _, err := c.ReadTimeout(); err != nil {
+ return fmt.Errorf("server.read_timeout 无效: %w", err)
+ }
+ if _, err := c.WriteTimeout(); err != nil {
+ return fmt.Errorf("server.write_timeout 无效: %w", err)
+ }
+ if _, err := c.ShutdownTimeout(); err != nil {
+ return fmt.Errorf("server.shutdown_timeout 无效: %w", err)
+ }
+ if _, err := c.EnqueueTimeout(); err != nil {
+ return fmt.Errorf("dispatch.enqueue_timeout 无效: %w", err)
+ }
+ if _, err := c.CollectorReconnectDelay(); err != nil {
+ return fmt.Errorf("collector.reconnect_delay 无效: %w", err)
+ }
+ if strings.TrimSpace(c.Targets.FilePath) == "" {
+ return errors.New("targets.file_path 不能为空")
+ }
+ if c.Targets.MaxRecords <= 0 {
+ return errors.New("targets.max_records 必须大于 0")
+ }
+ if _, err := c.TargetsFlushInterval(); err != nil {
+ return fmt.Errorf("targets.flush_interval 无效: %w", err)
+ }
+ return nil
+}
+
+func (c Config) RequestTimeout() (time.Duration, error) {
+ return time.ParseDuration(c.QQBot.RequestTimout)
+}
+
+func (c Config) ReadTimeout() (time.Duration, error) {
+ return time.ParseDuration(c.Server.ReadTimeout)
+}
+
+func (c Config) WriteTimeout() (time.Duration, error) {
+ return time.ParseDuration(c.Server.WriteTimeout)
+}
+
+func (c Config) ShutdownTimeout() (time.Duration, error) {
+ return time.ParseDuration(c.Server.ShutdownTimeout)
+}
+
+func (c Config) EnqueueTimeout() (time.Duration, error) {
+ return time.ParseDuration(c.Dispatch.EnqueueTimeout)
+}
+
+func (c Config) CollectorReconnectDelay() (time.Duration, error) {
+ return time.ParseDuration(c.Collector.ReconnectDelay)
+}
+
+func (c Config) TargetsFlushInterval() (time.Duration, error) {
+ return time.ParseDuration(c.Targets.FlushInterval)
+}
diff --git a/config_loader.go b/config_loader.go
new file mode 100644
index 0000000..cac7227
--- /dev/null
+++ b/config_loader.go
@@ -0,0 +1,11 @@
+package qqbot
+
+import "github.com/sky22333/qqbot/config"
+
+func LoadConfig(path string) (Config, error) {
+ return config.Load(path)
+}
+
+func DefaultConfig() Config {
+ return config.Default()
+}
diff --git a/go.mod b/go.mod
new file mode 100644
index 0000000..cd4e145
--- /dev/null
+++ b/go.mod
@@ -0,0 +1,8 @@
+module github.com/sky22333/qqbot
+
+go 1.26.1
+
+require (
+ github.com/BurntSushi/toml v1.6.0
+ github.com/gorilla/websocket v1.5.3
+)
diff --git a/go.sum b/go.sum
new file mode 100644
index 0000000..40ae17b
--- /dev/null
+++ b/go.sum
@@ -0,0 +1,4 @@
+github.com/BurntSushi/toml v1.6.0 h1:dRaEfpa2VI55EwlIW72hMRHdWouJeRF7TPYhI+AUQjk=
+github.com/BurntSushi/toml v1.6.0/go.mod h1:ukJfTF/6rtPPRCnwkur4qwRxa8vTRFBF0uk2lLoLwho=
+github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aNNg=
+github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
diff --git a/internal/collector/collector.go b/internal/collector/collector.go
new file mode 100644
index 0000000..1c72134
--- /dev/null
+++ b/internal/collector/collector.go
@@ -0,0 +1,255 @@
+package collector
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "log/slog"
+ "strings"
+ "sync"
+ "sync/atomic"
+ "time"
+
+ "github.com/gorilla/websocket"
+ "github.com/sky22333/qqbot/config"
+ "github.com/sky22333/qqbot/internal/qqapi"
+ "github.com/sky22333/qqbot/internal/targets"
+ "github.com/sky22333/qqbot/message"
+)
+
+const (
+ intentPublicGuildMessages = 1 << 30
+ intentDirectMessage = 1 << 12
+ intentGroupAndC2C = 1 << 25
+ intentGuildMembers = 1 << 1
+)
+
+var intentLevels = []int{
+ intentPublicGuildMessages | intentDirectMessage | intentGroupAndC2C,
+ intentPublicGuildMessages | intentGroupAndC2C,
+ intentPublicGuildMessages | intentGuildMembers,
+}
+
+type wsPayload struct {
+ Op int `json:"op"`
+ D json.RawMessage `json:"d"`
+ S *int64 `json:"s,omitempty"`
+ T string `json:"t,omitempty"`
+}
+
+type helloData struct {
+ HeartbeatInterval int64 `json:"heartbeat_interval"`
+}
+
+type c2cMessageEvent struct {
+ ID string `json:"id"`
+ Content string `json:"content"`
+ Author struct {
+ UserOpenID string `json:"user_openid"`
+ } `json:"author"`
+}
+
+type groupMessageEvent struct {
+ ID string `json:"id"`
+ Content string `json:"content"`
+ GroupOpenID string `json:"group_openid"`
+}
+
+type Collector struct {
+ cfg config.Config
+ logger *slog.Logger
+ client *qqapi.Client
+ store *targets.Store
+
+ ctx context.Context
+ cancel context.CancelFunc
+ wg sync.WaitGroup
+}
+
+func New(cfg config.Config, logger *slog.Logger, store *targets.Store) (*Collector, error) {
+ client, err := qqapi.NewClient(cfg)
+ if err != nil {
+ return nil, err
+ }
+ if logger == nil {
+ logger = slog.Default()
+ }
+ ctx, cancel := context.WithCancel(context.Background())
+ return &Collector{
+ cfg: cfg,
+ logger: logger,
+ client: client,
+ store: store,
+ ctx: ctx,
+ cancel: cancel,
+ }, nil
+}
+
+func (c *Collector) Start() {
+ c.wg.Add(1)
+ go func() {
+ defer c.wg.Done()
+ c.runLoop()
+ }()
+}
+
+func (c *Collector) Stop() {
+ c.cancel()
+ c.wg.Wait()
+}
+
+func (c *Collector) runLoop() {
+ reconnectDelay, _ := c.cfg.CollectorReconnectDelay()
+ if reconnectDelay <= 0 {
+ reconnectDelay = 3 * time.Second
+ }
+ for {
+ select {
+ case <-c.ctx.Done():
+ return
+ default:
+ }
+ if err := c.runOnce(); err != nil {
+ if c.ctx.Err() != nil {
+ return
+ }
+ c.logger.Error("collector 连接中断", "error", err)
+ }
+ timer := time.NewTimer(reconnectDelay)
+ select {
+ case <-c.ctx.Done():
+ timer.Stop()
+ return
+ case <-timer.C:
+ }
+ }
+}
+
+func (c *Collector) runOnce() error {
+ token, err := c.client.AccessToken(c.ctx)
+ if err != nil {
+ return err
+ }
+ gatewayURL, err := c.client.GatewayURL(c.ctx)
+ if err != nil {
+ return err
+ }
+ conn, _, err := websocket.DefaultDialer.DialContext(c.ctx, gatewayURL, nil)
+ if err != nil {
+ return err
+ }
+ defer conn.Close()
+ stopClose := make(chan struct{})
+ go func() {
+ select {
+ case <-c.ctx.Done():
+ _ = conn.Close()
+ case <-stopClose:
+ }
+ }()
+ defer close(stopClose)
+ c.logger.Info("collector 已连接 gateway")
+
+ var lastSeq atomic.Int64
+ intentIndex := 0
+ heartbeatStop := make(chan struct{})
+ defer close(heartbeatStop)
+
+ for {
+ select {
+ case <-c.ctx.Done():
+ return nil
+ default:
+ }
+
+ _, data, err := conn.ReadMessage()
+ if err != nil {
+ return err
+ }
+ payload := wsPayload{}
+ if err := json.Unmarshal(data, &payload); err != nil {
+ continue
+ }
+ if payload.S != nil {
+ lastSeq.Store(*payload.S)
+ }
+
+ switch payload.Op {
+ case 10:
+ hello := helloData{}
+ if err := json.Unmarshal(payload.D, &hello); err == nil && hello.HeartbeatInterval > 0 {
+ go startHeartbeat(c.ctx, conn, hello.HeartbeatInterval, &lastSeq, heartbeatStop)
+ }
+ if err := sendIdentify(conn, token, intentLevels[intentIndex]); err != nil {
+ return err
+ }
+ case 9:
+ if intentIndex < len(intentLevels)-1 {
+ intentIndex++
+ }
+ if err := sendIdentify(conn, token, intentLevels[intentIndex]); err != nil {
+ return err
+ }
+ case 0:
+ c.handleDispatch(payload.T, payload.D)
+ case 7:
+ return errors.New("gateway 要求重连")
+ }
+ }
+}
+
+func (c *Collector) handleDispatch(eventType string, raw json.RawMessage) {
+ switch strings.TrimSpace(eventType) {
+ case "C2C_MESSAGE_CREATE":
+ event := c2cMessageEvent{}
+ if err := json.Unmarshal(raw, &event); err != nil {
+ return
+ }
+ if event.Author.UserOpenID == "" {
+ return
+ }
+ _ = c.store.Upsert(message.TargetC2C, event.Author.UserOpenID, event.ID, event.Content)
+ c.logger.Info("采集到 c2c 目标", "target_id", event.Author.UserOpenID, "message_id", event.ID)
+ case "GROUP_AT_MESSAGE_CREATE":
+ event := groupMessageEvent{}
+ if err := json.Unmarshal(raw, &event); err != nil {
+ return
+ }
+ if event.GroupOpenID == "" {
+ return
+ }
+ _ = c.store.Upsert(message.TargetGroup, event.GroupOpenID, event.ID, event.Content)
+ c.logger.Info("采集到 group 目标", "target_id", event.GroupOpenID, "message_id", event.ID)
+ }
+}
+
+func startHeartbeat(ctx context.Context, conn *websocket.Conn, intervalMS int64, seq *atomic.Int64, stop <-chan struct{}) {
+ ticker := time.NewTicker(time.Duration(intervalMS) * time.Millisecond)
+ defer ticker.Stop()
+ for {
+ select {
+ case <-ctx.Done():
+ return
+ case <-stop:
+ return
+ case <-ticker.C:
+ payload := map[string]any{
+ "op": 1,
+ "d": seq.Load(),
+ }
+ _ = conn.WriteJSON(payload)
+ }
+ }
+}
+
+func sendIdentify(conn *websocket.Conn, token string, intents int) error {
+ payload := map[string]any{
+ "op": 2,
+ "d": map[string]any{
+ "token": "QQBot " + token,
+ "intents": intents,
+ "shard": []int{0, 1},
+ },
+ }
+ return conn.WriteJSON(payload)
+}
diff --git a/internal/httpserver/server.go b/internal/httpserver/server.go
new file mode 100644
index 0000000..091d434
--- /dev/null
+++ b/internal/httpserver/server.go
@@ -0,0 +1,215 @@
+package httpserver
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "log/slog"
+ "net/http"
+ "strings"
+ "time"
+
+ "github.com/sky22333/qqbot/config"
+ "github.com/sky22333/qqbot/internal/notifier"
+ "github.com/sky22333/qqbot/internal/targets"
+ "github.com/sky22333/qqbot/message"
+)
+
+type Server struct {
+ cfg config.Config
+ logger *slog.Logger
+ notifier *notifier.Notifier
+ targets *targets.Store
+ srv *http.Server
+}
+
+func New(cfg config.Config, logger *slog.Logger, n *notifier.Notifier, t *targets.Store) (*Server, error) {
+ if logger == nil {
+ logger = slog.Default()
+ }
+ readTimeout, err := cfg.ReadTimeout()
+ if err != nil {
+ return nil, err
+ }
+ writeTimeout, err := cfg.WriteTimeout()
+ if err != nil {
+ return nil, err
+ }
+ handler := &Server{
+ cfg: cfg,
+ logger: logger,
+ notifier: n,
+ targets: t,
+ }
+ mux := http.NewServeMux()
+ mux.HandleFunc("/healthz", handler.healthz)
+ mux.HandleFunc("/readyz", handler.readyz)
+ mux.HandleFunc("/api/v1/messages/send", handler.sendSync)
+ mux.HandleFunc("/api/v1/messages", handler.enqueue)
+ mux.HandleFunc("/api/v1/messages/", handler.queryStatus)
+ mux.HandleFunc("/api/v1/targets", handler.listTargets)
+
+ handler.srv = &http.Server{
+ Addr: cfg.Server.ListenAddr,
+ Handler: mux,
+ ReadTimeout: readTimeout,
+ WriteTimeout: writeTimeout,
+ }
+ return handler, nil
+}
+
+func (s *Server) Start() error {
+ s.logger.Info("HTTP 服务启动", "addr", s.cfg.Server.ListenAddr)
+ err := s.srv.ListenAndServe()
+ if errors.Is(err, http.ErrServerClosed) {
+ return nil
+ }
+ return err
+}
+
+func (s *Server) Shutdown(ctx context.Context) error {
+ return s.srv.Shutdown(ctx)
+}
+
+func (s *Server) healthz(w http.ResponseWriter, _ *http.Request) {
+ writeJSON(w, http.StatusOK, map[string]any{"ok": true, "time": time.Now()})
+}
+
+func (s *Server) readyz(w http.ResponseWriter, _ *http.Request) {
+ writeJSON(w, http.StatusOK, map[string]any{"ready": true, "time": time.Now()})
+}
+
+func (s *Server) sendSync(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodPost {
+ writeError(w, http.StatusMethodNotAllowed, "method not allowed")
+ return
+ }
+ if !s.authorized(r) {
+ writeError(w, http.StatusUnauthorized, "unauthorized")
+ return
+ }
+ req, err := s.decodePushRequest(w, r)
+ if err != nil {
+ writeError(w, http.StatusBadRequest, err.Error())
+ return
+ }
+ result, err := s.notifier.Send(r.Context(), req)
+ if err != nil {
+ writeError(w, http.StatusBadGateway, err.Error())
+ return
+ }
+ writeJSON(w, http.StatusOK, map[string]any{
+ "code": 0,
+ "message": "ok",
+ "data": result,
+ })
+}
+
+func (s *Server) enqueue(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodPost {
+ writeError(w, http.StatusMethodNotAllowed, "method not allowed")
+ return
+ }
+ if !s.authorized(r) {
+ writeError(w, http.StatusUnauthorized, "unauthorized")
+ return
+ }
+ req, err := s.decodePushRequest(w, r)
+ if err != nil {
+ writeError(w, http.StatusBadRequest, err.Error())
+ return
+ }
+ requestID, err := s.notifier.Enqueue(r.Context(), req)
+ if err != nil {
+ writeError(w, http.StatusServiceUnavailable, err.Error())
+ return
+ }
+ writeJSON(w, http.StatusAccepted, map[string]any{
+ "code": 0,
+ "message": "accepted",
+ "data": map[string]any{
+ "request_id": requestID,
+ },
+ })
+}
+
+func (s *Server) queryStatus(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodGet {
+ writeError(w, http.StatusMethodNotAllowed, "method not allowed")
+ return
+ }
+ if !s.authorized(r) {
+ writeError(w, http.StatusUnauthorized, "unauthorized")
+ return
+ }
+ requestID := strings.TrimPrefix(r.URL.Path, "/api/v1/messages/")
+ if requestID == "" {
+ writeError(w, http.StatusBadRequest, "request id 不能为空")
+ return
+ }
+ status, ok := s.notifier.GetStatus(requestID)
+ if !ok {
+ writeError(w, http.StatusNotFound, "not found")
+ return
+ }
+ writeJSON(w, http.StatusOK, map[string]any{
+ "code": 0,
+ "message": "ok",
+ "data": status,
+ })
+}
+
+func (s *Server) listTargets(w http.ResponseWriter, r *http.Request) {
+ if r.Method != http.MethodGet {
+ writeError(w, http.StatusMethodNotAllowed, "method not allowed")
+ return
+ }
+ if !s.authorized(r) {
+ writeError(w, http.StatusUnauthorized, "unauthorized")
+ return
+ }
+ targetType := strings.TrimSpace(r.URL.Query().Get("target_type"))
+ items := s.targets.List(200, targetType)
+ writeJSON(w, http.StatusOK, map[string]any{
+ "code": 0,
+ "message": "ok",
+ "data": items,
+ })
+}
+
+func (s *Server) decodePushRequest(w http.ResponseWriter, r *http.Request) (message.PushRequest, error) {
+ defer r.Body.Close()
+ r.Body = http.MaxBytesReader(w, r.Body, s.cfg.Server.MaxBodyBytes)
+ decoder := json.NewDecoder(r.Body)
+ decoder.DisallowUnknownFields()
+ req := message.PushRequest{}
+ if err := decoder.Decode(&req); err != nil {
+ return message.PushRequest{}, err
+ }
+ return req, nil
+}
+
+func (s *Server) authorized(r *http.Request) bool {
+ if strings.TrimSpace(s.cfg.Server.APIToken) == "" {
+ return true
+ }
+ auth := r.Header.Get("Authorization")
+ if !strings.HasPrefix(auth, "Bearer ") {
+ return false
+ }
+ token := strings.TrimPrefix(auth, "Bearer ")
+ return token == s.cfg.Server.APIToken
+}
+
+func writeError(w http.ResponseWriter, status int, msg string) {
+ writeJSON(w, status, map[string]any{
+ "code": status,
+ "message": msg,
+ })
+}
+
+func writeJSON(w http.ResponseWriter, status int, payload any) {
+ w.Header().Set("Content-Type", "application/json; charset=utf-8")
+ w.WriteHeader(status)
+ _ = json.NewEncoder(w).Encode(payload)
+}
diff --git a/internal/notifier/notifier.go b/internal/notifier/notifier.go
new file mode 100644
index 0000000..660b750
--- /dev/null
+++ b/internal/notifier/notifier.go
@@ -0,0 +1,326 @@
+package notifier
+
+import (
+ "context"
+ "crypto/rand"
+ "encoding/hex"
+ "errors"
+ "fmt"
+ "log/slog"
+ "strings"
+ "sync"
+ "time"
+
+ "github.com/sky22333/qqbot/config"
+ "github.com/sky22333/qqbot/internal/qqapi"
+ "github.com/sky22333/qqbot/internal/targets"
+ "github.com/sky22333/qqbot/message"
+)
+
+type idempotentRecord struct {
+ result message.PushResult
+ expiresAt time.Time
+}
+
+type statusRecord struct {
+ status message.DeliveryStatus
+ expiresAt time.Time
+}
+
+type job struct {
+ req message.PushRequest
+}
+
+type Notifier struct {
+ cfg config.Config
+ logger *slog.Logger
+ client *qqapi.Client
+
+ ctx context.Context
+ cancel context.CancelFunc
+ wg sync.WaitGroup
+
+ queue chan job
+
+ mu sync.RWMutex
+ idempotent map[string]idempotentRecord
+ statuses map[string]statusRecord
+ targets *targets.Store
+}
+
+func New(cfg config.Config, logger *slog.Logger) (*Notifier, error) {
+ client, err := qqapi.NewClient(cfg)
+ if err != nil {
+ return nil, err
+ }
+ if logger == nil {
+ logger = slog.Default()
+ }
+ ctx, cancel := context.WithCancel(context.Background())
+ n := &Notifier{
+ cfg: cfg,
+ logger: logger,
+ client: client,
+ ctx: ctx,
+ cancel: cancel,
+ queue: make(chan job, cfg.Dispatch.QueueSize),
+ idempotent: make(map[string]idempotentRecord),
+ statuses: make(map[string]statusRecord),
+ }
+ n.startWorkers()
+ n.startCleanup()
+ return n, nil
+}
+
+func (n *Notifier) SetTargetStore(store *targets.Store) {
+ n.targets = store
+}
+
+func (n *Notifier) Close() {
+ n.cancel()
+ n.wg.Wait()
+}
+
+func (n *Notifier) Enqueue(ctx context.Context, req message.PushRequest) (string, error) {
+ req = n.fillTargetIfMissing(req)
+ if err := validateRequest(req); err != nil {
+ return "", err
+ }
+ if req.RequestID == "" {
+ req.RequestID = newRequestID()
+ }
+ n.setStatus(message.DeliveryStatus{
+ RequestID: req.RequestID,
+ State: message.StateQueued,
+ UpdatedAt: time.Now(),
+ })
+
+ timeout, _ := n.cfg.EnqueueTimeout()
+ timer := time.NewTimer(timeout)
+ defer timer.Stop()
+
+ select {
+ case <-ctx.Done():
+ return "", ctx.Err()
+ case <-n.ctx.Done():
+ return "", errors.New("notifier 已关闭")
+ case <-timer.C:
+ n.setStatus(message.DeliveryStatus{
+ RequestID: req.RequestID,
+ State: message.StateFailed,
+ Error: "入队超时",
+ UpdatedAt: time.Now(),
+ })
+ return "", errors.New("入队超时")
+ case n.queue <- job{req: req}:
+ return req.RequestID, nil
+ }
+}
+
+func (n *Notifier) Send(ctx context.Context, req message.PushRequest) (message.PushResult, error) {
+ req = n.fillTargetIfMissing(req)
+ if err := validateRequest(req); err != nil {
+ return message.PushResult{}, err
+ }
+ if req.RequestID == "" {
+ req.RequestID = newRequestID()
+ }
+ if req.IdempotencyKey != "" {
+ if result, ok := n.getIdempotent(req.IdempotencyKey); ok {
+ n.setStatus(message.DeliveryStatus{
+ RequestID: req.RequestID,
+ State: message.StateSuccess,
+ Result: &result,
+ UpdatedAt: time.Now(),
+ })
+ return result, nil
+ }
+ }
+ n.setStatus(message.DeliveryStatus{
+ RequestID: req.RequestID,
+ State: message.StateSending,
+ UpdatedAt: time.Now(),
+ })
+ result, err := n.sendWithRetry(ctx, req)
+ if err != nil {
+ n.setStatus(message.DeliveryStatus{
+ RequestID: req.RequestID,
+ State: message.StateFailed,
+ Error: err.Error(),
+ UpdatedAt: time.Now(),
+ })
+ return message.PushResult{}, err
+ }
+ if req.IdempotencyKey != "" {
+ n.setIdempotent(req.IdempotencyKey, result)
+ }
+ n.setStatus(message.DeliveryStatus{
+ RequestID: req.RequestID,
+ State: message.StateSuccess,
+ Result: &result,
+ UpdatedAt: time.Now(),
+ })
+ return result, nil
+}
+
+func (n *Notifier) fillTargetIfMissing(req message.PushRequest) message.PushRequest {
+ if strings.TrimSpace(req.TargetID) != "" || n.targets == nil {
+ return req
+ }
+ req.TargetType = message.TargetType(strings.TrimSpace(string(req.TargetType)))
+ if req.TargetType == "" {
+ item, ok := n.targets.LatestAny()
+ if !ok {
+ return req
+ }
+ req.TargetType = item.TargetType
+ req.TargetID = item.TargetID
+ return req
+ }
+ item, ok := n.targets.Latest(req.TargetType)
+ if !ok {
+ return req
+ }
+ req.TargetID = item.TargetID
+ return req
+}
+
+func (n *Notifier) GetStatus(requestID string) (message.DeliveryStatus, bool) {
+ n.mu.RLock()
+ defer n.mu.RUnlock()
+ record, ok := n.statuses[requestID]
+ if !ok || time.Now().After(record.expiresAt) {
+ return message.DeliveryStatus{}, false
+ }
+ return record.status, true
+}
+
+func (n *Notifier) startWorkers() {
+ for i := 0; i < n.cfg.Dispatch.Workers; i++ {
+ n.wg.Add(1)
+ go func(workerID int) {
+ defer n.wg.Done()
+ for {
+ select {
+ case <-n.ctx.Done():
+ return
+ case task := <-n.queue:
+ _, err := n.Send(n.ctx, task.req)
+ if err != nil {
+ n.logger.Error("消息发送失败", "worker", workerID, "request_id", task.req.RequestID, "error", err)
+ }
+ }
+ }
+ }(i + 1)
+ }
+}
+
+func (n *Notifier) startCleanup() {
+ interval := time.Duration(n.cfg.Runtime.CleanupIntervalSec) * time.Second
+ n.wg.Add(1)
+ go func() {
+ defer n.wg.Done()
+ ticker := time.NewTicker(interval)
+ defer ticker.Stop()
+ for {
+ select {
+ case <-n.ctx.Done():
+ return
+ case <-ticker.C:
+ now := time.Now()
+ n.mu.Lock()
+ for key, val := range n.idempotent {
+ if now.After(val.expiresAt) {
+ delete(n.idempotent, key)
+ }
+ }
+ for key, val := range n.statuses {
+ if now.After(val.expiresAt) {
+ delete(n.statuses, key)
+ }
+ }
+ n.mu.Unlock()
+ }
+ }
+ }()
+}
+
+func (n *Notifier) sendWithRetry(ctx context.Context, req message.PushRequest) (message.PushResult, error) {
+ backoff := time.Duration(n.cfg.Dispatch.RetryBackoffMS) * time.Millisecond
+ max := n.cfg.Dispatch.RetryMax
+ var lastErr error
+ for attempt := 0; attempt <= max; attempt++ {
+ result, err := n.client.Send(ctx, req)
+ if err == nil {
+ return result, nil
+ }
+ lastErr = err
+ var apiErr *qqapi.APIError
+ if errors.As(err, &apiErr) {
+ if !apiErr.Temporary() {
+ return message.PushResult{}, err
+ }
+ }
+ if attempt == max {
+ break
+ }
+ sleep := backoff * time.Duration(1<= 500
+}
+
+type tokenResponse struct {
+ AccessToken string `json:"access_token"`
+ ExpiresIn any `json:"expires_in"`
+}
+
+type messageResp struct {
+ ID string `json:"id"`
+ Timestamp string `json:"timestamp"`
+}
+
+type gatewayResp struct {
+ URL string `json:"url"`
+}
+
+type apiErrPayload struct {
+ Code int `json:"code"`
+ Message string `json:"message"`
+}
+
+type Client struct {
+ cfg config.Config
+ httpClient *http.Client
+
+ mu sync.RWMutex
+ token string
+ expires time.Time
+ appID string
+ secret string
+ tokenURL string
+ baseURL string
+}
+
+func NewClient(cfg config.Config) (*Client, error) {
+ timeout, err := cfg.RequestTimeout()
+ if err != nil {
+ return nil, err
+ }
+ transport := &http.Transport{
+ MaxIdleConns: 128,
+ MaxIdleConnsPerHost: 64,
+ IdleConnTimeout: 90 * time.Second,
+ }
+ return &Client{
+ cfg: cfg,
+ httpClient: &http.Client{
+ Timeout: timeout,
+ Transport: transport,
+ },
+ appID: cfg.QQBot.AppID,
+ secret: cfg.QQBot.ClientSecret,
+ tokenURL: strings.TrimRight(cfg.QQBot.TokenURL, "/"),
+ baseURL: strings.TrimRight(cfg.QQBot.APIBase, "/"),
+ }, nil
+}
+
+func (c *Client) Send(ctx context.Context, req message.PushRequest) (message.PushResult, error) {
+ token, err := c.getToken(ctx)
+ if err != nil {
+ return message.PushResult{}, err
+ }
+ res, err := c.sendWithToken(ctx, token, req)
+ if err != nil {
+ var apiErr *APIError
+ if errors.As(err, &apiErr) && apiErr.StatusCode == http.StatusUnauthorized {
+ c.invalidateToken()
+ token, tokenErr := c.getToken(ctx)
+ if tokenErr != nil {
+ return message.PushResult{}, tokenErr
+ }
+ return c.sendWithToken(ctx, token, req)
+ }
+ return message.PushResult{}, err
+ }
+ return res, nil
+}
+
+func (c *Client) AccessToken(ctx context.Context) (string, error) {
+ return c.getToken(ctx)
+}
+
+func (c *Client) GatewayURL(ctx context.Context) (string, error) {
+ token, err := c.getToken(ctx)
+ if err != nil {
+ return "", err
+ }
+ httpReq, err := http.NewRequestWithContext(ctx, http.MethodGet, c.baseURL+"/gateway", nil)
+ if err != nil {
+ return "", err
+ }
+ httpReq.Header.Set("Authorization", "QQBot "+token)
+ resp, err := c.httpClient.Do(httpReq)
+ if err != nil {
+ return "", err
+ }
+ defer resp.Body.Close()
+ raw, err := io.ReadAll(resp.Body)
+ if err != nil {
+ return "", err
+ }
+ if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+ return "", fmt.Errorf("获取 gateway 失败: status=%d body=%s", resp.StatusCode, string(raw))
+ }
+ data := gatewayResp{}
+ if err := json.Unmarshal(raw, &data); err != nil {
+ return "", err
+ }
+ if strings.TrimSpace(data.URL) == "" {
+ return "", errors.New("gateway url 为空")
+ }
+ return data.URL, nil
+}
+
+func (c *Client) sendWithToken(ctx context.Context, token string, req message.PushRequest) (message.PushResult, error) {
+ url, body, err := c.buildRequest(req)
+ if err != nil {
+ return message.PushResult{}, err
+ }
+ httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, url, bytes.NewReader(body))
+ if err != nil {
+ return message.PushResult{}, err
+ }
+ httpReq.Header.Set("Authorization", "QQBot "+token)
+ httpReq.Header.Set("Content-Type", "application/json")
+
+ resp, err := c.httpClient.Do(httpReq)
+ if err != nil {
+ return message.PushResult{}, err
+ }
+ defer resp.Body.Close()
+ raw, err := io.ReadAll(resp.Body)
+ if err != nil {
+ return message.PushResult{}, err
+ }
+ if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+ apiErr := apiErrPayload{}
+ _ = json.Unmarshal(raw, &apiErr)
+ return message.PushResult{}, &APIError{
+ StatusCode: resp.StatusCode,
+ Code: apiErr.Code,
+ Message: apiErr.Message,
+ TraceID: resp.Header.Get("x-tps-trace-id"),
+ }
+ }
+ out := messageResp{}
+ if err := json.Unmarshal(raw, &out); err != nil {
+ return message.PushResult{}, err
+ }
+ return message.PushResult{
+ RequestID: req.RequestID,
+ MessageID: out.ID,
+ Timestamp: parseTime(out.Timestamp),
+ }, nil
+}
+
+func (c *Client) buildRequest(req message.PushRequest) (string, []byte, error) {
+ if strings.TrimSpace(req.TargetID) == "" {
+ return "", nil, errors.New("target_id 不能为空")
+ }
+ if strings.TrimSpace(req.Content) == "" {
+ return "", nil, errors.New("content 不能为空")
+ }
+ payload := map[string]any{
+ "content": req.Content,
+ "msg_type": 0,
+ }
+ if c.cfg.QQBot.Markdown {
+ payload = map[string]any{
+ "markdown": map[string]any{"content": req.Content},
+ "msg_type": 2,
+ }
+ }
+ body, err := json.Marshal(payload)
+ if err != nil {
+ return "", nil, err
+ }
+ switch req.TargetType {
+ case message.TargetC2C:
+ return fmt.Sprintf("%s/v2/users/%s/messages", c.baseURL, req.TargetID), body, nil
+ case message.TargetGroup:
+ return fmt.Sprintf("%s/v2/groups/%s/messages", c.baseURL, req.TargetID), body, nil
+ case message.TargetChannel:
+ return fmt.Sprintf("%s/channels/%s/messages", c.baseURL, req.TargetID), body, nil
+ default:
+ return "", nil, fmt.Errorf("不支持的 target_type: %s", req.TargetType)
+ }
+}
+
+func (c *Client) getToken(ctx context.Context) (string, error) {
+ c.mu.RLock()
+ if c.token != "" && time.Until(c.expires) > 5*time.Minute {
+ token := c.token
+ c.mu.RUnlock()
+ return token, nil
+ }
+ c.mu.RUnlock()
+
+ c.mu.Lock()
+ defer c.mu.Unlock()
+ if c.token != "" && time.Until(c.expires) > 5*time.Minute {
+ return c.token, nil
+ }
+
+ reqBody, _ := json.Marshal(map[string]string{
+ "appId": c.appID,
+ "clientSecret": c.secret,
+ })
+ httpReq, err := http.NewRequestWithContext(ctx, http.MethodPost, c.tokenURL, bytes.NewReader(reqBody))
+ if err != nil {
+ return "", err
+ }
+ httpReq.Header.Set("Content-Type", "application/json")
+ resp, err := c.httpClient.Do(httpReq)
+ if err != nil {
+ return "", err
+ }
+ defer resp.Body.Close()
+ raw, err := io.ReadAll(resp.Body)
+ if err != nil {
+ return "", err
+ }
+ if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+ return "", fmt.Errorf("获取 token 失败: status=%d body=%s", resp.StatusCode, string(raw))
+ }
+ tokenData := tokenResponse{}
+ if err := json.Unmarshal(raw, &tokenData); err != nil {
+ return "", err
+ }
+ if tokenData.AccessToken == "" {
+ return "", errors.New("token 为空")
+ }
+ expSec := parseExpiresIn(tokenData.ExpiresIn)
+ if expSec <= 0 {
+ expSec = 7200
+ }
+ c.token = tokenData.AccessToken
+ c.expires = time.Now().Add(time.Duration(expSec) * time.Second)
+ return c.token, nil
+}
+
+func parseExpiresIn(raw any) int64 {
+ switch v := raw.(type) {
+ case float64:
+ return int64(v)
+ case int64:
+ return v
+ case int:
+ return int64(v)
+ case json.Number:
+ n, err := v.Int64()
+ if err == nil {
+ return n
+ }
+ case string:
+ s := strings.TrimSpace(v)
+ if s == "" {
+ return 0
+ }
+ n, err := strconv.ParseInt(s, 10, 64)
+ if err == nil {
+ return n
+ }
+ }
+ return 0
+}
+
+func (c *Client) invalidateToken() {
+ c.mu.Lock()
+ defer c.mu.Unlock()
+ c.token = ""
+ c.expires = time.Time{}
+}
+
+func parseTime(raw string) time.Time {
+ if raw == "" {
+ return time.Now()
+ }
+ if t, err := time.Parse(time.RFC3339, raw); err == nil {
+ return t
+ }
+ if t, err := time.Parse("2006-01-02T15:04:05Z07:00", raw); err == nil {
+ return t
+ }
+ return time.Now()
+}
diff --git a/internal/targets/store.go b/internal/targets/store.go
new file mode 100644
index 0000000..fe41165
--- /dev/null
+++ b/internal/targets/store.go
@@ -0,0 +1,280 @@
+package targets
+
+import (
+ "context"
+ "encoding/json"
+ "errors"
+ "os"
+ "path/filepath"
+ "sort"
+ "strings"
+ "sync"
+ "time"
+
+ "github.com/sky22333/qqbot/message"
+)
+
+type KnownTarget struct {
+ TargetType message.TargetType `json:"target_type"`
+ TargetID string `json:"target_id"`
+ FirstSeenAt time.Time `json:"first_seen_at"`
+ LastSeenAt time.Time `json:"last_seen_at"`
+ LastMessageID string `json:"last_message_id,omitempty"`
+ LastContent string `json:"last_content,omitempty"`
+ SeenCount int64 `json:"seen_count"`
+}
+
+type Store struct {
+ filePath string
+ maxRecords int
+ flushInterval time.Duration
+
+ mu sync.RWMutex
+ records map[string]KnownTarget
+ latest map[message.TargetType]KnownTarget
+ latestX KnownTarget
+ hasLast bool
+ dirty bool
+ version uint64
+
+ ctx context.Context
+ cancel context.CancelFunc
+ wg sync.WaitGroup
+ flushSig chan struct{}
+}
+
+func NewStore(filePath string, maxRecords int, flushInterval time.Duration) (*Store, error) {
+ if strings.TrimSpace(filePath) == "" {
+ return nil, errors.New("targets file path 不能为空")
+ }
+ if maxRecords <= 0 {
+ maxRecords = 10000
+ }
+ if flushInterval <= 0 {
+ flushInterval = 2 * time.Second
+ }
+ ctx, cancel := context.WithCancel(context.Background())
+ s := &Store{
+ filePath: filePath,
+ maxRecords: maxRecords,
+ flushInterval: flushInterval,
+ records: make(map[string]KnownTarget),
+ latest: make(map[message.TargetType]KnownTarget),
+ ctx: ctx,
+ cancel: cancel,
+ flushSig: make(chan struct{}, 1),
+ }
+ if err := s.load(); err != nil {
+ cancel()
+ return nil, err
+ }
+ s.startFlusher()
+ return s, nil
+}
+
+func (s *Store) Upsert(targetType message.TargetType, targetID, msgID, content string) error {
+ targetID = strings.TrimSpace(targetID)
+ if targetID == "" {
+ return nil
+ }
+ key := string(targetType) + ":" + targetID
+ now := time.Now()
+
+ s.mu.Lock()
+ defer s.mu.Unlock()
+
+ record, ok := s.records[key]
+ if !ok {
+ record = KnownTarget{
+ TargetType: targetType,
+ TargetID: targetID,
+ FirstSeenAt: now,
+ }
+ }
+ record.LastSeenAt = now
+ record.LastMessageID = strings.TrimSpace(msgID)
+ record.LastContent = strings.TrimSpace(content)
+ record.SeenCount++
+ s.records[key] = record
+ s.latest[record.TargetType] = record
+ s.latestX = record
+ s.hasLast = true
+ s.compactIfNeededLocked()
+ s.dirty = true
+ s.version++
+ s.signalFlushLocked()
+ return nil
+}
+
+func (s *Store) List(limit int, targetType string) []KnownTarget {
+ s.mu.RLock()
+ defer s.mu.RUnlock()
+
+ targetType = strings.TrimSpace(strings.ToLower(targetType))
+ items := make([]KnownTarget, 0, len(s.records))
+ for _, r := range s.records {
+ if targetType != "" && string(r.TargetType) != targetType {
+ continue
+ }
+ items = append(items, r)
+ }
+ sort.Slice(items, func(i, j int) bool {
+ return items[i].LastSeenAt.After(items[j].LastSeenAt)
+ })
+ if limit > 0 && len(items) > limit {
+ items = items[:limit]
+ }
+ return items
+}
+
+func (s *Store) Latest(targetType message.TargetType) (KnownTarget, bool) {
+ s.mu.RLock()
+ defer s.mu.RUnlock()
+ item, ok := s.latest[targetType]
+ if !ok {
+ return KnownTarget{}, false
+ }
+ return item, true
+}
+
+func (s *Store) LatestAny() (KnownTarget, bool) {
+ s.mu.RLock()
+ defer s.mu.RUnlock()
+ if !s.hasLast {
+ return KnownTarget{}, false
+ }
+ return s.latestX, true
+}
+
+func (s *Store) load() error {
+ if _, err := os.Stat(s.filePath); err != nil {
+ if os.IsNotExist(err) {
+ return nil
+ }
+ return err
+ }
+ raw, err := os.ReadFile(s.filePath)
+ if err != nil {
+ return err
+ }
+ var list []KnownTarget
+ if err := json.Unmarshal(raw, &list); err != nil {
+ return err
+ }
+ for _, item := range list {
+ key := string(item.TargetType) + ":" + item.TargetID
+ s.records[key] = item
+ }
+ s.rebuildLatestLocked()
+ return nil
+}
+
+func (s *Store) Close() error {
+ s.cancel()
+ s.wg.Wait()
+ return s.flushNow()
+}
+
+func (s *Store) startFlusher() {
+ s.wg.Add(1)
+ go func() {
+ defer s.wg.Done()
+ ticker := time.NewTicker(s.flushInterval)
+ defer ticker.Stop()
+ for {
+ select {
+ case <-s.ctx.Done():
+ return
+ case <-ticker.C:
+ _ = s.flushNow()
+ case <-s.flushSig:
+ _ = s.flushNow()
+ }
+ }
+ }()
+}
+
+func (s *Store) flushNow() error {
+ records, version, ok := s.snapshotForFlush()
+ if !ok {
+ return nil
+ }
+ if err := s.writeRecords(records); err != nil {
+ return err
+ }
+ s.mu.Lock()
+ if s.version == version {
+ s.dirty = false
+ }
+ s.mu.Unlock()
+ return nil
+}
+
+func (s *Store) snapshotForFlush() ([]KnownTarget, uint64, bool) {
+ s.mu.RLock()
+ defer s.mu.RUnlock()
+ if !s.dirty {
+ return nil, 0, false
+ }
+ list := make([]KnownTarget, 0, len(s.records))
+ for _, item := range s.records {
+ list = append(list, item)
+ }
+ sort.Slice(list, func(i, j int) bool {
+ return list[i].LastSeenAt.After(list[j].LastSeenAt)
+ })
+ return list, s.version, true
+}
+
+func (s *Store) writeRecords(list []KnownTarget) error {
+ if err := os.MkdirAll(filepath.Dir(s.filePath), 0o755); err != nil {
+ return err
+ }
+ data, err := json.MarshalIndent(list, "", " ")
+ if err != nil {
+ return err
+ }
+ return os.WriteFile(s.filePath, data, 0o644)
+}
+
+func (s *Store) signalFlushLocked() {
+ select {
+ case s.flushSig <- struct{}{}:
+ default:
+ }
+}
+
+func (s *Store) compactIfNeededLocked() {
+ if len(s.records) <= s.maxRecords {
+ return
+ }
+ list := make([]KnownTarget, 0, len(s.records))
+ for _, item := range s.records {
+ list = append(list, item)
+ }
+ sort.Slice(list, func(i, j int) bool {
+ return list[i].LastSeenAt.After(list[j].LastSeenAt)
+ })
+ cut := list[s.maxRecords:]
+ for _, item := range cut {
+ key := string(item.TargetType) + ":" + item.TargetID
+ delete(s.records, key)
+ }
+ s.rebuildLatestLocked()
+}
+
+func (s *Store) rebuildLatestLocked() {
+ clear(s.latest)
+ s.latestX = KnownTarget{}
+ s.hasLast = false
+ for _, item := range s.records {
+ prev, ok := s.latest[item.TargetType]
+ if !ok || item.LastSeenAt.After(prev.LastSeenAt) {
+ s.latest[item.TargetType] = item
+ }
+ if !s.hasLast || item.LastSeenAt.After(s.latestX.LastSeenAt) {
+ s.latestX = item
+ s.hasLast = true
+ }
+ }
+}
diff --git a/message/types.go b/message/types.go
new file mode 100644
index 0000000..56264fe
--- /dev/null
+++ b/message/types.go
@@ -0,0 +1,42 @@
+package message
+
+import "time"
+
+type TargetType string
+
+const (
+ TargetC2C TargetType = "c2c"
+ TargetGroup TargetType = "group"
+ TargetChannel TargetType = "channel"
+)
+
+type PushRequest struct {
+ RequestID string `json:"request_id"`
+ IdempotencyKey string `json:"idempotency_key"`
+ TargetType TargetType `json:"target_type"`
+ TargetID string `json:"target_id"`
+ Content string `json:"content"`
+}
+
+type PushResult struct {
+ RequestID string `json:"request_id"`
+ MessageID string `json:"message_id"`
+ Timestamp time.Time `json:"timestamp"`
+}
+
+type DeliveryState string
+
+const (
+ StateQueued DeliveryState = "queued"
+ StateSending DeliveryState = "sending"
+ StateSuccess DeliveryState = "success"
+ StateFailed DeliveryState = "failed"
+)
+
+type DeliveryStatus struct {
+ RequestID string `json:"request_id"`
+ State DeliveryState `json:"state"`
+ Error string `json:"error,omitempty"`
+ Result *PushResult `json:"result,omitempty"`
+ UpdatedAt time.Time `json:"updated_at"`
+}
diff --git a/sdk.go b/sdk.go
new file mode 100644
index 0000000..19f8dec
--- /dev/null
+++ b/sdk.go
@@ -0,0 +1,50 @@
+package qqbot
+
+import (
+ "context"
+ "log/slog"
+ "os"
+
+ "github.com/sky22333/qqbot/config"
+ "github.com/sky22333/qqbot/internal/notifier"
+)
+
+type Client struct {
+ notifier *notifier.Notifier
+}
+
+func New(cfg Config) (*Client, error) {
+ if err := cfg.Validate(); err != nil {
+ return nil, err
+ }
+ logger := slog.New(slog.NewJSONHandler(os.Stdout, nil))
+ n, err := notifier.New(cfg, logger)
+ if err != nil {
+ return nil, err
+ }
+ return &Client{notifier: n}, nil
+}
+
+func NewFromConfigFile(path string) (*Client, error) {
+ cfg, err := config.Load(path)
+ if err != nil {
+ return nil, err
+ }
+ return New(cfg)
+}
+
+func (c *Client) Send(ctx context.Context, req PushRequest) (PushResult, error) {
+ return c.notifier.Send(ctx, req)
+}
+
+func (c *Client) Enqueue(ctx context.Context, req PushRequest) (string, error) {
+ return c.notifier.Enqueue(ctx, req)
+}
+
+func (c *Client) GetStatus(requestID string) (DeliveryStatus, bool) {
+ return c.notifier.GetStatus(requestID)
+}
+
+func (c *Client) Close() {
+ c.notifier.Close()
+}
diff --git a/sdk_send_test.go b/sdk_send_test.go
new file mode 100644
index 0000000..a4f266b
--- /dev/null
+++ b/sdk_send_test.go
@@ -0,0 +1,66 @@
+package qqbot
+
+import (
+ "context"
+ "os"
+ "strings"
+ "testing"
+ "time"
+)
+
+func TestSendNotificationWithConfig(t *testing.T) {
+ enabled := strings.EqualFold(os.Getenv("QQBOT_REAL_SEND_TEST"), "true") || os.Getenv("QQBOT_REAL_SEND_TEST") == "1"
+ if !enabled {
+ t.Skip("QQBOT_REAL_SEND_TEST 未开启，跳过真实发送测试")
+ }
+
+ configPath := os.Getenv("QQBOT_TEST_CONFIG")
+ if strings.TrimSpace(configPath) == "" {
+ configPath = "configs/config.toml"
+ }
+
+ cfg, err := LoadConfig(configPath)
+ if err != nil {
+ t.Fatalf("加载配置失败: %v", err)
+ }
+
+ if strings.Contains(cfg.QQBot.AppID, "你的") || strings.Contains(cfg.QQBot.ClientSecret, "你的") {
+ t.Skip("请先替换 qqbot.app_id 和 qqbot.client_secret")
+ }
+ targetID := strings.TrimSpace(os.Getenv("QQBOT_TEST_TARGET_ID"))
+ if targetID == "" {
+ t.Skip("QQBOT_TEST_TARGET_ID 为空，跳过真实发送测试")
+ }
+ targetType := strings.TrimSpace(strings.ToLower(os.Getenv("QQBOT_TEST_TARGET_TYPE")))
+ if targetType == "" {
+ targetType = string(TargetC2C)
+ }
+ if targetType != string(TargetC2C) && targetType != string(TargetGroup) && targetType != string(TargetChannel) {
+ t.Fatalf("QQBOT_TEST_TARGET_TYPE 无效: %s", targetType)
+ }
+ content := strings.TrimSpace(os.Getenv("QQBOT_TEST_CONTENT"))
+ if content == "" {
+ content = "来自qqbot真实发送测试的通知"
+ }
+
+ client, err := New(cfg)
+ if err != nil {
+ t.Fatalf("初始化客户端失败: %v", err)
+ }
+ defer client.Close()
+
+ ctx, cancel := context.WithTimeout(context.Background(), 25*time.Second)
+ defer cancel()
+
+ result, err := client.Send(ctx, PushRequest{
+ TargetType: TargetType(targetType),
+ TargetID: targetID,
+ Content: content,
+ })
+ if err != nil {
+ t.Fatalf("发送失败: %v", err)
+ }
+ if strings.TrimSpace(result.MessageID) == "" {
+ t.Fatalf("发送成功但 message_id 为空: %+v", result)
+ }
+}
diff --git a/types.go b/types.go
new file mode 100644
index 0000000..f42ca37
--- /dev/null
+++ b/types.go
@@ -0,0 +1,20 @@
+package qqbot
+
+import (
+ "github.com/sky22333/qqbot/config"
+ "github.com/sky22333/qqbot/message"
+)
+
+type Config = config.Config
+
+type TargetType = message.TargetType
+
+const (
+ TargetC2C = message.TargetC2C
+ TargetGroup = message.TargetGroup
+ TargetChannel = message.TargetChannel
+)
+
+type PushRequest = message.PushRequest
+type PushResult = message.PushResult
+type DeliveryStatus = message.DeliveryStatus