mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-09-20 17:08:01 +00:00
Compare commits
23 Commits
release/v1
...
v1.2.0
| Author | SHA1 | Date | |
|---|---|---|---|
| 140cd34b56 | |||
| b237787c90 | |||
| 69ff3089a4 | |||
| e839eb8220 | |||
| d893bfa76f | |||
| 93ab794a82 | |||
| 12cabcb290 | |||
| 44bd915fbf | |||
| ba49dfda44 | |||
| b2eafdf885 | |||
| 8c397ecf65 | |||
| 632f6743d3 | |||
| 9d930db4ea | |||
| 0a164fe4b9 | |||
| fd5a291df1 | |||
| 5175e7d6e0 | |||
| 71e3325439 | |||
| 18fec9b003 | |||
| fc236120e3 | |||
| a66739e59b | |||
| da01af1ad7 | |||
| 741e284cd4 | |||
| ce5bff9275 |
661
LICENSE
Normal file
661
LICENSE
Normal file
@ -0,0 +1,661 @@
|
||||
GNU AFFERO GENERAL PUBLIC LICENSE
|
||||
Version 3, 19 November 2007
|
||||
|
||||
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
|
||||
Everyone is permitted to copy and distribute verbatim copies
|
||||
of this license document, but changing it is not allowed.
|
||||
|
||||
Preamble
|
||||
|
||||
The GNU Affero General Public License is a free, copyleft license for
|
||||
software and other kinds of works, specifically designed to ensure
|
||||
cooperation with the community in the case of network server software.
|
||||
|
||||
The licenses for most software and other practical works are designed
|
||||
to take away your freedom to share and change the works. By contrast,
|
||||
our General Public Licenses are 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.
|
||||
|
||||
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.
|
||||
|
||||
Developers that use our General Public Licenses protect your rights
|
||||
with two steps: (1) assert copyright on the software, and (2) offer
|
||||
you this License which gives you legal permission to copy, distribute
|
||||
and/or modify the software.
|
||||
|
||||
A secondary benefit of defending all users' freedom is that
|
||||
improvements made in alternate versions of the program, if they
|
||||
receive widespread use, become available for other developers to
|
||||
incorporate. Many developers of free software are heartened and
|
||||
encouraged by the resulting cooperation. However, in the case of
|
||||
software used on network servers, this result may fail to come about.
|
||||
The GNU General Public License permits making a modified version and
|
||||
letting the public access it on a server without ever releasing its
|
||||
source code to the public.
|
||||
|
||||
The GNU Affero General Public License is designed specifically to
|
||||
ensure that, in such cases, the modified source code becomes available
|
||||
to the community. It requires the operator of a network server to
|
||||
provide the source code of the modified version running there to the
|
||||
users of that server. Therefore, public use of a modified version, on
|
||||
a publicly accessible server, gives the public access to the source
|
||||
code of the modified version.
|
||||
|
||||
An older license, called the Affero General Public License and
|
||||
published by Affero, was designed to accomplish similar goals. This is
|
||||
a different license, not a version of the Affero GPL, but Affero has
|
||||
released a new version of the Affero GPL which permits relicensing under
|
||||
this license.
|
||||
|
||||
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 Affero 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. Remote Network Interaction; Use with the GNU General Public License.
|
||||
|
||||
Notwithstanding any other provision of this License, if you modify the
|
||||
Program, your modified version must prominently offer all users
|
||||
interacting with it remotely through a computer network (if your version
|
||||
supports such interaction) an opportunity to receive the Corresponding
|
||||
Source of your version by providing access to the Corresponding Source
|
||||
from a network server at no charge, through some standard or customary
|
||||
means of facilitating copying of software. This Corresponding Source
|
||||
shall include the Corresponding Source for any work covered by version 3
|
||||
of the GNU General Public License that is incorporated pursuant to the
|
||||
following paragraph.
|
||||
|
||||
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 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 work with which it is combined will remain governed by version
|
||||
3 of the GNU General Public License.
|
||||
|
||||
14. Revised Versions of this License.
|
||||
|
||||
The Free Software Foundation may publish revised and/or new versions of
|
||||
the GNU Affero 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 Affero 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 Affero 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 Affero 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.
|
||||
|
||||
<one line to give the program's name and a brief idea of what it does.>
|
||||
Copyright (C) <year> <name of author>
|
||||
|
||||
This program is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU Affero 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 Affero General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU Affero General Public License
|
||||
along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||||
|
||||
Also add information on how to contact you by electronic and paper mail.
|
||||
|
||||
If your software can interact with users remotely through a computer
|
||||
network, you should also make sure that it provides a way for users to
|
||||
get its source. For example, if your program is a web application, its
|
||||
interface could display a "Source" link that leads users to an archive
|
||||
of the code. There are many ways you could offer source, and different
|
||||
solutions will be better for different programs; see section 13 for the
|
||||
specific requirements.
|
||||
|
||||
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 AGPL, see
|
||||
<https://www.gnu.org/licenses/>.
|
||||
226
README.md
226
README.md
@ -2,6 +2,70 @@
|
||||
|
||||
HomeAgent 插件开发 SDK，用于构建与 HomeAgent 平台交互的智能插件。
|
||||
|
||||
## 版本与兼容性
|
||||
|
||||
当前：**SDK 1.2.0**（需内核 **1.2.0+**）。
|
||||
|
||||
**版本号跟随内核的中版本，patch 位恒为 `.0`**：
|
||||
|
||||
| 内核版本 | 对应 SDK |
|
||||
|---|---|
|
||||
| 1.0.0 / 1.0.1 / … / 1.0.4 | 1.0.0 |
|
||||
| 1.1.0 / 1.1.1 / … / 1.1.N | **1.1.0** |
|
||||
| 1.2.0 起 | 1.2.0 |
|
||||
|
||||
内核的 patch 位专用于 bugfix 与漏洞修复，不碰公开接口，所以 SDK 版本号不跟着动——
|
||||
否则你要么被迫跟版、要么怀疑自己版本过时，而接口其实一个字都没变。
|
||||
|
||||
**1.0.x 插件升到 1.1.x：不需要改代码，也不需要重编。** 1.1.0 的新增全部是
|
||||
「插件调用、内核实现」方向，不调就不受影响（已用 SDK 0.9.2 编的旧 `plugin.bin`
|
||||
实测验证：在新内核上直接建链通过，因为握手校验的是 `ProtocolVersion`、不是 SDK 版本）。
|
||||
想用新字段时重编即可。
|
||||
|
||||
**1.1.x 插件升到 1.2.x：接口纯追加，但必须重编。** 公开接口没有签名变更（新增
|
||||
`InjectOptions` 与六个 `*Opts` 变体、`ChannelDef.ContextPolicy`），不调新能力就不受影响；
|
||||
但内核的**插件运行协议升到了 2**（统一共享内存区的 fd3 布局改变，**不支持滚动升级**），
|
||||
所以 `plugin.bin` 必须用配套的 `hmapdev` 重编后与内核**同批**安装——否则握手时协议版本
|
||||
不匹配会被拒绝（错误信息会明确提示用配套 hmapdev 重编，不会静默降级）。
|
||||
|
||||
## 注入行为与上下文裁剪（1.2.0）
|
||||
|
||||
「记不记入记忆」与「要不要据此裁剪上下文」这两件事，原先只有 `ToolDef` 能声明；
|
||||
1.2.0 起**注入侧也能声明**，并且二者共用同一套语义与取值。
|
||||
|
||||
```go
|
||||
type InjectOptions struct {
|
||||
NoMemory bool // true = 不参与记忆计算（向量化/关键词提取/蒸馏），原文仍留在上下文
|
||||
ContextPolicy string // ""/none = 不裁剪（默认）；prune = 据此裁剪上下文
|
||||
CleanerName string // 计算层过滤函数名：先经 Cleaner 得到实际有效内容，再计算/裁剪
|
||||
}
|
||||
|
||||
const (
|
||||
ContextPolicyNone = "none"
|
||||
ContextPolicyPrune = "prune"
|
||||
)
|
||||
|
||||
// 六个变体，与旧的三参数方法一一对应，只多一个 opts
|
||||
InjectTextOpts(source, channel, text string, opts InjectOptions)
|
||||
InjectInterruptTextOpts(source, channel, text string, opts InjectOptions)
|
||||
InjectInputSyncOpts(source, channel, text string, opts InjectOptions) string
|
||||
InjectInputMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
|
||||
InjectInputMediaSyncOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) string
|
||||
InjectInterruptMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
|
||||
```
|
||||
|
||||
要点：
|
||||
|
||||
- **零值 `InjectOptions{}` 与旧的三参数方法逐键等价**（记入记忆 + 不裁剪）。旧方法保留为
|
||||
零值糖（`InjectText` / `InjectInterruptText` / `InjectTextNoMemory` …），存量插件不改一行、
|
||||
不需重编即可继续调用。
|
||||
- **裁剪（`prune`）必须显式声明**：它会归档丢弃低相关事件，是有副作用的行为，故默认关闭。
|
||||
内核只放行 `""` / `none` / `prune`（`ValidContextPolicy`），未声明的取值会被拒。
|
||||
- 裁剪前先经该插件注册的 **`Cleaner`**（由 `CleanerName` 指定）拿到实际有效内容，
|
||||
避开「按原文裁剪、按清洗后计算」这种不一致。
|
||||
- `ChannelDef` 也有同名 `context_policy`（并且 1.2.0 给它补上了 JSON tag——通道定义要跨进程
|
||||
传给内核，而 `Cleaner` 是函数必须忽略；无 tag 时新增字段会被静默丢掉）。
|
||||
|
||||
## SDK API 接口
|
||||
|
||||
### Plugin 接口
|
||||
@ -36,6 +100,7 @@ type Plugin interface {
|
||||
| 设置 | `Settings()` | 访问设置 API |
|
||||
| 事件 | `Events()` | 访问事件订阅器（外部插件仅订阅） |
|
||||
| 注入 | `InjectText(source, channel, text)` / `InjectInterruptText(source, channel, text)` / `InjectTextNoMemory(source, channel, text)` | 向管道注入文本 |
|
||||
| 多模态注入 | `InjectInputMedia(source, channel, text, blocks)` / `InjectInputMediaSync(...)` / `InjectInterruptMedia(...)` | 注入带图片/音频的输入（1.1.0 新增） |
|
||||
| 自动重启 | `SetAutoRestart(enabled)` / `AutoRestart()` | 控制崩溃自动重启 |
|
||||
|
||||
### 阶段钩子
|
||||
@ -106,6 +171,30 @@ type 枚举值：
|
||||
| `InjectInterruptText(source, channel, text)` | 注入中断文本，打断当前处理，路由到指定通道 |
|
||||
| `InjectTextNoMemory(source, channel, text)` | 注入文本，不记入内存，路由到指定通道 |
|
||||
|
||||
### 多模态注入（1.1.0 新增）
|
||||
|
||||
| 方法 | 说明 |
|
||||
|------|------|
|
||||
| `InjectInputMedia(source, channel, text, blocks)` | 注入带媒体的输入，异步 |
|
||||
| `InjectInputMediaSync(source, channel, text, blocks)` | 注入带媒体的输入并同步等待回复文本 |
|
||||
| `InjectInterruptMedia(source, channel, text, blocks)` | 注入带媒体的中断，可抢占当前处理 |
|
||||
|
||||
`blocks` 是 `[]sdk.ContentBlock`，与 `SetToolBlocks` 用同一类型：
|
||||
|
||||
```go
|
||||
s.InjectInputMedia("myplugin", "webui", "帮我看看这张图", []sdk.ContentBlock{{
|
||||
Type: "image_url",
|
||||
ImageURL: &sdk.ImageURL{URL: "data:image/png;base64," + b64, Detail: "auto"},
|
||||
}})
|
||||
```
|
||||
|
||||
与 `SetToolBlocks` 的区别：`SetToolBlocks` 只能在工具处理函数内部调用，媒体要等到
|
||||
下一条 tool message 才到模型手上；这三个方法是插件**主动发起一轮带媒体的对话**，
|
||||
媒体在本轮就随消息发给模型，并自动落进媒体存储、挂上媒体记忆引用。
|
||||
|
||||
媒体块里的 `data:` URL 会被内核落盘去重；`http(s)` URL 只透传给模型，不入库
|
||||
（入库需要内核发起网络请求，涉及超时、鉴权与 SSRF）。
|
||||
|
||||
`source` 标识来源，`channel` 指定目标输出通道。
|
||||
|
||||
### Triple 扩展字段
|
||||
@ -115,6 +204,61 @@ Triple 数据结构新增字段：
|
||||
- `Confidence` — 置信度（0.0~1.0）
|
||||
- `SubjectType` — 主体类型
|
||||
- `ObjectType` — 客体类型
|
||||
- `SentenceText` — 原始句子文本（1.1.0 新增），写入 `sentences` 表；媒体引用挂在句子上
|
||||
- `MediaDigests` — 关联的媒体 digest 列表（1.1.0 新增）
|
||||
|
||||
### 记忆里的媒体（1.1.0 新增）
|
||||
|
||||
媒体在纯文本记忆里以**标记**形式存在，格式 `[<mime> <短digest>] <描述>`：
|
||||
|
||||
```
|
||||
[image/png a1b2c3d4e5f6] 一张紫蓝红三色带图
|
||||
```
|
||||
|
||||
描述文本是持久的语义记忆（检索靠它），digest 是回到字节的钥匙（反查靠它）。
|
||||
标记由内核生成，插件不必自己拼——**填 digest 就够**。
|
||||
|
||||
#### 图记忆
|
||||
|
||||
```go
|
||||
s.Memory().Commit([]sdk.Triple{{
|
||||
Subject: "配色图", Relation: "包含", Object: "三色带",
|
||||
MediaDigests: []string{"a1b2c3d4e5f6"}, // 短 digest 即可，内核补全
|
||||
}})
|
||||
```
|
||||
|
||||
没给 `SentenceText` 时内核会用标记本身充当句子——媒体必须有句子落点，
|
||||
否则引用无从挂起。
|
||||
|
||||
#### 知识库
|
||||
|
||||
```go
|
||||
s.DocMemory().InsertWithMedia(&sdk.Doc{
|
||||
Title: "带图笔记",
|
||||
Content: "正文",
|
||||
}, []sdk.MediaAttachment{
|
||||
{MIME: "image/png", Data: pngBytes, Name: "chart.png"}, // 新内容，落盘去重
|
||||
{Digest: "a1b2c3d4e5f6"}, // 引用已有内容
|
||||
})
|
||||
```
|
||||
|
||||
`Insert` 保持原签名不变，正文里已有的标记同样会被挂成文档级引用。
|
||||
`Query` 返回的 `Doc` 带 `MediaDigests` 与 `Attachments`（mime + 描述，
|
||||
**不含字节**——一次检索可能命中几十份媒体）。删除文档时引用自动释放。
|
||||
|
||||
#### 文本记忆
|
||||
|
||||
```go
|
||||
s.TextMemory().Append(sdk.TextEvent{
|
||||
Role: "user", Content: "看这张图",
|
||||
Attachments: []sdk.MediaAttachment{{MIME: "image/png", Data: pngBytes}},
|
||||
})
|
||||
```
|
||||
|
||||
`RecentEvents` 读回时正文里的标记会被反解成 `Attachments`。
|
||||
|
||||
媒体存储可在内核侧关闭（`core.memory.media.enabled=false`），此时以上接口
|
||||
全部退化为纯文本行为：不报错、不 panic，与本特性上线前一致。
|
||||
|
||||
### ToolDef 字段说明
|
||||
|
||||
@ -140,18 +284,23 @@ func New(name string, sett SettingsAPI, regTool ToolRegistrar, regStage StageReg
|
||||
|
||||
插件开发者只需实现 `Plugin` 接口并导出 `NewPluginFactory()` 入口函数。
|
||||
|
||||
## plugindev 工具链
|
||||
## hmapdev 工具链
|
||||
|
||||
`plugindev` 提供插件开发全流程支持。预编译二进制作为 **release 附件**分发（linux/darwin/windows × amd64/arm64），从
|
||||
`hmapdev` 提供插件开发全流程支持，最终产出 `.hmap` 插件包（工具名即来自该包格式）。
|
||||
预编译二进制作为 **release 附件**分发（linux/darwin/windows × amd64/arm64），从
|
||||
[Releases](https://gitcode.com/JianFeeeee/homeagent-sdk/releases) 下载后加入 PATH 即可：
|
||||
|
||||
> 改名说明：工具链原名 `plugindev`，自 1.2.0 起更名 `hmapdev`。
|
||||
> SDK 存储目录同时由 `~/.homeagent/plugindev/sdk` 迁到 `~/.homeagent/hmapdev/sdk`
|
||||
> （旧目录会被自动沿用，不会丢已装版本）。
|
||||
|
||||
```bash
|
||||
# 从 release 附件下载（以 v1.0.0 / linux amd64 为例）
|
||||
curl -Lo plugindev https://gitcode.com/JianFeeeee/homeagent-sdk/releases/download/v1.0.0/plugindev_linux_amd64
|
||||
chmod +x plugindev
|
||||
# 从 release 附件下载（以最新 SDK 发布 / linux amd64 为例）
|
||||
curl -Lo hmapdev https://gitcode.com/JianFeeeee/homeagent-sdk/releases/download/<版本>/hmapdev_linux_amd64
|
||||
chmod +x hmapdev
|
||||
|
||||
# 或从源码自己编
|
||||
cd tools/plugindev && go build -o plugindev .
|
||||
cd tools/hmapdev && go build -o hmapdev .
|
||||
```
|
||||
|
||||
> 二进制不再随仓库分发（旧的 `bin/` 目录已停用）：5 个平台各 26-28MB，
|
||||
@ -159,11 +308,11 @@ cd tools/plugindev && go build -o plugindev .
|
||||
|
||||
| 命令 | 说明 |
|
||||
|------|------|
|
||||
| `plugindev init <name> [--lua]` | 初始化插件项目（生成 plg.json、plugin.go 或 main.lua、go.mod、README.md） |
|
||||
| `plugindev build [flags]` | 编译并打包为 `.hmap` 包（支持跨平台编译和 bundle 模式） |
|
||||
| `plugindev clean` | 清理 `build/`、`dist/` 目录及生成文件（plugin.json、z_bridge_gen.go） |
|
||||
| `plugindev debug [dir]` | 通过 Yaegi Go 解释器加载插件源码，启动交互式 REPL 调试 |
|
||||
| `plugindev sdk <command>` | SDK 版本管理（子命令：list/install/use/path/current/latest） |
|
||||
| `hmapdev init <name> [--lua]` | 初始化插件项目（生成 plg.json、plugin.go 或 main.lua、go.mod、README.md） |
|
||||
| `hmapdev build [flags]` | 编译并打包为 `.hmap` 包（支持跨平台编译和 bundle 模式） |
|
||||
| `hmapdev clean` | 清理 `build/`、`dist/` 目录及生成文件（plugin.json、z_bridge_gen.go） |
|
||||
| `hmapdev debug [dir]` | 通过 Yaegi Go 解释器加载插件源码，启动交互式 REPL 调试 |
|
||||
| `hmapdev sdk <command>` | SDK 版本管理（子命令：list/install/use/path/current/latest） |
|
||||
|
||||
支持 **Go** 和 **Lua** 两种插件语言。
|
||||
|
||||
@ -270,7 +419,7 @@ return plugin
|
||||
|
||||
- `sdk.RegisterOnRemoveHandler(fn func())` — 注册删除清理回调。内核在 `RemovePlugin` 流程中、插件 `Stop()` **之后**执行（后注册先执行，执行后清空、幂等）。用于删除插件自身创建的持久化文件（数据/缓存/状态文件）。
|
||||
- 内核卸载时一并清理：工具注册、`disabled_plugins` 记录、插件配置项定义（`plugin.<name>.*`）与插件配置表（`config_<name>`），卸载后插件配置区完全消失。
|
||||
- 示例：`example/calendar`（删 events.json）、`example/memo`（删 memos.json）、`example/rss`（删订阅数据目录）、`example/weather`（删缓存目录）；`plugindev` 模板含 onRemove 演示。
|
||||
- 示例：`example/calendar`（删 events.json）、`example/memo`（删 memos.json）、`example/rss`（删订阅数据目录）、`example/weather`（删缓存目录）；`hmapdev` 模板含 onRemove 演示。
|
||||
|
||||
```go
|
||||
sdk.RegisterOnRemoveHandler(func() {
|
||||
@ -288,6 +437,31 @@ enabled := sdk.AutoRestart()
|
||||
|
||||
插件崩溃时平台自动拉起，保障服务可用性。
|
||||
|
||||
> ⚠️ `SetAutoRestart` 的典型用法是「外部连接建好后再判定能否自动重启」，而连接建立
|
||||
> 通常在后台 goroutine 里，内核又在另一个 goroutine 读它——这对读写天然并发。
|
||||
> **SDK 1.1.0 已给这个标志与全部 API 字段加锁**（`-race` 实测 11 处竞态，
|
||||
> 生产表现是插件重载瞬间偶发 nil 解引用崩溃）。早于 1.1.0 的版本建议升级。
|
||||
|
||||
## 插件开发者的并发约定
|
||||
|
||||
`PluginSDK` 是**被多个 goroutine 同时使用的共享对象**：你在 `Start()` 里起的轮询、
|
||||
监听、定时器都拿着同一份 `*PluginSDK` 往里注消息，而内核会在加载/重载时写它的
|
||||
API 字段。因此：
|
||||
|
||||
- **SDK 侧已保证的**：全部 API 访问器（`Memory()`/`DocMemory()`/…）、全部注入方法、
|
||||
`SetAutoRestart`/`AutoRestart`、`RegisterTool`/`RegisterStage`、
|
||||
`RunStopHandlers`/`RunOnRemoveHandlers`（幂等，并发调也只执行一次）。
|
||||
- **你需要自己保证的**：`StageContext` 的字段全部导出，并发读写必须自己持
|
||||
`ctx.Lock()`/`ctx.RLock()`。尤其是 `ctx.Extra`——**map 的并发写在 Go 里是直接 fatal，
|
||||
`recover` 接不住**。
|
||||
|
||||
```go
|
||||
ctx.Lock()
|
||||
ctx.Extra["mykey"] = value
|
||||
ctx.FinalText += "补充说明"
|
||||
ctx.Unlock()
|
||||
```
|
||||
|
||||
## 受限 SDK vs 完整 SDK
|
||||
|
||||
外部插件（第三方分发）使用**受限 SDK**，仅暴露安全子集：
|
||||
@ -319,6 +493,11 @@ enabled := sdk.AutoRestart()
|
||||
| [rss](example/rss) | Go | RSS 订阅 |
|
||||
| [sanitizer](example/sanitizer) | Go | 内容清洗/安全过滤 |
|
||||
|
||||
**发版时附带预编译示例产物**：SDK 的 release 除 5 平台 `hmapdev` 外，还包含各示例插件的
|
||||
`.hmap` 与 `SHA256SUMS`/`MANIFEST.txt`。原因是插件二进制与内核**协议绑定**（`ProtocolVersion`
|
||||
+ 共享内存区魔数），只发工具链不发示例产物，很容易拿旧产物去装而握手失败——那看起来像
|
||||
「插件坏了」而不是「版本不配套」。
|
||||
|
||||
## Remote Device SDK
|
||||
|
||||
用于开发**远程设备接入适配器**的 C 语言 SDK，零外部依赖，兼容嵌入式平台。
|
||||
@ -420,10 +599,10 @@ ha_transport_t my_transport = {
|
||||
|
||||
### 使用方式
|
||||
|
||||
通过 `plugindev` 工具链初始化项目：
|
||||
通过 `hmapdev` 工具链初始化项目：
|
||||
|
||||
```bash
|
||||
plugindev init my-adapter --type remotedevice
|
||||
hmapdev init my-adapter --type remotedevice
|
||||
```
|
||||
|
||||
生成 `main.c` + `CMakeLists.txt`，可直接编译或作为三方库引入：
|
||||
@ -635,17 +814,17 @@ curl -X POST http://<homeagent-server>:8080/api/v1/device/esp32-cam-1/cmd \
|
||||
### 位置
|
||||
|
||||
- **SDK 源码**: `remotedevice/`
|
||||
- **plugindev 模板**: `plugindev init --type remotedevice`
|
||||
- **hmapdev 模板**: `hmapdev init --type remotedevice`
|
||||
|
||||
## 构建与安装
|
||||
|
||||
### 构建
|
||||
|
||||
```bash
|
||||
plugindev build
|
||||
hmapdev build
|
||||
```
|
||||
|
||||
输出 `.hmap` 包到 `dist/` 目录（默认 bundle 多平台合集；单平台构建使用 `plugindev build --no-bundle`）。
|
||||
输出 `.hmap` 包到 `dist/` 目录（默认 bundle 多平台合集；单平台构建使用 `hmapdev build --no-bundle`）。
|
||||
|
||||
### 安装
|
||||
|
||||
@ -663,3 +842,16 @@ curl -X POST http://127.0.0.1:9876/plugins \
|
||||
```
|
||||
|
||||
或通过 WebUI 插件管理页面上传，也可手动将 `.hmap` 放入插件目录后重启平台。
|
||||
|
||||
## 许可
|
||||
|
||||
SDK 以 **AGPL-3.0-only** 发布，全文见 [LICENSE](LICENSE)。
|
||||
|
||||
**这对插件开发者是实质性约束**：SDK 会随插件一起**静态链接**（其源码进入插件二进制），
|
||||
插件因此是本 SDK 的衍生作品，**必须以相同许可（AGPL-3.0-only）发布**；并且因为 AGPL §13
|
||||
覆盖网络交互，通过 HTTP/WebSocket 等向用户提供服务的插件同样要向使用者提供源码。
|
||||
若你的插件需要闭源，唯一合规路径是另行取得本项目的例外/商业授权——目前不提供。
|
||||
|
||||
第三方组件（Go 依赖：go-sqlite3、gojieba、bubbletea 等，均为 MIT / BSD-3 / Apache-2.0）
|
||||
保持各自原有许可。平台侧的模型与推理运行时（Chinese-CLIP Apache-2.0、ONNX Runtime MIT）
|
||||
不属于本 SDK，其许可全文随发行包放在 `/usr/share/doc/homeagent/licenses/`。
|
||||
|
||||
252
README_EN.md
252
README_EN.md
@ -2,6 +2,83 @@
|
||||
|
||||
Plugin development SDK for building intelligent plugins that interact with the HomeAgent platform.
|
||||
|
||||
## Version and Compatibility
|
||||
|
||||
Current: **SDK 1.2.0** (requires kernel **1.2.0+**).
|
||||
|
||||
**The version tracks the kernel's minor version, with the patch position pinned at `.0`**:
|
||||
|
||||
| Kernel version | Matching SDK |
|
||||
|---|---|
|
||||
| 1.0.0 / 1.0.1 / … / 1.0.4 | 1.0.0 |
|
||||
| 1.1.0 / 1.1.1 / … / 1.1.N | **1.1.0** |
|
||||
| 1.2.0 onward | 1.2.0 |
|
||||
|
||||
The kernel's patch position is reserved for bugfixes and vulnerability fixes, which never touch the
|
||||
public interface, so the SDK version has no reason to move with it — otherwise you would either be
|
||||
forced to chase releases or suspect your version is stale, when not one character of the interface
|
||||
has changed.
|
||||
|
||||
**Upgrading a 1.0.x plugin to 1.1.x: no code changes, no rebuild.** Everything added in 1.1.0 is
|
||||
in the "plugin calls, kernel implements" direction, so not calling it means not being affected
|
||||
(verified with an old `plugin.bin` built against SDK 0.9.2: it handshakes fine on the new kernel,
|
||||
because the handshake validates `ProtocolVersion`, not the SDK version). Rebuild only when you want
|
||||
the new fields.
|
||||
|
||||
**Upgrading a 1.1.x plugin to 1.2.x: the interface is purely additive, but a rebuild is required.**
|
||||
No public signature changed (the SDK adds `InjectOptions`, six `*Opts` variants and
|
||||
`ChannelDef.ContextPolicy`), so not calling the new capabilities means not being affected — but the
|
||||
kernel's **plugin protocol went to 2** (the fd3 layout of the unified shared-memory region changed,
|
||||
and **rolling upgrades are not supported**). `plugin.bin` must therefore be rebuilt with the matching
|
||||
`hmapdev` and installed **together with** the kernel; otherwise the handshake fails on protocol
|
||||
version mismatch (the error says explicitly to rebuild with the matching hmapdev — it never
|
||||
degrades silently).
|
||||
|
||||
## Injection Behaviour and Context Pruning (1.2.0)
|
||||
|
||||
"Should this go into memory" and "should the context be pruned based on this" used to be
|
||||
something only `ToolDef` could declare. Since 1.2.0 **injections can declare them too**, sharing
|
||||
the same semantics and values.
|
||||
|
||||
```go
|
||||
type InjectOptions struct {
|
||||
NoMemory bool // true = excluded from memory computation (vectorize/keywords/distill); the
|
||||
// original text still stays in context
|
||||
ContextPolicy string // ""/none = do not prune (default); prune = prune context based on this
|
||||
CleanerName string // name of the compute-layer cleaner: run it first to get the effective
|
||||
// content, then compute/prune on that
|
||||
}
|
||||
|
||||
const (
|
||||
ContextPolicyNone = "none"
|
||||
ContextPolicyPrune = "prune"
|
||||
)
|
||||
|
||||
// Six variants, one-to-one with the older three-argument methods, plus opts
|
||||
InjectTextOpts(source, channel, text string, opts InjectOptions)
|
||||
InjectInterruptTextOpts(source, channel, text string, opts InjectOptions)
|
||||
InjectInputSyncOpts(source, channel, text string, opts InjectOptions) string
|
||||
InjectInputMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
|
||||
InjectInputMediaSyncOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) string
|
||||
InjectInterruptMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
|
||||
```
|
||||
|
||||
Key points:
|
||||
|
||||
- **A zero-valued `InjectOptions{}` is key-for-key equivalent to the older three-argument methods**
|
||||
(recorded in memory, not pruned). The old methods remain as zero-value sugar (`InjectText`,
|
||||
`InjectInterruptText`, `InjectTextNoMemory`, …), so existing plugins keep working without a single
|
||||
line changed *or* a rebuild.
|
||||
- **Pruning (`prune`) must be declared explicitly**: it archives/drops low-relevance events, which
|
||||
is a side effect, so it is off by default. The kernel only accepts `""` / `none` / `prune`
|
||||
(`ValidContextPolicy`); anything else is rejected.
|
||||
- Pruning first goes through the plugin's registered **`Cleaner`** (named by `CleanerName`) to get
|
||||
the effective content, avoiding the inconsistency of "prune on the raw text, compute on the
|
||||
cleaned text".
|
||||
- `ChannelDef` carries the same `context_policy` (1.2.0 also gave `ChannelDef` JSON tags — the
|
||||
definition crosses the process boundary, while `Cleaner` is a function that must be ignored; with
|
||||
no tags, newly added fields would be silently dropped).
|
||||
|
||||
## SDK API Surface
|
||||
|
||||
### Plugin Interface
|
||||
@ -36,6 +113,7 @@ The SDK instance injected via `Start(sdk *PluginSDK)` provides:
|
||||
| Settings | `Settings()` | Access settings API |
|
||||
| Events | `Events()` | Access event subscriber (subscribe-only for external plugins) |
|
||||
| Inject | `InjectText(source, channel, text)` / `InjectInterruptText(source, channel, text)` / `InjectTextNoMemory(source, channel, text)` | Inject text into the agent pipeline |
|
||||
| Media inject | `InjectInputMedia(source, channel, text, blocks)` / `InjectInputMediaSync(...)` / `InjectInterruptMedia(...)` | Inject input carrying images/audio (added in 1.1.0) |
|
||||
| Auto-Restart | `SetAutoRestart(enabled)` / `AutoRestart()` | Control automatic restart on crash |
|
||||
|
||||
### Stage Hooks
|
||||
@ -106,6 +184,32 @@ Type enum values:
|
||||
| `InjectInterruptText(source, channel, text)` | Inject interrupt text, interrupt current processing, route to specified channel |
|
||||
| `InjectTextNoMemory(source, channel, text)` | Inject text without memory recording, route to specified channel |
|
||||
|
||||
### Multimodal Injection (added in 1.1.0)
|
||||
|
||||
| Method | Description |
|
||||
|--------|-------------|
|
||||
| `InjectInputMedia(source, channel, text, blocks)` | Inject media-bearing input, asynchronous |
|
||||
| `InjectInputMediaSync(source, channel, text, blocks)` | Inject media-bearing input and wait for the reply text |
|
||||
| `InjectInterruptMedia(source, channel, text, blocks)` | Inject a media-bearing interrupt that can preempt current processing |
|
||||
|
||||
`blocks` is `[]sdk.ContentBlock`, the same type `SetToolBlocks` takes:
|
||||
|
||||
```go
|
||||
s.InjectInputMedia("myplugin", "webui", "take a look at this", []sdk.ContentBlock{{
|
||||
Type: "image_url",
|
||||
ImageURL: &sdk.ImageURL{URL: "data:image/png;base64," + b64, Detail: "auto"},
|
||||
}})
|
||||
```
|
||||
|
||||
How this differs from `SetToolBlocks`: that one is only callable inside a tool handler and
|
||||
its media reaches the model with the *next* tool message. These three let a plugin
|
||||
**initiate a turn that carries media** — the media goes out with this turn's message and is
|
||||
automatically stored in the media store with a memory reference attached.
|
||||
|
||||
`data:` URLs in the blocks are stored and deduplicated by the kernel; `http(s)` URLs are
|
||||
passed to the model only and never stored (storing them would require the kernel to make
|
||||
network requests, bringing timeouts, auth and SSRF into scope).
|
||||
|
||||
`source` identifies the origin, `channel` specifies the target output channel.
|
||||
|
||||
### Triple Extended Fields
|
||||
@ -115,6 +219,65 @@ The Triple data structure includes additional fields:
|
||||
- `Confidence` — confidence score (0.0–1.0)
|
||||
- `SubjectType` — subject type
|
||||
- `ObjectType` — object type
|
||||
- `SentenceText` — the original sentence (added in 1.1.0), written to the `sentences` table; media references hang off the sentence
|
||||
- `MediaDigests` — associated media digests (added in 1.1.0)
|
||||
|
||||
### Media in Memory (added in 1.1.0)
|
||||
|
||||
Inside plain-text memory, media is represented as a **marker** of the form
|
||||
`[<mime> <short digest>] <description>`:
|
||||
|
||||
```
|
||||
[image/png a1b2c3d4e5f6] a purple-blue-red three-band chart
|
||||
```
|
||||
|
||||
The description is the durable semantic memory (retrieval uses it); the digest is the key
|
||||
back to the bytes (reverse lookup uses it). Markers are generated by the kernel — a plugin
|
||||
never has to assemble one, it just **supplies the digest**.
|
||||
|
||||
#### Graph memory
|
||||
|
||||
```go
|
||||
s.Memory().Commit([]sdk.Triple{{
|
||||
Subject: "palette", Relation: "contains", Object: "three-band",
|
||||
MediaDigests: []string{"a1b2c3d4e5f6"}, // short digest is fine, the kernel resolves it
|
||||
}})
|
||||
```
|
||||
|
||||
With no `SentenceText`, the kernel uses the marker itself as the sentence — media must have
|
||||
a sentence to hang off, otherwise the reference has nowhere to attach.
|
||||
|
||||
#### Knowledge base
|
||||
|
||||
```go
|
||||
s.DocMemory().InsertWithMedia(&sdk.Doc{
|
||||
Title: "illustrated note",
|
||||
Content: "body",
|
||||
}, []sdk.MediaAttachment{
|
||||
{MIME: "image/png", Data: pngBytes, Name: "chart.png"}, // new content, stored and deduped
|
||||
{Digest: "a1b2c3d4e5f6"}, // reference existing content
|
||||
})
|
||||
```
|
||||
|
||||
`Insert` keeps its original signature; markers already present in the body are bound as
|
||||
document-level references too. `Query` fills `MediaDigests` and `Attachments` (mime plus
|
||||
description, **no bytes** — one query can match dozens of media items). Removing a document
|
||||
releases its references.
|
||||
|
||||
#### Text memory
|
||||
|
||||
```go
|
||||
s.TextMemory().Append(sdk.TextEvent{
|
||||
Role: "user", Content: "look at this",
|
||||
Attachments: []sdk.MediaAttachment{{MIME: "image/png", Data: pngBytes}},
|
||||
})
|
||||
```
|
||||
|
||||
`RecentEvents` decodes markers in the body back into `Attachments`.
|
||||
|
||||
The media store can be disabled kernel-side (`core.memory.media.enabled=false`); all of the
|
||||
above then degrades to plain-text behaviour — no errors, no panics, identical to how it
|
||||
behaved before this feature shipped.
|
||||
|
||||
### ToolDef Field Reference
|
||||
|
||||
@ -140,19 +303,24 @@ func New(name string, sett SettingsAPI, regTool ToolRegistrar, regStage StageReg
|
||||
|
||||
Plugin developers only need to implement the `Plugin` interface and export a `NewPlugin()` entry function.
|
||||
|
||||
## plugindev Toolchain
|
||||
## hmapdev Toolchain
|
||||
|
||||
`plugindev` provides full development workflow support. Prebuilt binaries ship as **release assets**
|
||||
`hmapdev` provides full development workflow support and produces `.hmap` plugin bundles (the tool is
|
||||
named after that package format). Prebuilt binaries ship as **release assets**
|
||||
(linux/darwin/windows × amd64/arm64); download from
|
||||
[Releases](https://gitcode.com/JianFeeeee/homeagent-sdk/releases) and put it on your PATH:
|
||||
|
||||
> Rename note: the toolchain was called `plugindev` and is `hmapdev` since 1.2.0.
|
||||
> The SDK store moved from `~/.homeagent/plugindev/sdk` to `~/.homeagent/hmapdev/sdk`
|
||||
> (the old directory is still honored, so installed versions are not lost).
|
||||
|
||||
```bash
|
||||
# From release assets (v1.0.0 / linux amd64 shown)
|
||||
curl -Lo plugindev https://gitcode.com/JianFeeeee/homeagent-sdk/releases/download/v1.0.0/plugindev_linux_amd64
|
||||
chmod +x plugindev
|
||||
# From release assets (latest SDK release / linux amd64 shown)
|
||||
curl -Lo hmapdev https://gitcode.com/JianFeeeee/homeagent-sdk/releases/download/<version>/hmapdev_linux_amd64
|
||||
chmod +x hmapdev
|
||||
|
||||
# Or build from source
|
||||
cd tools/plugindev && go build -o plugindev .
|
||||
cd tools/hmapdev && go build -o hmapdev .
|
||||
```
|
||||
|
||||
> Binaries no longer ship inside the repository (the old `bin/` directory is retired): five
|
||||
@ -161,11 +329,11 @@ cd tools/plugindev && go build -o plugindev .
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `plugindev init <name> [--lua]` | Initialize plugin project (generates plg.json, plugin.go or main.lua, go.mod, README.md) |
|
||||
| `plugindev build [flags]` | Build and package into a `.hmap` (supports cross-compilation and bundle mode) |
|
||||
| `plugindev clean` | Clean `build/` and `dist/` plus generated files |
|
||||
| `plugindev debug [dir]` | Load plugin source through the Yaegi Go interpreter and start an interactive REPL |
|
||||
| `plugindev sdk <command>` | SDK version management (list/install/use/path/current/latest) |
|
||||
| `hmapdev init <name> [--lua]` | Initialize plugin project (generates plg.json, plugin.go or main.lua, go.mod, README.md) |
|
||||
| `hmapdev build [flags]` | Build and package into a `.hmap` (supports cross-compilation and bundle mode) |
|
||||
| `hmapdev clean` | Clean `build/` and `dist/` plus generated files |
|
||||
| `hmapdev debug [dir]` | Load plugin source through the Yaegi Go interpreter and start an interactive REPL |
|
||||
| `hmapdev sdk <command>` | SDK version management (list/install/use/path/current/latest) |
|
||||
|
||||
Supports both **Go** and **Lua** plugin languages.
|
||||
|
||||
@ -237,7 +405,7 @@ Supports both **Go** and **Lua** plugin languages.
|
||||
|
||||
- `sdk.RegisterOnRemoveHandler(fn func())` — Register a remove cleanup callback. The kernel runs it **after** the plugin's `Stop()` in the `RemovePlugin` flow (LIFO order, cleared after running — idempotent). Use it to delete persistent files the plugin created itself (data/cache/state files).
|
||||
- The kernel also cleans up on uninstall: tool registrations, the `disabled_plugins` record, the plugin's config definitions (`plugin.<name>.*`) and its config table (`config_<name>`) — the plugin's config section disappears completely after removal.
|
||||
- Examples: `example/calendar` (removes events.json), `example/memo` (removes memos.json), `example/rss` (removes the subscription data dir), `example/weather` (removes the cache dir); the `plugindev` template includes an onRemove demo.
|
||||
- Examples: `example/calendar` (removes events.json), `example/memo` (removes memos.json), `example/rss` (removes the subscription data dir), `example/weather` (removes the cache dir); the `hmapdev` template includes an onRemove demo.
|
||||
|
||||
```go
|
||||
sdk.RegisterOnRemoveHandler(func() {
|
||||
@ -255,6 +423,33 @@ enabled := sdk.AutoRestart()
|
||||
|
||||
The platform automatically restarts the plugin on crash, ensuring service availability.
|
||||
|
||||
> ⚠️ `SetAutoRestart` is typically used to decide whether auto-restart is safe *after* an
|
||||
> external connection has been established, and that connection setup usually happens in a
|
||||
> background goroutine while the kernel reads the flag from another one — which is inherently
|
||||
> concurrent. **SDK 1.1.0 locks this flag and all API fields** (`-race` reported 11 data races;
|
||||
> in production this showed up as sporadic nil-dereference crashes during plugin reload). Upgrade
|
||||
> if you are on anything earlier.
|
||||
|
||||
## Concurrency Contract for Plugin Developers
|
||||
|
||||
`PluginSDK` is a **shared object used by multiple goroutines**: the polling, listening and timer
|
||||
callbacks you start in `Start()` all hold the same `*PluginSDK` and push messages into it, while
|
||||
the kernel writes its API fields during load/reload. So:
|
||||
|
||||
- **Guaranteed by the SDK**: all API accessors (`Memory()`/`DocMemory()`/…), all injection methods,
|
||||
`SetAutoRestart`/`AutoRestart`, `RegisterTool`/`RegisterStage`, and
|
||||
`RunStopHandlers`/`RunOnRemoveHandlers` (idempotent; concurrent calls still run it once).
|
||||
- **Your responsibility**: every field of `StageContext` is exported, and concurrent read/write
|
||||
must hold `ctx.Lock()`/`ctx.RLock()`. Especially `ctx.Extra` — **concurrent map writes are a
|
||||
fatal in Go, and `recover` cannot catch it**.
|
||||
|
||||
```go
|
||||
ctx.Lock()
|
||||
ctx.Extra["mykey"] = value
|
||||
ctx.FinalText += "supplementary note"
|
||||
ctx.Unlock()
|
||||
```
|
||||
|
||||
## Restricted SDK vs Full SDK
|
||||
|
||||
External plugins (third-party distribution) use a **restricted SDK** that only exposes a safe subset:
|
||||
@ -286,6 +481,13 @@ Internal plugins (platform built-in) have full SDK access including SocialAPI wr
|
||||
| [rss](example/rss) | Go | RSS subscriptions |
|
||||
| [sanitizer](example/sanitizer) | Go | Content sanitization / safety filtering |
|
||||
|
||||
**Prebuilt example artifacts ship with every release**: besides the 5-platform `hmapdev`, an SDK
|
||||
release contains the example plugins' `.hmap` files plus `SHA256SUMS`/`MANIFEST.txt`. The reason is
|
||||
that plugin binaries are **protocol-bound** to the kernel (`ProtocolVersion` + the shared-memory
|
||||
magic), so shipping the toolchain without matching artifacts invites installing an old artifact —
|
||||
which fails the handshake and looks like "the plugin is broken" rather than "the versions don't
|
||||
match".
|
||||
|
||||
## Remote Device SDK
|
||||
|
||||
A C language SDK for developing **remote device access adapters** with zero external dependencies, compatible with embedded platforms.
|
||||
@ -370,10 +572,10 @@ ha_transport_t my_transport = {
|
||||
|
||||
### Usage
|
||||
|
||||
Initialize a project via the `plugindev` toolchain:
|
||||
Initialize a project via the `hmapdev` toolchain:
|
||||
|
||||
```bash
|
||||
plugindev init my-adapter --type remotedevice
|
||||
hmapdev init my-adapter --type remotedevice
|
||||
```
|
||||
|
||||
Generates `main.c` + `CMakeLists.txt`, can be built directly or used as a third-party library:
|
||||
@ -583,17 +785,17 @@ curl -X POST http://<homeagent-server>:8080/api/v1/device/esp32-cam-1/cmd \
|
||||
### Location
|
||||
|
||||
- **SDK Source**: `remotedevice/`
|
||||
- **plugindev template**: `plugindev init --type remotedevice`
|
||||
- **hmapdev template**: `hmapdev init --type remotedevice`
|
||||
|
||||
## Building & Installing
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
plugindev build
|
||||
hmapdev build
|
||||
```
|
||||
|
||||
Outputs a `.hmap` package to the `dist/` directory (default is the multi-platform bundle; use `plugindev build --no-bundle` for a single-target build).
|
||||
Outputs a `.hmap` package to the `dist/` directory (default is the multi-platform bundle; use `hmapdev build --no-bundle` for a single-target build).
|
||||
|
||||
### Install
|
||||
|
||||
@ -611,3 +813,19 @@ curl -X POST http://127.0.0.1:9876/plugins \
|
||||
```
|
||||
|
||||
Or upload via the WebUI plugin management page, or manually place the `.hmap` in the plugin directory and restart the platform.
|
||||
|
||||
## License
|
||||
|
||||
The SDK is released under **AGPL-3.0-only** — see [LICENSE](LICENSE).
|
||||
|
||||
**This is a substantive constraint for plugin developers**: the SDK is **statically linked** into
|
||||
your plugin (its source ends up in the plugin binary), so the plugin is a derivative work of
|
||||
this SDK and **must be released under the same license**. Because AGPL §13 covers network
|
||||
interaction, a plugin that serves users over HTTP/WebSocket must also offer them the source.
|
||||
If you need a closed-source plugin, the only compliant route is a separate exception/commercial
|
||||
license from this project — none is offered today.
|
||||
|
||||
Third-party components (Go dependencies: go-sqlite3, gojieba, bubbletea, … — MIT / BSD-3 /
|
||||
Apache-2.0) keep their own licenses. The platform-side model and inference runtime
|
||||
(Chinese-CLIP Apache-2.0, ONNX Runtime MIT) are not part of this SDK; their full license texts
|
||||
ship with the release packages under `/usr/share/doc/homeagent/licenses/`.
|
||||
|
||||
@ -5,7 +5,7 @@ ai_image plugin
|
||||
## Build
|
||||
|
||||
```bash
|
||||
plugindev build
|
||||
hmapdev build
|
||||
```
|
||||
|
||||
## Install
|
||||
|
||||
@ -5,7 +5,7 @@ calendar plugin
|
||||
## Build
|
||||
|
||||
```bash
|
||||
plugindev build
|
||||
hmapdev build
|
||||
```
|
||||
|
||||
## Install
|
||||
|
||||
@ -520,7 +520,8 @@ func (p *Plugin) checkReminders() {
|
||||
p.mu.Unlock()
|
||||
|
||||
for _, msg := range injectMsgs {
|
||||
p.sdk.InjectInterruptText("calendar", "calendar", msg)
|
||||
// NoMemory：日程到点提醒，不是记忆内容。
|
||||
p.sdk.InjectInterruptTextOpts("calendar", "calendar", msg, sdk.InjectOptions{NoMemory: true})
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@ -17,7 +17,7 @@ lua main.lua # 使用 sdk.lua mock，不依赖内核
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
plugindev build
|
||||
hmapdev build
|
||||
```
|
||||
|
||||
## 安装
|
||||
|
||||
@ -292,8 +292,9 @@ func (p *Plugin) periodicCheck() {
|
||||
continue
|
||||
}
|
||||
if p.sdk != nil {
|
||||
p.sdk.InjectInterruptText(p.name, p.name,
|
||||
fmt.Sprintf("注意，你还有%d条待办未完成，请检查", n))
|
||||
// NoMemory：这是定时提醒，不是记忆内容。
|
||||
p.sdk.InjectInterruptTextOpts(p.name, p.name,
|
||||
fmt.Sprintf("注意，你还有%d条待办未完成，请检查", n), sdk.InjectOptions{NoMemory: true})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
"name": "qq",
|
||||
"name_zh": "QQ消息",
|
||||
"name_en": "qq",
|
||||
"version": "1.2.0",
|
||||
"version": "1.4.0",
|
||||
"description": "QQ 消息收发插件，通过 NapCat 协议桥接",
|
||||
"author": "HomeAgent",
|
||||
"entry": "plugin.so",
|
||||
|
||||
@ -85,6 +85,34 @@ type DownloadTask struct {
|
||||
CreatedAt string `json:"created_at"`
|
||||
}
|
||||
|
||||
type qqAuthContext struct {
|
||||
active bool
|
||||
owner bool
|
||||
messageID int64
|
||||
userID int64
|
||||
groupID int64
|
||||
isGroup bool
|
||||
generation uint64
|
||||
}
|
||||
|
||||
var qqMessageIDRe = regexp.MustCompile(`message_id=(-?\d+)`)
|
||||
|
||||
// 默认只开放公共信息与当前 QQ 会话所需能力。日历、邮件、记忆、知识库、
|
||||
// 主机文件/命令、设备、配置、插件管理及 QQ 联系人/跨会话列表均不在白名单中。
|
||||
const defaultPublicToolAllowlist = `["output_send__qq","output_list_channels","qq_get_message","qq_get_history","qq_mark_read","qq_get_group_member_info","qq_get_group_files","qq_video_download","weather_*","browser_search","browser_fetch","browser_render","ocr_*","multimodal_*","bili_*","music_*","ai_image_*"]`
|
||||
|
||||
const defaultGroupToolAllowlists = `{"*":["output_send__qq","output_list_channels","qq_get_message","qq_get_history","qq_mark_read","qq_get_group_member_info","qq_get_group_files","qq_video_download","weather_*","browser_search","browser_fetch","browser_render","ocr_*","multimodal_*","bili_*","music_*","ai_image_*"]}`
|
||||
|
||||
const (
|
||||
// 单轮 QQ 触发的工具调用总数上限（0 = 不限制）。只作跑飞兜底，
|
||||
// 不应拦下正常的长时间多步任务。
|
||||
defaultMaxQQToolCalls = 200
|
||||
// 单轮 QQ 主动发送的不同消息条数上限（0 = 不限制）。
|
||||
defaultMaxQQOutputCalls = 20
|
||||
// 单轮内同一条消息（参数完全相同）允许重复发送的次数（0 = 不限制）。
|
||||
defaultMaxDuplicateSend = 1
|
||||
)
|
||||
|
||||
type Plugin struct {
|
||||
name string
|
||||
sdk *sdk.PluginSDK
|
||||
@ -93,7 +121,7 @@ type Plugin struct {
|
||||
remoteDir string
|
||||
filesDir string
|
||||
webhookToken string
|
||||
adminIDs []int64
|
||||
ownerIDs []int64
|
||||
botID int64
|
||||
botNickname string
|
||||
dmPolicy string
|
||||
@ -108,12 +136,26 @@ type Plugin struct {
|
||||
typingMu sync.Mutex
|
||||
typingMap map[int64]*typingState
|
||||
|
||||
// msg_id → peer 映射 + 会话最新状态（<7 天兜底 get_history + list_chats）
|
||||
msgMu sync.Mutex
|
||||
msgMap map[int64]msgRef // message_id → {peer, time}
|
||||
chats map[int64]*chatMeta // peerID → 会话状态（群号或 QQ 号）
|
||||
}
|
||||
authMu sync.RWMutex
|
||||
auth qqAuthContext
|
||||
authGeneration uint64
|
||||
authByMessageID map[int64]qqAuthContext
|
||||
lastDenial string
|
||||
denialLocked bool
|
||||
toolCallCount int
|
||||
outputCallCount int
|
||||
outputSignatures map[string]int
|
||||
maxQQToolCalls int
|
||||
maxQQOutputCalls int
|
||||
maxDuplicateSend int
|
||||
groupToolAllowlists map[int64][]string // 0 表示通配配置 "*"
|
||||
privateToolAllowlist []string
|
||||
|
||||
// msg_id → peer 映射 + 会话最新状态（<7 天兜底 get_history + list_chats）
|
||||
msgMu sync.Mutex
|
||||
msgMap map[int64]msgRef // message_id → {peer, time}
|
||||
chats map[int64]*chatMeta // peerID → 会话状态（群号或 QQ 号）
|
||||
}
|
||||
|
||||
type typingState struct {
|
||||
userID int64
|
||||
@ -258,7 +300,13 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{Key: "listen", Default: "0.0.0.0:25580", Type: "string", DisplayName: "监听地址", Description: "Webhook HTTP 监听地址", Category: "qq"})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{Key: "napcat_url", Default: "http://127.0.0.1:3000", Type: "string", DisplayName: "NapCat 地址", Description: "NapCat HTTP API 基础 URL", Category: "qq"})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{Key: "admin", Default: "", Type: "string", DisplayName: "管理员 QQ", Description: "管理员 QQ 号列表，逗号分隔。收到其消息时标记【重要！老大消息】", Category: "qq"})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{Key: "owner", Default: "", Type: "string", DisplayName: "Bot 所有者 QQ", Description: "Bot 所有者 QQ 号列表，逗号分隔。所有者无论私聊或群聊均拥有完整工具权限", Category: "qq"})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{Key: "admin", Default: "", Type: "string", DisplayName: "Bot 所有者 QQ（旧配置）", Description: "兼容旧版 admin 配置；owner 为空时作为 Bot 所有者列表", Category: "qq"})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{Key: "group_tool_allowlists", Default: defaultGroupToolAllowlists, Type: "string", DisplayName: "群聊工具白名单", Description: "JSON 对象：群号到允许工具名/前缀*的数组；* 为未单独配置群的默认白名单。Bot 所有者不受限制", Category: "qq"})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{Key: "private_tool_allowlist", Default: defaultPublicToolAllowlist, Type: "string", DisplayName: "非所有者私聊工具白名单", Description: "JSON 数组，支持工具精确名和尾部 * 前缀。硬性私人资源工具不能由此白名单放行；Bot 所有者不受权限限制", Category: "qq"})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{Key: "max_qq_tool_calls", Default: defaultMaxQQToolCalls, Type: "int", DisplayName: "单轮 QQ 工具调用上限", Description: "QQ 输入触发的单轮推理最多调用工具次数（0=不限制）；仅作跑飞兜底，不拦参数不同的必需调用", Category: "qq"})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{Key: "max_qq_output_calls", Default: defaultMaxQQOutputCalls, Type: "int", DisplayName: "单轮 QQ 发送上限", Description: "单轮最多主动发送的不同消息条数（0=不限制）；参数不同的消息不视为重复", Category: "qq"})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{Key: "max_duplicate_qq_send", Default: defaultMaxDuplicateSend, Type: "int", DisplayName: "单轮相同 QQ 发送上限", Description: "单轮内参数完全相同的 output_send__qq 允许重复的次数（0=不限制）；这才是循环保险的真正触发条件", Category: "qq"})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{Key: "dm_policy", Default: "open", Type: "string", DisplayName: "私聊策略", Description: "open / allowlist / disabled", Category: "qq", Options: []string{"open", "allowlist", "disabled"}})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{Key: "allow_from", Default: "", Type: "string", DisplayName: "私聊白名单", Description: "允许私聊机器人的 QQ 号列表，逗号分隔", Category: "qq"})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{Key: "group_policy", Default: "open", Type: "string", DisplayName: "群聊策略", Description: "open / allowlist / disabled", Category: "qq", Options: []string{"open", "allowlist", "disabled"}})
|
||||
@ -274,7 +322,16 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
p.listenAddr = getSetting[string](settings, "listen", "0.0.0.0:25580")
|
||||
p.webhookToken = getSetting[string](settings, "webhook_token", "")
|
||||
p.napcatURL = strings.TrimRight(getSetting[string](settings, "napcat_url", "http://127.0.0.1:3000"), "/")
|
||||
p.adminIDs = parseIDList(getSetting[string](settings, "admin", ""))
|
||||
ownerRaw := getSetting[string](settings, "owner", "")
|
||||
if strings.TrimSpace(ownerRaw) == "" {
|
||||
ownerRaw = getSetting[string](settings, "admin", "")
|
||||
}
|
||||
p.ownerIDs = parseIDList(ownerRaw)
|
||||
p.groupToolAllowlists = parseGroupToolAllowlists(getSetting[string](settings, "group_tool_allowlists", defaultGroupToolAllowlists))
|
||||
p.privateToolAllowlist = parseToolAllowlist(getSetting[string](settings, "private_tool_allowlist", defaultPublicToolAllowlist))
|
||||
p.maxQQToolCalls = nonNegativeOrDefault(int(getSetting[int64](settings, "max_qq_tool_calls", int64(defaultMaxQQToolCalls))), defaultMaxQQToolCalls)
|
||||
p.maxQQOutputCalls = nonNegativeOrDefault(int(getSetting[int64](settings, "max_qq_output_calls", int64(defaultMaxQQOutputCalls))), defaultMaxQQOutputCalls)
|
||||
p.maxDuplicateSend = nonNegativeOrDefault(int(getSetting[int64](settings, "max_duplicate_qq_send", int64(defaultMaxDuplicateSend))), defaultMaxDuplicateSend)
|
||||
p.dmPolicy = normalizePolicy(getSetting[string](settings, "dm_policy", "open"))
|
||||
p.groupPolicy = normalizePolicy(getSetting[string](settings, "group_policy", "open"))
|
||||
p.allowFrom = parseIDSet(getSetting[string](settings, "allow_from", ""))
|
||||
@ -312,10 +369,11 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
`发送QQ群聊/私聊消息，支持文字、语音、图片、文件。
|
||||
meta JSON 格式：
|
||||
{
|
||||
"group_id": 123456, // 群号（与 user_id 二选一）
|
||||
"user_id": 123456, // QQ号（与 group_id 二选一）
|
||||
"group_id": 123456, // 群号
|
||||
"user_id": 123456, // QQ号
|
||||
"reply_to": 12345 // 可选，回复指定消息 ID
|
||||
}
|
||||
路由规则：仅 group_id 发群；仅 user_id 发私聊；两者同时存在时发到 group_id，并在消息头 @user_id。
|
||||
type 枚举: text（文字）/ voice（语音转文字后发送）/ image（图片URL）/ file（文件URL）`,
|
||||
sdk.ChannelDef{}, p.handleChannelOutput)
|
||||
|
||||
@ -354,6 +412,10 @@ type 枚举: text（文字）/ voice（语音转文字后发送）/ image（图
|
||||
Name: tp + "get_message", Description: botInfo + "通过 message_id 从 NapCat 实时获取消息正文、发送者、附件等信息。message_id 从中断消息的 message_id=N 获取，或从 reply_to 的 message_id 获取。",
|
||||
NoMemory: false,
|
||||
Cleaner: cleaner,
|
||||
// 消息正文只在当轮需要（决策怎么回复）；用完即裁剪。
|
||||
// 不裁的后果是每条 QQ 消息的完整正文都留在 L0 上下文里，
|
||||
// 长会话下持续挤占 token 预算（§13.8）。
|
||||
ContextPolicy: "prune",
|
||||
Parameters: map[string]interface{}{
|
||||
"type": "object", "properties": map[string]interface{}{
|
||||
"message_id": map[string]interface{}{"type": "integer", "description": "NapCat消息ID（从中断消息的 message_id=N 或 reply_to.message_id 获取）"},
|
||||
@ -599,7 +661,13 @@ type 枚举: text（文字）/ voice（语音转文字后发送）/ image（图
|
||||
NoMemory: true,
|
||||
}, p.handleSendLike)
|
||||
|
||||
s.RegisterStage(sdk.StageBeforeToolcall, p.beforeOwnToolcall, sdk.StageScopeOwnTools)
|
||||
// 全局权限门：只有 QQ 当前输入需要受此插件约束；Bot 所有者始终完整放行。
|
||||
s.RegisterStage(sdk.StageOnInput, p.onInputAuthContext, sdk.StageScopeGlobal)
|
||||
s.RegisterStage(sdk.StageBeforeToolcall, p.beforeToolcall, sdk.StageScopeGlobal)
|
||||
// before_toolcall 的 Response 只用于拒绝当前工具。下一次模型补全到达时必须清掉，
|
||||
// 否则内核会把它误当作“结束整个推理”的最终响应。
|
||||
s.RegisterStage(sdk.StagePostAction, p.clearDeniedResponse, sdk.StageScopeGlobal)
|
||||
s.RegisterStage(sdk.StageAfterOutput, p.afterOutputAuthContext, sdk.StageScopeGlobal)
|
||||
|
||||
// ---- HTTP server for NapCat webhook ----
|
||||
mux := http.NewServeMux()
|
||||
@ -757,8 +825,8 @@ func parseIDList(raw string) []int64 {
|
||||
return out
|
||||
}
|
||||
|
||||
func (p *Plugin) isAdmin(userID int64) bool {
|
||||
for _, id := range p.adminIDs {
|
||||
func (p *Plugin) isOwner(userID int64) bool {
|
||||
for _, id := range p.ownerIDs {
|
||||
if id == userID {
|
||||
return true
|
||||
}
|
||||
@ -766,6 +834,261 @@ func (p *Plugin) isAdmin(userID int64) bool {
|
||||
return false
|
||||
}
|
||||
|
||||
func parseToolAllowlist(raw string) []string {
|
||||
var patterns []string
|
||||
if json.Unmarshal([]byte(raw), &patterns) != nil {
|
||||
return nil
|
||||
}
|
||||
out := make([]string, 0, len(patterns))
|
||||
for _, pattern := range patterns {
|
||||
if pattern = strings.TrimSpace(pattern); pattern != "" {
|
||||
out = append(out, pattern)
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func parseGroupToolAllowlists(raw string) map[int64][]string {
|
||||
var encoded map[string][]string
|
||||
if json.Unmarshal([]byte(raw), &encoded) != nil {
|
||||
return map[int64][]string{}
|
||||
}
|
||||
out := make(map[int64][]string, len(encoded))
|
||||
for key, patterns := range encoded {
|
||||
var groupID int64
|
||||
if key != "*" {
|
||||
parsed, err := strconv.ParseInt(strings.TrimSpace(key), 10, 64)
|
||||
if err != nil || parsed <= 0 {
|
||||
continue
|
||||
}
|
||||
groupID = parsed
|
||||
}
|
||||
clean := make([]string, 0, len(patterns))
|
||||
for _, pattern := range patterns {
|
||||
if pattern = strings.TrimSpace(pattern); pattern != "" {
|
||||
clean = append(clean, pattern)
|
||||
}
|
||||
}
|
||||
out[groupID] = clean
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func matchesToolAllowlist(name string, patterns []string) bool {
|
||||
for _, pattern := range patterns {
|
||||
if pattern == name {
|
||||
return true
|
||||
}
|
||||
if strings.HasSuffix(pattern, "*") && strings.HasPrefix(name, strings.TrimSuffix(pattern, "*")) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// nonNegativeOrDefault 保留 0（表示“不限制”），仅把负数纠正为默认值。
|
||||
func nonNegativeOrDefault(value, fallback int) int {
|
||||
if value < 0 {
|
||||
return fallback
|
||||
}
|
||||
return value
|
||||
}
|
||||
|
||||
// isHardPrivateTool 是不可由群/私聊白名单覆盖的私人资源边界。
|
||||
// output_send__qq 及 QQ 当前会话工具在参数级另行约束，不在此处按名称误杀。
|
||||
func isHardPrivateTool(name string) bool {
|
||||
for _, prefix := range []string{
|
||||
"calendar_", "email_", "mail_", "agentmail_", "memory_", "knowledge_",
|
||||
"device_", "devicectl_", "terminal_", "shell_", "command_", "exec_",
|
||||
"filesystem_", "agentfs_", "config_", "settings_", "plugin_", "plugins_",
|
||||
} {
|
||||
if strings.HasPrefix(name, prefix) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return matchesToolAllowlist(name, []string{
|
||||
"read_file", "write_file", "edit_file", "delete_file", "list_files", "run_command",
|
||||
"homeagent_config", "homeagent_restart", "output_send__email", "output_send__mail",
|
||||
})
|
||||
}
|
||||
|
||||
func argInt64(args map[string]interface{}, key string) (int64, bool) {
|
||||
value, exists := args[key]
|
||||
if !exists || value == nil {
|
||||
return 0, false
|
||||
}
|
||||
parsed, err := convInt64(value)
|
||||
return parsed, err == nil && parsed != 0
|
||||
}
|
||||
|
||||
func (p *Plugin) sessionToolArgsAllowed(name string, args map[string]interface{}, auth qqAuthContext) (bool, string) {
|
||||
if !auth.active || auth.owner {
|
||||
return true, ""
|
||||
}
|
||||
currentPeer := auth.userID
|
||||
if auth.isGroup {
|
||||
currentPeer = auth.groupID
|
||||
}
|
||||
if currentPeer == 0 {
|
||||
return false, "可信 QQ 会话身份不完整"
|
||||
}
|
||||
matchCurrentPeer := func() bool {
|
||||
groupID, hasGroup := argInt64(args, "group_id")
|
||||
userID, hasUser := argInt64(args, "user_id")
|
||||
if auth.isGroup {
|
||||
return hasGroup && groupID == auth.groupID && !hasUser
|
||||
}
|
||||
return hasUser && userID == auth.userID && !hasGroup
|
||||
}
|
||||
|
||||
switch name {
|
||||
case p.name + "_get_history", p.name + "_mark_read":
|
||||
if !matchCurrentPeer() {
|
||||
return false, "只能访问当前 QQ 会话"
|
||||
}
|
||||
case p.name + "_get_message":
|
||||
messageID, ok := argInt64(args, "message_id")
|
||||
if !ok {
|
||||
return false, "缺少有效 message_id"
|
||||
}
|
||||
if messageID == auth.messageID {
|
||||
return true, ""
|
||||
}
|
||||
peerID, isGroup, _, found := p.lookupMsgRef(messageID)
|
||||
if !found || isGroup != auth.isGroup || peerID != currentPeer {
|
||||
return false, "message_id 不属于当前 QQ 会话"
|
||||
}
|
||||
case p.name + "_get_group_member_info", p.name + "_get_group_files":
|
||||
groupID, ok := argInt64(args, "group_id")
|
||||
if !auth.isGroup || !ok || groupID != auth.groupID {
|
||||
return false, "只能访问当前 QQ 群的数据"
|
||||
}
|
||||
}
|
||||
return true, ""
|
||||
}
|
||||
|
||||
// activateAuthContext 只接收 OneBot 事件中的可信 ID。多个中断在同一推理轮合并时
|
||||
// 采用最小权限合并，防止“非所有者请求 + 随后所有者消息”意外提升前一请求权限。
|
||||
// message_id 映射供排队输入在 StageOnInput 精确恢复身份，不依赖昵称或用户正文。
|
||||
func (p *Plugin) activateAuthContext(messageID, userID, groupID int64, isGroup bool) {
|
||||
p.authMu.Lock()
|
||||
defer p.authMu.Unlock()
|
||||
if p.authByMessageID == nil {
|
||||
p.authByMessageID = make(map[int64]qqAuthContext)
|
||||
}
|
||||
p.authGeneration++
|
||||
next := qqAuthContext{
|
||||
active: true, owner: p.isOwner(userID), messageID: messageID, userID: userID,
|
||||
groupID: groupID, isGroup: isGroup, generation: p.authGeneration,
|
||||
}
|
||||
if messageID != 0 {
|
||||
p.authByMessageID[messageID] = next
|
||||
if len(p.authByMessageID) > 2048 {
|
||||
cutoff := p.authGeneration - 1024
|
||||
for id, auth := range p.authByMessageID {
|
||||
if auth.generation < cutoff {
|
||||
delete(p.authByMessageID, id)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
if !p.auth.active {
|
||||
p.auth = next
|
||||
return
|
||||
}
|
||||
if p.auth.userID == userID && p.auth.groupID == groupID && p.auth.isGroup == isGroup {
|
||||
p.auth.owner = p.auth.owner && next.owner
|
||||
p.auth.messageID = next.messageID
|
||||
p.auth.generation = next.generation
|
||||
return
|
||||
}
|
||||
// 不同可信来源被内核合并到同一推理时，只在双方都是所有者时保留完整权限。
|
||||
bothOwners := p.auth.owner && next.owner
|
||||
sameGroup := p.auth.isGroup && next.isGroup && p.auth.groupID == groupID
|
||||
p.auth.owner = bothOwners
|
||||
p.auth.messageID = 0
|
||||
p.auth.userID = 0
|
||||
p.auth.isGroup = sameGroup
|
||||
if sameGroup {
|
||||
p.auth.groupID = groupID
|
||||
} else {
|
||||
p.auth.groupID = 0
|
||||
}
|
||||
p.auth.generation = next.generation
|
||||
}
|
||||
|
||||
func messageIDFromInput(raw string) int64 {
|
||||
match := qqMessageIDRe.FindStringSubmatch(raw)
|
||||
if len(match) != 2 {
|
||||
return 0
|
||||
}
|
||||
id, _ := strconv.ParseInt(match[1], 10, 64)
|
||||
return id
|
||||
}
|
||||
|
||||
func (p *Plugin) onInputAuthContext(ctx *sdk.StageContext) error {
|
||||
ctx.RLock()
|
||||
source, _ := ctx.Extra["input_source"].(string)
|
||||
raw := ctx.RawMessage
|
||||
ctx.RUnlock()
|
||||
p.authMu.Lock()
|
||||
defer p.authMu.Unlock()
|
||||
if source != p.name {
|
||||
p.auth = qqAuthContext{}
|
||||
p.resetTurnGuardLocked()
|
||||
return nil
|
||||
}
|
||||
if messageID := messageIDFromInput(raw); messageID != 0 {
|
||||
if auth, ok := p.authByMessageID[messageID]; ok {
|
||||
p.auth = auth
|
||||
delete(p.authByMessageID, messageID)
|
||||
p.resetTurnGuardLocked()
|
||||
return nil
|
||||
}
|
||||
}
|
||||
// QQ 来源却无法精确匹配可信 OneBot 事件时必须强制降权，不能复用上一条消息的身份。
|
||||
p.auth = qqAuthContext{active: true}
|
||||
p.resetTurnGuardLocked()
|
||||
return nil
|
||||
}
|
||||
|
||||
func (p *Plugin) resetTurnGuardLocked() {
|
||||
p.lastDenial = ""
|
||||
p.denialLocked = false
|
||||
p.toolCallCount = 0
|
||||
p.outputCallCount = 0
|
||||
p.outputSignatures = make(map[string]int)
|
||||
}
|
||||
|
||||
func (p *Plugin) afterOutputAuthContext(ctx *sdk.StageContext) error {
|
||||
p.authMu.Lock()
|
||||
p.auth = qqAuthContext{}
|
||||
p.resetTurnGuardLocked()
|
||||
p.authMu.Unlock()
|
||||
return nil
|
||||
}
|
||||
|
||||
func (p *Plugin) currentToolAllowed(name string) (bool, qqAuthContext) {
|
||||
p.authMu.RLock()
|
||||
auth := p.auth
|
||||
var patterns []string
|
||||
if auth.active && !auth.owner {
|
||||
if auth.isGroup {
|
||||
patterns, _ = p.groupToolAllowlists[auth.groupID]
|
||||
if patterns == nil {
|
||||
patterns = p.groupToolAllowlists[0]
|
||||
}
|
||||
} else {
|
||||
patterns = p.privateToolAllowlist
|
||||
}
|
||||
}
|
||||
p.authMu.RUnlock()
|
||||
if !auth.active || auth.owner {
|
||||
return true, auth
|
||||
}
|
||||
return matchesToolAllowlist(name, patterns), auth
|
||||
}
|
||||
|
||||
// isAtBot checks if the message contains an @-mention of the bot.
|
||||
func (p *Plugin) isAtBot(msg interface{}) bool {
|
||||
segments, ok := msg.([]interface{})
|
||||
@ -824,19 +1147,110 @@ func (p *Plugin) isGroupAllowed(groupID int64) bool {
|
||||
}
|
||||
}
|
||||
|
||||
func (p *Plugin) beforeOwnToolcall(ctx *sdk.StageContext) error {
|
||||
func (p *Plugin) setDenial(ctx *sdk.StageContext, message string) {
|
||||
ctx.Response = &message
|
||||
p.authMu.Lock()
|
||||
p.lastDenial = message
|
||||
p.authMu.Unlock()
|
||||
}
|
||||
|
||||
func (p *Plugin) clearPreviousDenial(ctx *sdk.StageContext) {
|
||||
p.authMu.Lock()
|
||||
last := p.lastDenial
|
||||
p.lastDenial = ""
|
||||
p.authMu.Unlock()
|
||||
if last != "" && ctx.Response != nil && *ctx.Response == last {
|
||||
ctx.Response = nil
|
||||
}
|
||||
}
|
||||
|
||||
func (p *Plugin) clearDeniedResponse(ctx *sdk.StageContext) error {
|
||||
ctx.Lock()
|
||||
defer ctx.Unlock()
|
||||
p.clearPreviousDenial(ctx)
|
||||
return nil
|
||||
}
|
||||
|
||||
func (p *Plugin) beforeToolcall(ctx *sdk.StageContext) error {
|
||||
ctx.Lock()
|
||||
defer ctx.Unlock()
|
||||
p.clearPreviousDenial(ctx)
|
||||
if len(ctx.ToolCalls) == 0 {
|
||||
return nil
|
||||
}
|
||||
tc := &ctx.ToolCalls[0]
|
||||
allowed, auth := p.currentToolAllowed(tc.Name)
|
||||
if !auth.active {
|
||||
return nil
|
||||
}
|
||||
|
||||
p.authMu.Lock()
|
||||
p.toolCallCount++
|
||||
toolCount := p.toolCallCount
|
||||
denialLocked := p.denialLocked
|
||||
if tc.Name == "output_send__"+p.name {
|
||||
p.outputCallCount++
|
||||
signatureBytes, _ := json.Marshal(tc.Arguments)
|
||||
signature := string(signatureBytes)
|
||||
p.outputSignatures[signature]++
|
||||
duplicateCount := p.outputSignatures[signature]
|
||||
distinctCount := len(p.outputSignatures)
|
||||
// 循环保险只拦“参数完全相同的重复调用”。参数不同的必需调用一律放行，
|
||||
// 否则多次 cmd_run / update_schedule / 多条不同消息都会被误杀。
|
||||
if p.maxDuplicateSend > 0 && duplicateCount > p.maxDuplicateSend {
|
||||
p.authMu.Unlock()
|
||||
msg := fmt.Sprintf("QQ 循环保险已阻止重复发送：本轮第 %d 次出现参数完全相同的消息；请勿重复发送同一内容", duplicateCount)
|
||||
p.setDenial(ctx, msg)
|
||||
return nil
|
||||
}
|
||||
if p.maxQQOutputCalls > 0 && distinctCount > p.maxQQOutputCalls {
|
||||
p.authMu.Unlock()
|
||||
msg := fmt.Sprintf("QQ 循环保险已阻止本次发送：单轮主动发送的不同消息数已达上限 %d（0=不限制，可在插件配置调整）", p.maxQQOutputCalls)
|
||||
p.setDenial(ctx, msg)
|
||||
return nil
|
||||
}
|
||||
}
|
||||
if p.maxQQToolCalls > 0 && toolCount > p.maxQQToolCalls {
|
||||
p.authMu.Unlock()
|
||||
msg := fmt.Sprintf("QQ 循环保险已阻止工具调用：单轮工具调用总数已达上限 %d（0=不限制，可在插件配置调整）", p.maxQQToolCalls)
|
||||
p.setDenial(ctx, msg)
|
||||
return nil
|
||||
}
|
||||
p.authMu.Unlock()
|
||||
|
||||
if denialLocked && tc.Name != "output_send__"+p.name {
|
||||
msg := fmt.Sprintf("QQ 权限策略已锁止本轮后续工具 %s；仅允许发送一次权限说明", tc.Name)
|
||||
p.setDenial(ctx, msg)
|
||||
return nil
|
||||
}
|
||||
if !auth.owner && isHardPrivateTool(tc.Name) {
|
||||
p.authMu.Lock()
|
||||
p.denialLocked = true
|
||||
p.authMu.Unlock()
|
||||
msg := fmt.Sprintf("QQ 权限策略拒绝私人资源工具 %s；该限制不能由群聊或私聊白名单覆盖，请不要重试", tc.Name)
|
||||
p.setDenial(ctx, msg)
|
||||
return nil
|
||||
}
|
||||
if !allowed {
|
||||
scope := "非所有者私聊"
|
||||
if auth.isGroup {
|
||||
scope = fmt.Sprintf("群聊 %d", auth.groupID)
|
||||
}
|
||||
msg := fmt.Sprintf("QQ 权限策略拒绝工具 %s：%s 的工具白名单未包含该工具；请不要重试，改为直接说明权限限制", tc.Name, scope)
|
||||
p.setDenial(ctx, msg)
|
||||
return nil
|
||||
}
|
||||
if argsAllowed, reason := p.sessionToolArgsAllowed(tc.Name, tc.Arguments, auth); !argsAllowed {
|
||||
msg := fmt.Sprintf("QQ 权限策略拒绝工具 %s：%s；请不要改用其他会话 ID 重试", tc.Name, reason)
|
||||
p.setDenial(ctx, msg)
|
||||
return nil
|
||||
}
|
||||
if tc.Name == p.name+"_group_manage" {
|
||||
cmd, _ := tc.Arguments["command"].(string)
|
||||
if requiresConfirmGroupCommand(cmd) {
|
||||
if ok, _ := tc.Arguments["confirm"].(bool); !ok {
|
||||
msg := fmt.Sprintf("QQ群管理命令 %s 属于高风险操作，必须显式传入 confirm=true 后才能执行", cmd)
|
||||
ctx.Response = &msg
|
||||
p.setDenial(ctx, msg)
|
||||
return nil
|
||||
}
|
||||
}
|
||||
@ -846,7 +1260,7 @@ func (p *Plugin) beforeOwnToolcall(ctx *sdk.StageContext) error {
|
||||
if requiresConfirmFriendCommand(cmd) {
|
||||
if ok, _ := tc.Arguments["confirm"].(bool); !ok {
|
||||
msg := fmt.Sprintf("QQ好友管理命令 %s 属于高风险操作，必须显式传入 confirm=true 后才能执行", cmd)
|
||||
ctx.Response = &msg
|
||||
p.setDenial(ctx, msg)
|
||||
return nil
|
||||
}
|
||||
}
|
||||
@ -978,8 +1392,8 @@ func (p *Plugin) handleWebhook(w http.ResponseWriter, r *http.Request) {
|
||||
} else {
|
||||
interrupt = fmt.Sprintf("来自「%s」的私聊消息(message_id=%d, user_id=%d)。先用%sget_message(message_id=%d)取正文；若取不到（消息已过期），改用%sget_history(user_id=%d)按会话拉取上下文，或用%slist_chats 查看未读会话。用%s回复对方", nickname, evt.MessageID, evt.UserID, tp, evt.MessageID, tp, evt.UserID, tp, outputTool)
|
||||
}
|
||||
if p.isAdmin(evt.UserID) {
|
||||
interrupt = "【重要！老大消息】" + interrupt
|
||||
if p.isOwner(evt.UserID) {
|
||||
interrupt = "【重要！Bot 所有者消息】" + interrupt
|
||||
}
|
||||
|
||||
if text != "" {
|
||||
@ -1012,12 +1426,16 @@ func (p *Plugin) handleWebhook(w http.ResponseWriter, r *http.Request) {
|
||||
}
|
||||
}
|
||||
|
||||
// 必须在注入前记录 OneBot 可信来源；权限判断绝不依赖昵称、正文或模型参数。
|
||||
p.activateAuthContext(evt.MessageID, evt.UserID, evt.GroupID, evt.MessageType == "group")
|
||||
|
||||
if evt.MessageType == "private" {
|
||||
p.startTyping(evt.UserID)
|
||||
}
|
||||
|
||||
if p.sdk != nil {
|
||||
p.sdk.InjectInterruptText(p.name, p.name, interrupt)
|
||||
// NoMemory：HTTP 侧来的中断提示，不是对话内容。
|
||||
p.sdk.InjectInterruptTextOpts(p.name, p.name, interrupt, sdk.InjectOptions{NoMemory: true})
|
||||
}
|
||||
w.WriteHeader(http.StatusOK)
|
||||
}
|
||||
@ -1320,6 +1738,8 @@ func (p *Plugin) getMsgFromNapcat(msgID int64) (interface{}, error) {
|
||||
|
||||
// handleChannelOutput — output_send(channel="qq") 的处理器
|
||||
// args 包含 payload, type, (可选 meta)
|
||||
// 成功时只返回极简标记，不回传 NapCat 完整响应——避免"已发送"类富回执喂给模型
|
||||
// 造成"看到成功→继续发下一条"的回声循环（issue: output loop echo）。
|
||||
func (p *Plugin) handleChannelOutput(args map[string]interface{}) (interface{}, error) {
|
||||
payload, _ := args["payload"].(string)
|
||||
rawType, _ := args["type"].(string)
|
||||
@ -1352,10 +1772,15 @@ func (p *Plugin) handleChannelOutput(args map[string]interface{}) (interface{},
|
||||
p.stopTyping(userID)
|
||||
}
|
||||
|
||||
var sendErr error
|
||||
switch rawType {
|
||||
case "text":
|
||||
text := p.sensitiveFilter(payload)
|
||||
msg := map[string]interface{}{"message": text}
|
||||
message := interface{}(text)
|
||||
if groupID != 0 && userID != 0 {
|
||||
message = messageWithMention(userID, map[string]interface{}{"type": "text", "data": map[string]interface{}{"text": text}})
|
||||
}
|
||||
msg := map[string]interface{}{"message": message}
|
||||
if groupID != 0 {
|
||||
msg["group_id"] = groupID
|
||||
} else {
|
||||
@ -1365,9 +1790,10 @@ func (p *Plugin) handleChannelOutput(args map[string]interface{}) (interface{},
|
||||
msg["reply_to"] = replyTo
|
||||
}
|
||||
if groupID != 0 {
|
||||
return p.napcat("send_group_msg", msg)
|
||||
_, sendErr = p.napcat("send_group_msg", msg)
|
||||
} else {
|
||||
_, sendErr = p.napcat("send_private_msg", msg)
|
||||
}
|
||||
return p.napcat("send_private_msg", msg)
|
||||
|
||||
case "voice", "audio":
|
||||
text := p.sensitiveFilter(payload)
|
||||
@ -1387,21 +1813,23 @@ func (p *Plugin) handleChannelOutput(args map[string]interface{}) (interface{},
|
||||
os.Remove(audioFile)
|
||||
uri := fmt.Sprintf("file:///app/files/%s", filepath.Base(dest))
|
||||
cqMsg := fmt.Sprintf("[CQ:record,file=%s]", uri)
|
||||
msg := map[string]interface{}{"message": cqMsg}
|
||||
message := interface{}(cqMsg)
|
||||
if groupID != 0 && userID != 0 {
|
||||
message = messageWithMention(userID, map[string]interface{}{"type": "record", "data": map[string]interface{}{"file": uri}})
|
||||
}
|
||||
msg := map[string]interface{}{"message": message}
|
||||
if groupID != 0 {
|
||||
msg["group_id"] = groupID
|
||||
} else {
|
||||
msg["user_id"] = userID
|
||||
}
|
||||
if groupID != 0 {
|
||||
return p.napcat("send_group_msg", msg)
|
||||
_, sendErr = p.napcat("send_group_msg", msg)
|
||||
} else {
|
||||
_, sendErr = p.napcat("send_private_msg", msg)
|
||||
}
|
||||
return p.napcat("send_private_msg", msg)
|
||||
|
||||
case "image", "file":
|
||||
// 收敛到 output 通道：payload 支持本地路径或 http(s) URL。
|
||||
// 本地路径拷入 NapCat 共享目录转 file:// URI（与 voice 分支同模式），
|
||||
// 此后 agent 发本地文件不再需要单独的 upload_group_file 工具。
|
||||
uri := payload
|
||||
if !strings.HasPrefix(payload, "http://") && !strings.HasPrefix(payload, "https://") &&
|
||||
!strings.HasPrefix(payload, "file://") {
|
||||
@ -1423,34 +1851,48 @@ func (p *Plugin) handleChannelOutput(args map[string]interface{}) (interface{},
|
||||
if rawType == "image" {
|
||||
cqTag = "image"
|
||||
}
|
||||
msg := map[string]interface{}{"message": fmt.Sprintf("[CQ:%s,file=%s]", cqTag, uri)}
|
||||
message := interface{}(fmt.Sprintf("[CQ:%s,file=%s]", cqTag, uri))
|
||||
if groupID != 0 && userID != 0 {
|
||||
message = messageWithMention(userID, map[string]interface{}{"type": cqTag, "data": map[string]interface{}{"file": uri}})
|
||||
}
|
||||
msg := map[string]interface{}{"message": message}
|
||||
if groupID != 0 {
|
||||
msg["group_id"] = groupID
|
||||
} else {
|
||||
msg["user_id"] = userID
|
||||
}
|
||||
if groupID != 0 {
|
||||
return p.napcat("send_group_msg", msg)
|
||||
_, sendErr = p.napcat("send_group_msg", msg)
|
||||
} else {
|
||||
_, sendErr = p.napcat("send_private_msg", msg)
|
||||
}
|
||||
return p.napcat("send_private_msg", msg)
|
||||
|
||||
default:
|
||||
return nil, fmt.Errorf("不支持的 type: %s（枚举值: text/voice/image/file）", rawType)
|
||||
}
|
||||
|
||||
if sendErr != nil {
|
||||
return nil, sendErr
|
||||
}
|
||||
// 成功：返回极简标记。不再回传 NapCat 原始响应（含 message_id 等）给模型，
|
||||
// 避免模型把"发送成功"当成"上一步完成，继续下一步"的信号驱动循环。
|
||||
return "ok", nil
|
||||
}
|
||||
|
||||
func (p *Plugin) buildOutputHelp() string {
|
||||
return `【参数】
|
||||
payload — 消息载荷。type=text时直接填文字，type=voice时填文字（自动转语音），type=image/file时填URL
|
||||
meta — JSON 元数据，必含 group_id（群聊）或 user_id（私聊），可选 reply_to
|
||||
meta — JSON 元数据，含 group_id（群聊）和/或 user_id（私聊或群内@），可选 reply_to
|
||||
type — text / voice / image / file
|
||||
|
||||
【示例】
|
||||
群聊文字：output_send__qq(payload="你好", meta="{\"group_id\":123456789}", type="text")
|
||||
私聊语音：output_send__qq(payload="你好", meta="{\"user_id\":123456789}", type="voice")
|
||||
群内@用户：output_send__qq(payload="你好", meta="{\"group_id\":123456789,\"user_id\":987654321}", type="text")
|
||||
发送图片：output_send__qq(payload="https://example.com/img.jpg", meta="{\"group_id\":123456789}", type="image")
|
||||
|
||||
【注意】
|
||||
- group_id 与 user_id 同时存在时始终发送到 group_id，并在消息头 @user_id
|
||||
- type=text 时 payload 直接是文字，无需 JSON 包裹
|
||||
- type=voice 时 payload 是文字内容，自动转语音发送
|
||||
- type=image/file 时 payload 是 URL 或路径`
|
||||
@ -2088,8 +2530,10 @@ func (p *Plugin) handleDownloadFile(args map[string]interface{}) (interface{}, e
|
||||
p.updateDownloadTask(t, "done", savePath, "")
|
||||
log.Printf("[qq] 文件下载完成: %s", savePath)
|
||||
if p.sdk != nil {
|
||||
p.sdk.InjectInterruptText(p.name, p.name,
|
||||
fmt.Sprintf("文件下载完成: %s，保存在 %s", filepath.Base(savePath), savePath))
|
||||
// NoMemory：下载完成的状态通知，不是记忆内容。
|
||||
p.sdk.InjectInterruptTextOpts(p.name, p.name,
|
||||
fmt.Sprintf("文件下载完成: %s，保存在 %s", filepath.Base(savePath), savePath),
|
||||
sdk.InjectOptions{NoMemory: true})
|
||||
}
|
||||
} else {
|
||||
errMsg = "下载失败，文件可能已过期"
|
||||
@ -2557,6 +3001,13 @@ func (p *Plugin) handleVideoDownload(args map[string]interface{}) (interface{},
|
||||
|
||||
// ======== NapCat HTTP Client ========
|
||||
|
||||
func messageWithMention(userID int64, content interface{}) []interface{} {
|
||||
return []interface{}{
|
||||
map[string]interface{}{"type": "at", "data": map[string]interface{}{"qq": strconv.FormatInt(userID, 10)}},
|
||||
content,
|
||||
}
|
||||
}
|
||||
|
||||
func (p *Plugin) napcat(action string, params map[string]interface{}) (interface{}, error) {
|
||||
data, _ := json.Marshal(params)
|
||||
url := fmt.Sprintf("%s/%s", p.napcatURL, action)
|
||||
@ -2675,12 +3126,19 @@ func convInt64(v interface{}) (int64, error) {
|
||||
|
||||
func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, error) {
|
||||
return &Plugin{
|
||||
name: name,
|
||||
allowFrom: make(map[int64]struct{}),
|
||||
groupAllowFrom: make(map[int64]struct{}),
|
||||
downloadTasks: make([]*DownloadTask, 0),
|
||||
typingMap: make(map[int64]*typingState),
|
||||
dmPolicy: "open",
|
||||
groupPolicy: "open",
|
||||
name: name,
|
||||
allowFrom: make(map[int64]struct{}),
|
||||
groupAllowFrom: make(map[int64]struct{}),
|
||||
authByMessageID: make(map[int64]qqAuthContext),
|
||||
outputSignatures: make(map[string]int),
|
||||
maxQQToolCalls: defaultMaxQQToolCalls,
|
||||
maxQQOutputCalls: defaultMaxQQOutputCalls,
|
||||
maxDuplicateSend: defaultMaxDuplicateSend,
|
||||
groupToolAllowlists: parseGroupToolAllowlists(defaultGroupToolAllowlists),
|
||||
privateToolAllowlist: parseToolAllowlist(defaultPublicToolAllowlist),
|
||||
downloadTasks: make([]*DownloadTask, 0),
|
||||
typingMap: make(map[int64]*typingState),
|
||||
dmPolicy: "open",
|
||||
groupPolicy: "open",
|
||||
}, nil
|
||||
}
|
||||
|
||||
204
example/qq/plugin_test.go
Normal file
204
example/qq/plugin_test.go
Normal file
@ -0,0 +1,204 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"gitcode.com/JianFeeeee/homeagent-sdk/sdk"
|
||||
)
|
||||
|
||||
func newPermissionTestPlugin(t *testing.T) *Plugin {
|
||||
t.Helper()
|
||||
instance, err := NewPluginFactory("qq", nil)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
return instance.(*Plugin)
|
||||
}
|
||||
|
||||
func toolCallContext(name string, args map[string]interface{}) *sdk.StageContext {
|
||||
return &sdk.StageContext{ToolCalls: []sdk.ToolCall{{Name: name, Arguments: args}}}
|
||||
}
|
||||
|
||||
func TestOwnerBypassesQQPermissionBoundary(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
p.auth = qqAuthContext{active: true, owner: true, userID: 2198972886}
|
||||
ctx := toolCallContext("calendar_list", nil)
|
||||
if err := p.beforeToolcall(ctx); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if ctx.Response != nil {
|
||||
t.Fatalf("owner call rejected: %s", *ctx.Response)
|
||||
}
|
||||
}
|
||||
|
||||
func TestPrivateResourceCannotBeAllowlisted(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
p.privateToolAllowlist = append(p.privateToolAllowlist, "calendar_*")
|
||||
p.auth = qqAuthContext{active: true, userID: 10001}
|
||||
ctx := toolCallContext("calendar_list", nil)
|
||||
if err := p.beforeToolcall(ctx); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if ctx.Response == nil || !strings.Contains(*ctx.Response, "私人资源工具") {
|
||||
t.Fatalf("expected private-resource denial, got %#v", ctx.Response)
|
||||
}
|
||||
}
|
||||
|
||||
func TestNonOwnerQQHistoryIsScopedToCurrentGroup(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
p.auth = qqAuthContext{active: true, messageID: 88, userID: 10001, groupID: 20002, isGroup: true}
|
||||
|
||||
ctx := toolCallContext("qq_get_history", map[string]interface{}{"group_id": int64(20003)})
|
||||
if err := p.beforeToolcall(ctx); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if ctx.Response == nil || !strings.Contains(*ctx.Response, "当前 QQ 会话") {
|
||||
t.Fatalf("cross-group history not rejected: %#v", ctx.Response)
|
||||
}
|
||||
|
||||
ctx = toolCallContext("qq_get_history", map[string]interface{}{"group_id": int64(20002)})
|
||||
if err := p.beforeToolcall(ctx); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if ctx.Response != nil {
|
||||
t.Fatalf("current-group history rejected: %s", *ctx.Response)
|
||||
}
|
||||
}
|
||||
|
||||
func TestUnmatchedQQInputIsDowngraded(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
p.auth = qqAuthContext{active: true, owner: true, userID: 2198972886}
|
||||
ctx := &sdk.StageContext{
|
||||
RawMessage: "来自未知事件(message_id=404)",
|
||||
Extra: map[string]interface{}{"input_source": "qq"},
|
||||
}
|
||||
if err := p.onInputAuthContext(ctx); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !p.auth.active || p.auth.owner || p.auth.userID != 0 {
|
||||
t.Fatalf("unmatched input reused prior privilege: %+v", p.auth)
|
||||
}
|
||||
}
|
||||
|
||||
func TestDuplicateQQOutputIsStopped(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
p.maxDuplicateSend = 1
|
||||
p.auth = qqAuthContext{active: true, owner: true, userID: 2198972886}
|
||||
args := map[string]interface{}{"payload": "same", "type": "text", "meta": `{"user_id":123}`}
|
||||
|
||||
ctx := toolCallContext("output_send__qq", args)
|
||||
if err := p.beforeToolcall(ctx); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if ctx.Response != nil {
|
||||
t.Fatalf("first send rejected: %s", *ctx.Response)
|
||||
}
|
||||
|
||||
ctx = toolCallContext("output_send__qq", args)
|
||||
if err := p.beforeToolcall(ctx); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if ctx.Response == nil || !strings.Contains(*ctx.Response, "循环保险") {
|
||||
t.Fatalf("duplicate send not stopped: %#v", ctx.Response)
|
||||
}
|
||||
}
|
||||
|
||||
func TestGroupAndUserRouteAddsLeadingMention(t *testing.T) {
|
||||
var path string
|
||||
var request map[string]interface{}
|
||||
server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
path = r.URL.Path
|
||||
if err := json.NewDecoder(r.Body).Decode(&request); err != nil {
|
||||
t.Errorf("decode request: %v", err)
|
||||
}
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
_, _ = w.Write([]byte(`{"status":"ok","retcode":0,"data":{"message_id":1}}`))
|
||||
}))
|
||||
defer server.Close()
|
||||
|
||||
p := newPermissionTestPlugin(t)
|
||||
p.napcatURL = server.URL
|
||||
p.httpClient = server.Client()
|
||||
_, err := p.handleChannelOutput(map[string]interface{}{
|
||||
"payload": "hello",
|
||||
"type": "text",
|
||||
"meta": `{"group_id":20002,"user_id":10001}`,
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if path != "/send_group_msg" {
|
||||
t.Fatalf("path=%q, want /send_group_msg", path)
|
||||
}
|
||||
segments, ok := request["message"].([]interface{})
|
||||
if !ok || len(segments) < 2 {
|
||||
t.Fatalf("message is not a segment array: %#v", request["message"])
|
||||
}
|
||||
mention, _ := segments[0].(map[string]interface{})
|
||||
data, _ := mention["data"].(map[string]interface{})
|
||||
if mention["type"] != "at" || data["qq"] != "10001" {
|
||||
t.Fatalf("leading mention=%#v", mention)
|
||||
}
|
||||
}
|
||||
|
||||
// 回归：循环保险曾按“总数”拦截，导致参数不同且必需的调用被误杀。
|
||||
// 现在只拦参数完全相同的重复调用。
|
||||
func TestDistinctQQOutputsAreNotTreatedAsDuplicates(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
p.auth = qqAuthContext{active: true, owner: true, userID: 2198972886}
|
||||
// maxDuplicateSend 默认 1：同一条消息重复才会被拦，不同消息必须全部放行。
|
||||
for i := 0; i < 5; i++ {
|
||||
ctx := toolCallContext("output_send__qq", map[string]interface{}{
|
||||
"payload": fmt.Sprintf("message-%d", i),
|
||||
"type": "text",
|
||||
"meta": `{"user_id":123}`,
|
||||
})
|
||||
if err := p.beforeToolcall(ctx); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if ctx.Response != nil {
|
||||
t.Fatalf("distinct message %d was blocked: %s", i, *ctx.Response)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestDistinctNecessaryToolCallsAreNotBlocked(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
p.auth = qqAuthContext{active: true, owner: true, userID: 2198972886}
|
||||
// 旧实现 maxQQToolCalls=32 会在第 33 个不同参数的必需调用处误拦。
|
||||
for i := 0; i < 50; i++ {
|
||||
ctx := toolCallContext("cmd_run", map[string]interface{}{"command": fmt.Sprintf("cmd-%d", i)})
|
||||
if err := p.beforeToolcall(ctx); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if ctx.Response != nil {
|
||||
t.Fatalf("necessary tool call %d was blocked: %s", i, *ctx.Response)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestZeroLimitsMeanUnlimited(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
p.maxQQOutputCalls = 0
|
||||
p.maxDuplicateSend = 0
|
||||
p.maxQQToolCalls = 0
|
||||
p.auth = qqAuthContext{active: true, owner: true, userID: 2198972886}
|
||||
for i := 0; i < 30; i++ {
|
||||
ctx := toolCallContext("output_send__qq", map[string]interface{}{
|
||||
"payload": "same-content",
|
||||
"type": "text",
|
||||
"meta": `{"user_id":123}`,
|
||||
})
|
||||
if err := p.beforeToolcall(ctx); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if ctx.Response != nil {
|
||||
t.Fatalf("0 should mean unlimited, blocked at %d: %s", i, *ctx.Response)
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -5,7 +5,7 @@ rss plugin
|
||||
## Build
|
||||
|
||||
```bash
|
||||
plugindev build
|
||||
hmapdev build
|
||||
```
|
||||
|
||||
## Install
|
||||
|
||||
@ -300,7 +300,10 @@ func (p *Plugin) checkFeed(sub FeedSub) {
|
||||
lines = append(lines, line)
|
||||
}
|
||||
|
||||
p.sdk.InjectInterruptText("rss", "rss", strings.Join(lines, "\n"))
|
||||
// 中断注入是「系统通知」，NoMemory 写明意图：这类提醒不参与记忆计算，
|
||||
// 原文仍进上下文（模型当轮看得到）。
|
||||
p.sdk.InjectInterruptTextOpts("rss", "rss", strings.Join(lines, "\n"),
|
||||
sdk.InjectOptions{NoMemory: true})
|
||||
p.saveData()
|
||||
}
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@ weather plugin
|
||||
## Build
|
||||
|
||||
```bash
|
||||
plugindev build
|
||||
hmapdev build
|
||||
```
|
||||
|
||||
## Install
|
||||
|
||||
58
meta/meta.go
58
meta/meta.go
@ -6,10 +6,51 @@ var (
|
||||
// Version 是 HomeAgent SDK 版本号。
|
||||
// 通过 `-ldflags="-X gitcode.com/JianFeeeee/homeagent-sdk/meta.Version=vX.Y.Z"` 注入。
|
||||
//
|
||||
// 版本号语义：**SDK 版本跟随核心的中版本，patch 位恒为 .0**。
|
||||
// 整条核心 1.1.x 线（1.1.0、1.1.1、1.1.7…）共用 SDK 1.1.0；
|
||||
// 只有核心进入 1.2.0 这种中版本跃迁时 SDK 才升到 1.2.0。
|
||||
// 这样插件开发者只需关心「我在为哪个中版本写插件」，
|
||||
// 不必跟着核心的每个 bugfix 换 SDK 依赖（见 核心仓 docs/git-branching.md §七）。
|
||||
//
|
||||
// 1.0.0：插件运行模型从 C ABI 动态库改为子进程 + 共享内存。
|
||||
// 公开 SDK 接口（sdk/ 目录）**零改动**——插件业务代码不需要改一行，
|
||||
// 但产物形态变了（plugin.so → plugin.bin），必须用新版 plugindev 重编。
|
||||
Version = "1.0.0"
|
||||
// 公开 SDK 接口零改动，但产物形态变了（plugin.so → plugin.bin）。
|
||||
// 1.1.0：多模态贯通插件边界。**全部是新增，无签名变更**：
|
||||
// - Triple.SentenceText / Triple.MediaDigests
|
||||
// - Doc.MediaDigests / Doc.Attachments、MediaAttachment
|
||||
// - TextEvent.Attachments
|
||||
// - DocMemoryAPI.InsertWithMedia
|
||||
// - IOInjector 的 InjectInputMedia / InjectInputMediaSync /
|
||||
// InjectInterruptMedia；PluginSDK 补上缺失的 SetToolBlocks 包装
|
||||
// 同版修掉两处并发竞态（sdk/stress_test.go 的 -race 实证，不是理论风险）：
|
||||
// PluginSDK 的 API 字段与 autoRestart 标志此前无锁，而写方
|
||||
// （内核注入 API、插件 SetAutoRestart）与读方（插件后台 goroutine
|
||||
// 注入、内核 registry 读 AutoRestart）天然跨 goroutine。
|
||||
// 存量插件不需要改一行也不需要重编：新增方法由**插件调用、内核实现**，
|
||||
// 不调就不受影响。想用新字段的插件重编即可。
|
||||
//
|
||||
// 1.2.0：注入行为的记忆/裁剪标志位。**全部是新增，无签名变更**：
|
||||
// - InjectOptions{NoMemory, ContextPolicy}
|
||||
// - IOInjector 的六个 *Opts 变体（排队/中断/同步/带媒体各一对）
|
||||
// - ChannelDef.ContextPolicy（顺带给 ChannelDef 补上 JSON tag：
|
||||
// 它要跨进程传给内核，而 Cleaner 是函数必须忽略；无 tag 时只能
|
||||
// 手写字段白名单，新增字段会被静默丢掉）
|
||||
// 语义：零值 InjectOptions 与旧的三参数方法完全等价（记入记忆 +
|
||||
// 不裁剪），因此存量插件不需要改一行也不需要重编。
|
||||
// 裁剪（ContextPolicy=prune）必须显式声明——它会归档丢弃低相关事件。
|
||||
//
|
||||
// ❗main 分支上此值是**下一个未发布中版本**；已发布的值看对应的
|
||||
// release/vX.Y.x 分支与 tag（见 核心仓 docs/git-branching.md §2.1 与 §七.1）。
|
||||
//
|
||||
// 现为 1.2.0：核心的 1.2.x 线正在发布中（release/v1.2.x 承载 1.2.0），
|
||||
// 但 **SDK 不跟 beta 发版**（§七.2）——SDK 1.2.0 的定版与 tag 随核心的
|
||||
// **正式** tag 一起做（§七.3）。在那之前 1.2.0 仍是 SDK 尚未发布的中版本，
|
||||
// 所以 main 就停在 1.2.0。
|
||||
//
|
||||
// 注意：这里与核心 main **故意不对称**。核心一旦切出 release/v1.2.x，
|
||||
// 1.2.0 就归发布线所有，main 立刻推进到 1.3.0；而 SDK 因为要等正式 tag，
|
||||
// 它的 main 在 v1.2.0 打出来之前不得越过 1.2.0。
|
||||
// （曾误按 §七.4 把这里推到 1.3.0，等于宣称 1.2.0 已发布。）
|
||||
Version = "1.2.0"
|
||||
|
||||
// Commit 是构建时的 Git commit hash。
|
||||
Commit = "unknown"
|
||||
@ -20,13 +61,22 @@ var (
|
||||
// SDKName 是 SDK 名称。
|
||||
SDKName = "HomeAgent SDK"
|
||||
|
||||
// CoreModule 是核心仓的 Go module path，供 plugindev 生成 go.mod 时使用。
|
||||
// CoreModule 是核心仓的 Go module path，供 hmapdev 生成 go.mod 时使用。
|
||||
CoreModule = "gitcode.com/JianFeeeee/HomeAgent"
|
||||
|
||||
// CoreVersion 是此 SDK 所兼容的最低核心版本。
|
||||
//
|
||||
// 1.0.0 是硬下限而非建议值：0.9.x 内核只会 dlopen `.so`，
|
||||
// 本版工具链产出的 `plugin.bin` 在旧内核上根本不会被识别。
|
||||
//
|
||||
// ⚠️ 1.1.0 新增的媒体接口需要核心 **1.1.1+**（更早的核心没有
|
||||
// doc.insertWithMedia / io.injectMedia* 这些 RPC，调用会返回 unknown method）。
|
||||
// 这里仍写 1.0.0，因为它是「SDK 能在其上运行」的下限；
|
||||
// 媒体接口是可选能力，不用就不受影响。
|
||||
//
|
||||
// ⚠️ 1.2.0 新增的注入标志位同理需要核心 **1.2.0+**：内核在 1.2.0 之前会
|
||||
// 忽略注入参数里的 no_memory/context_policy 字段（不会报错，但不生效）。
|
||||
// 想用这些标志位的插件应当要求核心 1.2.0+；不用就不受影响。
|
||||
CoreVersion = "1.0.0"
|
||||
)
|
||||
|
||||
|
||||
150
package/build-examples.sh
Normal file
150
package/build-examples.sh
Normal file
@ -0,0 +1,150 @@
|
||||
#!/usr/bin/env bash
|
||||
# 给 SDK 发版打包**示例插件**的 .hmap 产物。
|
||||
#
|
||||
# 为什么要在 SDK 仓库里发示例插件的 hmap：
|
||||
# 插件二进制与内核是**协议绑定**的（internal/plugin/proc/protocol.go 的
|
||||
# ProtocolVersion + 统一共享内存区魔数）。SDK 升版往往同时意味着协议变化，
|
||||
# 而示例插件（qq/memo/browser/…）是使用者最常直接安装的东西。
|
||||
# 如果 SDK 只发工具链不发示例产物，使用者要么自己重编、要么用到与本版 SDK
|
||||
# 不匹配的旧产物——后者的表现是握手失败（协议/魔数不匹配），而且看起来像
|
||||
# 「插件坏了」而不是「版本不配套」。
|
||||
#
|
||||
# 用法：
|
||||
# package/build-examples.sh [TARGET] [OUT_DIR]
|
||||
# TARGET native(默认) | linux/amd64 | linux/arm64 | darwin/amd64 | darwin/arm64 | windows/amd64 | all
|
||||
# OUT_DIR 产物目录（默认 build/examples）
|
||||
#
|
||||
# 产物：
|
||||
# <OUT_DIR>/<name>_<goos>_<goarch>.hmap 每个示例插件一份
|
||||
# <OUT_DIR>/SHA256SUMS 全部产物齐全**之后**才计算
|
||||
# <OUT_DIR>/MANIFEST.txt 版本、协议版本、产自哪个 commit
|
||||
#
|
||||
# 纪律（与本项目其它构建脚本一致）：
|
||||
# 1. 判成功看**产物是否存在**，不看退出码——hmapdev 对部分错误只打印不退出。
|
||||
# 2. SHA256SUMS 必须在全部产物生成完毕后一次算完，边打边算会漏掉后生成的包。
|
||||
set -uo pipefail
|
||||
|
||||
SDK_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
TARGET="${1:-native}"
|
||||
OUT_DIR="${2:-$SDK_ROOT/build/examples}"
|
||||
GO="${GO:-$(command -v go 2>/dev/null || echo go)}"
|
||||
|
||||
case "$TARGET" in
|
||||
native) GOOS=""; GOARCH="" ;;
|
||||
linux/amd64) GOOS=linux; GOARCH=amd64 ;;
|
||||
linux/arm64) GOOS=linux; GOARCH=arm64 ;;
|
||||
darwin/amd64) GOOS=darwin; GOARCH=amd64 ;;
|
||||
darwin/arm64) GOOS=darwin; GOARCH=arm64 ;;
|
||||
windows/amd64)
|
||||
# 明确拒绝，而不是让调用方拿到一句深层 Go 编译错误。
|
||||
# 协议 2 的统一共享内存区只移植到了 Unix：内核 internal/plugin/proc/
|
||||
# shmpass_windows.go 仍是旧的 SHM_STAGE/SHM_EVTRING 两段布局，
|
||||
# 插件模板 proc_shm_windows.go 也缺 attachUnifiedShm。
|
||||
echo "windows 目标暂不支持：协议 2 的统一共享内存区未移植到 Windows（内核与插件模板均缺实现）。" >&2
|
||||
exit 1
|
||||
;;
|
||||
all)
|
||||
echo "本脚本一次只构建一个平台；请由 package/build.sh 传入具体目标。" >&2
|
||||
exit 1
|
||||
;;
|
||||
*)
|
||||
echo "Unknown target: $TARGET" >&2
|
||||
echo "Usage: $0 [native|linux/amd64|linux/arm64|darwin/amd64|darwin/arm64|windows/amd64|all] [OUT_DIR]" >&2
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
export CGO_ENABLED=0
|
||||
|
||||
# 按平台逐个构建，**不用** bundle 模式：
|
||||
# - bundle 会连 windows 一起编，而协议 2 的统一共享区尚未移植到 Windows
|
||||
# （内核 shmpass_windows.go 仍是旧的两段布局），必然失败；
|
||||
# - 逐平台构建每个目标都产出一份 .hmap，正是发版要附的产物。
|
||||
# 平台名解析成本脚本后面用（校验和与 MANIFEST 都要写清楚是哪个平台）。
|
||||
if [ -z "${GOOS:-}" ]; then
|
||||
GOOS="$(go env GOOS)"; GOARCH="$(go env GOARCH)"
|
||||
fi
|
||||
|
||||
# 1) 先保证工具链可用：示例必须用**本仓当前源码**构建，否则产物协议与这一版 SDK 不符。
|
||||
# 允许外部指定（发版脚本会在跨平台构建后把刚产出的工具链路径传进来）。
|
||||
# 工具链二进制名由 plugindev 改为 hmapdev；旧变量名 PLUGINDEV 仍兼容。
|
||||
HMAPDEV="${HMAPDEV:-${PLUGINDEV:-$SDK_ROOT/build/hmapdev}}"
|
||||
if [ ! -x "$PLUGINDEV" ]; then
|
||||
echo "[examples] 先构建 hmapdev ..."
|
||||
( cd "$SDK_ROOT/tools/hmapdev" && "$GO" build -o "$HMAPDEV" . ) || {
|
||||
echo "[examples] hmapdev 构建失败，无法继续" >&2; exit 1; }
|
||||
fi
|
||||
if [ ! -x "$PLUGINDEV" ]; then
|
||||
echo "[examples] hmapdev 不存在或不可执行：$HMAPDEV" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "=== 协议 ==="
|
||||
echo " ProtocolVersion = $(grep -m1 '^const ProtocolVersion' "$SDK_ROOT/../internal/plugin/proc/protocol.go" 2>/dev/null | grep -oE '[0-9]+' || echo '?（本仓非内核仓，跳过）')"
|
||||
|
||||
mkdir -p "$OUT_DIR"
|
||||
# 清掉上一次的校验和：残留的 SHA256SUMS 会掩盖本次缺产物。
|
||||
rm -f "$OUT_DIR"/SHA256SUMS "$OUT_DIR"/MANIFEST.txt
|
||||
|
||||
ok=0
|
||||
fail=0
|
||||
failed_names=""
|
||||
|
||||
for dir in "$SDK_ROOT"/example/*/; do
|
||||
[ -f "$dir/plugin.go" ] || continue
|
||||
name="$(basename "$dir")"
|
||||
|
||||
# 清掉旧产物：残留会让人（和本脚本）误判成功。
|
||||
rm -rf "$dir/build" "$dir/dist"
|
||||
|
||||
out=$( cd "$dir" && "$PLUGINDEV" build --no-bundle --target "$GOOS/$GOARCH" 2>&1 )
|
||||
rc=$?
|
||||
|
||||
# 判据是**退出码 + 产物存在**，两者都要。
|
||||
# 只看退出码：hmapdev 曾经出错也退 0（已修，但脚本不该依赖它「现在」是对的）。
|
||||
# 只看产物：部分平台失败时会留下上一次的产物，看起来像成功。
|
||||
hmap="$(ls "$dir"/dist/*.hmap 2>/dev/null | head -1)"
|
||||
if [ $rc -eq 0 ] && [ -n "$hmap" ]; then
|
||||
# 保留插件自己声明的产物名（它用的是 plg.json 的 name_en，是插件的身份），
|
||||
# 只在前面加平台前缀避免多平台互相覆盖。
|
||||
dest="$OUT_DIR/${GOOS}_${GOARCH}_$(basename "$hmap")"
|
||||
cp "$hmap" "$dest"
|
||||
printf "✓ %-14s → %s (%s)\n" "$name" "$(basename "$dest")" "$(du -h "$dest" | cut -f1)"
|
||||
ok=$((ok + 1))
|
||||
else
|
||||
printf "✗ %-14s 构建失败 (rc=%d)\n" "$name" "$rc"
|
||||
echo "$out" | tail -6 | sed 's/^/ /'
|
||||
fail=$((fail + 1))
|
||||
failed_names="$failed_names $name"
|
||||
fi
|
||||
done
|
||||
|
||||
echo
|
||||
echo "示例产物: 成功 $ok / 失败 $fail"
|
||||
[ -n "$failed_names" ] && echo "失败:$failed_names"
|
||||
|
||||
# 有失败就不算发版闭环：宁可整个中断，也不要发出「少几个插件」的包。
|
||||
if [ $fail -ne 0 ]; then
|
||||
echo "[examples] 有示例构建失败，不生成 SHA256SUMS" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# 2) 全部产物齐了才算校验和。
|
||||
( cd "$OUT_DIR" && sha256sum ./*.hmap > SHA256SUMS )
|
||||
|
||||
VERSION="${VERSION:-$(git -C "$SDK_ROOT" describe --tags --dirty 2>/dev/null || echo unknown)}"
|
||||
COMMIT="${COMMIT:-$(git -C "$SDK_ROOT" rev-parse --short HEAD 2>/dev/null || echo unknown)}"
|
||||
{
|
||||
echo "sdk_version: $VERSION"
|
||||
echo "sdk_commit: $COMMIT"
|
||||
echo "target: $GOOS/$GOARCH"
|
||||
echo "plugins: $ok"
|
||||
echo "built_at: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
|
||||
echo
|
||||
echo "这些 .hmap 与本版 SDK 的插件协议绑定，必须与同版本内核配套安装。"
|
||||
echo "校验：sha256sum -c SHA256SUMS"
|
||||
} > "$OUT_DIR/MANIFEST.txt"
|
||||
|
||||
echo "[examples] 产物: $OUT_DIR"
|
||||
echo "[examples] 清单: $OUT_DIR/MANIFEST.txt"
|
||||
echo "[examples] 校验: $OUT_DIR/SHA256SUMS"
|
||||
@ -5,6 +5,13 @@ PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
BUILD_DIR="${PROJECT_ROOT}/build"
|
||||
VERSION="${VERSION:-$(git -C "$PROJECT_ROOT" describe --tags --dirty 2>/dev/null || echo "0.7.1")}"
|
||||
GO="${GO:-$(command -v go 2>/dev/null || echo "/home/jianf/go1.26.5/go/bin/go")}"
|
||||
# 宿主平台必须在**本脚本 export GOOS/GOARCH 之前**取定。
|
||||
# 否则 `go env GOOS` 会返回被 export 的目标平台（此前 `build.sh all all`
|
||||
# 就是因此拿 darwin 二进制在 linux 上跑，报 cannot execute binary file）。
|
||||
NATIVE_GOOS="$(env -u GOOS -u GOARCH "$GO" env GOOS 2>/dev/null || uname -s | tr 'A-Z' 'a-z')"
|
||||
NATIVE_GOARCH="$(env -u GOOS -u GOARCH "$GO" env GOARCH 2>/dev/null || uname -m)"
|
||||
case "$NATIVE_GOARCH" in x86_64|amd64) NATIVE_GOARCH="amd64" ;; aarch64|arm64) NATIVE_GOARCH="arm64" ;; esac
|
||||
case "$NATIVE_GOOS" in darwin|linux|windows) ;; *) NATIVE_GOOS="linux" ;; esac
|
||||
GOCACHE="${GOCACHE:-}"
|
||||
GOPATH="${GOPATH:-}"
|
||||
|
||||
@ -28,7 +35,7 @@ case "$TARGET" in
|
||||
;;
|
||||
*)
|
||||
echo "Unknown target: $TARGET"
|
||||
echo "Usage: $0 [native|linux/amd64|linux/arm64|darwin/amd64|darwin/arm64|windows/amd64|all] [all|plugindev]"
|
||||
echo "Usage: $0 [native|linux/amd64|linux/arm64|darwin/amd64|darwin/arm64|windows/amd64|all] [all|hmapdev|examples]"
|
||||
exit 1
|
||||
esac
|
||||
|
||||
@ -42,12 +49,12 @@ export CGO_ENABLED=0
|
||||
|
||||
mkdir -p "$BUILD_DIR"
|
||||
|
||||
build_plugindev() {
|
||||
local src="tools/plugindev"
|
||||
local out="$BUILD_DIR/plugindev${SUFFIX:+_$SUFFIX}"
|
||||
build_hmapdev() {
|
||||
local src="tools/hmapdev"
|
||||
local out="$BUILD_DIR/hmapdev${SUFFIX:+_$SUFFIX}"
|
||||
if [ "$GOOS" = "windows" ]; then out="${out}.exe"; fi
|
||||
|
||||
echo "[BUILD] plugindev ${GOOS:-linux}/${GOARCH:-amd64} → $out"
|
||||
echo "[BUILD] hmapdev ${GOOS:-linux}/${GOARCH:-amd64} → $out"
|
||||
cd "$PROJECT_ROOT/$src"
|
||||
"$GO" build -trimpath -ldflags "-X gitcode.com/JianFeeeee/homeagent-sdk/meta.Version=${VERSION}" \
|
||||
-o "$out" .
|
||||
@ -55,9 +62,47 @@ build_plugindev() {
|
||||
cd "$PROJECT_ROOT"
|
||||
}
|
||||
|
||||
# 示例插件产物随 SDK 一起发。
|
||||
#
|
||||
# 为什么必须发：插件二进制与内核是**协议绑定**的（ProtocolVersion + 统一共享
|
||||
# 内存区魔数）。SDK 升版常伴随协议变化，只发工具链不发示例产物，使用者很可能
|
||||
# 拿旧产物去装，表现是握手失败（魔数不匹配）——看起来像「插件坏了」而不是
|
||||
# 「版本不配套」。
|
||||
#
|
||||
# 用**宿主可执行**的那把工具链（而非 PATH 里的），保证产物与本次发版同源。
|
||||
#
|
||||
# 为什么不能用目标平台的那把：示例的跨平台构建是由 hmapdev 的 `--target GOOS/GOARCH`
|
||||
# 完成的，被执行的进程本身必須能在当前机器上跑。拿目标平台的二进制去跑只会得到
|
||||
# “cannot execute binary file: Exec format error”（`build.sh all all` 在 darwin 处断过）。
|
||||
build_examples() {
|
||||
local dev
|
||||
dev="$BUILD_DIR/hmapdev_${NATIVE_GOOS}_${NATIVE_GOARCH}"
|
||||
[ "$NATIVE_GOOS" = "windows" ] && dev="${dev}.exe"
|
||||
# 宿主工具链缺失时先补建（`all` 的第一个目标可能不是宿主平台）。
|
||||
if [ ! -x "$dev" ]; then
|
||||
echo "[BUILD] 先补建宿主工具链 ${NATIVE_GOOS}/${NATIVE_GOARCH}（示例的跨平台由 --target 完成）"
|
||||
( unset GOOS GOARCH; bash "$0" "${NATIVE_GOOS}/${NATIVE_GOARCH}" hmapdev ) || return 1
|
||||
fi
|
||||
if [ ! -x "$dev" ]; then
|
||||
echo "[BUILD] 无法构建示例：缺少宿主可执行的工具链 $dev" >&2
|
||||
echo " 先跑： $0 ${NATIVE_GOOS}/${NATIVE_GOARCH} hmapdev" >&2
|
||||
return 1
|
||||
fi
|
||||
echo "[BUILD] example plugins ${GOOS:-linux}/${GOARCH:-amd64} → $BUILD_DIR/examples（用 ${NATIVE_GOOS}/${NATIVE_GOARCH} 的工具链交叉构建）"
|
||||
PLUGINDEV="$dev" VERSION="$VERSION" bash "$PROJECT_ROOT/package/build-examples.sh" "$TARGET" "$BUILD_DIR/examples"
|
||||
echo " OK"
|
||||
}
|
||||
|
||||
case "$COMPONENT" in
|
||||
all|plugindev) build_plugindev ;;
|
||||
all)
|
||||
# 工具链必须先建完：示例用它来构建（同源保证协议一致）。
|
||||
build_hmapdev
|
||||
build_examples
|
||||
;;
|
||||
hmapdev) build_hmapdev ;;
|
||||
examples) build_examples ;;
|
||||
*)
|
||||
echo "Unknown component: $COMPONENT"
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
|
||||
@ -48,7 +48,7 @@ Function pageConfirm
|
||||
${EndIf}
|
||||
${NSD_CreateLabel} 0 5u 100% 12u "将安装以下组件:"
|
||||
Pop $0
|
||||
${NSD_CreateLabel} 15u 20u 100% 12u "• plugindev.exe — 插件开发工具"
|
||||
${NSD_CreateLabel} 15u 20u 100% 12u "• hmapdev.exe — 插件开发工具"
|
||||
Pop $0
|
||||
${NSD_CreateLabel} 15u 35u 100% 12u "• SDK ${SDK_VERSION} — 将从远程仓库自动下载"
|
||||
Pop $0
|
||||
@ -64,11 +64,11 @@ Section "Install" SEC_INSTALL
|
||||
SetOutPath "$INSTDIR"
|
||||
|
||||
DetailPrint "复制工具链文件..."
|
||||
File "plugindev.exe"
|
||||
File "hmapdev.exe"
|
||||
|
||||
DetailPrint "创建快捷方式..."
|
||||
CreateDirectory "$SMPROGRAMS\${PRODUCT_NAME}"
|
||||
CreateShortCut "$SMPROGRAMS\${PRODUCT_NAME}\plugindev.lnk" "$INSTDIR\plugindev.exe" "" "$INSTDIR\plugindev.exe" 0
|
||||
CreateShortCut "$SMPROGRAMS\${PRODUCT_NAME}\hmapdev.lnk" "$INSTDIR\hmapdev.exe" "" "$INSTDIR\hmapdev.exe" 0
|
||||
|
||||
DetailPrint "配置环境变量..."
|
||||
; Add to system PATH
|
||||
@ -93,23 +93,23 @@ Section "Install" SEC_INSTALL
|
||||
DetailPrint "Git 已安装: $1"
|
||||
${Else}
|
||||
DetailPrint "未检测到 Git，将跳过 SDK 自动下载"
|
||||
DetailPrint "安装完成后请手动运行: plugindev sdk install ${SDK_VERSION}"
|
||||
DetailPrint "安装完成后请手动运行: hmapdev sdk install ${SDK_VERSION}"
|
||||
${EndIf}
|
||||
|
||||
${If} $hasGit == "1"
|
||||
DetailPrint "正在下载 SDK ${SDK_VERSION}..."
|
||||
nsExec::ExecToStack '"$INSTDIR\plugindev.exe" sdk install ${SDK_VERSION}'
|
||||
nsExec::ExecToStack '"$INSTDIR\hmapdev.exe" sdk install ${SDK_VERSION}'
|
||||
Pop $0
|
||||
Pop $1
|
||||
${If} $0 == 0
|
||||
StrCpy $sdkInstallOk "1"
|
||||
DetailPrint "SDK ${SDK_VERSION} 下载完成"
|
||||
DetailPrint "正在激活 SDK ${SDK_VERSION}..."
|
||||
nsExec::Exec '"$INSTDIR\plugindev.exe" sdk use ${SDK_VERSION}'
|
||||
nsExec::Exec '"$INSTDIR\hmapdev.exe" sdk use ${SDK_VERSION}'
|
||||
Pop $0
|
||||
${Else}
|
||||
DetailPrint "SDK 下载失败 (错误码: $0)"
|
||||
DetailPrint "请手动运行: plugindev sdk install ${SDK_VERSION}"
|
||||
DetailPrint "请手动运行: hmapdev sdk install ${SDK_VERSION}"
|
||||
${EndIf}
|
||||
${EndIf}
|
||||
|
||||
@ -126,10 +126,10 @@ SectionEnd
|
||||
|
||||
Section "Uninstall"
|
||||
Delete "$INSTDIR\Uninstall.exe"
|
||||
Delete "$INSTDIR\plugindev.exe"
|
||||
Delete "$INSTDIR\hmapdev.exe"
|
||||
RMDir /r "$INSTDIR\sdk"
|
||||
RMDir "$INSTDIR"
|
||||
Delete "$SMPROGRAMS\${PRODUCT_NAME}\plugindev.lnk"
|
||||
Delete "$SMPROGRAMS\${PRODUCT_NAME}\hmapdev.lnk"
|
||||
RMDir "$SMPROGRAMS\${PRODUCT_NAME}"
|
||||
DeleteRegValue HKLM "SYSTEM\CurrentControlSet\Control\Session Manager\Environment" "HOMEAGENT_SDK_DIR"
|
||||
DeleteRegKey HKLM "Software\Microsoft\CurrentVersion\Uninstall\${PRODUCT_NAME}"
|
||||
|
||||
@ -25,13 +25,18 @@ type Relation struct {
|
||||
}
|
||||
|
||||
// Triple represents a subject-relation-object triple for the knowledge graph.
|
||||
//
|
||||
// SentenceText 是这条三元组的原句，会写进 sentences 表；媒体引用挂在句子上，
|
||||
// 所以 MediaDigests 非空时内核会保证句子存在（不给就自动合成一句）。
|
||||
type Triple struct {
|
||||
Subject string `json:"subject"`
|
||||
Relation string `json:"relation"`
|
||||
Object string `json:"object"`
|
||||
Confidence float64 `json:"confidence,omitempty"`
|
||||
SubjectType string `json:"subject_type,omitempty"`
|
||||
ObjectType string `json:"object_type,omitempty"`
|
||||
Subject string `json:"subject"`
|
||||
Relation string `json:"relation"`
|
||||
Object string `json:"object"`
|
||||
Confidence float64 `json:"confidence,omitempty"`
|
||||
SubjectType string `json:"subject_type,omitempty"`
|
||||
ObjectType string `json:"object_type,omitempty"`
|
||||
SentenceText string `json:"sentence_text,omitempty"`
|
||||
MediaDigests []string `json:"media_digests,omitempty"`
|
||||
}
|
||||
|
||||
// TextMemoryAPI provides access to chronological text event storage.
|
||||
@ -40,27 +45,54 @@ type TextMemoryAPI interface {
|
||||
}
|
||||
|
||||
// TextEvent represents a single text memory event.
|
||||
// MediaAttachment 描述一份与记忆关联的媒体。
|
||||
//
|
||||
// 两个方向共用一个类型：
|
||||
// - 写入（InsertWithMedia）：给 Data + MIME 就是新内容；只给 Digest 则是引用已有内容。
|
||||
// - 读出（Query）：内核只填 Digest/MIME，**不回 Data**——
|
||||
// 一次检索可能命中几十张图，把字节全塞回插件会把 ABI 消息撑爆。
|
||||
// 需要字节时拿 Digest 单独取。
|
||||
//
|
||||
// 刻意没有 Description 字段：媒体不作为文本被索引，也不带任何生成的描述。
|
||||
// 它只按自己的原生向量被检索与召回；附加文字请写在文档 / 三元组的文本里。
|
||||
type MediaAttachment struct {
|
||||
Digest string `json:"digest,omitempty"`
|
||||
MIME string `json:"mime,omitempty"`
|
||||
Data []byte `json:"data,omitempty"`
|
||||
Name string `json:"name,omitempty"`
|
||||
}
|
||||
|
||||
type TextEvent struct {
|
||||
Role string `json:"role"`
|
||||
Content string `json:"content"`
|
||||
Timestamp int64 `json:"timestamp"`
|
||||
Channel string `json:"channel,omitempty"`
|
||||
Role string `json:"role"`
|
||||
Content string `json:"content"`
|
||||
Timestamp int64 `json:"timestamp"`
|
||||
Channel string `json:"channel,omitempty"`
|
||||
Attachments []MediaAttachment `json:"attachments,omitempty"`
|
||||
}
|
||||
|
||||
// DocMemoryAPI provides access to the document vector store.
|
||||
type DocMemoryAPI interface {
|
||||
Query(text string, topK int) []*Doc
|
||||
Insert(doc *Doc) error
|
||||
// InsertWithMedia 写入文档并关联媒体。attachments 里带 Data 的会落进
|
||||
// 内容寻址存储（相同字节只存一份），只带 Digest 的直接引用已有内容。
|
||||
// 媒体成为文档直接持有的一等记忆块：文档向量会融合它们的原生向量，
|
||||
// 因此图片按自己的向量被召回，不依赖任何生成的描述文本。
|
||||
InsertWithMedia(doc *Doc, attachments []MediaAttachment) error
|
||||
Remove(id string)
|
||||
Stats() map[string]interface{}
|
||||
}
|
||||
|
||||
// Doc represents a document in the document store.
|
||||
//
|
||||
// MediaDigests / Attachments 在 Query 返回时由内核填充（仅元数据，不带字节）。
|
||||
type Doc struct {
|
||||
ID string `json:"id"`
|
||||
Title string `json:"title"`
|
||||
Content string `json:"content"`
|
||||
Score float64 `json:"score,omitempty"`
|
||||
ID string `json:"id"`
|
||||
Title string `json:"title"`
|
||||
Content string `json:"content"`
|
||||
Score float64 `json:"score,omitempty"`
|
||||
MediaDigests []string `json:"media_digests,omitempty"`
|
||||
Attachments []MediaAttachment `json:"attachments,omitempty"`
|
||||
}
|
||||
|
||||
// SocialAPI provides read-only access to the social graph (person profiles and relationships).
|
||||
@ -75,9 +107,9 @@ type SocialAPI interface {
|
||||
|
||||
// PersonProfile represents a person's complete profile (traits + social relations).
|
||||
type PersonProfile struct {
|
||||
Name string `json:"name"`
|
||||
Traits map[string]string `json:"traits,omitempty"`
|
||||
Relations []SocialRelation `json:"relations,omitempty"`
|
||||
Name string `json:"name"`
|
||||
Traits map[string]string `json:"traits,omitempty"`
|
||||
Relations []SocialRelation `json:"relations,omitempty"`
|
||||
}
|
||||
|
||||
// SocialRelation represents a social relationship between two persons.
|
||||
|
||||
378
sdk/plugin.go
378
sdk/plugin.go
@ -35,12 +35,63 @@ const (
|
||||
StageAfterOutput Stage = "after_output"
|
||||
)
|
||||
|
||||
// 上下文策略：决定一次工具调用/输入/注入是否依据其内容裁剪上下文。
|
||||
//
|
||||
// 默认（空串或 ContextPolicyNone）**不裁剪**：裁剪会归档丢弃低相关事件，
|
||||
// 必须由工具/通道/注入点显式声明才发生——否则一个只想往上下文里塞内容的
|
||||
// 插件会在背后把别人的内容挤掉，且看不出是谁干的。
|
||||
const (
|
||||
ContextPolicyNone = "none"
|
||||
ContextPolicyPrune = "prune"
|
||||
)
|
||||
|
||||
// ValidContextPolicy 校验策略取值；空串等价于 ContextPolicyNone。
|
||||
func ValidContextPolicy(policy string) bool {
|
||||
switch policy {
|
||||
case "", ContextPolicyNone, ContextPolicyPrune:
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// InjectOptions 声明一次注入行为在记忆层与上下文层的表现。
|
||||
//
|
||||
// 零值 = 记入记忆 + 不裁剪上下文，与历史行为（三参数注入方法）完全一致，
|
||||
// 因此调用方只有在确实需要改变行为时才需要填它。
|
||||
//
|
||||
// 为什么注入也要这两个标志：注入的内容来源千差万别——轮询到的频道消息
|
||||
// 属于真实对话（该记），而“任务还在跑”“连接已重连”这类提醒不该污染记忆，
|
||||
// 也不该把上下文按它的内容裁一遍。按调用点声明比按通道一刀切准确。
|
||||
//
|
||||
// NoMemory: 此次注入不参与记忆计算（向量化/关键词提取/蒸馏），原文仍留在上下文
|
||||
// ContextPolicy: 此次注入后是否依据（清洗后的）内容裁剪上下文；默认不裁剪。
|
||||
//
|
||||
// 中断注入也允许声明 prune——它同样会携带内容进入上下文。
|
||||
//
|
||||
// CleanerName: 此次注入的内容用哪个**已注册的通道 cleaner** 清洗。
|
||||
//
|
||||
// 空串 = 按注入的 source 查通道定义（既有行为）。
|
||||
// 为什么要能显式指定：注入的 source 未必是注册过的输入通道名，
|
||||
// 而注入内容往往带 ANSI/JSON 包装，需要清洗后才是有效内容；
|
||||
// 不指定就只能退到「按 source 查不到就不清洗」。
|
||||
type InjectOptions struct {
|
||||
NoMemory bool
|
||||
ContextPolicy string
|
||||
CleanerName string
|
||||
}
|
||||
|
||||
// ChannelDef 描述通道在记忆计算层的行为，与 ToolDef.NoMemory/Cleaner 语义一致。
|
||||
// NoMemory: 此通道输入/输出不参与记忆计算（向量化/关键词提取/蒸馏），但原文保留在上下文中
|
||||
// Cleaner: 计算层过滤函数，不改原文；仅在向量化/jieba/蒸馏/存档提取关键词时调用
|
||||
// ContextPolicy: 此通道的输入到达后是否据此裁剪上下文，默认 none（不裁剪）
|
||||
//
|
||||
// JSON tag 是必需的：通道定义要跨进程传给内核，而 Cleaner 是函数（必须忽略）。
|
||||
// 没有 tag 时既无法整体 marshal（func 不支持），又会诱使调用方手写字段白名单——
|
||||
// 那样新增字段会被静默丢掉。
|
||||
type ChannelDef struct {
|
||||
NoMemory bool
|
||||
Cleaner func(string) string
|
||||
NoMemory bool `json:"no_memory,omitempty"`
|
||||
Cleaner func(string) string `json:"-"`
|
||||
ContextPolicy string `json:"context_policy,omitempty"`
|
||||
}
|
||||
|
||||
// StageContext provides context for stage handlers.
|
||||
@ -61,14 +112,18 @@ type StageContext struct {
|
||||
Memory []MemItem
|
||||
NoMemory bool
|
||||
Extra map[string]interface{}
|
||||
Errors []string // 阶段处理过程中的错误信息
|
||||
Errors []string // 阶段处理过程中的错误信息
|
||||
}
|
||||
|
||||
func (c *StageContext) RLock() { c.mu.RLock() }
|
||||
func (c *StageContext) RUnlock() { c.mu.RUnlock() }
|
||||
func (c *StageContext) Lock() { c.mu.Lock() }
|
||||
func (c *StageContext) Unlock() { c.mu.Unlock() }
|
||||
func (c *StageContext) IsResponded() bool { c.mu.RLock(); defer c.mu.RUnlock(); return c.Response != nil }
|
||||
func (c *StageContext) RLock() { c.mu.RLock() }
|
||||
func (c *StageContext) RUnlock() { c.mu.RUnlock() }
|
||||
func (c *StageContext) Lock() { c.mu.Lock() }
|
||||
func (c *StageContext) Unlock() { c.mu.Unlock() }
|
||||
func (c *StageContext) IsResponded() bool {
|
||||
c.mu.RLock()
|
||||
defer c.mu.RUnlock()
|
||||
return c.Response != nil
|
||||
}
|
||||
|
||||
// MemItem represents a memory item in stage context.
|
||||
type MemItem struct {
|
||||
@ -96,12 +151,13 @@ type ToolResult struct {
|
||||
|
||||
// ToolDef describes a tool that the plugin exposes.
|
||||
type ToolDef struct {
|
||||
Name string `json:"name"`
|
||||
Plugin string `json:"plugin,omitempty"`
|
||||
Description string `json:"description"`
|
||||
Parameters map[string]interface{} `json:"parameters"`
|
||||
NoMemory bool `json:"no_memory,omitempty"` // 此工具输出不参与记忆计算，但原文保留
|
||||
Cleaner func(string) string `json:"-"` // 计算层过滤函数，不改原文；仅在向量化/jieba/蒸馏时调用
|
||||
Name string `json:"name"`
|
||||
Plugin string `json:"plugin,omitempty"`
|
||||
Description string `json:"description"`
|
||||
Parameters map[string]interface{} `json:"parameters"`
|
||||
NoMemory bool `json:"no_memory,omitempty"` // 此工具输出不参与记忆计算，但原文保留
|
||||
Cleaner func(string) string `json:"-"` // 计算层过滤函数，不改原文；仅在向量化/jieba/蒸馏时调用
|
||||
ContextPolicy string `json:"context_policy,omitempty"` // 上下文策略：""(默认，不裁剪) / ContextPolicyNone / ContextPolicyPrune
|
||||
}
|
||||
|
||||
// IOInjector provides methods for injecting input and interrupts into the agent pipeline.
|
||||
@ -117,6 +173,20 @@ type IOInjector interface {
|
||||
// SetToolBlocks 插件工具注入多模态内容块（image_url/audio_url），内核在下一条
|
||||
// tool message 的 content 数组里带上这些块，让模型在后续轮次看到图/听到音频。
|
||||
SetToolBlocks(blocks []ContentBlock)
|
||||
InjectInputMedia(source, channel, text string, blocks []ContentBlock)
|
||||
InjectInputMediaSync(source, channel, text string, blocks []ContentBlock) string
|
||||
InjectInterruptMedia(source, channel, text string, blocks []ContentBlock)
|
||||
|
||||
// 以下 Opts 变体让调用点在**这一次注入**上声明记忆与裁剪行为。
|
||||
//
|
||||
// 上面那些不带 opts 的方法等价于传零值 InjectOptions（记入记忆 + 不裁剪），
|
||||
// 保留它们是为了不破坏已有插件；新代码应当用 Opts 变体把意图写清楚。
|
||||
InjectTextOpts(source, channel, text string, opts InjectOptions)
|
||||
InjectInterruptTextOpts(source, channel, text string, opts InjectOptions)
|
||||
InjectInputSyncOpts(source, channel, text string, opts InjectOptions) string
|
||||
InjectInputMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
|
||||
InjectInputMediaSyncOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) string
|
||||
InjectInterruptMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
|
||||
}
|
||||
|
||||
// EventType identifies the kind of system event.
|
||||
@ -221,6 +291,24 @@ type PluginSDK struct {
|
||||
events EventSubscriber
|
||||
plgMgr PluginMgrAPI
|
||||
|
||||
// apiMu 保护上面这些由内核注入的 API 字段，以及 autoRestart。
|
||||
//
|
||||
// 这些字段的写方与读方天然跨 goroutine：
|
||||
// - 写方是内核（加载/重载插件时注入 API）与插件自己（SetAutoRestart）；
|
||||
// - 读方是插件在 Start() 里起的后台 goroutine（轮询、监听、定时器
|
||||
// 都要拿 injector 往管道里注消息），以及内核 registry —— 它在
|
||||
// 另一个 goroutine 读 AutoRestart() 决定崩溃后是否重启。
|
||||
// SetAutoRestart 的文档用法本身就是「连接建立后再决定能否自动重启」，
|
||||
// 而连接建立通常发生在后台 goroutine 里，于是这对读写必然并发。
|
||||
//
|
||||
// sdk/stress_test.go 的 -race 实测确认这是真竞态，不是理论风险。
|
||||
// 未加锁时的生产表现是偶发 nil 解引用崩溃（读到半个接口值）。
|
||||
//
|
||||
// 约定：只在持锁期间取字段值，取完立刻释放再调用。
|
||||
// 持锁调用会把 InjectInputSync 这类阻塞到 agent 回复（可达数分钟）的
|
||||
// 方法与 SetIOInjector 串到一起，让插件重载卡死。
|
||||
apiMu sync.RWMutex
|
||||
|
||||
autoRestart bool
|
||||
|
||||
stopMu sync.Mutex
|
||||
@ -247,28 +335,57 @@ func New(name string, sett SettingsAPI, regTool ToolRegistrar, regStage StageReg
|
||||
func (s *PluginSDK) PluginName() string { return s.name }
|
||||
|
||||
// Settings returns the settings API for reading/writing plugin configuration.
|
||||
// sett 在 New 时一次性写入且无 setter，故不需要加锁。
|
||||
func (s *PluginSDK) Settings() SettingsAPI { return s.sett }
|
||||
|
||||
// Memory returns the graph memory API (may be nil if not available).
|
||||
func (s *PluginSDK) Memory() MemoryAPI { return s.mem }
|
||||
func (s *PluginSDK) Memory() MemoryAPI {
|
||||
s.apiMu.RLock()
|
||||
defer s.apiMu.RUnlock()
|
||||
return s.mem
|
||||
}
|
||||
|
||||
// TextMemory returns the text memory API (may be nil if not available).
|
||||
func (s *PluginSDK) TextMemory() TextMemoryAPI { return s.textMem }
|
||||
func (s *PluginSDK) TextMemory() TextMemoryAPI {
|
||||
s.apiMu.RLock()
|
||||
defer s.apiMu.RUnlock()
|
||||
return s.textMem
|
||||
}
|
||||
|
||||
// DocMemory returns the document memory API (may be nil if not available).
|
||||
func (s *PluginSDK) DocMemory() DocMemoryAPI { return s.docMem }
|
||||
func (s *PluginSDK) DocMemory() DocMemoryAPI {
|
||||
s.apiMu.RLock()
|
||||
defer s.apiMu.RUnlock()
|
||||
return s.docMem
|
||||
}
|
||||
|
||||
// Knowledge returns the knowledge store API (may be nil if not available).
|
||||
func (s *PluginSDK) Knowledge() KnowledgeAPI { return s.know }
|
||||
func (s *PluginSDK) Knowledge() KnowledgeAPI {
|
||||
s.apiMu.RLock()
|
||||
defer s.apiMu.RUnlock()
|
||||
return s.know
|
||||
}
|
||||
|
||||
// LLM returns the LLM provider API (may be nil if not available).
|
||||
func (s *PluginSDK) LLM() LLMAPI { return s.llm }
|
||||
func (s *PluginSDK) LLM() LLMAPI {
|
||||
s.apiMu.RLock()
|
||||
defer s.apiMu.RUnlock()
|
||||
return s.llm
|
||||
}
|
||||
|
||||
// Social returns the social graph API (may be nil if not available).
|
||||
func (s *PluginSDK) Social() SocialAPI { return s.social }
|
||||
func (s *PluginSDK) Social() SocialAPI {
|
||||
s.apiMu.RLock()
|
||||
defer s.apiMu.RUnlock()
|
||||
return s.social
|
||||
}
|
||||
|
||||
// Events returns the event subscriber for listening to kernel events (may be nil if not available).
|
||||
func (s *PluginSDK) Events() EventSubscriber { return s.events }
|
||||
func (s *PluginSDK) Events() EventSubscriber {
|
||||
s.apiMu.RLock()
|
||||
defer s.apiMu.RUnlock()
|
||||
return s.events
|
||||
}
|
||||
|
||||
// RegisterTool registers a tool that the LLM can call.
|
||||
func (s *PluginSDK) RegisterTool(name string, def ToolDef, handler ToolHandler) error {
|
||||
@ -282,8 +399,9 @@ func (s *PluginSDK) RegisterTool(name string, def ToolDef, handler ToolHandler)
|
||||
}
|
||||
|
||||
// RegisterStage registers a handler for a pipeline stage.
|
||||
// scope: StageScopeGlobal (default) — receives all stage events.
|
||||
// StageScopeOwnTools — only before_toolcall/after_toolcall for this plugin's tools.
|
||||
//
|
||||
// scope: StageScopeGlobal (default) — receives all stage events.
|
||||
// StageScopeOwnTools — only before_toolcall/after_toolcall for this plugin's tools.
|
||||
func (s *PluginSDK) RegisterStage(stage Stage, handler StageHandler, scope ...StageScope) {
|
||||
if s.regStage == nil {
|
||||
return
|
||||
@ -333,8 +451,11 @@ func (s *PluginSDK) RegisterPluginAPI(name string) error {
|
||||
// def: 通道在记忆计算层的行为（NoMemory/Cleaner）
|
||||
// handler: receives args map with keys: payload (string), type (string), meta (string|optional)
|
||||
func (s *PluginSDK) RegisterOutputChannel(name string, caps int, desc string, def ChannelDef, handler ToolHandler) error {
|
||||
if s.regOutput != nil {
|
||||
return s.regOutput(name, caps, desc, def, handler)
|
||||
s.apiMu.RLock()
|
||||
reg := s.regOutput
|
||||
s.apiMu.RUnlock()
|
||||
if reg != nil {
|
||||
return reg(name, caps, desc, def, handler)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
@ -343,76 +464,229 @@ func (s *PluginSDK) RegisterOutputChannel(name string, caps int, desc string, de
|
||||
// def.NoMemory: 此通道输入不参与记忆计算
|
||||
// def.Cleaner: 计算层对输入文本清洗后（不改原文）再向量化/提关键词
|
||||
func (s *PluginSDK) RegisterInputChannel(name string, def ChannelDef) error {
|
||||
if s.regInput != nil {
|
||||
return s.regInput(name, def)
|
||||
s.apiMu.RLock()
|
||||
reg := s.regInput
|
||||
s.apiMu.RUnlock()
|
||||
if reg != nil {
|
||||
return reg(name, def)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// 以下 setter 由内核在启动/重载时调用，与插件后台 goroutine 的读并发，故加锁。
|
||||
|
||||
// SetOutputChannelRegistrar sets the output channel registrar (called by the core at startup).
|
||||
func (s *PluginSDK) SetOutputChannelRegistrar(r OutputChannelRegistrar) { s.regOutput = r }
|
||||
func (s *PluginSDK) SetOutputChannelRegistrar(r OutputChannelRegistrar) {
|
||||
s.apiMu.Lock()
|
||||
s.regOutput = r
|
||||
s.apiMu.Unlock()
|
||||
}
|
||||
|
||||
// SetInputChannelRegistrar sets the input channel registrar (called by the core at startup).
|
||||
func (s *PluginSDK) SetInputChannelRegistrar(r InputChannelRegistrar) { s.regInput = r }
|
||||
func (s *PluginSDK) SetInputChannelRegistrar(r InputChannelRegistrar) {
|
||||
s.apiMu.Lock()
|
||||
s.regInput = r
|
||||
s.apiMu.Unlock()
|
||||
}
|
||||
|
||||
// SetIOInjector sets the IO injector (called by the core at startup).
|
||||
func (s *PluginSDK) SetIOInjector(io IOInjector) { s.io = io }
|
||||
func (s *PluginSDK) SetIOInjector(io IOInjector) {
|
||||
s.apiMu.Lock()
|
||||
s.io = io
|
||||
s.apiMu.Unlock()
|
||||
}
|
||||
|
||||
// SetMemoryAPI sets the memory API (called by the core at startup).
|
||||
func (s *PluginSDK) SetMemoryAPI(mem MemoryAPI) { s.mem = mem }
|
||||
func (s *PluginSDK) SetTextMemoryAPI(tm TextMemoryAPI) { s.textMem = tm }
|
||||
func (s *PluginSDK) SetDocMemoryAPI(dm DocMemoryAPI) { s.docMem = dm }
|
||||
func (s *PluginSDK) SetKnowledgeAPI(kn KnowledgeAPI) { s.know = kn }
|
||||
func (s *PluginSDK) SetLLMAPI(llm LLMAPI) { s.llm = llm }
|
||||
func (s *PluginSDK) SetSocialAPI(social SocialAPI) { s.social = social }
|
||||
func (s *PluginSDK) SetEventSubscriber(es EventSubscriber) { s.events = es }
|
||||
func (s *PluginSDK) SetMemoryAPI(mem MemoryAPI) {
|
||||
s.apiMu.Lock()
|
||||
s.mem = mem
|
||||
s.apiMu.Unlock()
|
||||
}
|
||||
|
||||
func (s *PluginSDK) SetTextMemoryAPI(tm TextMemoryAPI) {
|
||||
s.apiMu.Lock()
|
||||
s.textMem = tm
|
||||
s.apiMu.Unlock()
|
||||
}
|
||||
|
||||
func (s *PluginSDK) SetDocMemoryAPI(dm DocMemoryAPI) {
|
||||
s.apiMu.Lock()
|
||||
s.docMem = dm
|
||||
s.apiMu.Unlock()
|
||||
}
|
||||
|
||||
func (s *PluginSDK) SetKnowledgeAPI(kn KnowledgeAPI) {
|
||||
s.apiMu.Lock()
|
||||
s.know = kn
|
||||
s.apiMu.Unlock()
|
||||
}
|
||||
|
||||
func (s *PluginSDK) SetLLMAPI(llm LLMAPI) {
|
||||
s.apiMu.Lock()
|
||||
s.llm = llm
|
||||
s.apiMu.Unlock()
|
||||
}
|
||||
|
||||
func (s *PluginSDK) SetSocialAPI(social SocialAPI) {
|
||||
s.apiMu.Lock()
|
||||
s.social = social
|
||||
s.apiMu.Unlock()
|
||||
}
|
||||
|
||||
func (s *PluginSDK) SetEventSubscriber(es EventSubscriber) {
|
||||
s.apiMu.Lock()
|
||||
s.events = es
|
||||
s.apiMu.Unlock()
|
||||
}
|
||||
|
||||
// SetPluginMgrAPI sets the plugin manager API (called by the bridge at startup).
|
||||
func (s *PluginSDK) SetPluginMgrAPI(pm PluginMgrAPI) { s.plgMgr = pm }
|
||||
func (s *PluginSDK) SetPluginMgrAPI(pm PluginMgrAPI) {
|
||||
s.apiMu.Lock()
|
||||
s.plgMgr = pm
|
||||
s.apiMu.Unlock()
|
||||
}
|
||||
|
||||
// PluginMgr returns the plugin manager API (ReloadOne / ReloadPlugins / list).
|
||||
// May be nil if the host did not wire it.
|
||||
func (s *PluginSDK) PluginMgr() PluginMgrAPI { return s.plgMgr }
|
||||
func (s *PluginSDK) PluginMgr() PluginMgrAPI {
|
||||
s.apiMu.RLock()
|
||||
defer s.apiMu.RUnlock()
|
||||
return s.plgMgr
|
||||
}
|
||||
|
||||
// ---- IO Convenience Methods ----
|
||||
|
||||
// injector 取当前 injector 的快照。
|
||||
//
|
||||
// 取完即释放锁再调用：InjectInputSync 会阻塞到 agent 回复（可达数分钟），
|
||||
// 若持锁调用，插件重载时的 SetIOInjector 会一起卡住。
|
||||
func (s *PluginSDK) injector() IOInjector {
|
||||
s.apiMu.RLock()
|
||||
defer s.apiMu.RUnlock()
|
||||
return s.io
|
||||
}
|
||||
|
||||
// InjectInterruptText injects a text interrupt that can preempt current LLM processing.
|
||||
// 等价于 InjectInterruptTextOpts(..., InjectOptions{})：记入记忆、不裁剪。
|
||||
func (s *PluginSDK) InjectInterruptText(source, channel, text string) {
|
||||
if s.io != nil {
|
||||
s.io.InjectInterruptText(source, channel, text)
|
||||
}
|
||||
s.InjectInterruptTextOpts(source, channel, text, InjectOptions{})
|
||||
}
|
||||
|
||||
// InjectText injects a text message into the agent pipeline.
|
||||
// 等价于 InjectTextOpts(..., InjectOptions{})：记入记忆、不裁剪。
|
||||
func (s *PluginSDK) InjectText(source, channel, text string) {
|
||||
if s.io != nil {
|
||||
s.io.InjectText(source, channel, text)
|
||||
}
|
||||
s.InjectTextOpts(source, channel, text, InjectOptions{})
|
||||
}
|
||||
|
||||
// InjectTextNoMemory injects a text message without generating memory.
|
||||
// 等价于 InjectTextOpts(..., InjectOptions{NoMemory: true})。
|
||||
func (s *PluginSDK) InjectTextNoMemory(source, channel, text string) {
|
||||
if s.io != nil {
|
||||
s.io.InjectTextNoMemory(source, channel, text)
|
||||
}
|
||||
s.InjectTextOpts(source, channel, text, InjectOptions{NoMemory: true})
|
||||
}
|
||||
|
||||
// InjectInputSync injects a text message and synchronously waits for the agent reply,
|
||||
// returning the reply text (empty string if none). Replies must be dispatched back
|
||||
// to the source channel by the caller.
|
||||
func (s *PluginSDK) InjectInputSync(source, channel, text string) string {
|
||||
if s.io == nil {
|
||||
return s.InjectInputSyncOpts(source, channel, text, InjectOptions{})
|
||||
}
|
||||
|
||||
// InjectInputMedia 注入带媒体内容块（image_url/audio_url）的输入。
|
||||
// blocks 会落进媒体存储被记忆引用捕获，同时作为当前轮 content 数组
|
||||
// 发给 LLM，让模型在「本轮」就看到图/听到音频——区别于 SetToolBlocks
|
||||
// 的「下一轮 tool message」语义。
|
||||
// 等价于 InjectInputMediaOpts(..., InjectOptions{})。
|
||||
func (s *PluginSDK) InjectInputMedia(source, channel, text string, blocks []ContentBlock) {
|
||||
s.InjectInputMediaOpts(source, channel, text, blocks, InjectOptions{})
|
||||
}
|
||||
|
||||
// InjectInputMediaSync 注入带媒体内容块的输入并同步等待 agent 回复。
|
||||
// 等价于 InjectInputMediaSyncOpts(..., InjectOptions{})。
|
||||
func (s *PluginSDK) InjectInputMediaSync(source, channel, text string, blocks []ContentBlock) string {
|
||||
return s.InjectInputMediaSyncOpts(source, channel, text, blocks, InjectOptions{})
|
||||
}
|
||||
|
||||
// ---- 带 InjectOptions 的注入（声明记忆/裁剪行为）----
|
||||
|
||||
// InjectTextOpts 注入文本到 agent，并在这一次注入上声明记忆与裁剪行为。
|
||||
func (s *PluginSDK) InjectTextOpts(source, channel, text string, opts InjectOptions) {
|
||||
if io := s.injector(); io != nil {
|
||||
io.InjectTextOpts(source, channel, text, opts)
|
||||
}
|
||||
}
|
||||
|
||||
// InjectInterruptTextOpts 注入可抢占当前处理的中断文本。
|
||||
//
|
||||
// 中断也允许声明 ContextPolicyPrune：中断同样携带内容进入上下文，
|
||||
// 是否需要据此裁剪由调用方决定（默认不裁剪）。
|
||||
func (s *PluginSDK) InjectInterruptTextOpts(source, channel, text string, opts InjectOptions) {
|
||||
if io := s.injector(); io != nil {
|
||||
io.InjectInterruptTextOpts(source, channel, text, opts)
|
||||
}
|
||||
}
|
||||
|
||||
// InjectInputSyncOpts 注入输入并同步等待回复，同时在这次注入上声明记忆/裁剪行为。
|
||||
func (s *PluginSDK) InjectInputSyncOpts(source, channel, text string, opts InjectOptions) string {
|
||||
io := s.injector()
|
||||
if io == nil {
|
||||
return ""
|
||||
}
|
||||
return s.io.InjectInputSync(source, channel, text)
|
||||
return io.InjectInputSyncOpts(source, channel, text, opts)
|
||||
}
|
||||
|
||||
// InjectInputMediaOpts 注入带媒体块的输入，并声明记忆/裁剪行为。
|
||||
func (s *PluginSDK) InjectInputMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) {
|
||||
if io := s.injector(); io != nil {
|
||||
io.InjectInputMediaOpts(source, channel, text, blocks, opts)
|
||||
}
|
||||
}
|
||||
|
||||
// InjectInputMediaSyncOpts 注入带媒体块的输入并同步等待回复，同时声明记忆/裁剪行为。
|
||||
func (s *PluginSDK) InjectInputMediaSyncOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) string {
|
||||
io := s.injector()
|
||||
if io == nil {
|
||||
return ""
|
||||
}
|
||||
return io.InjectInputMediaSyncOpts(source, channel, text, blocks, opts)
|
||||
}
|
||||
|
||||
// InjectInterruptMediaOpts 注入带媒体块的中断，并声明记忆/裁剪行为。
|
||||
func (s *PluginSDK) InjectInterruptMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) {
|
||||
if io := s.injector(); io != nil {
|
||||
io.InjectInterruptMediaOpts(source, channel, text, blocks, opts)
|
||||
}
|
||||
}
|
||||
|
||||
// InjectInterruptMedia 注入带媒体内容块的中断，可抢占当前 LLM 处理。
|
||||
// blocks 随中断消息一起发给模型。
|
||||
func (s *PluginSDK) InjectInterruptMedia(source, channel, text string, blocks []ContentBlock) {
|
||||
if io := s.injector(); io != nil {
|
||||
io.InjectInterruptMedia(source, channel, text, blocks)
|
||||
}
|
||||
}
|
||||
|
||||
// SetToolBlocks 在工具处理函数内注入多模态内容块，内核在下一条 tool message
|
||||
// 的 content 数组里带上它们。需要「本轮就让模型看到」时用 InjectInputMedia。
|
||||
func (s *PluginSDK) SetToolBlocks(blocks []ContentBlock) {
|
||||
if io := s.injector(); io != nil {
|
||||
io.SetToolBlocks(blocks)
|
||||
}
|
||||
}
|
||||
|
||||
// SetAutoRestart 设置插件是否允许内核自动重启（崩溃后自动重载）。
|
||||
// 默认 true。如果插件有无法恢复的状态（如外部连接），应设为 false。
|
||||
func (s *PluginSDK) SetAutoRestart(enabled bool) { s.autoRestart = enabled }
|
||||
func (s *PluginSDK) SetAutoRestart(enabled bool) {
|
||||
s.apiMu.Lock()
|
||||
s.autoRestart = enabled
|
||||
s.apiMu.Unlock()
|
||||
}
|
||||
|
||||
// AutoRestart 返回插件是否允许自动重启。
|
||||
func (s *PluginSDK) AutoRestart() bool { return s.autoRestart }
|
||||
func (s *PluginSDK) AutoRestart() bool {
|
||||
s.apiMu.RLock()
|
||||
defer s.apiMu.RUnlock()
|
||||
return s.autoRestart
|
||||
}
|
||||
|
||||
// RegisterStopHandler 注册插件停止阶段的清理回调。
|
||||
// 注册的 handler 会在插件 Stop() 之前按"后注册先执行"的顺序调用，
|
||||
|
||||
760
sdk/stress_test.go
Normal file
760
sdk/stress_test.go
Normal file
@ -0,0 +1,760 @@
|
||||
package sdk
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"strings"
|
||||
"sync"
|
||||
"sync/atomic"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// SDK 公开接口的并发压力测试（1.1.0 媒体接口上线后新增）。
|
||||
//
|
||||
// 为什么这一层需要压测：SDK 是**被多个 goroutine 同时使用的共享对象**。
|
||||
// 一个插件的典型形态是 Start() 里起若干后台 goroutine（轮询、监听、定时器），
|
||||
// 它们各自持同一个 *PluginSDK 往里注入消息；内核侧同时还有 stage 扇出、
|
||||
// 工具调用、以及读 AutoRestart() 决定崩溃后是否重启。
|
||||
// 单线程单测全绿不代表这些并发路径成立。
|
||||
//
|
||||
// 关注点不是吞吐数字，而是不变量：
|
||||
// 1. 注入调用不丢、不串（媒体块必须与文本配对，不能张冠李戴）
|
||||
// 2. 状态字段的读写不产生数据竞争（-race 下必须干净）
|
||||
// 3. handler 注册/执行在并发下"恰好一次"
|
||||
// 4. 跨进程 JSON 序列化对新媒体类型必须字节级往返一致
|
||||
//
|
||||
// 媒体接口尤其需要 3 与 4：媒体块要经 JSON 过子进程边界，
|
||||
// 而 []byte 在 JSON 里是 base64，往返不一致的后果是图片静默损坏。
|
||||
|
||||
// ---------- 测试替身 ----------
|
||||
|
||||
// recordingInjector 记录每一次注入调用，用于验证"不丢不串"。
|
||||
type recordingInjector struct {
|
||||
mu sync.Mutex
|
||||
calls []injectCall
|
||||
|
||||
// 计数用原子量：并发路径上只增不减，可在不持锁时安全读。
|
||||
nText, nMedia, nInterrupt, nSync atomic.Int64
|
||||
}
|
||||
|
||||
type injectCall struct {
|
||||
kind string // text / media / interruptMedia / sync ...
|
||||
source string
|
||||
channel string
|
||||
text string
|
||||
blocks []ContentBlock
|
||||
opts InjectOptions // 调用点声明的记忆/裁剪行为
|
||||
}
|
||||
|
||||
func (r *recordingInjector) record(c injectCall) {
|
||||
r.mu.Lock()
|
||||
r.calls = append(r.calls, c)
|
||||
r.mu.Unlock()
|
||||
}
|
||||
|
||||
func (r *recordingInjector) InjectInterruptText(s, c, t string) {
|
||||
r.nInterrupt.Add(1)
|
||||
r.record(injectCall{kind: "interruptText", source: s, channel: c, text: t})
|
||||
}
|
||||
|
||||
func (r *recordingInjector) InjectText(s, c, t string) {
|
||||
r.nText.Add(1)
|
||||
r.record(injectCall{kind: "text", source: s, channel: c, text: t})
|
||||
}
|
||||
|
||||
func (r *recordingInjector) InjectTextNoMemory(s, c, t string) {
|
||||
r.nText.Add(1)
|
||||
r.record(injectCall{kind: "textNoMem", source: s, channel: c, text: t})
|
||||
}
|
||||
|
||||
func (r *recordingInjector) InjectInputSync(s, c, t string) string {
|
||||
r.nSync.Add(1)
|
||||
r.record(injectCall{kind: "sync", source: s, channel: c, text: t})
|
||||
return "reply:" + t
|
||||
}
|
||||
|
||||
func (r *recordingInjector) SetToolBlocks(blocks []ContentBlock) {
|
||||
r.record(injectCall{kind: "toolBlocks", blocks: blocks})
|
||||
}
|
||||
|
||||
func (r *recordingInjector) InjectInputMedia(s, c, t string, b []ContentBlock) {
|
||||
r.nMedia.Add(1)
|
||||
r.record(injectCall{kind: "media", source: s, channel: c, text: t, blocks: b})
|
||||
}
|
||||
|
||||
func (r *recordingInjector) InjectInputMediaSync(s, c, t string, b []ContentBlock) string {
|
||||
r.nMedia.Add(1)
|
||||
r.nSync.Add(1)
|
||||
r.record(injectCall{kind: "mediaSync", source: s, channel: c, text: t, blocks: b})
|
||||
return "reply:" + t
|
||||
}
|
||||
|
||||
func (r *recordingInjector) InjectInterruptMedia(s, c, t string, b []ContentBlock) {
|
||||
r.nMedia.Add(1)
|
||||
r.record(injectCall{kind: "interruptMedia", source: s, channel: c, text: t, blocks: b})
|
||||
}
|
||||
|
||||
// ---- 带 InjectOptions 的注入：记录 opts 以便测试断言标志位确实传到了内核 ----
|
||||
|
||||
func (r *recordingInjector) InjectTextOpts(s, c, t string, o InjectOptions) {
|
||||
r.nText.Add(1)
|
||||
r.record(injectCall{kind: "textOpts", source: s, channel: c, text: t, opts: o})
|
||||
}
|
||||
|
||||
func (r *recordingInjector) InjectInterruptTextOpts(s, c, t string, o InjectOptions) {
|
||||
r.nInterrupt.Add(1)
|
||||
r.record(injectCall{kind: "interruptTextOpts", source: s, channel: c, text: t, opts: o})
|
||||
}
|
||||
|
||||
func (r *recordingInjector) InjectInputSyncOpts(s, c, t string, o InjectOptions) string {
|
||||
r.nSync.Add(1)
|
||||
r.record(injectCall{kind: "syncOpts", source: s, channel: c, text: t, opts: o})
|
||||
return "reply:" + t
|
||||
}
|
||||
|
||||
func (r *recordingInjector) InjectInputMediaOpts(s, c, t string, b []ContentBlock, o InjectOptions) {
|
||||
r.nMedia.Add(1)
|
||||
r.record(injectCall{kind: "mediaOpts", source: s, channel: c, text: t, blocks: b, opts: o})
|
||||
}
|
||||
|
||||
func (r *recordingInjector) InjectInputMediaSyncOpts(s, c, t string, b []ContentBlock, o InjectOptions) string {
|
||||
r.nMedia.Add(1)
|
||||
r.nSync.Add(1)
|
||||
r.record(injectCall{kind: "mediaSyncOpts", source: s, channel: c, text: t, blocks: b, opts: o})
|
||||
return "reply:" + t
|
||||
}
|
||||
|
||||
func (r *recordingInjector) InjectInterruptMediaOpts(s, c, t string, b []ContentBlock, o InjectOptions) {
|
||||
r.nMedia.Add(1)
|
||||
r.record(injectCall{kind: "interruptMediaOpts", source: s, channel: c, text: t, blocks: b, opts: o})
|
||||
}
|
||||
|
||||
func (r *recordingInjector) snapshot() []injectCall {
|
||||
r.mu.Lock()
|
||||
defer r.mu.Unlock()
|
||||
return append([]injectCall{}, r.calls...)
|
||||
}
|
||||
|
||||
var _ IOInjector = (*recordingInjector)(nil)
|
||||
|
||||
// imageBlock 构造一个带可识别 URL 的图片块。
|
||||
func imageBlock(tag string) ContentBlock {
|
||||
return ContentBlock{
|
||||
Type: "image_url",
|
||||
ImageURL: &ImageURL{URL: "data:image/png;base64," + tag, Detail: "auto"},
|
||||
}
|
||||
}
|
||||
|
||||
// ---------- 1. 媒体注入并发不丢不串 ----------
|
||||
|
||||
// 三个媒体注入方法在高并发下必须：调用数精确、且每次调用的 text 与 blocks 配对不错。
|
||||
//
|
||||
// "不串"是这里的关键断言。注入是插件里最容易被后台 goroutine 并发调用的入口，
|
||||
// 若实现里出现任何共享中间状态（比如把 blocks 暂存到 SDK 字段再读出），
|
||||
// 高并发下就会出现 A 的文本配上 B 的图——而两者单独看都"成功"了，不报错。
|
||||
func TestStress_MediaInjectionConcurrentNoCrossTalk(t *testing.T) {
|
||||
const workers, perWorker = 32, 200
|
||||
|
||||
inj := &recordingInjector{}
|
||||
s := &PluginSDK{name: "stress"}
|
||||
s.SetIOInjector(inj)
|
||||
|
||||
var wg sync.WaitGroup
|
||||
for w := 0; w < workers; w++ {
|
||||
wg.Add(1)
|
||||
go func(w int) {
|
||||
defer wg.Done()
|
||||
for i := 0; i < perWorker; i++ {
|
||||
// tag 唯一标识这次调用，文本与图片 URL 里都带上它。
|
||||
tag := fmt.Sprintf("w%d-i%d", w, i)
|
||||
switch i % 3 {
|
||||
case 0:
|
||||
s.InjectInputMedia("src", "ch", tag, []ContentBlock{imageBlock(tag)})
|
||||
case 1:
|
||||
if got := s.InjectInputMediaSync("src", "ch", tag, []ContentBlock{imageBlock(tag)}); got != "reply:"+tag {
|
||||
t.Errorf("同步注入回复错位: got %q want %q", got, "reply:"+tag)
|
||||
}
|
||||
default:
|
||||
s.InjectInterruptMedia("src", "ch", tag, []ContentBlock{imageBlock(tag)})
|
||||
}
|
||||
}
|
||||
}(w)
|
||||
}
|
||||
wg.Wait()
|
||||
|
||||
total := int64(workers * perWorker)
|
||||
if got := inj.nMedia.Load(); got != total {
|
||||
t.Fatalf("媒体注入调用数 = %d，期望 %d（有调用丢失）", got, total)
|
||||
}
|
||||
|
||||
// 逐条校验文本与媒体块配对：URL 必须含该次调用自己的 tag。
|
||||
seen := map[string]bool{}
|
||||
for _, c := range inj.snapshot() {
|
||||
if len(c.blocks) == 0 {
|
||||
continue
|
||||
}
|
||||
if c.blocks[0].ImageURL == nil {
|
||||
t.Fatalf("媒体块 ImageURL 丢失: %+v", c.blocks[0])
|
||||
}
|
||||
if !strings.HasSuffix(c.blocks[0].ImageURL.URL, c.text) {
|
||||
t.Fatalf("文本与媒体块错位: text=%q url=%q", c.text, c.blocks[0].ImageURL.URL)
|
||||
}
|
||||
if seen[c.text] {
|
||||
t.Fatalf("同一次调用被记录两次: %s", c.text)
|
||||
}
|
||||
seen[c.text] = true
|
||||
}
|
||||
if len(seen) != int(total) {
|
||||
t.Fatalf("去重后调用数 = %d，期望 %d", len(seen), total)
|
||||
}
|
||||
}
|
||||
|
||||
// ---------- 2. 注入期间热替换 injector ----------
|
||||
|
||||
// 内核在插件运行期间可能重新注入 API（重载、恢复、子进程重连握手）。
|
||||
// 此时插件的后台 goroutine 仍在注入。这条路径若无同步就是对 s.io 的数据竞争，
|
||||
// 在 -race 下会被抓出；生产表现是偶发 nil 解引用崩溃。
|
||||
func TestStress_InjectorSwapDuringInjection(t *testing.T) {
|
||||
s := &PluginSDK{name: "stress"}
|
||||
s.SetIOInjector(&recordingInjector{})
|
||||
|
||||
stop := make(chan struct{})
|
||||
var injectors, swapper sync.WaitGroup
|
||||
|
||||
// 注入方：持续打直到 stop
|
||||
for w := 0; w < 8; w++ {
|
||||
injectors.Add(1)
|
||||
go func() {
|
||||
defer injectors.Done()
|
||||
for {
|
||||
select {
|
||||
case <-stop:
|
||||
return
|
||||
default:
|
||||
s.InjectInputMedia("src", "ch", "x", []ContentBlock{imageBlock("x")})
|
||||
s.InjectText("src", "ch", "y")
|
||||
}
|
||||
}
|
||||
}()
|
||||
}
|
||||
|
||||
// 替换方：反复换 injector（含换成 nil——内核卸载 API 时的真实状态）
|
||||
swapper.Add(1)
|
||||
go func() {
|
||||
defer swapper.Done()
|
||||
for i := 0; i < 500; i++ {
|
||||
if i%7 == 0 {
|
||||
s.SetIOInjector(nil)
|
||||
} else {
|
||||
s.SetIOInjector(&recordingInjector{})
|
||||
}
|
||||
}
|
||||
}()
|
||||
|
||||
// 先等替换跑完，再告知注入方退出。
|
||||
// 顺序写反了就是死锁：注入方只依 close(stop) 退出。
|
||||
swapper.Wait()
|
||||
close(stop)
|
||||
injectors.Wait()
|
||||
// 断言就是「没崩、-race 没报」。nil injector 时必须静默跳过而非 panic。
|
||||
}
|
||||
|
||||
// ---------- 3. autoRestart 标志的并发读写 ----------
|
||||
|
||||
// SetAutoRestart 的文档用途是"插件有无法恢复的状态（如外部连接）时设为 false"——
|
||||
// 而连接建立本身通常是异步的，所以这个写入天然发生在后台 goroutine。
|
||||
// 内核侧 registry 在另一个 goroutine 读 AutoRestart() 决定崩溃后是否重启。
|
||||
// 这是一对跨 goroutine 的读写，必须同步。
|
||||
func TestStress_AutoRestartFlagConcurrent(t *testing.T) {
|
||||
s := &PluginSDK{name: "stress", autoRestart: true}
|
||||
|
||||
var wg sync.WaitGroup
|
||||
for w := 0; w < 16; w++ {
|
||||
wg.Add(1)
|
||||
go func(w int) {
|
||||
defer wg.Done()
|
||||
for i := 0; i < 500; i++ {
|
||||
s.SetAutoRestart(i%2 == 0)
|
||||
}
|
||||
}(w)
|
||||
}
|
||||
// 读方模拟内核 registry
|
||||
for r := 0; r < 8; r++ {
|
||||
wg.Add(1)
|
||||
go func() {
|
||||
defer wg.Done()
|
||||
for i := 0; i < 500; i++ {
|
||||
_ = s.AutoRestart()
|
||||
}
|
||||
}()
|
||||
}
|
||||
wg.Wait()
|
||||
}
|
||||
|
||||
// ---------- 4. stop / onRemove handler 的"恰好一次" ----------
|
||||
|
||||
// RunStopHandlers 的契约是"执行后清空，幂等"。内核在停止插件时可能并发触发
|
||||
// （超时强杀与正常 Stop 竞争），handler 里往往是关连接、落盘——
|
||||
// 执行两次的后果从"重复写文件"到"close 已关闭的 channel 直接 panic"。
|
||||
func TestStress_StopHandlersExactlyOnce(t *testing.T) {
|
||||
const n = 300
|
||||
s := &PluginSDK{name: "stress"}
|
||||
|
||||
var counters [n]atomic.Int64
|
||||
for i := 0; i < n; i++ {
|
||||
i := i
|
||||
s.RegisterStopHandler(func() { counters[i].Add(1) })
|
||||
}
|
||||
|
||||
var wg sync.WaitGroup
|
||||
for w := 0; w < 16; w++ {
|
||||
wg.Add(1)
|
||||
go func() {
|
||||
defer wg.Done()
|
||||
s.RunStopHandlers()
|
||||
}()
|
||||
}
|
||||
wg.Wait()
|
||||
|
||||
for i := 0; i < n; i++ {
|
||||
if got := counters[i].Load(); got != 1 {
|
||||
t.Fatalf("handler %d 执行 %d 次，期望恰好 1 次", i, got)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 注册与执行并发：已注册的 handler 一次都不能多跑，未跑到的也不能被丢。
|
||||
// 断言用"每个 handler 的执行次数 <= 1"而非"总数相等"——
|
||||
// 与 RunStopHandlers 竞争的注册可能落在快照之后，那属于合法的未执行。
|
||||
func TestStress_StopHandlersRegisterWhileRunning(t *testing.T) {
|
||||
s := &PluginSDK{name: "stress"}
|
||||
const n = 500
|
||||
var counters [n]atomic.Int64
|
||||
|
||||
var wg sync.WaitGroup
|
||||
wg.Add(1)
|
||||
go func() {
|
||||
defer wg.Done()
|
||||
for i := 0; i < n; i++ {
|
||||
i := i
|
||||
s.RegisterStopHandler(func() { counters[i].Add(1) })
|
||||
}
|
||||
}()
|
||||
wg.Add(1)
|
||||
go func() {
|
||||
defer wg.Done()
|
||||
for i := 0; i < 50; i++ {
|
||||
s.RunStopHandlers()
|
||||
}
|
||||
}()
|
||||
wg.Wait()
|
||||
s.RunStopHandlers() // 收尾：把剩下的都跑掉
|
||||
|
||||
for i := 0; i < n; i++ {
|
||||
if got := counters[i].Load(); got > 1 {
|
||||
t.Fatalf("handler %d 被执行 %d 次（重复执行）", i, got)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestStress_OnRemoveHandlersExactlyOnce(t *testing.T) {
|
||||
const n = 200
|
||||
s := &PluginSDK{name: "stress"}
|
||||
|
||||
var counters [n]atomic.Int64
|
||||
for i := 0; i < n; i++ {
|
||||
i := i
|
||||
s.RegisterOnRemoveHandler(func() { counters[i].Add(1) })
|
||||
}
|
||||
|
||||
var wg sync.WaitGroup
|
||||
for w := 0; w < 12; w++ {
|
||||
wg.Add(1)
|
||||
go func() {
|
||||
defer wg.Done()
|
||||
s.RunOnRemoveHandlers()
|
||||
}()
|
||||
}
|
||||
wg.Wait()
|
||||
|
||||
for i := 0; i < n; i++ {
|
||||
if got := counters[i].Load(); got != 1 {
|
||||
t.Fatalf("onRemove handler %d 执行 %d 次，期望恰好 1 次", i, got)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// ---------- 5. StageContext 并发读改写 ----------
|
||||
|
||||
// StageContext 是全部 stage handler 共享的可变状态，字段全导出、靠调用方自觉
|
||||
// 持 Lock/RLock。媒体链路让 Extra 成为新热点（media_blocks 挂在这里），
|
||||
// 而 map 的并发写在 Go 里是直接 fatal，recover 都接不住。
|
||||
//
|
||||
// 这条测试锁定的不变量：按约定持锁的并发读改写不丢更新、不 fatal。
|
||||
func TestStress_StageContextConcurrentExtraAndFinalText(t *testing.T) {
|
||||
ctx := &StageContext{Extra: map[string]interface{}{}}
|
||||
|
||||
const workers, rounds = 16, 200
|
||||
var wg sync.WaitGroup
|
||||
for w := 0; w < workers; w++ {
|
||||
wg.Add(1)
|
||||
go func(w int) {
|
||||
defer wg.Done()
|
||||
for i := 0; i < rounds; i++ {
|
||||
// 写：模拟插件往 Extra 塞媒体块并追加文本（读-改-写）
|
||||
ctx.Lock()
|
||||
ctx.Extra[fmt.Sprintf("k%d-%d", w, i)] = []ContentBlock{imageBlock("x")}
|
||||
ctx.FinalText += "."
|
||||
ctx.Unlock()
|
||||
|
||||
// 读：模拟另一个 handler 检查是否已被响应
|
||||
_ = ctx.IsResponded()
|
||||
ctx.RLock()
|
||||
_ = len(ctx.Extra)
|
||||
ctx.RUnlock()
|
||||
}
|
||||
}(w)
|
||||
}
|
||||
wg.Wait()
|
||||
|
||||
ctx.RLock()
|
||||
defer ctx.RUnlock()
|
||||
if len(ctx.Extra) != workers*rounds {
|
||||
t.Fatalf("Extra 键数 = %d，期望 %d（出现 lost update）", len(ctx.Extra), workers*rounds)
|
||||
}
|
||||
if len(ctx.FinalText) != workers*rounds {
|
||||
t.Fatalf("FinalText 长度 = %d，期望 %d（出现 lost update）", len(ctx.FinalText), workers*rounds)
|
||||
}
|
||||
}
|
||||
|
||||
// ---------- 6. OwnTools scope 包装器的并发正确性 ----------
|
||||
|
||||
// StageScopeOwnTools 的包装闭环里要读 ctx.ToolCalls 判断归属。
|
||||
// 并发下若判断与执行之间状态被改写，就会出现"别人的工具触发了我的 handler"——
|
||||
// 后果是插件对不属于自己的工具结果动手，且没有任何错误。
|
||||
func TestStress_OwnToolsScopeNoCrossPluginLeak(t *testing.T) {
|
||||
var registered StageHandler
|
||||
s := &PluginSDK{
|
||||
name: "mine",
|
||||
regStage: func(stage Stage, h StageHandler) { registered = h },
|
||||
}
|
||||
|
||||
var fired atomic.Int64
|
||||
s.RegisterStage(StageBeforeToolcall, func(ctx *StageContext) error {
|
||||
fired.Add(1)
|
||||
ctx.RLock()
|
||||
defer ctx.RUnlock()
|
||||
// 触发了就必须确实是自己的工具
|
||||
if len(ctx.ToolCalls) == 0 || ctx.ToolCalls[0].Plugin != "mine" {
|
||||
t.Errorf("handler 被别的插件的工具触发: %+v", ctx.ToolCalls)
|
||||
}
|
||||
return nil
|
||||
}, StageScopeOwnTools)
|
||||
|
||||
if registered == nil {
|
||||
t.Fatal("handler 未注册")
|
||||
}
|
||||
|
||||
const workers, rounds = 16, 100
|
||||
var wg sync.WaitGroup
|
||||
var mineCount atomic.Int64
|
||||
for w := 0; w < workers; w++ {
|
||||
wg.Add(1)
|
||||
go func(w int) {
|
||||
defer wg.Done()
|
||||
for i := 0; i < rounds; i++ {
|
||||
// 每个 goroutine 用自己的 ctx——真实内核里 stage 扇出共享同一个
|
||||
// ctx，但那部分的并发由内核 host 仲裁；这里验证包装器本身。
|
||||
owner := "other"
|
||||
if (w+i)%2 == 0 {
|
||||
owner = "mine"
|
||||
mineCount.Add(1)
|
||||
}
|
||||
ctx := &StageContext{Extra: map[string]interface{}{}}
|
||||
ctx.ToolCalls = []ToolCall{{Plugin: owner, Name: "t"}}
|
||||
if err := registered(ctx); err != nil {
|
||||
t.Errorf("handler 返回错误: %v", err)
|
||||
}
|
||||
}
|
||||
}(w)
|
||||
}
|
||||
wg.Wait()
|
||||
|
||||
if got, want := fired.Load(), mineCount.Load(); got != want {
|
||||
t.Fatalf("handler 触发 %d 次，期望 %d 次（漏触发或跨插件触发）", got, want)
|
||||
}
|
||||
}
|
||||
|
||||
// ---------- 7. 媒体类型的 JSON 往返（跨进程边界的真实形态） ----------
|
||||
|
||||
// 媒体块与附件要经 JSON 过子进程边界。[]byte 在 JSON 里是 base64，
|
||||
// 往返不一致的后果是图片字节静默损坏——落进 CAS 后 digest 校验才会发现，
|
||||
// 而那时已经无从追查是谁改坏的。
|
||||
func TestStress_MediaTypesJSONRoundTripAtScale(t *testing.T) {
|
||||
// 覆盖真实会遇到的边界：空、单字节、含 0x00、全 0xFF、超过 base64 分组边界的长度
|
||||
sizes := []int{0, 1, 2, 3, 255, 256, 1023, 4096, 65537}
|
||||
for _, n := range sizes {
|
||||
data := make([]byte, n)
|
||||
for i := range data {
|
||||
data[i] = byte(i * 7 % 256)
|
||||
}
|
||||
att := MediaAttachment{
|
||||
Digest: strings.Repeat("a", 64),
|
||||
MIME: "image/png",
|
||||
Data: data,
|
||||
Name: "图片-名字 with space & 符号.png",
|
||||
}
|
||||
b, err := json.Marshal(att)
|
||||
if err != nil {
|
||||
t.Fatalf("size=%d marshal: %v", n, err)
|
||||
}
|
||||
var back MediaAttachment
|
||||
if err := json.Unmarshal(b, &back); err != nil {
|
||||
t.Fatalf("size=%d unmarshal: %v", n, err)
|
||||
}
|
||||
if len(back.Data) != n {
|
||||
t.Fatalf("size=%d 往返后长度 = %d", n, len(back.Data))
|
||||
}
|
||||
for i := range data {
|
||||
if back.Data[i] != data[i] {
|
||||
t.Fatalf("size=%d 第 %d 字节损坏: %02x != %02x", n, i, back.Data[i], data[i])
|
||||
}
|
||||
}
|
||||
if back.Name != att.Name || back.MIME != att.MIME || back.Digest != att.Digest {
|
||||
t.Fatalf("size=%d 元数据往返不一致: %+v", n, back)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// omitempty 必须真的生效：读路径上内核不回 Data，若序列化仍产出 "data":null
|
||||
// 之类的键，跨进程消息会凭空变大，且插件侧无法区分"没有字节"与"空字节"。
|
||||
func TestStress_MediaTypesOmitEmpty(t *testing.T) {
|
||||
cases := []struct {
|
||||
name string
|
||||
v interface{}
|
||||
absent []string
|
||||
present []string
|
||||
}{
|
||||
{
|
||||
name: "Triple 无媒体",
|
||||
v: Triple{Subject: "甲方", Relation: "签署", Object: "合同"},
|
||||
absent: []string{"media_digests", "sentence_text", "confidence", "subject_type", "object_type"},
|
||||
present: []string{"subject", "relation", "object"},
|
||||
},
|
||||
{
|
||||
name: "Triple 带媒体",
|
||||
v: Triple{Subject: "甲方", Relation: "包含", Object: "图", MediaDigests: []string{"abc12345"}, SentenceText: "句子"},
|
||||
absent: []string{"confidence"},
|
||||
present: []string{"media_digests", "sentence_text"},
|
||||
},
|
||||
{
|
||||
name: "Doc 读路径无字节",
|
||||
v: Doc{ID: "d1", Title: "标题", Content: "正文", Attachments: []MediaAttachment{{Digest: "abc12345", MIME: "image/png"}}},
|
||||
absent: []string{"\"data\"", "media_digests", "score"},
|
||||
present: []string{"attachments", "digest", "mime"},
|
||||
},
|
||||
{
|
||||
name: "TextEvent 无附件",
|
||||
v: TextEvent{Role: "user", Content: "hi"},
|
||||
absent: []string{"attachments", "channel"},
|
||||
present: []string{"role", "content"},
|
||||
},
|
||||
{
|
||||
name: "ContentBlock 纯文本",
|
||||
v: ContentBlock{Type: "text", Text: "hi"},
|
||||
absent: []string{"image_url", "audio_url"},
|
||||
present: []string{"type", "text"},
|
||||
},
|
||||
{
|
||||
name: "ContentBlock 图片",
|
||||
v: imageBlock("AAA"),
|
||||
absent: []string{"audio_url", "\"text\""},
|
||||
present: []string{"image_url", "detail"},
|
||||
},
|
||||
}
|
||||
for _, c := range cases {
|
||||
b, err := json.Marshal(c.v)
|
||||
if err != nil {
|
||||
t.Fatalf("%s marshal: %v", c.name, err)
|
||||
}
|
||||
s := string(b)
|
||||
for _, k := range c.absent {
|
||||
if strings.Contains(s, k) {
|
||||
t.Errorf("%s: 不该出现的键 %s —— %s", c.name, k, s)
|
||||
}
|
||||
}
|
||||
for _, k := range c.present {
|
||||
if !strings.Contains(s, k) {
|
||||
t.Errorf("%s: 缺少键 %s —— %s", c.name, k, s)
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 媒体块在并发序列化下必须各自独立：ImageURL/AudioURL 是指针，
|
||||
// 若某处复用同一个指针再改写，序列化结果会互相污染。
|
||||
func TestStress_ContentBlockConcurrentMarshal(t *testing.T) {
|
||||
const workers, rounds = 16, 300
|
||||
var wg sync.WaitGroup
|
||||
for w := 0; w < workers; w++ {
|
||||
wg.Add(1)
|
||||
go func(w int) {
|
||||
defer wg.Done()
|
||||
for i := 0; i < rounds; i++ {
|
||||
tag := fmt.Sprintf("w%d-i%d", w, i)
|
||||
blocks := []ContentBlock{
|
||||
{Type: "text", Text: tag},
|
||||
imageBlock(tag),
|
||||
{Type: "audio_url", AudioURL: &AudioURL{URL: "data:audio/wav;base64," + tag}},
|
||||
}
|
||||
b, err := json.Marshal(blocks)
|
||||
if err != nil {
|
||||
t.Errorf("marshal: %v", err)
|
||||
return
|
||||
}
|
||||
var back []ContentBlock
|
||||
if err := json.Unmarshal(b, &back); err != nil {
|
||||
t.Errorf("unmarshal: %v", err)
|
||||
return
|
||||
}
|
||||
if len(back) != 3 {
|
||||
t.Errorf("块数 = %d", len(back))
|
||||
return
|
||||
}
|
||||
if back[0].ImageURL != nil || back[0].AudioURL != nil {
|
||||
t.Errorf("文本块被填了媒体指针: %+v", back[0])
|
||||
}
|
||||
if back[1].ImageURL == nil || !strings.HasSuffix(back[1].ImageURL.URL, tag) {
|
||||
t.Errorf("图片块 URL 错位: %+v", back[1].ImageURL)
|
||||
}
|
||||
if back[1].AudioURL != nil {
|
||||
t.Errorf("图片块被填了音频指针")
|
||||
}
|
||||
if back[2].AudioURL == nil || !strings.HasSuffix(back[2].AudioURL.URL, tag) {
|
||||
t.Errorf("音频块 URL 错位: %+v", back[2].AudioURL)
|
||||
}
|
||||
}
|
||||
}(w)
|
||||
}
|
||||
wg.Wait()
|
||||
}
|
||||
|
||||
// ---------- 8. 注册面的并发 ----------
|
||||
|
||||
// 插件在 Start() 里起多个 goroutine 分别注册工具是常见写法。
|
||||
// def.Plugin 的默认填充若不是每次调用独立的，就会出现工具归属错乱——
|
||||
// 表现是 OwnTools scope 失效、WebUI 里工具挂在别的插件名下。
|
||||
func TestStress_RegisterToolConcurrentPluginDefaulting(t *testing.T) {
|
||||
var mu sync.Mutex
|
||||
got := map[string]string{} // toolName -> def.Plugin
|
||||
|
||||
s := &PluginSDK{
|
||||
name: "mine",
|
||||
regTool: func(name string, def ToolDef, h ToolHandler) error {
|
||||
mu.Lock()
|
||||
got[name] = def.Plugin
|
||||
mu.Unlock()
|
||||
return nil
|
||||
},
|
||||
}
|
||||
|
||||
const workers, perWorker = 16, 100
|
||||
var wg sync.WaitGroup
|
||||
for w := 0; w < workers; w++ {
|
||||
wg.Add(1)
|
||||
go func(w int) {
|
||||
defer wg.Done()
|
||||
for i := 0; i < perWorker; i++ {
|
||||
name := fmt.Sprintf("tool_w%d_i%d", w, i)
|
||||
def := ToolDef{Description: "d", Parameters: map[string]interface{}{}}
|
||||
// 一半显式指定归属，一半靠 SDK 填默认值
|
||||
if i%2 == 0 {
|
||||
def.Plugin = "explicit"
|
||||
}
|
||||
if err := s.RegisterTool(name, def, func(map[string]interface{}) (interface{}, error) {
|
||||
return nil, nil
|
||||
}); err != nil {
|
||||
t.Errorf("RegisterTool: %v", err)
|
||||
}
|
||||
}
|
||||
}(w)
|
||||
}
|
||||
wg.Wait()
|
||||
|
||||
if len(got) != workers*perWorker {
|
||||
t.Fatalf("注册工具数 = %d，期望 %d", len(got), workers*perWorker)
|
||||
}
|
||||
for name, owner := range got {
|
||||
want := "mine"
|
||||
if isEvenSuffix(name) {
|
||||
want = "explicit"
|
||||
}
|
||||
if owner != want {
|
||||
t.Fatalf("工具 %s 归属 = %q，期望 %q", name, owner, want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// isEvenSuffix 判断 tool_wX_iY 里的 Y 是否为偶数。
|
||||
func isEvenSuffix(name string) bool {
|
||||
idx := strings.LastIndex(name, "_i")
|
||||
if idx < 0 {
|
||||
return false
|
||||
}
|
||||
n := 0
|
||||
if _, err := fmt.Sscanf(name[idx+2:], "%d", &n); err != nil {
|
||||
return false
|
||||
}
|
||||
return n%2 == 0
|
||||
}
|
||||
|
||||
// nil 依赖下所有便捷方法必须静默降级而非 panic。
|
||||
//
|
||||
// 这是"媒体存储可关闭"在 SDK 层的对应物：内核未注入某个 API 时
|
||||
// （精简部署、插件权限不足、子进程握手尚未完成），插件的调用不该崩。
|
||||
func TestStress_NilDependenciesDegradeSilently(t *testing.T) {
|
||||
s := &PluginSDK{name: "bare"}
|
||||
|
||||
const workers = 16
|
||||
var wg sync.WaitGroup
|
||||
for w := 0; w < workers; w++ {
|
||||
wg.Add(1)
|
||||
go func() {
|
||||
defer wg.Done()
|
||||
for i := 0; i < 200; i++ {
|
||||
s.InjectText("s", "c", "t")
|
||||
s.InjectTextNoMemory("s", "c", "t")
|
||||
s.InjectInterruptText("s", "c", "t")
|
||||
if got := s.InjectInputSync("s", "c", "t"); got != "" {
|
||||
t.Errorf("无 injector 时同步注入应返回空串，got %q", got)
|
||||
}
|
||||
s.InjectInputMedia("s", "c", "t", []ContentBlock{imageBlock("x")})
|
||||
if got := s.InjectInputMediaSync("s", "c", "t", nil); got != "" {
|
||||
t.Errorf("无 injector 时媒体同步注入应返回空串，got %q", got)
|
||||
}
|
||||
s.InjectInterruptMedia("s", "c", "t", nil)
|
||||
|
||||
// getter 全部应返回 nil 而非 panic
|
||||
_ = s.Memory()
|
||||
_ = s.TextMemory()
|
||||
_ = s.DocMemory()
|
||||
_ = s.Knowledge()
|
||||
_ = s.LLM()
|
||||
_ = s.Social()
|
||||
_ = s.Events()
|
||||
_ = s.PluginMgr()
|
||||
_ = s.Settings()
|
||||
|
||||
// 注册面无 registrar 时应返回 nil error
|
||||
if err := s.RegisterTool("t", ToolDef{}, nil); err != nil {
|
||||
t.Errorf("无 registrar 时 RegisterTool 应返回 nil，got %v", err)
|
||||
}
|
||||
if err := s.RegisterPluginAPI("a"); err != nil {
|
||||
t.Errorf("无 registrar 时 RegisterPluginAPI 应返回 nil，got %v", err)
|
||||
}
|
||||
s.RegisterStage(StageOnInput, func(*StageContext) error { return nil })
|
||||
}
|
||||
}()
|
||||
}
|
||||
wg.Wait()
|
||||
}
|
||||
@ -20,6 +20,15 @@ type BuildConfig struct {
|
||||
Replaces []string
|
||||
}
|
||||
|
||||
// buildFailed 记录本次构建是否有平台失败。
|
||||
//
|
||||
// 为什么要它：这两个构建函数遇到错误只是 Printf 后 return，而 cmdBuild 返回
|
||||
// void，于是**构建失败却以 0 退出**。调用方（批量重编脚本、CI、发版脚本）
|
||||
// 只能靠翻日志发现失败——实测中一个示例的 windows 目标编译失败，脚本却报
|
||||
// 「17/17 全绿」，并因此少产出 16 个 .hmap。
|
||||
// 判成功要看退出码，不能靠人读日志。
|
||||
var buildFailed bool
|
||||
|
||||
func cmdBuild(args []string) {
|
||||
// Read all config from plg.json first
|
||||
plg, err := readPlgJSON("plg.json")
|
||||
@ -92,11 +101,18 @@ func cmdBuild(args []string) {
|
||||
|
||||
if bundle || len(targets) == 0 {
|
||||
buildBundle(plg, outDir, sdkPath)
|
||||
return
|
||||
} else {
|
||||
for _, t := range targets {
|
||||
buildTarget(plg, t, outDir, sdkPath)
|
||||
}
|
||||
}
|
||||
|
||||
for _, t := range targets {
|
||||
buildTarget(plg, t, outDir, sdkPath)
|
||||
// 以非零码退出：调用方（批量重编、CI、发版脚本）靠退出码判成败。
|
||||
// 以前这里直接 return，失败也退 0，于是「构建失败」只能靠人翻日志发现——
|
||||
// 实测中就因此把一次部分失败当成了全绿。
|
||||
if buildFailed {
|
||||
fmt.Println("error: 至少一个目标构建失败（详见上面日志）")
|
||||
os.Exit(1)
|
||||
}
|
||||
}
|
||||
|
||||
@ -105,13 +121,33 @@ func cmdBuild(args []string) {
|
||||
// 子进程模式下各平台产物同名（plugin.bin）——进程边界即 ABI 边界，
|
||||
// 不存在平台特有扩展名，故 zip 内按平台加后缀区分；
|
||||
// 内核安装时按当前平台挑对应条目重命名为 plugin.bin。
|
||||
//
|
||||
// **不含 windows**：插件只能运行在 homed 能跑的平台上，而 homed 已明确放弃
|
||||
// Windows 原生支持（插件体系依赖 fd 继承 + 统一共享内存区的段内偏移，
|
||||
// Windows 句柄模型无法表达）。Windows 用户走 WSL2，而 WSL2 就是 linux/amd64。
|
||||
var allBundleTargets = []struct {
|
||||
target string
|
||||
entry string // 二进制在 zip 中的文件名
|
||||
}{
|
||||
{"linux/amd64", "plugin.bin.linux.amd64"},
|
||||
{"darwin/amd64", "plugin.bin.darwin.amd64"},
|
||||
{"windows/amd64", "plugin.bin.windows.amd64"},
|
||||
}
|
||||
|
||||
// checkTargetSupported 在构建前拦下**已知不支持**的目标，给出可执行的报错。
|
||||
//
|
||||
// 为什么要有它：插件运行在 homed 的进程里，所以目标平台必须是 homed 能跑的。
|
||||
// homed 已放弃 Windows 原生（原因：插件依赖 fd 继承与统一共享内存区段内偏移，
|
||||
// Windows 句柄模型无法表达），却还去构建 windows 插件，结果是死在一句
|
||||
// 「undefined: attachUnifiedShm」——看起来像代码 bug，实际是平台策略。
|
||||
// 这里换成明确的结论，并且**不静默跳过**：静默跳过会让人以为产出的包里包含 windows。
|
||||
func checkTargetSupported(target string) error {
|
||||
if strings.HasPrefix(target, "windows/") {
|
||||
return fmt.Errorf("不支持 windows 插件目标：插件运行在 homed 内，" +
|
||||
"而 homed 已放弃 Windows 原生支持（插件体系依赖 fd 继承与统一共享内存区" +
|
||||
"段内偏移解引用，Windows 句柄模型无法表达）。Windows 请用 WSL2——" +
|
||||
"它就是 linux/amd64，用 --target linux/amd64 即可")
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
func buildBundle(plg *PlgConfig, outDir string, sdkPath string) {
|
||||
@ -122,6 +158,7 @@ func buildBundle(plg *PlgConfig, outDir string, sdkPath string) {
|
||||
runtimeCleanup, err := generateProcRuntime()
|
||||
if err != nil {
|
||||
fmt.Printf(" error: %v\n", err)
|
||||
buildFailed = true
|
||||
return
|
||||
}
|
||||
defer runtimeCleanup()
|
||||
@ -132,9 +169,15 @@ func buildBundle(plg *PlgConfig, outDir string, sdkPath string) {
|
||||
var binaries []binEntry
|
||||
|
||||
for _, bt := range allBundleTargets {
|
||||
if err := checkTargetSupported(bt.target); err != nil {
|
||||
fmt.Printf(" error: %v\n", err)
|
||||
buildFailed = true
|
||||
return
|
||||
}
|
||||
cfg, errMsg := resolveBuild(bt.target)
|
||||
if cfg == nil {
|
||||
fmt.Printf(" error: %s\n", errMsg)
|
||||
buildFailed = true
|
||||
return
|
||||
}
|
||||
|
||||
@ -151,7 +194,10 @@ func buildBundle(plg *PlgConfig, outDir string, sdkPath string) {
|
||||
|
||||
fmt.Printf(" compiling %s/%s (子进程模式，CGO_ENABLED=0)...\n", cfg.goos, cfg.goarch)
|
||||
if err := cmd.Run(); err != nil {
|
||||
// 单平台失败即整包失败：bundle 少一个平台就是个坏包，
|
||||
// 却仍会生成 .hmap 让人以为打包成功。
|
||||
fmt.Printf(" error: build %s/%s: %v\n", cfg.goos, cfg.goarch, err)
|
||||
buildFailed = true
|
||||
return
|
||||
}
|
||||
binaries = append(binaries, binEntry{src: outPath, zip: bt.entry})
|
||||
@ -395,8 +441,8 @@ func ensureSDKResolvable(plg *PlgConfig, sdkModule, sdkPath string) {
|
||||
fmt.Printf(" %s\n", strings.TrimSpace(string(out)))
|
||||
}
|
||||
fmt.Printf(" 提示：%s 不在公共 proxy 上。用以下任一方式指向本机 SDK：\n", sdkModule)
|
||||
fmt.Printf(" plugindev sdk install latest # 装一份到 ~/.homeagent/plugindev/sdk\n")
|
||||
fmt.Printf(" plugindev build --sdk-path <路径> # 或直接指定源码目录\n")
|
||||
fmt.Printf(" hmapdev sdk install latest # 装一份到 ~/.homeagent/hmapdev/sdk\n")
|
||||
fmt.Printf(" hmapdev build --sdk-path <路径> # 或直接指定源码目录\n")
|
||||
}
|
||||
}
|
||||
|
||||
@ -411,17 +457,12 @@ func findLocalSDK(sdkPath string) string {
|
||||
candidates = append(candidates, abs)
|
||||
}
|
||||
}
|
||||
// plugindev 自身所在位置往上三级（tools/plugindev/plugindev → SDK 根）
|
||||
// hmapdev 自身所在位置往上三级（tools/hmapdev/hmapdev → SDK 根）
|
||||
if self, err := os.Executable(); err == nil {
|
||||
candidates = append(candidates, filepath.Dir(filepath.Dir(filepath.Dir(self))))
|
||||
}
|
||||
// plugindev sdk use 选定的版本
|
||||
store := os.Getenv("HOMEAGENT_SDK_DIR")
|
||||
if store == "" {
|
||||
if home, err := os.UserHomeDir(); err == nil {
|
||||
store = filepath.Join(home, ".homeagent", "plugindev", "sdk")
|
||||
}
|
||||
}
|
||||
// hmapdev sdk use 选定的版本（复用 sdkStore()，含改名前的旧目录回退）
|
||||
store := sdkStore()
|
||||
if store != "" {
|
||||
if d, err := os.ReadFile(filepath.Join(store, "current")); err == nil {
|
||||
if ver := strings.TrimSpace(string(d)); ver != "" {
|
||||
@ -465,7 +506,7 @@ func resolveSDKPath(sdkPath string) string {
|
||||
fmt.Printf("error: --sdk-path %q not a valid SDK\n", sdkPath)
|
||||
os.Exit(1)
|
||||
}
|
||||
// Detect from plugindev's own location (internal dev)
|
||||
// Detect from hmapdev's own location (internal dev)
|
||||
self, err := os.Executable()
|
||||
if err == nil {
|
||||
cand := filepath.Dir(filepath.Dir(filepath.Dir(self)))
|
||||
@ -473,14 +514,8 @@ func resolveSDKPath(sdkPath string) string {
|
||||
return cand
|
||||
}
|
||||
}
|
||||
// Active SDK via plugindev sdk use
|
||||
store := os.Getenv("HOMEAGENT_SDK_DIR")
|
||||
if store == "" {
|
||||
home, _ := os.UserHomeDir()
|
||||
if home != "" {
|
||||
store = filepath.Join(home, ".homeagent", "plugindev", "sdk")
|
||||
}
|
||||
}
|
||||
// Active SDK via hmapdev sdk use
|
||||
store := sdkStore()
|
||||
if store != "" {
|
||||
if d, err := os.ReadFile(filepath.Join(store, "current")); err == nil {
|
||||
ver := strings.TrimSpace(string(d))
|
||||
@ -492,7 +527,7 @@ func resolveSDKPath(sdkPath string) string {
|
||||
}
|
||||
}
|
||||
}
|
||||
fmt.Printf("error: cannot locate SDK. Use --sdk-path or 'plugindev sdk use'\n")
|
||||
fmt.Printf("error: cannot locate SDK. Use --sdk-path or 'hmapdev sdk use'\n")
|
||||
os.Exit(1)
|
||||
return ""
|
||||
}
|
||||
@ -544,6 +579,13 @@ func buildTarget(plg *PlgConfig, target, outDir, sdkPath string) {
|
||||
}
|
||||
defer runtimeCleanup()
|
||||
|
||||
// 已知未实现的目标在编译前拦下，给可执行的报错（见 checkTargetSupported）。
|
||||
if err := checkTargetSupported(target); err != nil {
|
||||
fmt.Printf(" error: %v\n", err)
|
||||
buildFailed = true
|
||||
return
|
||||
}
|
||||
|
||||
// Auto-link thirdpart/ contents + source_dirs + replace targets
|
||||
thirdpartCleanup := linkThirdpart(plg, target)
|
||||
defer thirdpartCleanup()
|
||||
@ -562,6 +604,7 @@ func buildTarget(plg *PlgConfig, target, outDir, sdkPath string) {
|
||||
fmt.Printf(" compiling %s/%s (子进程模式，CGO_ENABLED=0)...\n", cfg.goos, cfg.goarch)
|
||||
if err := cmd.Run(); err != nil {
|
||||
fmt.Printf(" error: build %s/%s: %v\n", cfg.goos, cfg.goarch, err)
|
||||
buildFailed = true
|
||||
return
|
||||
}
|
||||
|
||||
@ -7,12 +7,12 @@ import (
|
||||
"path/filepath"
|
||||
"strings"
|
||||
|
||||
"github.com/JianFeeeee/homeagent-sdk/tools/plugindev/yaegi"
|
||||
"gitcode.com/JianFeeeee/homeagent-sdk/tools/hmapdev/yaegi"
|
||||
)
|
||||
|
||||
// tmplLuaDebug is the temporary Lua debug script template
|
||||
const tmplLuaDebug = `-- HomeAgent Lua Plugin Debug
|
||||
-- Generated by plugindev debug --lua
|
||||
-- Generated by hmapdev debug --lua
|
||||
sdk = require("sdk")
|
||||
local ok, plugin = pcall(dofile, "main.lua")
|
||||
if not ok then
|
||||
@ -115,7 +115,7 @@ func debugLua(dir, sdkPath, luaPath string) {
|
||||
luaBin, err := exec.LookPath("lua")
|
||||
if err != nil {
|
||||
fmt.Println("error: lua interpreter not found in PATH")
|
||||
fmt.Println(" install Lua 5.1+ or use plugindev build to compile your plugin")
|
||||
fmt.Println(" install Lua 5.1+ or use hmapdev build to compile your plugin")
|
||||
os.Exit(1)
|
||||
}
|
||||
|
||||
@ -63,7 +63,7 @@ type TemplateData struct {
|
||||
// SDKLocalPath 是本机 SDK 源码绝对路径，写入生成的 go.mod 作为 replace 目标。
|
||||
//
|
||||
// 为何必须写：gitcode 的模块不在 proxy.golang.org 上，只 require 一个
|
||||
// 版本号的 go.mod 配上缺失的 go.sum，新用户第一次 `plugindev build`
|
||||
// 版本号的 go.mod 配上缺失的 go.sum，新用户第一次 `hmapdev build`
|
||||
// 必定死在 "missing go.sum entry"，而 `go mod tidy` 又会去公共 proxy 拉
|
||||
// 一个不存在的条目。有了本地 replace，go 完全不需要 go.sum 条目。
|
||||
SDKLocalPath string
|
||||
@ -71,7 +71,7 @@ type TemplateData struct {
|
||||
|
||||
func cmdInit(args []string) {
|
||||
if len(args) < 1 {
|
||||
fmt.Println("Usage: plugindev init <name> [--lua] [--type remotedevice]")
|
||||
fmt.Println("Usage: hmapdev init <name> [--lua] [--type remotedevice]")
|
||||
os.Exit(1)
|
||||
}
|
||||
|
||||
@ -192,7 +192,7 @@ func cmdInit(args []string) {
|
||||
if isLua {
|
||||
fmt.Printf(" cd %s && lua main.lua (standalone test)\n", dir)
|
||||
}
|
||||
fmt.Printf(" cd %s && plugindev build\n", dir)
|
||||
fmt.Printf(" cd %s && hmapdev build\n", dir)
|
||||
}
|
||||
|
||||
// detectSDKInfo reads the HomeAgent SDK's go.mod and meta to get module path, go version, and SDK version.
|
||||
@ -14,7 +14,12 @@ import (
|
||||
"time"
|
||||
)
|
||||
|
||||
const sdkDirName = "plugindev/sdk"
|
||||
const sdkDirName = "hmapdev/sdk"
|
||||
|
||||
// legacySDKDirName 是改名前的存储目录。工具链在 1.2.0 从 plugindev 改名 hmapdev；
|
||||
// 已装过旧版的机器上 SDK 仍在旧路径，直接换名会让它找不到已装 SDK
|
||||
// （表现为「没有活动版本」）。新目录不存在而旧目录存在时沿用旧目录。
|
||||
const legacySDKDirName = "plugindev/sdk"
|
||||
|
||||
// sdkStore returns the root directory for stored SDK versions.
|
||||
func sdkStore() string {
|
||||
@ -26,7 +31,15 @@ func sdkStore() string {
|
||||
fmt.Printf("error: cannot determine home directory: %v\n", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
return filepath.Join(home, ".homeagent", sdkDirName)
|
||||
dir := filepath.Join(home, ".homeagent", sdkDirName)
|
||||
if _, err := os.Stat(dir); err != nil {
|
||||
if legacy := filepath.Join(home, ".homeagent", legacySDKDirName); legacy != "" {
|
||||
if _, err := os.Stat(legacy); err == nil {
|
||||
return legacy
|
||||
}
|
||||
}
|
||||
}
|
||||
return dir
|
||||
}
|
||||
|
||||
func sdkCurrentDir() string {
|
||||
@ -50,13 +63,13 @@ func cmdSDK(args []string) {
|
||||
cmdSDKList()
|
||||
case "install":
|
||||
if len(args) < 2 {
|
||||
fmt.Println("Usage: plugindev sdk install <version>")
|
||||
fmt.Println("Usage: hmapdev sdk install <version>")
|
||||
os.Exit(1)
|
||||
}
|
||||
cmdSDKInstall(args[1])
|
||||
case "use":
|
||||
if len(args) < 2 {
|
||||
fmt.Println("Usage: plugindev sdk use <version>")
|
||||
fmt.Println("Usage: hmapdev sdk use <version>")
|
||||
os.Exit(1)
|
||||
}
|
||||
cmdSDKUse(args[1])
|
||||
@ -72,7 +85,7 @@ func cmdSDK(args []string) {
|
||||
}
|
||||
|
||||
func sdkHelp() {
|
||||
fmt.Print(`Usage: plugindev sdk <command>
|
||||
fmt.Print(`Usage: hmapdev sdk <command>
|
||||
|
||||
Manage installed HomeAgent SDK versions.
|
||||
|
||||
@ -85,9 +98,9 @@ Commands:
|
||||
latest Show the latest available version from remote
|
||||
|
||||
Examples:
|
||||
plugindev sdk install v0.7.1
|
||||
plugindev sdk install latest
|
||||
plugindev sdk use v0.7.1
|
||||
hmapdev sdk install v0.7.1
|
||||
hmapdev sdk install latest
|
||||
hmapdev sdk use v0.7.1
|
||||
`)
|
||||
}
|
||||
|
||||
@ -127,7 +140,7 @@ func cmdSDKList() {
|
||||
fmt.Printf(" %s %s\n", mark, v)
|
||||
}
|
||||
if current == "" {
|
||||
fmt.Println("\nNo version active. Use 'plugindev sdk use <version>' to set one.")
|
||||
fmt.Println("\nNo version active. Use 'hmapdev sdk use <version>' to set one.")
|
||||
}
|
||||
}
|
||||
|
||||
@ -292,7 +305,7 @@ func cmdSDKUse(version string) {
|
||||
verDir := sdkVersionDir(version)
|
||||
if _, err := os.Stat(verDir); os.IsNotExist(err) {
|
||||
fmt.Printf("SDK version %s is not installed.\n", version)
|
||||
fmt.Printf("Install it first: plugindev sdk install %s\n", version)
|
||||
fmt.Printf("Install it first: hmapdev sdk install %s\n", version)
|
||||
os.Exit(1)
|
||||
}
|
||||
setCurrentVersion(store, version)
|
||||
@ -305,7 +318,7 @@ func cmdSDKPath() {
|
||||
current := resolveCurrentVersion(store)
|
||||
if current == "" {
|
||||
fmt.Println("No active SDK version set.")
|
||||
fmt.Println("Use 'plugindev sdk use <version>' to set one.")
|
||||
fmt.Println("Use 'hmapdev sdk use <version>' to set one.")
|
||||
os.Exit(1)
|
||||
}
|
||||
fmt.Println(sdkVersionDir(current))
|
||||
@ -440,21 +453,21 @@ func parseSemver(tag string) [3]int {
|
||||
}
|
||||
|
||||
// activeSDKRoot returns the path to the active SDK root.
|
||||
// It replaces the old runtime.Caller(0) approach so plugindev can work
|
||||
// It replaces the old runtime.Caller(0) approach so hmapdev can work
|
||||
// independently of its own build location.
|
||||
func activeSDKRoot() string {
|
||||
store := sdkStore()
|
||||
current := resolveCurrentVersion(store)
|
||||
if current == "" {
|
||||
fmt.Printf("error: no active SDK version set\n")
|
||||
fmt.Printf(" Install one: plugindev sdk install latest\n")
|
||||
fmt.Printf(" Or set one: plugindev sdk use <version>\n")
|
||||
fmt.Printf(" Install one: hmapdev sdk install latest\n")
|
||||
fmt.Printf(" Or set one: hmapdev sdk use <version>\n")
|
||||
os.Exit(1)
|
||||
}
|
||||
root := sdkVersionDir(current)
|
||||
if _, err := os.Stat(root); os.IsNotExist(err) {
|
||||
fmt.Printf("error: active SDK version %s not found at %s\n", current, root)
|
||||
fmt.Printf(" Reinstall: plugindev sdk install %s\n", current)
|
||||
fmt.Printf(" Reinstall: hmapdev sdk install %s\n", current)
|
||||
os.Exit(1)
|
||||
}
|
||||
return root
|
||||
@ -1,4 +1,4 @@
|
||||
module github.com/JianFeeeee/homeagent-sdk/tools/plugindev
|
||||
module gitcode.com/JianFeeeee/homeagent-sdk/tools/hmapdev
|
||||
|
||||
go 1.21.0
|
||||
|
||||
@ -30,14 +30,14 @@ func help() {
|
||||
fmt.Print(`HomeAgent Plugin Dev Tool
|
||||
|
||||
Usage:
|
||||
plugindev init <name> Scaffold a new plugin project
|
||||
plugindev init <name> --lua Create Lua plugin
|
||||
plugindev init <name> --type remotedevice
|
||||
hmapdev init <name> Scaffold a new plugin project
|
||||
hmapdev init <name> --lua Create Lua plugin
|
||||
hmapdev init <name> --type remotedevice
|
||||
Create C remote device adapter
|
||||
plugindev build [flags] Compile and package plugin
|
||||
plugindev clean Clean build/dist artifacts
|
||||
plugindev debug [dir] Interpret and debug plugin source
|
||||
plugindev sdk <command> Manage SDK versions
|
||||
hmapdev build [flags] Compile and package plugin
|
||||
hmapdev clean Clean build/dist artifacts
|
||||
hmapdev debug [dir] Interpret and debug plugin source
|
||||
hmapdev sdk <command> Manage SDK versions
|
||||
|
||||
Flags:
|
||||
--outdir Output directory (default: dist)
|
||||
@ -56,7 +56,7 @@ const procGenFile = "z_proc_gen.go"
|
||||
// generateProcRuntime 把子进程运行时（平台无关主体 + 两个平台挂载实现）
|
||||
// 写入插件目录，返回清理函数。
|
||||
func generateProcRuntime() (func(), error) {
|
||||
// 清理历史 C ABI 产物：旧版 plugindev 生成过这两个文件，残留下来会与
|
||||
// 清理历史 C ABI 产物：旧版 hmapdev（原名 plugindev）生成过这两个文件，残留下来会与
|
||||
// 本模板的 main 冲突。无需人工清理就能从旧版升级。
|
||||
for _, stale := range []string{"z_bridge_gen.go", "z_entry.c"} {
|
||||
os.Remove(stale)
|
||||
@ -92,15 +92,21 @@ func TestProcTemplate_CoversAllCoreMethods(t *testing.T) {
|
||||
required := []string{
|
||||
// 注册面
|
||||
"tool.register", "stage.register", "output.register", "api.register", "input.register",
|
||||
// IO 注入
|
||||
"io.injectText", "io.injectInterrupt", "io.injectTextNoMem", "io.injectInputSync",
|
||||
// IO 注入（io.injectTextNoMem 见下方 deprecated：内核保留为兼容旧二进制，
|
||||
// 当前模板改走 io.injectText + NoMemory 标志位，不再发那个 id）
|
||||
"io.injectText", "io.injectInterrupt", "io.injectInputSync",
|
||||
"io.setToolBlocks",
|
||||
// 多模态注入（1.1.0 新增）。漏接线的后果是插件调 InjectInputMedia 静默无效果：
|
||||
// 模板不发这个 RPC，内核也就永远收不到，而两边都不报错。
|
||||
"io.injectMedia", "io.injectMediaSync", "io.injectInterruptMedia",
|
||||
// 生命周期
|
||||
"lifecycle.autoRestart",
|
||||
// 图记忆
|
||||
"memory.recall", "memory.commit", "memory.introspect", "memory.merge", "memory.purge",
|
||||
// 文档记忆
|
||||
"doc.query", "doc.insert", "doc.remove", "doc.stats",
|
||||
// 文档媒体（1.1.0 新增）
|
||||
"doc.insertWithMedia",
|
||||
// 知识库
|
||||
"knowledge.search", "knowledge.add", "knowledge.list",
|
||||
// 文本记忆
|
||||
@ -126,15 +132,37 @@ func TestProcTemplate_CoversAllCoreMethods(t *testing.T) {
|
||||
t.Errorf("模板缺少 core method %q（内核已提供，插件侧未接线）", m)
|
||||
}
|
||||
}
|
||||
|
||||
// 内核保留、但**当前模板不再发送**的 method id。
|
||||
//
|
||||
// 它们不是「公开接口新增却忘记接线」，而是刻意的向后兼容面：
|
||||
// 内核必须继续接受用旧模板编出的插件二进制发来的 id，而当前模板没有理由再发。
|
||||
//
|
||||
// 可复查的判据：ba49dfd 之前的模板里 InjectTextNoMemory 发的就是
|
||||
// "io.injectTextNoMem"；注入标志位落地后它改走 "io.injectText" + NoMemory。
|
||||
//
|
||||
// 为何要单独列而不是直接从 required 删掉：这条守卫的价值在于「新接口必须接线」，
|
||||
// 而把「内核有、模板就必须发」当不变量，会让它常驻误报——常驻误报的守卫迟早
|
||||
// 被人习惯性忽略，那时真漏接线也就没人看见了。
|
||||
deprecated := map[string]string{
|
||||
"io.injectTextNoMem": "旧模板经此表达「不进记忆」；现由 io.injectText + NoMemory 表达",
|
||||
}
|
||||
// 反向保护：allowlist 条目一旦又出现在模板里，说明它已过期，必须删掉，
|
||||
// 否则这里会悄悄变成「永久豁免」的垃圾抽屉。
|
||||
for m, why := range deprecated {
|
||||
if strings.Contains(src, `"`+m+`"`) {
|
||||
t.Errorf("deprecated 里的 %q 又出现在模板里（%s）——条目已过期，请从 deprecated 移除", m, why)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 模板必须处理内核发来的全部 7 个调用（原 C ABI 的 7 个 //export）。
|
||||
// 模板必须处理内核发来的全部调用（含无法 JSON 序列化的 Cleaner 回调）。
|
||||
func TestProcTemplate_HandlesAllKernelCalls(t *testing.T) {
|
||||
src := loadProcTemplate(t)
|
||||
for _, m := range []string{
|
||||
"handshake",
|
||||
"plugin.init", "plugin.start", "plugin.stop",
|
||||
"tool.invoke", "stage.invoke", "output.invoke",
|
||||
"tool.invoke", "cleaner.invoke", "stage.invoke", "output.invoke",
|
||||
} {
|
||||
if !strings.Contains(src, `case "`+m+`"`) {
|
||||
t.Errorf("模板未处理内核调用 %q", m)
|
||||
@ -142,6 +170,45 @@ func TestProcTemplate_HandlesAllKernelCalls(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// 工具调用的 payload 必须走内核标定的**调用帧**（funccall 模型）。
|
||||
//
|
||||
// 共享内存是内核内部实现（插件作者只看到普通 map），但模板必须在传输层
|
||||
// 正确读写 frame / args_len / result_ref。漏接线的后果很隐蔽：参数被静默
|
||||
// 丢弃、结果只走内联，性能退化而不报错。
|
||||
func TestProcTemplate_ToolInvokeUsesSharedRef(t *testing.T) {
|
||||
src := loadProcTemplate(t)
|
||||
for _, want := range []string{"frame", "args_len", "result_ref"} {
|
||||
if !strings.Contains(src, want) {
|
||||
t.Errorf("模板的 tool.invoke 必须处理 %q（payload 走内核标定的调用帧）", want)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 模板必须通过 arena.alloc / arena.free 向内核申请与归还共享内存。
|
||||
//
|
||||
// 共享内存是内核独占管理的**内部实现**：插件不能自己维护分配游标。
|
||||
// 历史上两版跨进程分配器（bump 游标 / 模板内位图 CAS）都因为把可变
|
||||
// 分配状态放在共享内存里而出竞态，所以这里做回归保护。
|
||||
func TestProcTemplate_UsesKernelArenaRPC(t *testing.T) {
|
||||
src := loadProcTemplate(t)
|
||||
|
||||
for _, m := range []string{`"arena.alloc"`, `"arena.free"`} {
|
||||
if !strings.Contains(src, m) {
|
||||
t.Errorf("模板缺少内核共享内存 RPC %s（插件必须向内核申请/归还）", m)
|
||||
}
|
||||
}
|
||||
|
||||
// 禁止插件侧再出现本地分配器符号。
|
||||
//
|
||||
// 只查代码不查注释：注释里会解释“为什么不再这么做”。
|
||||
code := stripComments(t, src)
|
||||
for _, forbidden := range []string{"arenaUsed", "arenaWrite"} {
|
||||
if strings.Contains(code, forbidden) {
|
||||
t.Errorf("模板不应再出现插件侧分配器 %q（共享内存由内核独占管理）", forbidden)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 共享段布局常量必须与内核 internal/plugin/proc/shm.go 一致。
|
||||
//
|
||||
// 字段索引错位是最危险的漂移：插件会读到相邻字段的数据，
|
||||
@ -276,10 +343,11 @@ func TestProcTemplate_DispatchesRequestsConcurrently(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// 协议与共享段版本不匹配必须拒绝，不得半兼容运行。
|
||||
// 协议与共享内存区域版本/魔数不匹配必须拒绝，不得半兼容运行。
|
||||
func TestProcTemplate_RejectsVersionMismatch(t *testing.T) {
|
||||
src := loadProcTemplate(t)
|
||||
for _, want := range []string{"协议版本不匹配", "共享段版本不匹配", "共享段魔数不匹配"} {
|
||||
// §13.1 起共享段合并为单一「统一区域」，魔数校验文案随之更新。
|
||||
for _, want := range []string{"协议版本不匹配", "共享段版本不匹配", "统一区域魔数不匹配"} {
|
||||
if !strings.Contains(src, want) {
|
||||
t.Errorf("握手应校验并拒绝 %q", want)
|
||||
}
|
||||
@ -511,7 +511,7 @@ const tmplReadme = `# {{.Plg.Name}}
|
||||
## Build
|
||||
|
||||
` + "```bash" + `
|
||||
plugindev build
|
||||
hmapdev build
|
||||
` + "```" + `
|
||||
|
||||
## Install
|
||||
@ -25,9 +25,35 @@ import (
|
||||
|
||||
// ---- 协议常量（须与内核 internal/plugin/proc/protocol.go 一致）----
|
||||
|
||||
const procProtocolVersion = 1
|
||||
// procProtocolVersion 必须与内核的 proc.ProtocolVersion 完全一致。
|
||||
//
|
||||
// v2：内核→插件的 payload 改用调用帧（tool/cleaner/output），媒体块改走
|
||||
// blocks_ref。v1 插件只读内联 args，遇上 v2 内核会拿到空参数；反过来 v2
|
||||
// 插件发 blocks_ref，v1 内核也会静默忽略。两边错配都不报错、只是静默失效，
|
||||
// 所以靠这个常量在握手上显式拦下。
|
||||
const procProtocolVersion = 2
|
||||
|
||||
// ---- 共享段布局（须与内核 internal/plugin/proc/shm.go 一致）----
|
||||
// ---- 统一共享内存区域布局（与内核 internal/plugin/proc/unified.go 一致）----
|
||||
|
||||
const (
|
||||
unifiedMagic = 0x554D5352 // "UMSR" — Unified Memory Shared Region
|
||||
unifiedVersion = 1
|
||||
superBlockSize = 64
|
||||
|
||||
sbOffMagic = 0
|
||||
sbOffVersion = 4
|
||||
sbOffGeneration = 8
|
||||
sbOffCapacity = 16
|
||||
sbOffCtxOff = 20
|
||||
sbOffCtxSize = 24
|
||||
sbOffEvtOff = 28
|
||||
sbOffEvtSize = 32
|
||||
sbOffArenaOff = 36
|
||||
sbOffArenaCap = 40
|
||||
sbOffArenaUsed = 44
|
||||
)
|
||||
|
||||
// ---- StageContext 段内部布局（与内核 internal/plugin/proc/shm.go 一致）----
|
||||
|
||||
const (
|
||||
shmStageFieldCount = 18
|
||||
@ -72,6 +98,197 @@ const (
|
||||
flagResponseSet = 1
|
||||
)
|
||||
|
||||
// SharedRef 跨进程共享内存描述符。
|
||||
//
|
||||
// ⚠️ 这是**内部实现细节**：插件开发者永远看不到它。公开 SDK 只暴露普通
|
||||
// 字符串与 Map；模板运行时在传输层按 payload 大小自动选择内联 JSON 还是
|
||||
// 共享槽。直接使用 SharedRef 属于运行时内部行为，不是插件 API。
|
||||
type SharedRef struct {
|
||||
Offset uint32 `json:"offset"`
|
||||
Length uint32 `json:"length"`
|
||||
Generation uint32 `json:"generation"`
|
||||
Flags uint32 `json:"flags"`
|
||||
}
|
||||
|
||||
func (r SharedRef) IsZero() bool { return r.Offset == 0 && r.Length == 0 }
|
||||
func (r SharedRef) Slice(data []byte) []byte {
|
||||
if r.IsZero() || int(r.Offset)+int(r.Length) > len(data) {
|
||||
return nil
|
||||
}
|
||||
return data[r.Offset : r.Offset+r.Length]
|
||||
}
|
||||
|
||||
// SharedRef.Flags 语义位（须与内核 internal/plugin/proc/arena.go 一致）。
|
||||
const (
|
||||
sharedRefFlagJSON = 1 << 0 // 载荷是 JSON
|
||||
sharedRefFlagExpand = 1 << 1 // 引用指向插件申请的扩容块
|
||||
)
|
||||
|
||||
// region 是内核传入的统一共享区域 mmap（handshake 时设置）。
|
||||
var region []byte
|
||||
|
||||
// arenaAlloc 向内核申请一块共享内存，内核返回偏移与大小（Length 为槽容量）。
|
||||
//
|
||||
// 分配器由内核独占管理（见内核 proc/arena.go）：插件只申请与归还，
|
||||
// 不做任何分配决策，因此不存在跨进程分配器的竞争。
|
||||
func arenaAlloc(size uint32) (SharedRef, error) {
|
||||
raw, err := callCore("arena.alloc", map[string]interface{}{"size": size})
|
||||
if err != nil {
|
||||
return SharedRef{}, err
|
||||
}
|
||||
var r struct {
|
||||
Ref SharedRef `json:"ref"`
|
||||
}
|
||||
if err := json.Unmarshal(raw, &r); err != nil {
|
||||
return SharedRef{}, err
|
||||
}
|
||||
if r.Ref.IsZero() {
|
||||
return SharedRef{}, fmt.Errorf("arena.alloc: 内核返回空引用")
|
||||
}
|
||||
return r.Ref, nil
|
||||
}
|
||||
|
||||
// arenaFree 通知内核回收先前申请的共享内存。
|
||||
func arenaFree(ref SharedRef) {
|
||||
if ref.IsZero() {
|
||||
return
|
||||
}
|
||||
callCoreVoid("arena.free", map[string]interface{}{"ref": ref})
|
||||
}
|
||||
|
||||
// ---- 调用帧（funccall 模型）辅助 ----
|
||||
//
|
||||
// 工具调用/清洗由内核发起：内核标定一块内存帧交给插件，插件在帧内工作，
|
||||
// 只有结果超出内核预留的预算时才向内核申请扩容块。
|
||||
|
||||
// frameInput 返回帧内的输入段（内核写入的参数/输入文本）。
|
||||
func frameInput(frame SharedRef, inputLen uint32) []byte {
|
||||
if frame.IsZero() || int(inputLen) > len(frame.Slice(region)) {
|
||||
return nil
|
||||
}
|
||||
return frame.Slice(region)[:inputLen]
|
||||
}
|
||||
|
||||
// frameOutput 尝试把 payload 写进帧的结果区（帧内 [inputLen, frame.Length)）。
|
||||
// 放不下时返回错误，由调用方决定是否申请扩容块。
|
||||
func frameOutput(frame SharedRef, inputLen uint32, payload []byte, jsonFlag bool) (SharedRef, error) {
|
||||
if frame.IsZero() {
|
||||
return SharedRef{}, fmt.Errorf("无调用帧")
|
||||
}
|
||||
area := frame.Slice(region)
|
||||
start := int(inputLen)
|
||||
if start > len(area) || len(payload) > len(area)-start {
|
||||
return SharedRef{}, fmt.Errorf("帧内空间不足（需 %d，剩 %d）", len(payload), len(area)-start)
|
||||
}
|
||||
copy(region[frame.Offset+uint32(start):], payload)
|
||||
ref := SharedRef{
|
||||
Offset: frame.Offset + uint32(start),
|
||||
Length: uint32(len(payload)),
|
||||
Generation: frame.Generation,
|
||||
}
|
||||
if jsonFlag {
|
||||
ref.Flags |= sharedRefFlagJSON
|
||||
}
|
||||
return ref, nil
|
||||
}
|
||||
|
||||
// arenaPut 申请一块扩容块并写入 payload，引用上打 sharedRefFlagExpand
|
||||
// 告知内核该块需单独归还（插件只申请，回收由内核做）。
|
||||
func arenaPut(payload []byte, jsonFlag bool) (SharedRef, error) {
|
||||
ref, err := arenaAlloc(uint32(len(payload)))
|
||||
if err != nil {
|
||||
return SharedRef{}, err
|
||||
}
|
||||
if len(payload) > int(ref.Length) {
|
||||
arenaFree(ref)
|
||||
return SharedRef{}, fmt.Errorf("扩容块容量不足（需 %d，得 %d）", len(payload), ref.Length)
|
||||
}
|
||||
copy(region[ref.Offset:ref.Offset+uint32(len(payload))], payload)
|
||||
ref.Length = uint32(len(payload))
|
||||
ref.Flags |= sharedRefFlagExpand
|
||||
if jsonFlag {
|
||||
ref.Flags |= sharedRefFlagJSON
|
||||
}
|
||||
return ref, nil
|
||||
}
|
||||
|
||||
// inlinePayloadLimit 是走内联 JSON 的上限。
|
||||
//
|
||||
// 小 payload 走内联省两次 RPC（申请 + 归还）；大 payload 走共享内存，
|
||||
// 避免把长文本塞进 NDJSON 帧。这是纯传输层优化，插件开发者无感。
|
||||
const inlinePayloadLimit = 512
|
||||
|
||||
// putInArena 把 payload 写入内核分配的共享槽，返回可随业务 RPC 回传的引用。
|
||||
//
|
||||
// 任一步失败都返回 ok=false，让调用方退回内联：共享内存只是优化，
|
||||
// 池满或超限绝不能影响功能。
|
||||
func putInArena(payload string) (SharedRef, bool) {
|
||||
if len(payload) <= inlinePayloadLimit || len(region) == 0 {
|
||||
return SharedRef{}, false
|
||||
}
|
||||
ref, err := arenaAlloc(uint32(len(payload)))
|
||||
if err != nil {
|
||||
return SharedRef{}, false
|
||||
}
|
||||
if len(payload) > int(ref.Length) || int(ref.Offset)+len(payload) > len(region) {
|
||||
arenaFree(ref)
|
||||
return SharedRef{}, false
|
||||
}
|
||||
copy(region[ref.Offset:ref.Offset+uint32(len(payload))], payload)
|
||||
ref.Length = uint32(len(payload))
|
||||
return ref, true
|
||||
}
|
||||
|
||||
// putValueInArena 把任意值 JSON 序列化后放进共享槽，太小或 arena 不可用时
|
||||
// 返回 false（调用方退到内联）。
|
||||
func putValueInArena(v interface{}) (SharedRef, bool) {
|
||||
blob, err := json.Marshal(v)
|
||||
if err != nil {
|
||||
return SharedRef{}, false
|
||||
}
|
||||
return putInArena(string(blob))
|
||||
}
|
||||
|
||||
// callWithText 按 payload 大小自动选择共享槽或内联，发起一次带文本的业务 RPC。
|
||||
//
|
||||
// 共享内存对插件开发者完全透明：SDK 层只看得到 string。
|
||||
func callWithText(method, source, channel, text string) (json.RawMessage, error) {
|
||||
return callWithTextOpts(method, source, channel, text, sdk.InjectOptions{})
|
||||
}
|
||||
|
||||
// callWithTextOpts 是 callWithText 的带标志位版本。
|
||||
//
|
||||
// 只在标志位非零时才写入参数：零值（记入记忆 + 不裁剪）与旧参数形态完全一致，
|
||||
// 便于内核侧做兼容与灰度。
|
||||
func callWithTextOpts(method, source, channel, text string, opts sdk.InjectOptions) (json.RawMessage, error) {
|
||||
if ref, ok := putInArena(text); ok {
|
||||
defer arenaFree(ref)
|
||||
args := map[string]interface{}{
|
||||
"source": source, "channel": channel, "text_ref": ref,
|
||||
}
|
||||
applyInjectOpts(args, opts)
|
||||
return callCore(method, args)
|
||||
}
|
||||
args := map[string]interface{}{
|
||||
"source": source, "channel": channel, "text": text,
|
||||
}
|
||||
applyInjectOpts(args, opts)
|
||||
return callCore(method, args)
|
||||
}
|
||||
|
||||
// applyInjectOpts 把 InjectOptions 摊进注入参数字典（仅非零值）。
|
||||
func applyInjectOpts(args map[string]interface{}, opts sdk.InjectOptions) {
|
||||
if opts.NoMemory {
|
||||
args["no_memory"] = true
|
||||
}
|
||||
if opts.ContextPolicy != "" {
|
||||
args["context_policy"] = opts.ContextPolicy
|
||||
}
|
||||
if opts.CleanerName != "" {
|
||||
args["cleaner_name"] = opts.CleanerName
|
||||
}
|
||||
}
|
||||
|
||||
// ---- 全局状态 ----
|
||||
|
||||
var (
|
||||
@ -88,15 +305,20 @@ var (
|
||||
|
||||
handlerMu sync.RWMutex
|
||||
toolHandlers = map[string]sdk.ToolHandler{}
|
||||
toolCleaners = map[string]func(string) string{}
|
||||
inputCleaners = map[string]func(string) string{}
|
||||
stageHandlers = map[string]sdk.StageHandler{}
|
||||
outputHandlers = map[string]sdk.ToolHandler{}
|
||||
outputCleaners = map[string]func(string) string{}
|
||||
|
||||
shm []byte
|
||||
|
||||
// region 见文件头部 SharedRef 注释（handshake 时设置）。
|
||||
|
||||
// 事件环（§3.6）：fd 4 = 事件环段 mmap，fd 5 = eventfd 读端
|
||||
evtRingData []byte
|
||||
evtNotifier evtWaiter
|
||||
evtHandlers = map[uint32]func(*sdk.Event){}
|
||||
evtRingData []byte
|
||||
evtNotifier evtWaiter
|
||||
evtHandlers = map[uint32]func(*sdk.Event){}
|
||||
evtHandlerMu sync.RWMutex
|
||||
)
|
||||
|
||||
@ -416,9 +638,14 @@ func buildPluginSDK(name string) *sdk.PluginSDK {
|
||||
func(toolName string, def sdk.ToolDef, handler sdk.ToolHandler) error {
|
||||
handlerMu.Lock()
|
||||
toolHandlers[toolName] = handler
|
||||
if def.Cleaner != nil {
|
||||
toolCleaners[toolName] = def.Cleaner
|
||||
} else {
|
||||
delete(toolCleaners, toolName)
|
||||
}
|
||||
handlerMu.Unlock()
|
||||
return callCoreVoid("tool.register", map[string]interface{}{
|
||||
"name": toolName, "def": def,
|
||||
"name": toolName, "def": def, "has_cleaner": def.Cleaner != nil,
|
||||
})
|
||||
},
|
||||
func(stage sdk.Stage, handler sdk.StageHandler) {
|
||||
@ -437,10 +664,16 @@ func buildPluginSDK(name string) *sdk.PluginSDK {
|
||||
func(chName string, caps int, desc string, def sdk.ChannelDef, handler sdk.ToolHandler) error {
|
||||
handlerMu.Lock()
|
||||
outputHandlers[chName] = handler
|
||||
if def.Cleaner != nil {
|
||||
outputCleaners[chName] = def.Cleaner
|
||||
} else {
|
||||
delete(outputCleaners, chName)
|
||||
}
|
||||
handlerMu.Unlock()
|
||||
return callCoreVoid("output.register", map[string]interface{}{
|
||||
"name": chName, "caps": caps, "desc": desc,
|
||||
"def": map[string]interface{}{"NoMemory": def.NoMemory},
|
||||
"def": map[string]interface{}{"NoMemory": def.NoMemory},
|
||||
"has_cleaner": def.Cleaner != nil,
|
||||
})
|
||||
},
|
||||
)
|
||||
@ -454,9 +687,19 @@ func buildPluginSDK(name string) *sdk.PluginSDK {
|
||||
base.SetTextMemoryAPI(procTextMemory{})
|
||||
base.SetPluginMgrAPI(procPluginMgr{})
|
||||
base.SetInputChannelRegistrar(func(chName string, def sdk.ChannelDef) error {
|
||||
handlerMu.Lock()
|
||||
if def.Cleaner != nil {
|
||||
inputCleaners[chName] = def.Cleaner
|
||||
} else {
|
||||
delete(inputCleaners, chName)
|
||||
}
|
||||
handlerMu.Unlock()
|
||||
return callCoreVoid("input.register", map[string]interface{}{
|
||||
"name": chName,
|
||||
"def": map[string]interface{}{"NoMemory": def.NoMemory},
|
||||
// 整个结构体：手写字段白名单会把新增字段静默丢掉
|
||||
// （ChannelDef.Cleaner 已标 json:"-"，可以整体 marshal）。
|
||||
"def": def,
|
||||
"has_cleaner": def.Cleaner != nil,
|
||||
})
|
||||
})
|
||||
return base
|
||||
@ -464,17 +707,32 @@ func buildPluginSDK(name string) *sdk.PluginSDK {
|
||||
|
||||
type procIO struct{}
|
||||
|
||||
// 下面六个三参数方法是 *Opts 变体的零值糖：记入记忆 + 不裁剪。
|
||||
|
||||
func (procIO) InjectText(s, c, t string) {
|
||||
callCoreVoid("io.injectText", map[string]string{"source": s, "channel": c, "text": t})
|
||||
procIO{}.InjectTextOpts(s, c, t, sdk.InjectOptions{})
|
||||
}
|
||||
func (procIO) InjectInterruptText(s, c, t string) {
|
||||
callCoreVoid("io.injectInterrupt", map[string]string{"source": s, "channel": c, "text": t})
|
||||
procIO{}.InjectInterruptTextOpts(s, c, t, sdk.InjectOptions{})
|
||||
}
|
||||
func (procIO) InjectTextNoMemory(s, c, t string) {
|
||||
callCoreVoid("io.injectTextNoMem", map[string]string{"source": s, "channel": c, "text": t})
|
||||
procIO{}.InjectTextOpts(s, c, t, sdk.InjectOptions{NoMemory: true})
|
||||
}
|
||||
func (procIO) InjectInputSync(s, c, t string) string {
|
||||
raw, err := callCore("io.injectInputSync", map[string]string{"source": s, "channel": c, "text": t})
|
||||
return procIO{}.InjectInputSyncOpts(s, c, t, sdk.InjectOptions{})
|
||||
}
|
||||
|
||||
// 以下为带标志位的注入：opts 决定这次注入是否进记忆、是否据此裁剪上下文。
|
||||
|
||||
func (procIO) InjectTextOpts(s, c, t string, opts sdk.InjectOptions) {
|
||||
// 忽略错误：注入是 fire-and-forget，与内联路径语义一致
|
||||
_, _ = callWithTextOpts("io.injectText", s, c, t, opts)
|
||||
}
|
||||
func (procIO) InjectInterruptTextOpts(s, c, t string, opts sdk.InjectOptions) {
|
||||
_, _ = callWithTextOpts("io.injectInterrupt", s, c, t, opts)
|
||||
}
|
||||
func (procIO) InjectInputSyncOpts(s, c, t string, opts sdk.InjectOptions) string {
|
||||
raw, err := callWithTextOpts("io.injectInputSync", s, c, t, opts)
|
||||
if err != nil {
|
||||
return ""
|
||||
}
|
||||
@ -485,11 +743,80 @@ func (procIO) InjectInputSync(s, c, t string) string {
|
||||
return r.Reply
|
||||
}
|
||||
func (procIO) SetToolBlocks(blocks []sdk.ContentBlock) {
|
||||
if err := callCoreVoid("io.setToolBlocks", map[string]interface{}{"blocks": blocks}); err != nil {
|
||||
// 媒体块经共享内存（blocks_ref）：本地生成的图/音频是 base64 data URL，
|
||||
// 一张图可达数 MB；内联时整份 base64 还要在 RPC 报文里再编码/再拷贝一遍。
|
||||
// 更重要的是内容本体落在共享段里，插件回调才能就地改写。
|
||||
// 小 payload（如纯文本块）仍走内联，省一次 RPC。
|
||||
args := map[string]interface{}{}
|
||||
if ref, ok := putValueInArena(blocks); ok {
|
||||
defer arenaFree(ref)
|
||||
args["blocks_ref"] = ref
|
||||
} else {
|
||||
args["blocks"] = blocks
|
||||
}
|
||||
if err := callCoreVoid("io.setToolBlocks", args); err != nil {
|
||||
log.Printf("SetToolBlocks: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// 带媒体的注入：插件主动发起一轮带图/音频的对话。
|
||||
// 与 SetToolBlocks 的区别是媒体在**本轮**就到模型手上，而不是等下一条 tool message。
|
||||
func (procIO) InjectInputMedia(s, c, t string, blocks []sdk.ContentBlock) {
|
||||
procIO{}.InjectInputMediaOpts(s, c, t, blocks, sdk.InjectOptions{})
|
||||
}
|
||||
|
||||
func (procIO) InjectInputMediaSync(s, c, t string, blocks []sdk.ContentBlock) string {
|
||||
return procIO{}.InjectInputMediaSyncOpts(s, c, t, blocks, sdk.InjectOptions{})
|
||||
}
|
||||
|
||||
func (procIO) InjectInterruptMedia(s, c, t string, blocks []sdk.ContentBlock) {
|
||||
procIO{}.InjectInterruptMediaOpts(s, c, t, blocks, sdk.InjectOptions{})
|
||||
}
|
||||
|
||||
func (procIO) InjectInputMediaOpts(s, c, t string, blocks []sdk.ContentBlock, opts sdk.InjectOptions) {
|
||||
args, free := mediaArgsOwned(s, c, t, blocks)
|
||||
defer free()
|
||||
applyInjectOpts(args, opts)
|
||||
callCoreVoid("io.injectMedia", args)
|
||||
}
|
||||
|
||||
func (procIO) InjectInputMediaSyncOpts(s, c, t string, blocks []sdk.ContentBlock, opts sdk.InjectOptions) string {
|
||||
args, free := mediaArgsOwned(s, c, t, blocks)
|
||||
defer free()
|
||||
applyInjectOpts(args, opts)
|
||||
raw, err := callCore("io.injectMediaSync", args)
|
||||
if err != nil {
|
||||
return ""
|
||||
}
|
||||
var r struct {
|
||||
Reply string `json:"reply"`
|
||||
}
|
||||
json.Unmarshal(raw, &r)
|
||||
return r.Reply
|
||||
}
|
||||
|
||||
func (procIO) InjectInterruptMediaOpts(s, c, t string, blocks []sdk.ContentBlock, opts sdk.InjectOptions) {
|
||||
args, free := mediaArgsOwned(s, c, t, blocks)
|
||||
defer free()
|
||||
applyInjectOpts(args, opts)
|
||||
callCoreVoid("io.injectInterruptMedia", args)
|
||||
}
|
||||
|
||||
// mediaArgsOwned 构造媒体注入参数，并返回释放函数。
|
||||
//
|
||||
// 为什么要返回释放函数而不是自己 defer：调用方可能是需要等应答的同步调用
|
||||
// （injectMediaSync），槽在应答到达前不能被回收，否则内核读到的是已释放的内存。
|
||||
func mediaArgsOwned(s, c, t string, blocks []sdk.ContentBlock) (map[string]interface{}, func()) {
|
||||
args := map[string]interface{}{"source": s, "channel": c, "text": t}
|
||||
ref, ok := putValueInArena(blocks)
|
||||
if !ok {
|
||||
args["blocks"] = blocks
|
||||
return args, func() {}
|
||||
}
|
||||
args["blocks_ref"] = ref
|
||||
return args, func() { arenaFree(ref) }
|
||||
}
|
||||
|
||||
type procMemory struct{}
|
||||
|
||||
func (procMemory) Recall(q []string, d int) ([]sdk.Entity, []sdk.Relation, error) {
|
||||
@ -555,7 +882,58 @@ func (procDocMemory) Query(text string, topK int) []*sdk.Doc {
|
||||
return r.Docs
|
||||
}
|
||||
func (procDocMemory) Insert(d *sdk.Doc) error {
|
||||
return callCoreVoid("doc.insert", map[string]interface{}{"doc": d})
|
||||
return callCoreVoid("doc.insert", docInsertArgs(d))
|
||||
}
|
||||
|
||||
// docInsertArgs 构造 doc.insert 参数：正文优先走共享内存。
|
||||
//
|
||||
// doc_content 可达几十 KB～数 MB，内联时整份要在 RPC 报文里再编码再拷贝一遍；
|
||||
// 且内容本体落在共享段里，插件回调才能就地改写。小文档仍内联。
|
||||
func docInsertArgs(d *sdk.Doc) map[string]interface{} {
|
||||
if ref, ok := putValueInArena(d); ok {
|
||||
defer arenaFree(ref)
|
||||
return map[string]interface{}{"doc_ref": ref}
|
||||
}
|
||||
return map[string]interface{}{"doc": d}
|
||||
}
|
||||
|
||||
// InsertWithMedia 写入文档并关联媒体。
|
||||
//
|
||||
// 内核会把 `[mime <短digest>] <描述>` 标记补进 Content 并挂上引用，回传的
|
||||
// doc 带着补好的 Content/ID/MediaDigests——回写进 d 让调用方能拿到这些。
|
||||
func (procDocMemory) InsertWithMedia(d *sdk.Doc, atts []sdk.MediaAttachment) error {
|
||||
// 文档正文与附件（含媒体 data URL）都优先走共享内存。
|
||||
args := map[string]interface{}{}
|
||||
var frees []func()
|
||||
defer func() {
|
||||
for _, f := range frees {
|
||||
f()
|
||||
}
|
||||
}()
|
||||
if ref, ok := putValueInArena(d); ok {
|
||||
frees = append(frees, func() { arenaFree(ref) })
|
||||
args["doc_ref"] = ref
|
||||
} else {
|
||||
args["doc"] = d
|
||||
}
|
||||
if ref, ok := putValueInArena(atts); ok {
|
||||
frees = append(frees, func() { arenaFree(ref) })
|
||||
args["attachments_ref"] = ref
|
||||
} else {
|
||||
args["attachments"] = atts
|
||||
}
|
||||
|
||||
raw, err := callCore("doc.insertWithMedia", args)
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
var r struct {
|
||||
Doc *sdk.Doc `json:"doc"`
|
||||
}
|
||||
if json.Unmarshal(raw, &r) == nil && r.Doc != nil {
|
||||
*d = *r.Doc
|
||||
}
|
||||
return nil
|
||||
}
|
||||
func (procDocMemory) Remove(id string) {
|
||||
callCoreVoid("doc.remove", map[string]string{"id": id})
|
||||
@ -584,6 +962,13 @@ func (procKnowledge) Search(q string, topK int) ([]*sdk.Knowledge, error) {
|
||||
return r.Results, nil
|
||||
}
|
||||
func (procKnowledge) Add(name, content string) error {
|
||||
// 知识正文可达数十 KB，优先走共享内存（内容是 JSON 字符串）。
|
||||
if ref, ok := putValueInArena(content); ok {
|
||||
defer arenaFree(ref)
|
||||
return callCoreVoid("knowledge.add", map[string]interface{}{
|
||||
"name": name, "content_ref": ref,
|
||||
})
|
||||
}
|
||||
return callCoreVoid("knowledge.add", map[string]string{"name": name, "content": content})
|
||||
}
|
||||
func (procKnowledge) List() ([]string, error) {
|
||||
@ -895,10 +1280,27 @@ func handleKernelRequest(req *rpcRequest) {
|
||||
|
||||
case "tool.invoke":
|
||||
var p struct {
|
||||
Name string `json:"name"`
|
||||
Args map[string]interface{} `json:"args"`
|
||||
Name string `json:"name"`
|
||||
Args map[string]interface{} `json:"args"`
|
||||
Frame SharedRef `json:"frame"`
|
||||
ArgsLen uint32 `json:"args_len"`
|
||||
}
|
||||
json.Unmarshal(req.Params, &p)
|
||||
|
||||
// 参数：内核标定帧的前段。只有直连 RPC 的调用方（无帧）才走
|
||||
// 内联 Args——生产路径永远走帧。
|
||||
args := p.Args
|
||||
if !p.Frame.IsZero() {
|
||||
if blob := frameInput(p.Frame, p.ArgsLen); len(blob) > 0 {
|
||||
var decoded map[string]interface{}
|
||||
if err := json.Unmarshal(blob, &decoded); err != nil {
|
||||
respondErr(req.ID, fmt.Errorf("解析共享参数: %w", err))
|
||||
return
|
||||
}
|
||||
args = decoded
|
||||
}
|
||||
}
|
||||
|
||||
handlerMu.RLock()
|
||||
h, ok := toolHandlers[p.Name]
|
||||
handlerMu.RUnlock()
|
||||
@ -906,12 +1308,68 @@ func handleKernelRequest(req *rpcRequest) {
|
||||
respondErr(req.ID, fmt.Errorf("未注册的工具: %s", p.Name))
|
||||
return
|
||||
}
|
||||
res, err := h(p.Args)
|
||||
res, err := h(args)
|
||||
if err != nil {
|
||||
respondErr(req.ID, err)
|
||||
return
|
||||
}
|
||||
respond(req.ID, map[string]interface{}{"result": res})
|
||||
|
||||
blob, err := json.Marshal(res)
|
||||
if err != nil {
|
||||
respondErr(req.ID, fmt.Errorf("序列化结果: %w", err))
|
||||
return
|
||||
}
|
||||
// 结果优先写进内核标定的帧；放不下才申请扩容块。
|
||||
outRef, err := frameOutput(p.Frame, p.ArgsLen, blob, true)
|
||||
if err != nil {
|
||||
outRef, err = arenaPut(blob, true)
|
||||
if err != nil {
|
||||
respondErr(req.ID, fmt.Errorf("结果扩容失败: %w", err))
|
||||
return
|
||||
}
|
||||
}
|
||||
respond(req.ID, map[string]interface{}{"result_ref": outRef})
|
||||
|
||||
case "cleaner.invoke":
|
||||
var p struct {
|
||||
Scope string `json:"scope"`
|
||||
Name string `json:"name"`
|
||||
Frame SharedRef `json:"frame"`
|
||||
InputLen uint32 `json:"input_len"`
|
||||
}
|
||||
if err := json.Unmarshal(req.Params, &p); err != nil {
|
||||
respondErr(req.ID, fmt.Errorf("解析 Cleaner 参数: %w", err))
|
||||
return
|
||||
}
|
||||
handlerMu.RLock()
|
||||
var cleaner func(string) string
|
||||
switch p.Scope {
|
||||
case "tool":
|
||||
cleaner = toolCleaners[p.Name]
|
||||
case "input":
|
||||
cleaner = inputCleaners[p.Name]
|
||||
case "output":
|
||||
cleaner = outputCleaners[p.Name]
|
||||
}
|
||||
handlerMu.RUnlock()
|
||||
if cleaner == nil {
|
||||
respondErr(req.ID, fmt.Errorf("%s %s 未注册 Cleaner", p.Scope, p.Name))
|
||||
return
|
||||
}
|
||||
|
||||
input := string(frameInput(p.Frame, p.InputLen))
|
||||
output := cleaner(input)
|
||||
|
||||
// 结果优先写进内核标定的帧；放不下才申请扩容块。
|
||||
outRef, err := frameOutput(p.Frame, p.InputLen, []byte(output), false)
|
||||
if err != nil {
|
||||
outRef, err = arenaPut([]byte(output), false)
|
||||
if err != nil {
|
||||
respondErr(req.ID, fmt.Errorf("结果扩容失败: %w", err))
|
||||
return
|
||||
}
|
||||
}
|
||||
respond(req.ID, map[string]interface{}{"text_ref": outRef})
|
||||
|
||||
case "stage.invoke":
|
||||
handleStageInvoke(req)
|
||||
@ -920,8 +1378,23 @@ func handleKernelRequest(req *rpcRequest) {
|
||||
var p struct {
|
||||
Channel string `json:"channel"`
|
||||
Args map[string]interface{} `json:"args"`
|
||||
Frame SharedRef `json:"frame"`
|
||||
ArgsLen uint32 `json:"args_len"`
|
||||
}
|
||||
json.Unmarshal(req.Params, &p)
|
||||
// 参数：内核标定帧的前段（§13.6）。只有直连 RPC 的调用方（无帧）
|
||||
// 才走内联 Args——生产路径永远走帧，大 payload 不再爆管道。
|
||||
args := p.Args
|
||||
if !p.Frame.IsZero() {
|
||||
if blob := frameInput(p.Frame, p.ArgsLen); len(blob) > 0 {
|
||||
var decoded map[string]interface{}
|
||||
if err := json.Unmarshal(blob, &decoded); err != nil {
|
||||
respondErr(req.ID, fmt.Errorf("解析共享输出参数: %w", err))
|
||||
return
|
||||
}
|
||||
args = decoded
|
||||
}
|
||||
}
|
||||
handlerMu.RLock()
|
||||
h, ok := outputHandlers[p.Channel]
|
||||
handlerMu.RUnlock()
|
||||
@ -930,7 +1403,7 @@ func handleKernelRequest(req *rpcRequest) {
|
||||
return
|
||||
}
|
||||
// 同步返回真实结果——内核据此告知模型成功/失败，不再假成功（§9.4）
|
||||
res, err := h(p.Args)
|
||||
res, err := h(args)
|
||||
if err != nil {
|
||||
respondErr(req.ID, err)
|
||||
return
|
||||
@ -997,10 +1470,10 @@ func handleKernelRequest(req *rpcRequest) {
|
||||
func handleHandshake(req *rpcRequest) {
|
||||
var p struct {
|
||||
Protocol int `json:"protocol"`
|
||||
ShmVersion uint32 `json:"shm_version"`
|
||||
ShmSize int `json:"shm_size"`
|
||||
PluginName string `json:"plugin_name"`
|
||||
EvtRingSize int `json:"evt_ring_size,omitempty"`
|
||||
ShmVersion uint32 `json:"shm_version"`
|
||||
ShmSize int `json:"shm_size"`
|
||||
PluginName string `json:"plugin_name"`
|
||||
EvtRingSize int `json:"evt_ring_size,omitempty"`
|
||||
}
|
||||
json.Unmarshal(req.Params, &p)
|
||||
|
||||
@ -1017,41 +1490,44 @@ func handleHandshake(req *rpcRequest) {
|
||||
pluginName = p.PluginName
|
||||
}
|
||||
|
||||
// 挂载 StageContext 共享段。
|
||||
// 传递机制按平台不同（Unix 用继承的 fd，Windows 用命名段），
|
||||
// 由 z_proc_shm_*.go 承担——本文件保持平台无关。
|
||||
// 挂载统一共享内存区域。
|
||||
// fd 3 (Unix) / 命名对象 (Windows) 传给插件子进程，包含 SuperBlock +
|
||||
// StageContext + EvtRing 两段。SuperBlock 记录各段的偏移与大小。
|
||||
if p.ShmSize > 0 {
|
||||
m, err := attachStageShm(p.ShmSize)
|
||||
m, err := attachUnifiedShm(p.ShmSize)
|
||||
if err != nil {
|
||||
respondErr(req.ID, fmt.Errorf("挂载共享段失败: %w", err))
|
||||
respondErr(req.ID, fmt.Errorf("挂载统一共享区域失败: %w", err))
|
||||
return
|
||||
}
|
||||
if got := binary.LittleEndian.Uint32(m[shmOffMagic:]); got != shmMagic {
|
||||
respondErr(req.ID, fmt.Errorf("共享段魔数不匹配（0x%x）", got))
|
||||
if got := binary.LittleEndian.Uint32(m[sbOffMagic:]); got != unifiedMagic {
|
||||
respondErr(req.ID, fmt.Errorf("统一区域魔数不匹配（0x%x，期望 0x%x）", got, unifiedMagic))
|
||||
return
|
||||
}
|
||||
shm = m
|
||||
}
|
||||
|
||||
// 挂载事件环段 + 打开通知句柄（§3.6）
|
||||
if p.EvtRingSize > 0 {
|
||||
er, err := attachEvtRingShm(p.EvtRingSize)
|
||||
if err != nil {
|
||||
respondErr(req.ID, fmt.Errorf("挂载事件环段失败: %w", err))
|
||||
return
|
||||
ctxOff := binary.LittleEndian.Uint32(m[sbOffCtxOff:])
|
||||
ctxSize := binary.LittleEndian.Uint32(m[sbOffCtxSize:])
|
||||
evtOff := binary.LittleEndian.Uint32(m[sbOffEvtOff:])
|
||||
evtSize := binary.LittleEndian.Uint32(m[sbOffEvtSize:])
|
||||
// shm 指向 StageContext 段，后续代码用 shm[off...] 访问该段内部字段
|
||||
shm = m[ctxOff : ctxOff+ctxSize]
|
||||
// region 保存完整 mmap 区域。arena 的偏移与大小由内核在
|
||||
// arena.alloc 的应答里下发，插件侧不再自己解析槽池布局。
|
||||
region = m
|
||||
// 挂载事件环段 + 打开通知句柄（§13.1：EvtRing 在统一区域内）
|
||||
if p.EvtRingSize > 0 && evtSize > 0 {
|
||||
er := m[evtOff : evtOff+evtSize]
|
||||
if got := binary.LittleEndian.Uint32(er[evtOffMagic : evtOffMagic+4]); got != evtRingMagic {
|
||||
respondErr(req.ID, fmt.Errorf("事件环魔数不匹配（0x%x）", got))
|
||||
return
|
||||
}
|
||||
notifier, err := openEvtNotifier()
|
||||
if err != nil {
|
||||
respondErr(req.ID, fmt.Errorf("打开事件通知句柄失败: %w", err))
|
||||
return
|
||||
}
|
||||
evtRingData = er
|
||||
evtNotifier = notifier
|
||||
go evtConsumerLoop()
|
||||
}
|
||||
if got := binary.LittleEndian.Uint32(er[evtOffMagic : evtOffMagic+4]); got != evtRingMagic {
|
||||
respondErr(req.ID, fmt.Errorf("事件环魔数不匹配（0x%x）", got))
|
||||
return
|
||||
}
|
||||
notifier, err := openEvtNotifier()
|
||||
if err != nil {
|
||||
respondErr(req.ID, fmt.Errorf("打开事件通知句柄失败: %w", err))
|
||||
return
|
||||
}
|
||||
evtRingData = er
|
||||
evtNotifier = notifier
|
||||
go evtConsumerLoop()
|
||||
}
|
||||
|
||||
respond(req.ID, map[string]interface{}{
|
||||
@ -10,31 +10,23 @@ import (
|
||||
|
||||
// Unix 侧共享段挂载：内核经 ExtraFiles 传入继承的 fd。
|
||||
//
|
||||
// fd 布局（与内核 internal/plugin/proc/plugin.go 的 ExtraFiles 顺序一致）：
|
||||
// 统一共享内存区域布局（§13.1）：
|
||||
//
|
||||
// fd 3 = StageContext 段（memfd / 已 unlink 的临时文件）
|
||||
// fd 4 = 事件环段
|
||||
// fd 5 = 事件通知（Linux eventfd / macOS pipe 读端）
|
||||
// fd 3 = 统一区域（SuperBlock + StageContext + EvtRing）
|
||||
// fd 4 = 事件通知（Linux eventfd / macOS pipe 读端）
|
||||
//
|
||||
// 继承的 fd 无需文件名，也不残留——这是选 memfd 而非 /dev/shm 的原因。
|
||||
const (
|
||||
fdStageShm = 3
|
||||
fdEvtRingShm = 4
|
||||
fdEvtNotifier = 5
|
||||
fdUnifiedShm = 3
|
||||
fdEvtNotifier = 4
|
||||
)
|
||||
|
||||
// attachStageShm 挂载 StageContext 共享段。
|
||||
// attachUnifiedShm 挂载统一共享内存区域。
|
||||
//
|
||||
// 各进程 mmap 到不同虚拟地址，段内一律用相对偏移而非指针，故仍能正确解引用
|
||||
// （实验 2 已验证父子 mmap 基址不同时偏移解引用正确）。
|
||||
func attachStageShm(size int) ([]byte, error) {
|
||||
return syscall.Mmap(fdStageShm, 0, size,
|
||||
syscall.PROT_READ|syscall.PROT_WRITE, syscall.MAP_SHARED)
|
||||
}
|
||||
|
||||
// attachEvtRingShm 挂载事件环段。
|
||||
func attachEvtRingShm(size int) ([]byte, error) {
|
||||
return syscall.Mmap(fdEvtRingShm, 0, size,
|
||||
func attachUnifiedShm(size int) ([]byte, error) {
|
||||
return syscall.Mmap(fdUnifiedShm, 0, size,
|
||||
syscall.PROT_READ|syscall.PROT_WRITE, syscall.MAP_SHARED)
|
||||
}
|
||||
|
||||
@ -13,7 +13,7 @@ import (
|
||||
|
||||
"github.com/traefik/yaegi/interp"
|
||||
"github.com/traefik/yaegi/stdlib"
|
||||
"github.com/JianFeeeee/homeagent-sdk/tools/plugindev/yaegi/mocksdk"
|
||||
"gitcode.com/JianFeeeee/homeagent-sdk/tools/hmapdev/yaegi/mocksdk"
|
||||
)
|
||||
|
||||
type YaegiDebugger struct {
|
||||
@ -83,18 +83,69 @@ type ToolResult struct {
|
||||
}
|
||||
|
||||
type ToolDef struct {
|
||||
Name string `json:"name"`
|
||||
Plugin string `json:"plugin,omitempty"`
|
||||
Description string `json:"description"`
|
||||
Parameters map[string]interface{} `json:"parameters"`
|
||||
NoMemory bool `json:"no_memory,omitempty"`
|
||||
Cleaner func(string) string `json:"-"`
|
||||
Name string `json:"name"`
|
||||
Plugin string `json:"plugin,omitempty"`
|
||||
Description string `json:"description"`
|
||||
Parameters map[string]interface{} `json:"parameters"`
|
||||
NoMemory bool `json:"no_memory,omitempty"`
|
||||
Cleaner func(string) string `json:"-"`
|
||||
ContextPolicy string `json:"context_policy,omitempty"`
|
||||
}
|
||||
|
||||
// 上下文策略取值，与公共 SDK 一致。
|
||||
const (
|
||||
ContextPolicyNone = "none"
|
||||
ContextPolicyPrune = "prune"
|
||||
)
|
||||
|
||||
// InjectOptions 与公共 SDK 同构：声明一次注入是否记入记忆、是否据此裁剪上下文、
|
||||
// 以及用哪个已注册的通道 cleaner 清洗注入内容。
|
||||
type InjectOptions struct {
|
||||
NoMemory bool
|
||||
ContextPolicy string
|
||||
CleanerName string
|
||||
}
|
||||
|
||||
type IOInjector interface {
|
||||
InjectInterruptText(source, channel, text string)
|
||||
InjectText(source, channel, text string)
|
||||
InjectTextNoMemory(source, channel, text string)
|
||||
// InjectInputSync 注入输入事件并同步等待 agent 回复（无回复时返回空串）。
|
||||
// 通道类插件（qq / a2a 等）靠它完成「收到入站 → agent 处理 → 回复取回」闭环，
|
||||
// 而 mock 此前只有带 flags 的 InjectInputSyncOpts、没有这个零值糖——
|
||||
// 于是一个能在 plugin.bin 里编译通过、在 yaegi 下却调不通的方法就长住了。
|
||||
InjectInputSync(source, channel, text string) string
|
||||
// 1.1.0 媒体注入。与公共 SDK 同构：插件在 yaegi 下调得通的方法，
|
||||
// 编成 plugin.bin 后必须也调得通，否则调试期与真实运行行为不一致。
|
||||
InjectInputMedia(source, channel, text string, blocks []ContentBlock)
|
||||
InjectInputMediaSync(source, channel, text string, blocks []ContentBlock) string
|
||||
InjectInterruptMedia(source, channel, text string, blocks []ContentBlock)
|
||||
SetToolBlocks(blocks []ContentBlock)
|
||||
|
||||
// 1.2.0 带标志位的注入，与公共 SDK 同构。
|
||||
InjectTextOpts(source, channel, text string, opts InjectOptions)
|
||||
InjectInterruptTextOpts(source, channel, text string, opts InjectOptions)
|
||||
InjectInputSyncOpts(source, channel, text string, opts InjectOptions) string
|
||||
InjectInputMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
|
||||
InjectInputMediaSyncOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) string
|
||||
InjectInterruptMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions)
|
||||
}
|
||||
|
||||
// ContentBlock 与公共 SDK 同构（OpenAI 多模态内容块格式）。
|
||||
type ContentBlock struct {
|
||||
Type string `json:"type"`
|
||||
Text string `json:"text,omitempty"`
|
||||
ImageURL *ImageURL `json:"image_url,omitempty"`
|
||||
AudioURL *AudioURL `json:"audio_url,omitempty"`
|
||||
}
|
||||
|
||||
type ImageURL struct {
|
||||
URL string `json:"url"`
|
||||
Detail string `json:"detail,omitempty"`
|
||||
}
|
||||
|
||||
type AudioURL struct {
|
||||
URL string `json:"url"`
|
||||
}
|
||||
|
||||
type EventType string
|
||||
@ -159,29 +210,33 @@ type mockSettings struct{ data map[string]interface{} }
|
||||
|
||||
func (s *mockSettings) Get(key string) (interface{}, error) {
|
||||
v, ok := s.data[key]
|
||||
if !ok { return nil, nil }
|
||||
if !ok {
|
||||
return nil, nil
|
||||
}
|
||||
return v, nil
|
||||
}
|
||||
func (s *mockSettings) Set(key string, value interface{}) error { s.data[key] = value; return nil }
|
||||
func (s *mockSettings) List(prefix string) ([]string, error) {
|
||||
var ks []string
|
||||
for k := range s.data {
|
||||
if strings.HasPrefix(k, prefix) { ks = append(ks, k) }
|
||||
if strings.HasPrefix(k, prefix) {
|
||||
ks = append(ks, k)
|
||||
}
|
||||
}
|
||||
return ks, nil
|
||||
}
|
||||
func (s *mockSettings) GetCore(key string) (interface{}, error) { return nil, nil }
|
||||
func (s *mockSettings) SetCore(key string, value interface{}) error { return nil }
|
||||
func (s *mockSettings) ListCore(prefix string) ([]string, error) { return nil, nil }
|
||||
func (s *mockSettings) GetPlugin(p, k string) (interface{}, error) { return nil, nil }
|
||||
func (s *mockSettings) SetPlugin(p, k string, v interface{}) error { return nil }
|
||||
func (s *mockSettings) GetCore(key string) (interface{}, error) { return nil, nil }
|
||||
func (s *mockSettings) SetCore(key string, value interface{}) error { return nil }
|
||||
func (s *mockSettings) ListCore(prefix string) ([]string, error) { return nil, nil }
|
||||
func (s *mockSettings) GetPlugin(p, k string) (interface{}, error) { return nil, nil }
|
||||
func (s *mockSettings) SetPlugin(p, k string, v interface{}) error { return nil }
|
||||
func (s *mockSettings) ListPlugin(p, prefix string) ([]string, error) { return nil, nil }
|
||||
func (s *mockSettings) RegisterDef(def ConfigDef) {
|
||||
logf("config def: %s = %s", def.Key, def.Default)
|
||||
}
|
||||
func (s *mockSettings) Defs(prefix string) []*ConfigDef { return nil }
|
||||
func (s *mockSettings) Dump() map[string]interface{} { return s.data }
|
||||
func (s *mockSettings) Plugins() []string { return nil }
|
||||
func (s *mockSettings) Dump() map[string]interface{} { return s.data }
|
||||
func (s *mockSettings) Plugins() []string { return nil }
|
||||
|
||||
type Entity struct {
|
||||
Name string `json:"name"`
|
||||
@ -195,10 +250,21 @@ type Relation struct {
|
||||
Object string `json:"object"`
|
||||
}
|
||||
|
||||
// Triple 与公共 SDK 同构。
|
||||
//
|
||||
// ❗字段名曾是 `Predicate`，而公共 SDK 一直叫 `Relation`。
|
||||
// yaegi 解释器下插件写 `Relation:` 会报未知字段，写 `Predicate:` 则在
|
||||
// 编成 plugin.bin 时报错——谁都不对。没人发现是因为没有任何代码
|
||||
// 对着 mocksdk 编译，漂移不会被编译器抓到。
|
||||
type Triple struct {
|
||||
Subject string `json:"subject"`
|
||||
Predicate string `json:"predicate"`
|
||||
Object string `json:"object"`
|
||||
Subject string `json:"subject"`
|
||||
Relation string `json:"relation"`
|
||||
Object string `json:"object"`
|
||||
Confidence float64 `json:"confidence,omitempty"`
|
||||
SubjectType string `json:"subject_type,omitempty"`
|
||||
ObjectType string `json:"object_type,omitempty"`
|
||||
SentenceText string `json:"sentence_text,omitempty"`
|
||||
MediaDigests []string `json:"media_digests,omitempty"`
|
||||
}
|
||||
|
||||
type MemoryAPI interface {
|
||||
@ -212,37 +278,57 @@ type MemoryAPI interface {
|
||||
type mockMemory struct{}
|
||||
|
||||
func (mockMemory) Recall(q []string, d int) ([]Entity, []Relation, error) { return nil, nil, nil }
|
||||
func (mockMemory) Commit(t []Triple) error { return nil }
|
||||
func (mockMemory) Introspect() (map[string]interface{}, error) { return map[string]interface{}{}, nil }
|
||||
func (mockMemory) MergeEntities(s, t string) (int, error) { return 0, nil }
|
||||
func (mockMemory) Purge(c map[string]string, m string) (int, error) { return 0, nil }
|
||||
func (mockMemory) Commit(t []Triple) error { return nil }
|
||||
func (mockMemory) Introspect() (map[string]interface{}, error) { return map[string]interface{}{}, nil }
|
||||
func (mockMemory) MergeEntities(s, t string) (int, error) { return 0, nil }
|
||||
func (mockMemory) Purge(c map[string]string, m string) (int, error) { return 0, nil }
|
||||
|
||||
type Doc struct {
|
||||
ID string `json:"id"`
|
||||
Title string `json:"title"`
|
||||
Content string `json:"content"`
|
||||
Source string `json:"source"`
|
||||
// 1.1.0：媒体字段。与公共 SDK 保持同构，否则插件在 yaegi 下跑得通、
|
||||
// 编成 plugin.bin 却编不过（或反之）。
|
||||
MediaDigests []string `json:"media_digests,omitempty"`
|
||||
Attachments []MediaAttachment `json:"attachments,omitempty"`
|
||||
}
|
||||
|
||||
// MediaAttachment 与公共 SDK 同构：写入时给 Data+MIME，引用已有内容时只给 Digest。
|
||||
type MediaAttachment struct {
|
||||
Digest string `json:"digest,omitempty"`
|
||||
MIME string `json:"mime,omitempty"`
|
||||
Data []byte `json:"data,omitempty"`
|
||||
Name string `json:"name,omitempty"`
|
||||
Description string `json:"description,omitempty"`
|
||||
}
|
||||
|
||||
type DocMemoryAPI interface {
|
||||
Query(text string, topK int) []*Doc
|
||||
Insert(doc *Doc) error
|
||||
InsertWithMedia(doc *Doc, attachments []MediaAttachment) error
|
||||
Remove(id string)
|
||||
Stats() map[string]interface{}
|
||||
}
|
||||
|
||||
type mockDocMemory struct{}
|
||||
|
||||
func (mockDocMemory) Query(t string, k int) []*Doc { return nil }
|
||||
func (mockDocMemory) Insert(doc *Doc) error { return nil }
|
||||
func (mockDocMemory) Remove(id string) {}
|
||||
func (mockDocMemory) Stats() map[string]interface{} { return nil }
|
||||
func (mockDocMemory) Query(t string, k int) []*Doc { return nil }
|
||||
func (mockDocMemory) Insert(doc *Doc) error { return nil }
|
||||
func (mockDocMemory) InsertWithMedia(doc *Doc, atts []MediaAttachment) error {
|
||||
logf("doc_insert_with_media: %d 份附件", len(atts))
|
||||
return nil
|
||||
}
|
||||
func (mockDocMemory) Remove(id string) {}
|
||||
func (mockDocMemory) Stats() map[string]interface{} { return nil }
|
||||
|
||||
type TextEvent struct {
|
||||
Timestamp int64 `json:"timestamp"`
|
||||
Role string `json:"role"`
|
||||
Content string `json:"content"`
|
||||
Source string `json:"source"`
|
||||
// 1.1.0：附件。读回时内核从正文标记反解，写入时内核把标记并进正文。
|
||||
Attachments []MediaAttachment `json:"attachments,omitempty"`
|
||||
}
|
||||
|
||||
type TextMemoryAPI interface {
|
||||
@ -305,8 +391,8 @@ type LLMAPI interface {
|
||||
type mockLLM struct{}
|
||||
|
||||
func (mockLLM) ListSources() []string { return nil }
|
||||
func (mockLLM) SetSource(n string) error { return nil }
|
||||
func (mockLLM) CurrentSource() string { return "" }
|
||||
func (mockLLM) SetSource(n string) error { return nil }
|
||||
func (mockLLM) CurrentSource() string { return "" }
|
||||
|
||||
type IOInjectorImpl struct{}
|
||||
|
||||
@ -319,27 +405,68 @@ func (IOInjectorImpl) InjectText(source, channel, text string) {
|
||||
func (IOInjectorImpl) InjectTextNoMemory(source, channel, text string) {
|
||||
logf("inject_text_no_memory: source=%s channel=%s", source, channel)
|
||||
}
|
||||
func (IOInjectorImpl) InjectInputMedia(source, channel, text string, blocks []ContentBlock) {
|
||||
logf("inject_input_media: source=%s channel=%s blocks=%d", source, channel, len(blocks))
|
||||
}
|
||||
func (IOInjectorImpl) InjectInputMediaSync(source, channel, text string, blocks []ContentBlock) string {
|
||||
logf("inject_input_media_sync: source=%s channel=%s blocks=%d", source, channel, len(blocks))
|
||||
return ""
|
||||
}
|
||||
func (IOInjectorImpl) InjectInterruptMedia(source, channel, text string, blocks []ContentBlock) {
|
||||
logf("inject_interrupt_media: source=%s channel=%s blocks=%d", source, channel, len(blocks))
|
||||
}
|
||||
func (IOInjectorImpl) SetToolBlocks(blocks []ContentBlock) {
|
||||
logf("set_tool_blocks: blocks=%d", len(blocks))
|
||||
}
|
||||
|
||||
// ---- 带 InjectOptions 的注入 ----
|
||||
|
||||
func (IOInjectorImpl) InjectInputSync(source, channel, text string) string {
|
||||
logf("inject_sync: source=%s channel=%s", source, channel)
|
||||
return ""
|
||||
}
|
||||
|
||||
func (IOInjectorImpl) InjectTextOpts(source, channel, text string, opts InjectOptions) {
|
||||
logf("inject_text_opts: source=%s channel=%s no_memory=%v policy=%s", source, channel, opts.NoMemory, opts.ContextPolicy)
|
||||
}
|
||||
func (IOInjectorImpl) InjectInterruptTextOpts(source, channel, text string, opts InjectOptions) {
|
||||
logf("inject_interrupt_opts: source=%s channel=%s no_memory=%v policy=%s", source, channel, opts.NoMemory, opts.ContextPolicy)
|
||||
}
|
||||
func (IOInjectorImpl) InjectInputSyncOpts(source, channel, text string, opts InjectOptions) string {
|
||||
logf("inject_sync_opts: source=%s channel=%s no_memory=%v policy=%s", source, channel, opts.NoMemory, opts.ContextPolicy)
|
||||
return ""
|
||||
}
|
||||
func (IOInjectorImpl) InjectInputMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) {
|
||||
logf("inject_input_media_opts: source=%s channel=%s blocks=%d no_memory=%v policy=%s", source, channel, len(blocks), opts.NoMemory, opts.ContextPolicy)
|
||||
}
|
||||
func (IOInjectorImpl) InjectInputMediaSyncOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) string {
|
||||
logf("inject_input_media_sync_opts: source=%s channel=%s blocks=%d no_memory=%v policy=%s", source, channel, len(blocks), opts.NoMemory, opts.ContextPolicy)
|
||||
return ""
|
||||
}
|
||||
func (IOInjectorImpl) InjectInterruptMediaOpts(source, channel, text string, blocks []ContentBlock, opts InjectOptions) {
|
||||
logf("inject_interrupt_media_opts: source=%s channel=%s blocks=%d no_memory=%v policy=%s", source, channel, len(blocks), opts.NoMemory, opts.ContextPolicy)
|
||||
}
|
||||
|
||||
type PluginSDK struct {
|
||||
Name string
|
||||
mu sync.RWMutex
|
||||
toolDefs map[string]ToolDef
|
||||
toolHandlers map[string]ToolHandler
|
||||
Name string
|
||||
mu sync.RWMutex
|
||||
toolDefs map[string]ToolDef
|
||||
toolHandlers map[string]ToolHandler
|
||||
stageHandlers map[string]StageHandler
|
||||
outChannels map[string]ToolHandler
|
||||
Settings SettingsAPI
|
||||
IO IOInjector
|
||||
outChannels map[string]ToolHandler
|
||||
Settings SettingsAPI
|
||||
IO IOInjector
|
||||
}
|
||||
|
||||
func New(name string) *PluginSDK {
|
||||
return &PluginSDK{
|
||||
Name: name,
|
||||
toolDefs: make(map[string]ToolDef),
|
||||
toolHandlers: make(map[string]ToolHandler),
|
||||
Name: name,
|
||||
toolDefs: make(map[string]ToolDef),
|
||||
toolHandlers: make(map[string]ToolHandler),
|
||||
stageHandlers: make(map[string]StageHandler),
|
||||
outChannels: make(map[string]ToolHandler),
|
||||
Settings: &mockSettings{data: map[string]interface{}{}},
|
||||
IO: IOInjectorImpl{},
|
||||
outChannels: make(map[string]ToolHandler),
|
||||
Settings: &mockSettings{data: map[string]interface{}{}},
|
||||
IO: IOInjectorImpl{},
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user