mirror of
https://gitcode.com/JianFeeeee/homeagent-sdk.git
synced 2026-09-21 09:28:04 +00:00
Compare commits
1 Commits
main
...
release/v1
| Author | SHA1 | Date | |
|---|---|---|---|
| 219b11a1f9 |
661
LICENSE
661
LICENSE
@ -1,661 +0,0 @@
|
||||
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/>.
|
||||
263
README.md
263
README.md
@ -2,108 +2,6 @@
|
||||
|
||||
HomeAgent 插件开发 SDK，用于构建与 HomeAgent 平台交互的智能插件。
|
||||
|
||||
## 版本与兼容性
|
||||
|
||||
当前：**SDK 1.3.0**（需内核 **1.3.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.1 / … / 1.2.N | **1.2.0** |
|
||||
| 1.3.0 起 | **1.3.0** |
|
||||
|
||||
内核的 patch 位专用于 bugfix 与漏洞修复，不碰公开接口，所以 SDK 版本号不跟着动——
|
||||
否则你要么被迫跟版、要么怀疑自己版本过时，而接口其实一个字都没变。
|
||||
|
||||
因此 **SDK 仓在一个中版本里只发一次**（`vX.Y.0`），核心的 `v1.3.1`/`v1.3.2`/… 不伴随 SDK 发版。
|
||||
（2026-09-13 曾误发过 `v1.3.1`，已撤回 —— patch 位带非零数字的 SDK tag 都是错误的。）
|
||||
|
||||
**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.3.0 新增：注入优先级与动态输出通道
|
||||
|
||||
### 注入优先级（`InjectOptions.Priority`）
|
||||
|
||||
插件可以声明**自己这次注入的中断级别**，内核按四级阶梯调度：
|
||||
|
||||
| 级别 | 常量 | 谁用 |
|
||||
|---|---|---|
|
||||
| L1–L3 | `PriorityL1` / `PriorityL2` / `PriorityL3` | 插件按紧急程度自选（L1 最低） |
|
||||
| L4 | `PriorityL4` | **保留给内核与内核级插件**（内核自身事件、内核级通道） |
|
||||
|
||||
- 零值（不声明）与旧的注入调用**完全等价**：按排队处理，不抢占任何正在执行的回合
|
||||
⇒ 存量插件不需要改一行、也不需要重编。
|
||||
- 高优先级中断可以**抢占**低优先级正在跑的回合；被抢占的回合挂起、之后恢复继续
|
||||
（现场保存/恢复对插件透明）。
|
||||
- 排队输入**没有级别**：排队就是排队，任何中断都能插到它前面。
|
||||
|
||||
### 动态输出通道（`UnregisterOutputChannel`）
|
||||
|
||||
`RegisterOutputChannel` 注册的通道此前只增不减。对**随资源生灭**的通道（典型：远程设备
|
||||
一台设备一个输出通道），设备掉线后通道还在，模型会继续对一个死通道发消息并以为发成功了。
|
||||
|
||||
1.3.0 起成对提供：
|
||||
|
||||
| API | 用途 |
|
||||
|---|---|
|
||||
| `UnregisterOutputChannel(name)` | 注销输出通道（含能力表与工具） |
|
||||
| `OutputChannelUnregistrar` / `SetOutputChannelUnregistrar` | 插件侧拿到注销句柄（内核注入） |
|
||||
|
||||
⚠️ 通道名要**由插件派生得又合法又唯一**（外部 id 不能直接当通道名）——
|
||||
设备 id 这类外部输入可能带 `/` 等字符，而通道名会拼进 LLM 函数名 `output_send__<name>`，
|
||||
违规会让**整条 LLM 请求**被上游拒绝（2026-09-13 生产事故：`device/<id>` 导致全量对话 403）。
|
||||
派生规则与约束见下方「输出通道」一节。
|
||||
|
||||
## 注入行为与上下文裁剪（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 接口
|
||||
@ -122,15 +20,11 @@ type Plugin interface {
|
||||
|
||||
通过 `Start(sdk *PluginSDK)` 注入的 SDK 实例提供以下方法：
|
||||
|
||||
> **通道的方向契约**：入站与出站是分开登记的两件事。凡是用 `InjectText*/InjectInput*/InjectInterrupt*`
|
||||
> 注入的通道名都要 `RegisterInputChannel` —— inputch 是内核最基本的**输入路由单位**，
|
||||
> 只有登记过的通道才能被"划给驻留子"；只登记出站通道时内核会兜底登记同名 inputch 并告警（兼容老插件）。
|
||||
|
||||
| 分类 | 方法 | 说明 |
|
||||
|------|------|------|
|
||||
| 阶段钩子 | `RegisterStage(stage, handler, scope...)` | 注册阶段回调，scope 可选：`StageScopeGlobal`（全局，默认）或 `StageScopeOwnTools`（仅自己工具） |
|
||||
| 输入通道 | `RegisterInputChannel(name, def)` | 注册输入通道（**入站**：谁会往这个通道注入输入），def 为 `ChannelDef`（NoMemory/Cleaner） |
|
||||
| 输出通道 | `RegisterOutputChannel(name, caps, desc, def, handler)` | 注册输出通道（**出站**：`output_send__<name>` 的回复发给谁），def 为 `ChannelDef`，caps 为能力位掩码。⚠️ 通道名只能用 `[A-Za-z0-9_-]`（见下方"输出通道"一节的命名约束） |
|
||||
| 输入通道 | `RegisterInputChannel(name, def)` | 注册输入通道，def 为 `ChannelDef`（NoMemory/Cleaner） |
|
||||
| 输出通道 | `RegisterOutputChannel(name, caps, desc, def, handler)` | 注册输出通道，def 为 `ChannelDef`，caps 为能力位掩码 |
|
||||
| 工具注册 | `RegisterTool(name, def, handler)` | 注册工具供 LLM 调用 |
|
||||
| 插件 API | `RegisterPluginAPI(name)` | 注册插件 API 供其他插件访问 |
|
||||
| 图记忆 | `Memory()` | 访问图记忆 API（实体-关系存储） |
|
||||
@ -177,14 +71,6 @@ sdk.RegisterInputChannel("qq", ChannelDef{
|
||||
|
||||
### 输出通道
|
||||
|
||||
> ⚠️ **命名约束（会进 LLM 函数名）**：内核按 `output_send__<name>` 生成工具，
|
||||
> 而上游对函数名的规范是 `^[a-zA-Z0-9_-]{1,64}$`。名字违规的后果不是
|
||||
> "这个工具不可用"，而是**整条请求被 400 拒绝**（`Invalid 'tools[N].function.name'`），
|
||||
> 网关 auto tier 全链条失败，表现成**整个 agent 不回应**。
|
||||
> 所以 `name` 只能用 `[A-Za-z0-9_-]`，并留出 `output_send__`（13 字符）的余量。
|
||||
> 名字若来自外部输入（设备自报 id 之类），请在插件侧派生一个合规且唯一的名字 ——
|
||||
> 内核**不会**替你净化。
|
||||
|
||||
```go
|
||||
sdk.RegisterOutputChannel("my-channel", CapText|CapFile, "通道描述", ChannelDef{}, handler)
|
||||
```
|
||||
@ -334,23 +220,18 @@ func New(name string, sett SettingsAPI, regTool ToolRegistrar, regStage StageReg
|
||||
|
||||
插件开发者只需实现 `Plugin` 接口并导出 `NewPluginFactory()` 入口函数。
|
||||
|
||||
## hmapdev 工具链
|
||||
## plugindev 工具链
|
||||
|
||||
`hmapdev` 提供插件开发全流程支持，最终产出 `.hmap` 插件包（工具名即来自该包格式）。
|
||||
预编译二进制作为 **release 附件**分发（linux/darwin/windows × amd64/arm64），从
|
||||
`plugindev` 提供插件开发全流程支持。预编译二进制作为 **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 附件下载（以最新 SDK 发布 / linux amd64 为例）
|
||||
curl -Lo hmapdev https://gitcode.com/JianFeeeee/homeagent-sdk/releases/download/<版本>/hmapdev_linux_amd64
|
||||
chmod +x hmapdev
|
||||
# 从 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
|
||||
|
||||
# 或从源码自己编
|
||||
cd tools/hmapdev && go build -o hmapdev .
|
||||
cd tools/plugindev && go build -o plugindev .
|
||||
```
|
||||
|
||||
> 二进制不再随仓库分发（旧的 `bin/` 目录已停用）：5 个平台各 26-28MB，
|
||||
@ -358,11 +239,11 @@ cd tools/hmapdev && go build -o hmapdev .
|
||||
|
||||
| 命令 | 说明 |
|
||||
|------|------|
|
||||
| `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） |
|
||||
| `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） |
|
||||
|
||||
支持 **Go** 和 **Lua** 两种插件语言。
|
||||
|
||||
@ -469,7 +350,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`（删缓存目录）；`hmapdev` 模板含 onRemove 演示。
|
||||
- 示例：`example/calendar`（删 events.json）、`example/memo`（删 memos.json）、`example/rss`（删订阅数据目录）、`example/weather`（删缓存目录）；`plugindev` 模板含 onRemove 演示。
|
||||
|
||||
```go
|
||||
sdk.RegisterOnRemoveHandler(func() {
|
||||
@ -487,43 +368,6 @@ enabled := sdk.AutoRestart()
|
||||
|
||||
插件崩溃时平台自动拉起，保障服务可用性。
|
||||
|
||||
重启是**有节制的**，默认参数（内核 `internal/plugin/registry.go`）：
|
||||
|
||||
| 参数 | 值 | 含义 |
|
||||
|---|---|---|
|
||||
| `procRestartBackoff` | `1s` | 第 n 次重启前等 `n × 1s`（线性退避，非立即拉起） |
|
||||
| `procMaxRestarts` | `3` | 窗口内允许的重启次数上限 |
|
||||
| `procCrashWindow` | `5min` | 窗口内无新崩溃则计数归零 |
|
||||
|
||||
即崩溃后的实际序列是 **1s → 2s → 3s**；同一 5 分钟窗口内第 **4** 次崩溃
|
||||
（`n > 3`）**不再自动拉起**，交人工介入。这不是「立即无感恢复」——
|
||||
如果插件需要秒级就位，请自己在 `OnStart` 里做好重连与重建。
|
||||
|
||||
> ⚠️ `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**，仅暴露安全子集：
|
||||
@ -535,57 +379,6 @@ ctx.Unlock()
|
||||
|
||||
内部插件（平台内置）拥有完整 SDK 访问权限，包括 SocialAPI 写操作和 EventPublisher。
|
||||
|
||||
## 项目声明 SDK 版本（plg.json 的 `sdk` 字段）
|
||||
|
||||
`hmapdev init` 生成的工程里，`plg.json` 会带一个 `sdk` 字段：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "MyPlugin",
|
||||
"version": "0.1.0",
|
||||
"entry": "plugin.bin",
|
||||
"sdk": "1.2.0"
|
||||
}
|
||||
```
|
||||
|
||||
它的语义是**本插件针对的 SDK 版本**，工具链据此在本地 SDK 存储里选择版本：
|
||||
命中就用它，并把 `go.mod` 的 `require`/`replace` 同步到该版本；未命中则**明确报错**
|
||||
（列出已装版本 + `hmapdev sdk install vX.Y.Z`），**绝不静默退化成 `current`**。
|
||||
|
||||
```bash
|
||||
$ hmapdev build
|
||||
[hmapdev] SDK 1.2.0（项目声明 sdk=1.2.0）
|
||||
```
|
||||
|
||||
为什么要这个字段：以前项目里没有任何「我要哪版 SDK」的声明，工具链只能用存储里的
|
||||
`current`——谁改过 `current` 就拿谁的版本编，出错时表现为一堆看不懂的编译错误
|
||||
（例如存储里只有陈旧的 `v0.8.0` 时，模板项目首次构建会报 `undefined: sdk.InjectOptions`）。
|
||||
|
||||
**写法必须是完整版本号（`1.2.0`），不接受区间写法（`1.2`）。** 原因见上文的版本纪律：
|
||||
SDK 版本跟随内核中版本、patch 位恒为 `.0`，一条内核线只对应一个 SDK 版本；
|
||||
写区间会让人误以为同一条线里还能挑不同 SDK（工具链会直接拒绝并说明这条规矩）。
|
||||
|
||||
- 显式 `--sdk-path` 或 `plg.json` 的 `sdk_path` 优先（本机改 SDK 联调时用）；
|
||||
- 存量工程（`plg.json` 没有 `sdk` 字段）行为不变，仍按 `current` 构建；
|
||||
- 产物 `.hmap` 里的 `plugin.json` 会记录**实际选中的 SDK 版本**，便于事后追溯。
|
||||
|
||||
## IDE 支持：VSCode 扩展（`tools/vscode-hmapdev`）
|
||||
|
||||
调试插件的实操回路是「构建 → 运行 → 看内核日志」，这三步都在 IDE 之外很别扭，
|
||||
所以仓库里带了一个 VSCode 扩展（[tools/vscode-hmapdev](tools/vscode-hmapdev)）：
|
||||
|
||||
- **plg.json 诊断**：必需字段、`sdk` 是否是完整版本号、声明的 SDK 是否已安装（直接给安装命令）；
|
||||
- **状态栏**：`插件 · SDK <声明> · hmapdev <版本>`，工具链缺失或工程有错时变色；
|
||||
- **命令 / 任务**：build / build（全部目标）/ clean / debug（解释执行），编译错误进 Problems；
|
||||
- **跟随内核日志**：读 `<dataDir>/log` 下最新的 `homed_*.log` 并按插件名过滤。
|
||||
|
||||
```bash
|
||||
cd tools/vscode-hmapdev && npm install && npm run compile # 然后在 VSCode 里按 F5
|
||||
```
|
||||
|
||||
它不是源码级调试器（没有断点/单步）：插件要么编译成产物在内核里跑、要么用
|
||||
`hmapdev debug` 解释执行，两条路都没有 DAP 会话；扩展做的是构建、运行、看日志与清单校验。
|
||||
|
||||
## 示例插件
|
||||
|
||||
| 插件 | 类型 | 说明 |
|
||||
@ -606,11 +399,6 @@ cd tools/vscode-hmapdev && npm install && npm run compile # 然后在 VSCode
|
||||
| [rss](example/rss) | Go | RSS 订阅 |
|
||||
| [sanitizer](example/sanitizer) | Go | 内容清洗/安全过滤 |
|
||||
|
||||
**发版时附带预编译示例产物**：SDK 的 release 除 5 平台 `hmapdev` 外，还包含各示例插件的
|
||||
`.hmap` 与 `SHA256SUMS`/`MANIFEST.txt`。原因是插件二进制与内核**协议绑定**（`ProtocolVersion`
|
||||
+ 共享内存区魔数），只发工具链不发示例产物，很容易拿旧产物去装而握手失败——那看起来像
|
||||
「插件坏了」而不是「版本不配套」。
|
||||
|
||||
## Remote Device SDK
|
||||
|
||||
用于开发**远程设备接入适配器**的 C 语言 SDK，零外部依赖，兼容嵌入式平台。
|
||||
@ -712,10 +500,10 @@ ha_transport_t my_transport = {
|
||||
|
||||
### 使用方式
|
||||
|
||||
通过 `hmapdev` 工具链初始化项目：
|
||||
通过 `plugindev` 工具链初始化项目：
|
||||
|
||||
```bash
|
||||
hmapdev init my-adapter --type remotedevice
|
||||
plugindev init my-adapter --type remotedevice
|
||||
```
|
||||
|
||||
生成 `main.c` + `CMakeLists.txt`，可直接编译或作为三方库引入：
|
||||
@ -927,17 +715,17 @@ curl -X POST http://<homeagent-server>:8080/api/v1/device/esp32-cam-1/cmd \
|
||||
### 位置
|
||||
|
||||
- **SDK 源码**: `remotedevice/`
|
||||
- **hmapdev 模板**: `hmapdev init --type remotedevice`
|
||||
- **plugindev 模板**: `plugindev init --type remotedevice`
|
||||
|
||||
## 构建与安装
|
||||
|
||||
### 构建
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
plugindev build
|
||||
```
|
||||
|
||||
输出 `.hmap` 包到 `dist/` 目录（默认 bundle 多平台合集；单平台构建使用 `hmapdev build --no-bundle`）。
|
||||
输出 `.hmap` 包到 `dist/` 目录（默认 bundle 多平台合集；单平台构建使用 `plugindev build --no-bundle`）。
|
||||
|
||||
### 安装
|
||||
|
||||
@ -955,16 +743,3 @@ 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/`。
|
||||
|
||||
199
README_EN.md
199
README_EN.md
@ -2,103 +2,6 @@
|
||||
|
||||
Plugin development SDK for building intelligent plugins that interact with the HomeAgent platform.
|
||||
|
||||
## Version and Compatibility
|
||||
|
||||
Current: **SDK 1.3.0** (requires kernel **1.3.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 / 1.2.1 / … / 1.2.N | **1.2.0** |
|
||||
| 1.3.0 onward | **1.3.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.
|
||||
|
||||
The SDK repository therefore publishes **exactly once per minor version** (`vX.Y.0`); kernel patches
|
||||
such as `v1.3.1` do not trigger an SDK release. (A `v1.3.1` tag was mistakenly cut on 2026-09-13 and
|
||||
has been withdrawn — any SDK tag with a non-zero patch position is wrong.)
|
||||
|
||||
## New in 1.3.0: Injection Priority and Dynamic Output Channels
|
||||
|
||||
- **`InjectOptions.Priority` / `PriorityL1`–`PriorityL4`** — a plugin declares the interrupt level of
|
||||
its own injection; the kernel schedules L1–L4, where **L4 is reserved for the kernel and
|
||||
kernel-level plugins**. The zero value is fully equivalent to the old three-argument call
|
||||
(queued, never preempting), so existing plugins need neither a code change nor a rebuild.
|
||||
Queued input has no level: anything can jump ahead of it.
|
||||
- **`UnregisterOutputChannel` / `OutputChannelUnregistrar` / `SetOutputChannelUnregistrar`** —
|
||||
channels that die with their resource (one channel per remote device) can now be unregistered;
|
||||
previously they lingered and the model kept "successfully" sending into a dead channel.
|
||||
- **Channel names must be legal and unique.** The name is spliced into the LLM function name
|
||||
`output_send__<name>`, so it may only contain `[A-Za-z0-9_-]`. A real production incident
|
||||
(2026-09-13): `device/<id>` made every LLM request fail with 403. Derive channel names from
|
||||
external IDs — never use the raw ID.
|
||||
|
||||
**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
|
||||
@ -323,24 +226,19 @@ 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.
|
||||
|
||||
## hmapdev Toolchain
|
||||
## plugindev Toolchain
|
||||
|
||||
`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**
|
||||
`plugindev` provides full development workflow support. 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 (latest SDK release / linux amd64 shown)
|
||||
curl -Lo hmapdev https://gitcode.com/JianFeeeee/homeagent-sdk/releases/download/<version>/hmapdev_linux_amd64
|
||||
chmod +x hmapdev
|
||||
# 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
|
||||
|
||||
# Or build from source
|
||||
cd tools/hmapdev && go build -o hmapdev .
|
||||
cd tools/plugindev && go build -o plugindev .
|
||||
```
|
||||
|
||||
> Binaries no longer ship inside the repository (the old `bin/` directory is retired): five
|
||||
@ -349,11 +247,11 @@ cd tools/hmapdev && go build -o hmapdev .
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `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) |
|
||||
| `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) |
|
||||
|
||||
Supports both **Go** and **Lua** plugin languages.
|
||||
|
||||
@ -425,7 +323,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 `hmapdev` 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 `plugindev` template includes an onRemove demo.
|
||||
|
||||
```go
|
||||
sdk.RegisterOnRemoveHandler(func() {
|
||||
@ -443,46 +341,6 @@ enabled := sdk.AutoRestart()
|
||||
|
||||
The platform automatically restarts the plugin on crash, ensuring service availability.
|
||||
|
||||
Restarts are **rate-limited**. Defaults (kernel `internal/plugin/registry.go`):
|
||||
|
||||
| Parameter | Value | Meaning |
|
||||
|---|---|---|
|
||||
| `procRestartBackoff` | `1s` | Before restart #n, wait `n × 1s` (linear backoff, not immediate) |
|
||||
| `procMaxRestarts` | `3` | Max restarts within the window |
|
||||
| `procCrashWindow` | `5min` | No new crash within the window resets the count |
|
||||
|
||||
So the actual sequence is **1s → 2s → 3s**; the **4th** crash in the same 5-minute
|
||||
window (`n > 3`) is **not** restarted automatically and needs manual intervention.
|
||||
This is not instant, invisible recovery — if your plugin must be back in seconds,
|
||||
reconnect and rebuild your own state in `OnStart`.
|
||||
|
||||
> ⚠️ `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:
|
||||
@ -514,13 +372,6 @@ 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.
|
||||
@ -605,10 +456,10 @@ ha_transport_t my_transport = {
|
||||
|
||||
### Usage
|
||||
|
||||
Initialize a project via the `hmapdev` toolchain:
|
||||
Initialize a project via the `plugindev` toolchain:
|
||||
|
||||
```bash
|
||||
hmapdev init my-adapter --type remotedevice
|
||||
plugindev init my-adapter --type remotedevice
|
||||
```
|
||||
|
||||
Generates `main.c` + `CMakeLists.txt`, can be built directly or used as a third-party library:
|
||||
@ -818,17 +669,17 @@ curl -X POST http://<homeagent-server>:8080/api/v1/device/esp32-cam-1/cmd \
|
||||
### Location
|
||||
|
||||
- **SDK Source**: `remotedevice/`
|
||||
- **hmapdev template**: `hmapdev init --type remotedevice`
|
||||
- **plugindev template**: `plugindev init --type remotedevice`
|
||||
|
||||
## Building & Installing
|
||||
|
||||
### Build
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
plugindev 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).
|
||||
Outputs a `.hmap` package to the `dist/` directory (default is the multi-platform bundle; use `plugindev build --no-bundle` for a single-target build).
|
||||
|
||||
### Install
|
||||
|
||||
@ -846,19 +697,3 @@ 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/`.
|
||||
|
||||
@ -1,47 +0,0 @@
|
||||
# a2a · Agent-to-Agent 通信
|
||||
|
||||
让本 Agent 与其他 Agent **双向互调**：既能对外暴露自己的能力，也能去问别的 Agent。
|
||||
|
||||
## 两个方向
|
||||
|
||||
| 方向 | 怎么实现 |
|
||||
|---|---|
|
||||
| **入站**（别人问我） | 插件起一个 HTTP 服务端，暴露 `/agent-card`（能力描述）与 `/a2a`（JSON-RPC 入口） |
|
||||
| **出站**（我问别人） | 提供 `a2a_query` / `a2a_discover` 工具，主动向远端 A2A Agent 发起请求 |
|
||||
|
||||
## HTTP 端点
|
||||
|
||||
| 路径 | 作用 |
|
||||
|---|---|
|
||||
| `GET /agent-card` | 返回 Agent Card：本 Agent 的能力描述，供对方发现 |
|
||||
| `POST /a2a` | JSON-RPC 2.0 入口，接收对方的任务请求 |
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `a2a_a2a_query` | 向另一个 A2A Agent 发查询并取回复 |
|
||||
| `a2a_a2a_discover` | 取对方的 Agent Card（能力描述） |
|
||||
| `a2a_a2a_status` | 看本插件运行状态（监听地址、当前配置） |
|
||||
| `a2a_a2a_configure` | 改配置并自动重启服务（可动态改监听地址） |
|
||||
| `a2a_a2a_restart` | 重启 HTTP 服务端（连接异常或改配置后用） |
|
||||
|
||||
> 工具名前缀取自插件名（`tp`），按默认 `a2a_` 列出。
|
||||
|
||||
## 配置项
|
||||
|
||||
| 键 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `listen` | `127.0.0.1:12000` | 服务端监听地址。**设为空可禁用 HTTP 服务**（只出站、不入站） |
|
||||
|
||||
## 典型用法
|
||||
|
||||
1. **先发现再调用**：`a2a_discover` 拿对方能力 → 决定要不要发、发什么 → `a2a_query`。
|
||||
跳过 discovery 直接问，容易问出对方不支持的东西。
|
||||
2. **只出站**：把 `listen` 设为空，本 Agent 不外露端口，但仍能主动联系别人。
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
```
|
||||
@ -2,7 +2,7 @@
|
||||
"name": "a2a",
|
||||
"name_zh": "A2A 代理通信",
|
||||
"name_en": "A2A Agent Communication",
|
||||
"version": "1.3.1",
|
||||
"version": "1.3.0",
|
||||
"description": "Agent-to-Agent 协议通信插件，支持双向 A2A 通信：可查询其他 Agent 并回复其请求。提供 HTTP 服务端暴露本 Agent 能力。",
|
||||
"author": "HomeAgent",
|
||||
"entry": "plugin.so",
|
||||
|
||||
@ -24,8 +24,8 @@ type Plugin struct {
|
||||
|
||||
// 会话表：session_id → 上下文前缀。A2A 无状态协议下由插件侧维护
|
||||
// 多轮上下文：同 session 的后续请求会把之前的对话拼进注入文本。
|
||||
sessMu sync.Mutex
|
||||
sessions map[string]*a2aSession
|
||||
sessMu sync.Mutex
|
||||
sessions map[string]*a2aSession
|
||||
}
|
||||
|
||||
// a2aSession 记录一个会话的轮次历史，用于延续上下文。
|
||||
@ -47,9 +47,6 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
s.SetAutoRestart(true)
|
||||
p.sdk = s
|
||||
p.sessions = make(map[string]*a2aSession)
|
||||
// 入站通道：本插件用 p.name 通道注入输入（见 InjectInputSync 调用），
|
||||
// 输入侧必须显式登记 —— 否则"把该 inputch 划给驻留子"会报 `inputch 未注册`。
|
||||
_ = s.RegisterInputChannel(p.name, sdk.ChannelDef{})
|
||||
tp := p.name + "_"
|
||||
|
||||
// 注册自身为输出通道：agent 回复 emit 到本通道时有落点，
|
||||
@ -69,7 +66,7 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
Key: "listen", Default: "127.0.0.1:12000",
|
||||
Type: "string", DisplayName: "监听地址",
|
||||
Description: "A2A 服务端监听地址，设为空可禁用 HTTP 服务",
|
||||
Category: p.name,
|
||||
Category: p.name,
|
||||
})
|
||||
|
||||
// Outbound: query + discover
|
||||
@ -78,10 +75,10 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
Parameters: map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"agent_url": map[string]interface{}{"type": "string", "description": "目标 Agent 的 A2A 端点 URL"},
|
||||
"query": map[string]interface{}{"type": "string", "description": "发送给目标 Agent 的文本查询"},
|
||||
"agent_url": map[string]interface{}{"type": "string", "description": "目标 Agent 的 A2A 端点 URL"},
|
||||
"query": map[string]interface{}{"type": "string", "description": "发送给目标 Agent 的文本查询"},
|
||||
"session_id": map[string]interface{}{"type": "string", "description": "可选。上次调用返回的 session_id，传入可延续与该 agent 的多轮对话上下文"},
|
||||
"timeout": map[string]interface{}{"type": "integer", "description": "超时时间（秒），默认 60"},
|
||||
"timeout": map[string]interface{}{"type": "integer", "description": "超时时间（秒），默认 60"},
|
||||
},
|
||||
"required": []string{"agent_url", "query"},
|
||||
},
|
||||
@ -290,7 +287,7 @@ func (p *Plugin) handleIncomingA2A(w http.ResponseWriter, r *http.Request) {
|
||||
Query string `json:"query,omitempty"`
|
||||
SessionID string `json:"session_id,omitempty"`
|
||||
Limit int `json:"limit,omitempty"`
|
||||
Message *struct {
|
||||
Message *struct {
|
||||
Role string `json:"role"`
|
||||
Parts []struct {
|
||||
Text string `json:"text,omitempty"`
|
||||
@ -350,7 +347,7 @@ func (p *Plugin) handleIncomingA2A(w http.ResponseWriter, r *http.Request) {
|
||||
if sess := p.sessions[sessionID]; sess != nil {
|
||||
sess.History = append(sess.History, "用户: "+queryText, "助手: "+reply)
|
||||
if len(sess.History) > maxSessionTurns*2 {
|
||||
sess.History = sess.History[len(sess.History)-maxSessionTurns*2:]
|
||||
sess.History = sess.History[len(sess.History)-maxSessionTurns*2 :]
|
||||
}
|
||||
sess.LastUsed = time.Now()
|
||||
}
|
||||
@ -360,11 +357,11 @@ func (p *Plugin) handleIncomingA2A(w http.ResponseWriter, r *http.Request) {
|
||||
"jsonrpc": "2.0",
|
||||
"id": req.ID,
|
||||
"result": map[string]interface{}{
|
||||
"id": fmt.Sprintf("task_%d", time.Now().UnixNano()),
|
||||
"status": "completed",
|
||||
"id": fmt.Sprintf("task_%d", time.Now().UnixNano()),
|
||||
"status": "completed",
|
||||
"session_id": sessionID,
|
||||
"message": map[string]interface{}{
|
||||
"role": "agent",
|
||||
"role": "agent",
|
||||
"parts": []map[string]string{{"type": "text", "text": reply}},
|
||||
},
|
||||
},
|
||||
@ -460,10 +457,10 @@ type A2AResponse struct {
|
||||
}
|
||||
|
||||
type A2AResult struct {
|
||||
TaskID string `json:"id,omitempty"`
|
||||
Status string `json:"status,omitempty"`
|
||||
SessionID string `json:"session_id,omitempty"`
|
||||
Message *A2AMessage `json:"message,omitempty"`
|
||||
TaskID string `json:"id,omitempty"`
|
||||
Status string `json:"status,omitempty"`
|
||||
SessionID string `json:"session_id,omitempty"`
|
||||
Message *A2AMessage `json:"message,omitempty"`
|
||||
AgentCard *A2AAgentCard `json:"agent_card,omitempty"`
|
||||
}
|
||||
|
||||
|
||||
@ -1,51 +0,0 @@
|
||||
# acp · Agent Client Protocol 通信
|
||||
|
||||
[ACP](https://agentclientprotocol.com/) 桥接：本 Agent 既能**当服务端**接别人的任务，也能**当客户端**去调别的 ACP Agent。
|
||||
|
||||
## 两个方向
|
||||
|
||||
| 角色 | 行为 |
|
||||
|---|---|
|
||||
| **服务端** | 在本机起 HTTP 服务，处理 `session/new` / `session/update`，接受其他 Agent 的任务请求 |
|
||||
| **客户端** | 通过 `acp_query` 向远程 ACP Agent 发 `session/new` 并读回复 |
|
||||
|
||||
## 协议端点
|
||||
|
||||
- `POST /api/session` —— JSON-RPC，支持 `session/new` 与 `session/update`
|
||||
- 客户端侧同时兼容**两种服务端**：SSE 型（流式 `session/reply`）与同步 JSON 型
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `acp_acp_query` | 向远程 ACP Agent 发起会话并等待回复，返回最终回答文本 |
|
||||
| `acp_acp_status` | 查看运行状态与**当前活跃会话数** |
|
||||
| `acp_acp_configure` | 改监听配置并重启 HTTP 服务 |
|
||||
|
||||
> 工具名前缀取自插件名（`tp`），按默认 `acp_` 列出。
|
||||
|
||||
`acp_query` 可指向的远端举例（源码注释给的）：
|
||||
|
||||
- opencode：`http://127.0.0.1:13000`
|
||||
- pi bridge：`http://127.0.0.1:12011`
|
||||
- 回环到自身：`http://127.0.0.1:12001`
|
||||
|
||||
## 配置项
|
||||
|
||||
| 键 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `listen` | `127.0.0.1:12001` | 服务端监听地址。**设为空可禁用 HTTP 服务**（只出站） |
|
||||
|
||||
## 与 a2a 的区别
|
||||
|
||||
| | a2a | acp |
|
||||
|---|---|---|
|
||||
| 面向 | Agent ↔ Agent 对等通信 | 客户端 → Agent 会话（每次一个 session） |
|
||||
| 会话 | 一问一答 | 有 session 生命周期，可续 |
|
||||
| 发现 | `/agent-card` | 无（需已知地址） |
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
```
|
||||
@ -2,7 +2,7 @@
|
||||
"name": "acp",
|
||||
"name_zh": "ACP 代理通信",
|
||||
"name_en": "ACP Agent Client Protocol",
|
||||
"version": "1.2.1",
|
||||
"version": "1.2.0",
|
||||
"description": "Agent Client Protocol 通信插件：充当 ACP 服务端接受其他 Agent 的任务请求，同时提供客户端工具向远程 ACP Agent（如 opencode）发起会话并读取回复",
|
||||
"author": "HomeAgent",
|
||||
"entry": "plugin.so",
|
||||
|
||||
@ -47,9 +47,6 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
s.SetAutoRestart(true)
|
||||
p.sdk = s
|
||||
p.sessions = make(map[string]*sessionState)
|
||||
// 入站通道：本插件用 p.name 通道注入输入（见 InjectInputSync 调用），
|
||||
// 输入侧必须显式登记 —— 否则"把该 inputch 划给驻留子"会报 `inputch 未注册`。
|
||||
_ = s.RegisterInputChannel(p.name, sdk.ChannelDef{})
|
||||
tp := p.name + "_"
|
||||
|
||||
// 注册自身为输出通道：agent 回复 emit 到本通道时有落点。
|
||||
|
||||
@ -1,34 +1,13 @@
|
||||
# ai_image · 文生图
|
||||
# ai_image
|
||||
|
||||
按文字提示生成图片，下载到本地并返回**文件路径**。
|
||||
ai_image plugin
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `ai_image_generate` | 按 prompt 生成图片 |
|
||||
|
||||
返回值是**本地文件路径**（永久，不过期）。要把图给用户看，再用导出的通道
|
||||
以 `type=image`、`payload=<该路径>` 发送。
|
||||
|
||||
## 配置项
|
||||
|
||||
| 键 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `api_key` | 空 | OpenAI / Stable Diffusion 的 API Key |
|
||||
| `base_url` | 空 | 自定义 OpenAI 兼容网关（**不带 `/v1` 尾缀**，如 `http://127.0.0.1:8081`）。留空走官方 `https://api.openai.com` |
|
||||
| `provider` | `openai` | 服务方：`openai` / `stability` |
|
||||
| `model` | `dall-e-3` | 模型名（如 `dall-e-3`、`sd-xl`） |
|
||||
| `size` | `1024x1024` | 默认尺寸，也可 `1024x1792` / `1792x1024` |
|
||||
|
||||
## 实现要点
|
||||
|
||||
- **返回本地路径而不是远端 URL**：远端图床链接会过期，写进记忆就成了悬空指针。
|
||||
下载到本地后路径稳定，可交给媒体存储做内容寻址。
|
||||
- 配了 `base_url` 就能指向自建/兼容网关，不必依赖官方接口。
|
||||
|
||||
## 构建
|
||||
## Build
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
plugindev build
|
||||
```
|
||||
|
||||
## Install
|
||||
|
||||
Upload the .hmap file through the Plugin Manager API.
|
||||
|
||||
@ -1,43 +0,0 @@
|
||||
# bili · B站视频下载
|
||||
|
||||
用 [yt-dlp](https://github.com/yt-dlp/yt-dlp) 把 B 站视频下载到本地。
|
||||
|
||||
## 前置依赖
|
||||
|
||||
需要系统里装有 `yt-dlp`：
|
||||
|
||||
```bash
|
||||
pip install -U yt-dlp # 或 apt install yt-dlp
|
||||
```
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `bili_video` | 下载 B 站视频；不指定 `format` 时先返回可用清晰度列表，指定后真正下载并返回文件路径 |
|
||||
|
||||
参数：
|
||||
|
||||
| 参数 | 说明 |
|
||||
|---|---|
|
||||
| `url` | 视频地址 |
|
||||
| `format` | 格式 ID。常用：`30112`/`30080`=1080P、`30064`=720P、`30032`=480P、`30016`=360P。不指定则自动选最优 |
|
||||
|
||||
## 配置项
|
||||
|
||||
| 键 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `output_dir` | `/tmp/bili_videos` | 下载目录 |
|
||||
| `proxy` | 空 | yt-dlp 使用的 HTTP 代理（如 `http://127.0.0.1:7890`）。留空则不设代理 |
|
||||
|
||||
## 实现要点
|
||||
|
||||
- **`output_dir` 有安全校验**：它是配置项，但会拒绝被配成系统目录，避免 yt-dlp 往任意位置写文件。
|
||||
- 两阶段用法：先不传 `format` 拿到清晰度清单（`format_id` + `format_note`），再带上选定的 ID 下载。这样模型不会盲选一个不存在的格式。
|
||||
- B 站在部分网络环境下需要代理，见上面的 `proxy`。
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
```
|
||||
@ -1,66 +0,0 @@
|
||||
# browser · 统一浏览器
|
||||
|
||||
一个插件覆盖三种"访问网页"的能力，从最轻到最重。**按需选层**是这个插件的重点 ——
|
||||
绝大多数抓取用 HTTP 就够，不该为了一句话启动 Chromium。
|
||||
|
||||
## 三种能力层
|
||||
|
||||
| 层 | 工具 | 何时用 |
|
||||
|---|---|---|
|
||||
| **搜索** | `browser_search` | 要的是"找到哪些页面"，不是页面本身 |
|
||||
| **quick（纯 HTTP）** | `browser_fetch`（`mode=quick`） | 静态页、API、能直接拿到 HTML |
|
||||
| **normal（无头渲染）** | `browser_render` / `browser_fetch`（`mode=render`） | JS 渲染的页面，HTTP 拿不到内容 |
|
||||
| **interactive（CDP）** | `browser_start` + `navigate`/`click`/`type`/`scroll`/`html`/`screenshot` | 需要交互：登录、点按、翻页 |
|
||||
|
||||
`browser_fetch` 的 `mode`：
|
||||
|
||||
- `auto`（默认）：先试 HTTP，**遇 403/429 才降级**用 Chromium 渲染
|
||||
- `render`：强制 Chromium
|
||||
- `quick`：纯 HTTP，不降级
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `browser_search` | 网页搜索 |
|
||||
| `browser_fetch` | 抓取 URL 内容，三种 mode 见上 |
|
||||
| `browser_render` | 无头 Chromium 渲染并提取文本（normal） |
|
||||
| `browser_start` | 启动交互式浏览器会话（CDP） |
|
||||
| `browser_navigate` | 导航到指定 URL |
|
||||
| `browser_click` | 点击元素 |
|
||||
| `browser_type` | 输入文本 |
|
||||
| `browser_scroll` | 滚动页面 |
|
||||
| `browser_html` | 取当前页 HTML |
|
||||
| `browser_screenshot` | 截图 |
|
||||
| `browser_install` | 安装 systemd 托管的共享浏览器后端 |
|
||||
| `browser_close` | 关闭会话 |
|
||||
|
||||
## 共享浏览器后端
|
||||
|
||||
`browser_install` 安装 `homeagent-browser.service`（systemd 托管）。
|
||||
装上之后**所有 agent 共享同一个 Chromium 实例与登录态**，各自占独立标签页互不干扰
|
||||
（同 source 复用自己的标签页）。
|
||||
|
||||
前提：本机已有 chromium 二进制，没有会提示先装（`apt install chromium` 或等价）。
|
||||
|
||||
## 实现要点
|
||||
|
||||
- **搜索用 `cn.bing.com` 而不是 `www.bing.com`**：后者对程序化请求常回 302（同意/重定向页），
|
||||
根本拿不到结果块。
|
||||
- **标题取 `<h2>` 里的 `<a>`**：直接抓结果块里第一个 `<a>` 会拿到来源行而非标题。
|
||||
- **摘要认 `b_lineclamp`**：旧版 Bing 用 `b_caption`，新版已迁走，两套都匹配。
|
||||
- **有 SSRF 防护**：见源码 `SSRF` 段，抓取前校验目标地址，避免被诱导访问内网。
|
||||
|
||||
## 测试
|
||||
|
||||
```bash
|
||||
go test -count=1 ./...
|
||||
```
|
||||
|
||||
`testdata/bing_cn.html` 是搜索解析的固定样本，用它做离线断言，避免测试依赖真实网络。
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
```
|
||||
@ -2,7 +2,7 @@
|
||||
"name": "browser",
|
||||
"name_zh": "浏览器",
|
||||
"name_en": "Browser",
|
||||
"version": "2.4.1",
|
||||
"version": "2.3.0",
|
||||
"description": "统一浏览器插件：搜索、HTTP抓取(quick)、无头渲染(normal)、交互式浏览器(interactive/CDP)",
|
||||
"author": "HomeAgent",
|
||||
"entry": "plugin.so",
|
||||
|
||||
@ -6,7 +6,6 @@ import (
|
||||
"encoding/base64"
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"html"
|
||||
"io"
|
||||
"log"
|
||||
"net"
|
||||
@ -46,20 +45,20 @@ type Plugin struct {
|
||||
// 登录态/cookies 跨 agent、跨会话、跨插件重启保留），每个 start 创建一个
|
||||
// 新标签页（CDP Target）。同 source 复用自己的标签页。浏览器进程在
|
||||
// 最后一个标签页关闭后保留（避免反复冷启动），仅插件 Stop 时回收。
|
||||
sharedAllocCtx context.Context
|
||||
sharedAllocCtx context.Context
|
||||
sharedAllocCancel context.CancelFunc
|
||||
sharedMu sync.Mutex
|
||||
sharedMu sync.Mutex
|
||||
}
|
||||
|
||||
type BrowserSession struct {
|
||||
id string
|
||||
allocCtx context.Context // 共享浏览器进程上下文（shared=true 时指向全局单例）
|
||||
cancel context.CancelFunc
|
||||
ctx context.Context // 本会话的 Target 上下文（一个标签页）
|
||||
createdAt time.Time
|
||||
timeout time.Duration
|
||||
closed bool
|
||||
mu sync.Mutex
|
||||
id string
|
||||
allocCtx context.Context // 共享浏览器进程上下文（shared=true 时指向全局单例）
|
||||
cancel context.CancelFunc
|
||||
ctx context.Context // 本会话的 Target 上下文（一个标签页）
|
||||
createdAt time.Time
|
||||
timeout time.Duration
|
||||
closed bool
|
||||
mu sync.Mutex
|
||||
currentURL string
|
||||
shared bool // true=共享浏览器的一个标签页；false=独占浏览器实例
|
||||
profileDir string // 非空表示使用持久化 profile（关闭时不删目录）
|
||||
@ -160,18 +159,6 @@ func errResult(msg string) map[string]interface{} {
|
||||
return map[string]interface{}{"isError": true, "content": msg}
|
||||
}
|
||||
|
||||
func parseBrowserSessionTimeout(args map[string]interface{}) (time.Duration, error) {
|
||||
raw := strings.TrimSpace(readArg(args, "timeout", ""))
|
||||
if raw == "" {
|
||||
return 0, fmt.Errorf("timeout is required；创建浏览器会话时必须明确指定关闭时长，如 15m 或 2h")
|
||||
}
|
||||
timeout, err := time.ParseDuration(raw)
|
||||
if err != nil || timeout <= 0 {
|
||||
return 0, fmt.Errorf("invalid timeout %q；请使用大于 0 的时长，如 15m 或 2h", raw)
|
||||
}
|
||||
return timeout, nil
|
||||
}
|
||||
|
||||
func newHTTPClient(timeout int, proxyURL string) *http.Client {
|
||||
transport := &http.Transport{
|
||||
DialContext: (&net.Dialer{
|
||||
@ -204,9 +191,6 @@ func newHTTPClient(timeout int, proxyURL string) *http.Client {
|
||||
func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
p.sdk = s
|
||||
s.SetAutoRestart(true)
|
||||
// 入站通道：本插件用 p.name 通道注入输入（见 InjectInputSync 调用），
|
||||
// 输入侧必须显式登记 —— 否则"把该 inputch 划给驻留子"会报 `inputch 未注册`。
|
||||
_ = s.RegisterInputChannel(p.name, sdk.ChannelDef{})
|
||||
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{
|
||||
Key: "timeout", Default: "30", Type: "int",
|
||||
@ -292,15 +276,14 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
|
||||
s.RegisterTool(tp+"start", sdk.ToolDef{
|
||||
Name: tp + "start",
|
||||
Description: "启动交互式浏览器会话。Agent 必须在创建时明确指定 timeout；到期后插件关闭标签页。同来源复用已有标签页时，也按本次 timeout 重新设定关闭时间。",
|
||||
Description: "启动交互式浏览器会话。优先连接 systemd 托管的共享浏览器后端（登录态全机共享、各 agent 独立标签页）；后端未安装时返回 need_install 引导（调 browser_install）；无法安装时自动降级本地临时模式。同来源复用已有标签页。",
|
||||
Parameters: map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"url": map[string]interface{}{"type": "string", "description": "初始导航 URL（可选）"},
|
||||
"timeout": map[string]interface{}{"type": "string", "description": "必填，会话关闭前的存活时长，如 15m、2h；必须大于 0"},
|
||||
"timeout": map[string]interface{}{"type": "string", "description": "会话超时(如 5m, 10m，默认 10m)"},
|
||||
"profile": map[string]interface{}{"type": "string", "description": "持久化档案名（可选，如 main）。同名档案共享登录态与浏览历史；不指定则为一次性临时会话"},
|
||||
},
|
||||
"required": []string{"timeout"},
|
||||
},
|
||||
}, p.handleBrowserStart)
|
||||
|
||||
@ -488,9 +471,7 @@ type searchResult struct {
|
||||
}
|
||||
|
||||
func (p *Plugin) bingSearch(query string, count int) ([]searchResult, error) {
|
||||
// 用 cn.bing.com：www.bing.com 对程序化请求常回 302（同意/重定向页），拿不到结果块。
|
||||
// 另：Bing 忽略 count 参数，翻页靠 first=，这里保留 count 只为兼容旧调用语义。
|
||||
u := fmt.Sprintf("https://cn.bing.com/search?q=%s&first=1&count=%d&setlang=zh-CN", url.QueryEscape(query), count)
|
||||
u := fmt.Sprintf("https://www.bing.com/search?q=%s&count=%d", url.QueryEscape(query), count)
|
||||
req, _ := http.NewRequest("GET", u, nil)
|
||||
req.Header.Set("User-Agent", "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36")
|
||||
req.Header.Set("Accept-Language", "zh-CN,zh;q=0.9,en;q=0.8")
|
||||
@ -500,112 +481,38 @@ func (p *Plugin) bingSearch(query string, count int) ([]searchResult, error) {
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
body, _ := io.ReadAll(resp.Body)
|
||||
if resp.StatusCode != http.StatusOK {
|
||||
return nil, fmt.Errorf("Bing 返回 HTTP %d（%d 字节）", resp.StatusCode, len(body))
|
||||
}
|
||||
results := parseBingResults(string(body), count)
|
||||
if len(results) == 0 {
|
||||
// 关键：把「解析不出来」与「真的没结果」区分开。
|
||||
// 以前两者都变成 "No results found."，版式一变就静默退化成「搜不到」。
|
||||
return nil, fmt.Errorf("Bing 返回 %d 字节但未解析出结果（可能被反爬或版式变更，可改用 deepsearch 插件）", len(body))
|
||||
}
|
||||
return results, nil
|
||||
return parseBingResults(string(body), count), nil
|
||||
}
|
||||
|
||||
var (
|
||||
bingBlockRe = regexp.MustCompile(`<li class="b_algo"`)
|
||||
bingTitleRe = regexp.MustCompile(`(?s)<h2[^>]*>\s*<a[^>]+href="([^"]+)"[^>]*>(.*?)</a>`)
|
||||
bingAnyLinkRe = regexp.MustCompile(`(?s)<a[^>]+href="([^"]+)"[^>]*>(.*?)</a>`)
|
||||
bingSnipRe = regexp.MustCompile(`(?s)<p class="b_lineclamp[^"]*"[^>]*>(.*?)</p>`)
|
||||
bingCaptionRe = regexp.MustCompile(`(?s)<div class="b_caption"[^>]*>(.*?)</div>`)
|
||||
)
|
||||
|
||||
// splitBingBlocks 按块标记切分，每块内容延伸到下一个块标记为止。
|
||||
//
|
||||
// 不用 `<li class="b_algo"(?s)(.*?)</li>`：结果块内部可能嵌套 <li>（deep links），
|
||||
// 非贪婪匹配会在错误位置截断；而且块内第一个 <a> 往往是 Bing 的「来源行」，
|
||||
// 取到的是 `deepin.orghttps://www.deepin.org` 这种垃圾标题。
|
||||
func splitBingBlocks(pageHTML string) []string {
|
||||
locs := bingBlockRe.FindAllStringIndex(pageHTML, -1)
|
||||
if len(locs) == 0 {
|
||||
return nil
|
||||
}
|
||||
blocks := make([]string, 0, len(locs))
|
||||
for i, loc := range locs {
|
||||
end := len(pageHTML)
|
||||
if i+1 < len(locs) {
|
||||
end = locs[i+1][0]
|
||||
}
|
||||
blocks = append(blocks, pageHTML[loc[1]:end])
|
||||
}
|
||||
return blocks
|
||||
}
|
||||
|
||||
func parseBingResults(pageHTML string, count int) []searchResult {
|
||||
if count <= 0 {
|
||||
count = 5
|
||||
}
|
||||
func parseBingResults(html string, count int) []searchResult {
|
||||
var results []searchResult
|
||||
for _, block := range splitBingBlocks(pageHTML) {
|
||||
re := regexp.MustCompile(`<li class="b_algo"(?s)(.*?)</li>`)
|
||||
matches := re.FindAllStringSubmatch(html, -1)
|
||||
for _, m := range matches {
|
||||
if len(results) >= count {
|
||||
break
|
||||
}
|
||||
// 标题：现代 Bing 是 <h2><a href=...>标题</a></h2>；没有 h2 时才退回到块内第一个链接。
|
||||
var href, title string
|
||||
if m := bingTitleRe.FindStringSubmatch(block); m != nil {
|
||||
href, title = m[1], html.UnescapeString(stripTags(m[2]))
|
||||
} else if m := bingAnyLinkRe.FindStringSubmatch(block); m != nil {
|
||||
href, title = m[1], html.UnescapeString(stripTags(m[2]))
|
||||
block := m[1]
|
||||
var r searchResult
|
||||
hrefRe := regexp.MustCompile(`<a[^>]+href="([^"]+)"[^>]*>`)
|
||||
if hm := hrefRe.FindStringSubmatch(block); len(hm) > 1 {
|
||||
r.URL = hm[1]
|
||||
}
|
||||
href = bingRealURL(html.UnescapeString(href))
|
||||
|
||||
// 摘要：新版在 p.b_lineclamp*，旧版在 div.b_caption > p
|
||||
var snippet string
|
||||
if m := bingSnipRe.FindStringSubmatch(block); m != nil {
|
||||
snippet = html.UnescapeString(stripTags(m[1]))
|
||||
} else if m := bingCaptionRe.FindStringSubmatch(block); m != nil {
|
||||
snippet = html.UnescapeString(stripTags(m[1]))
|
||||
titleRe := regexp.MustCompile(`<a[^>]+href="[^"]+"[^>]*>(.*?)</a>`)
|
||||
if tm := titleRe.FindStringSubmatch(block); len(tm) > 1 {
|
||||
r.Title = stripTags(tm[1])
|
||||
}
|
||||
|
||||
title, snippet = strings.TrimSpace(title), strings.TrimSpace(snippet)
|
||||
if href == "" || title == "" || !strings.HasPrefix(href, "http") {
|
||||
continue
|
||||
snipRe := regexp.MustCompile(`<div class="b_caption">.*?<p>(.*?)</p>`)
|
||||
if sm := snipRe.FindStringSubmatch(block); len(sm) > 1 {
|
||||
r.Snippet = stripTags(sm[1])
|
||||
}
|
||||
if r.URL != "" && r.Title != "" {
|
||||
results = append(results, r)
|
||||
}
|
||||
results = append(results, searchResult{Title: title, URL: href, Snippet: snippet})
|
||||
}
|
||||
return results
|
||||
}
|
||||
|
||||
// bingRealURL 解开 Bing 的跳转包装：/ck/a?...&u=a1<base64url>&... → 真实 URL。
|
||||
// 不解的话模型拿到的是 `https://cn.bing.com/ck/a?...` 这种不可读地址。
|
||||
func bingRealURL(href string) string {
|
||||
href = strings.TrimSpace(href)
|
||||
if href == "" {
|
||||
return ""
|
||||
}
|
||||
if !strings.Contains(href, "/ck/a") && !strings.Contains(href, "u=a1") {
|
||||
return href
|
||||
}
|
||||
u, err := url.Parse(href)
|
||||
if err != nil {
|
||||
return href
|
||||
}
|
||||
raw := u.Query().Get("u")
|
||||
if !strings.HasPrefix(raw, "a1") {
|
||||
return href
|
||||
}
|
||||
b64 := raw[2:]
|
||||
for _, enc := range []*base64.Encoding{base64.RawURLEncoding, base64.URLEncoding, base64.RawStdEncoding} {
|
||||
if dec, err := enc.DecodeString(b64); err == nil {
|
||||
s := string(dec)
|
||||
if strings.HasPrefix(s, "http://") || strings.HasPrefix(s, "https://") {
|
||||
return s
|
||||
}
|
||||
}
|
||||
}
|
||||
return href
|
||||
}
|
||||
|
||||
func (p *Plugin) handleSearch(args map[string]interface{}) (interface{}, error) {
|
||||
query := readArg(args, "query", "")
|
||||
if query == "" {
|
||||
@ -974,9 +881,10 @@ func (p *Plugin) localSpawnFailback() (context.Context, context.CancelFunc, cont
|
||||
}
|
||||
|
||||
func (p *Plugin) handleBrowserStart(args map[string]interface{}) (interface{}, error) {
|
||||
timeout, err := parseBrowserSessionTimeout(args)
|
||||
timeoutStr := readArg(args, "timeout", "10m")
|
||||
timeout, err := time.ParseDuration(timeoutStr)
|
||||
if err != nil {
|
||||
return errResult(err.Error()), nil
|
||||
timeout = 10 * time.Minute
|
||||
}
|
||||
|
||||
source := readArg(args, "source", "")
|
||||
@ -991,19 +899,13 @@ func (p *Plugin) handleBrowserStart(args map[string]interface{}) (interface{}, e
|
||||
s.mu.Lock()
|
||||
id := s.id
|
||||
cur := s.currentURL
|
||||
s.createdAt = time.Now()
|
||||
s.timeout = timeout
|
||||
closesAt := s.createdAt.Add(timeout)
|
||||
s.mu.Unlock()
|
||||
p.mu.Unlock()
|
||||
log.Printf("[%s] reused browser session %s: timeout=%v closes_at=%s source=%s", p.name, id, timeout, closesAt.Format(time.RFC3339), source)
|
||||
return map[string]interface{}{
|
||||
"id": id,
|
||||
"status": "reused",
|
||||
"url": cur,
|
||||
"timeout": timeout.String(),
|
||||
"closes_at": closesAt.Format(time.RFC3339),
|
||||
"note": "已复用本来源的现有标签页，并按本次 timeout 重新设定关闭时间",
|
||||
"id": id,
|
||||
"status": "reused",
|
||||
"url": cur,
|
||||
"note": "已复用本来源的现有标签页（登录态全机共享）",
|
||||
}, nil
|
||||
}
|
||||
}
|
||||
@ -1040,7 +942,7 @@ func (p *Plugin) handleBrowserStart(args map[string]interface{}) (interface{}, e
|
||||
"插件会注册 homeagent-browser.service 并启动。" +
|
||||
"若本机无法联网安装 chromium，可继续用本地临时模式（重试 browser_start 即自动降级）。"
|
||||
return map[string]interface{}{
|
||||
"error": "backend not installed",
|
||||
"error": "backend not installed",
|
||||
"need_install": true,
|
||||
"guide": guide,
|
||||
}, nil
|
||||
@ -1070,15 +972,13 @@ func (p *Plugin) handleBrowserStart(args map[string]interface{}) (interface{}, e
|
||||
session.currentURL = initURL
|
||||
}
|
||||
|
||||
closesAt := session.createdAt.Add(timeout)
|
||||
log.Printf("[%s] created browser session %s: url=%s timeout=%v closes_at=%s source=%s", p.name, id, initURL, timeout, closesAt.Format(time.RFC3339), source)
|
||||
log.Printf("[%s] created browser session %s: url=%s timeout=%v source=%s", p.name, id, initURL, timeout, source)
|
||||
return map[string]interface{}{
|
||||
"id": id,
|
||||
"status": "created",
|
||||
"mode": "shared-backend",
|
||||
"url": initURL,
|
||||
"timeout": timeout.String(),
|
||||
"closes_at": closesAt.Format(time.RFC3339),
|
||||
"id": id,
|
||||
"status": "created",
|
||||
"mode": "shared-backend",
|
||||
"url": initURL,
|
||||
"timeout": timeout.String(),
|
||||
}, nil
|
||||
}
|
||||
|
||||
@ -1144,11 +1044,11 @@ func (p *Plugin) handleScreenshot(args map[string]interface{}) (interface{}, err
|
||||
}
|
||||
b64 := base64.StdEncoding.EncodeToString(buf)
|
||||
return map[string]interface{}{
|
||||
"status": "ok",
|
||||
"format": format,
|
||||
"size": len(buf),
|
||||
"base64": b64,
|
||||
"data_uri": fmt.Sprintf("data:image/png;base64,%s", b64),
|
||||
"status": "ok",
|
||||
"format": format,
|
||||
"size": len(buf),
|
||||
"base64": b64,
|
||||
"data_uri": fmt.Sprintf("data:image/png;base64,%s", b64),
|
||||
}, nil
|
||||
}
|
||||
|
||||
@ -1179,11 +1079,11 @@ func (p *Plugin) handleHTML(args map[string]interface{}) (interface{}, error) {
|
||||
html = html[:maxChars] + "\n\n[HTML truncated]"
|
||||
}
|
||||
return map[string]interface{}{
|
||||
"status": "ok",
|
||||
"title": title,
|
||||
"url": currentURL,
|
||||
"html": html,
|
||||
"length": len(html),
|
||||
"status": "ok",
|
||||
"title": title,
|
||||
"url": currentURL,
|
||||
"html": html,
|
||||
"length": len(html),
|
||||
}, nil
|
||||
}
|
||||
|
||||
@ -1304,20 +1204,13 @@ func (p *Plugin) cleanupLoop() {
|
||||
case <-p.stopCh:
|
||||
return
|
||||
case <-ticker.C:
|
||||
now := time.Now()
|
||||
p.mu.Lock()
|
||||
for id, s := range p.sessions {
|
||||
s.mu.Lock()
|
||||
closesAt := s.createdAt.Add(s.timeout)
|
||||
expired := !now.Before(closesAt)
|
||||
s.mu.Unlock()
|
||||
if expired {
|
||||
log.Printf("[%s] cleanup: browser session %s reached agent-specified close time %s", p.name, id, closesAt.Format(time.RFC3339))
|
||||
delete(p.sessions, id)
|
||||
s.Close()
|
||||
// NoMemory：会话生命周期通知，不是记忆内容。
|
||||
p.sdk.InjectInterruptTextOpts(p.name, p.name,
|
||||
fmt.Sprintf("[浏览器会话 %s 已按指定时间关闭]", id), sdk.InjectOptions{NoMemory: true})
|
||||
if time.Since(s.createdAt) >= s.timeout {
|
||||
log.Printf("[%s] cleanup: browser session %s expired", p.name, id)
|
||||
delete(p.sessions, id)
|
||||
s.Close()
|
||||
p.sdk.InjectInterruptText(p.name, p.name, fmt.Sprintf("[浏览器会话 %s 已超时关闭]", id))
|
||||
}
|
||||
}
|
||||
p.mu.Unlock()
|
||||
@ -1417,7 +1310,7 @@ WantedBy=multi-user.target
|
||||
return map[string]interface{}{
|
||||
"status": "installed",
|
||||
"endpoint": cdpEndpoint,
|
||||
"chrome": chromePath,
|
||||
"chrome": chromePath,
|
||||
"profile": profileDir,
|
||||
"guide": guide,
|
||||
}, nil
|
||||
|
||||
@ -1,213 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"net/url"
|
||||
"os"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
func TestParseBrowserSessionTimeoutRequiresExplicitValue(t *testing.T) {
|
||||
_, err := parseBrowserSessionTimeout(map[string]interface{}{})
|
||||
if err == nil || !strings.Contains(err.Error(), "timeout is required") {
|
||||
t.Fatalf("expected required timeout error, got %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
func TestParseBrowserSessionTimeoutAcceptsPositiveDuration(t *testing.T) {
|
||||
got, err := parseBrowserSessionTimeout(map[string]interface{}{"timeout": "2h30m"})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if got != 2*time.Hour+30*time.Minute {
|
||||
t.Fatalf("timeout=%v", got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestParseBrowserSessionTimeoutRejectsInvalidOrNonPositive(t *testing.T) {
|
||||
for _, value := range []string{"invalid", "0s", "-1m"} {
|
||||
if _, err := parseBrowserSessionTimeout(map[string]interface{}{"timeout": value}); err == nil {
|
||||
t.Errorf("timeout %q should be rejected", value)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestBrowserStartReuseResetsExplicitCloseTime(t *testing.T) {
|
||||
p := &Plugin{
|
||||
name: "browser",
|
||||
sessions: map[string]*BrowserSession{
|
||||
"browser_1": {
|
||||
id: "browser_1",
|
||||
shared: true,
|
||||
sessionKey: "qq",
|
||||
createdAt: time.Now().Add(-time.Hour),
|
||||
timeout: time.Minute,
|
||||
currentURL: "https://example.com",
|
||||
},
|
||||
},
|
||||
}
|
||||
|
||||
before := time.Now()
|
||||
result, err := p.handleBrowserStart(map[string]interface{}{"source": "qq", "timeout": "3h"})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
out := result.(map[string]interface{})
|
||||
if out["status"] != "reused" || out["timeout"] != "3h0m0s" {
|
||||
t.Fatalf("unexpected result: %#v", out)
|
||||
}
|
||||
s := p.sessions["browser_1"]
|
||||
if s.timeout != 3*time.Hour || s.createdAt.Before(before) {
|
||||
t.Fatalf("deadline not reset: createdAt=%v timeout=%v", s.createdAt, s.timeout)
|
||||
}
|
||||
}
|
||||
|
||||
// ── Bing 解析器（2026-09 版式）─────────────────────────────
|
||||
//
|
||||
// 背景：旧实现把块内**第一个 <a>** 当标题 —— 拿到的是 Bing 的「来源行」
|
||||
// `deepin.orghttps://www.deepin.org`；摘要正则 `<div class="b_caption">.*?<p>`
|
||||
// 对现代 Bing 命中 0/N（摘要已迁到 p.b_lineclamp*），于是结果「有标题没摘要」，
|
||||
// 模型只好反复换词重搜。夹具 testdata/bing_cn.html 是真实 cn.bing.com 响应裁剪。
|
||||
|
||||
func TestParseBingResultsRealBingHTML(t *testing.T) {
|
||||
page, err := os.ReadFile("testdata/bing_cn.html")
|
||||
if err != nil {
|
||||
t.Fatalf("读取夹具失败: %v", err)
|
||||
}
|
||||
results := parseBingResults(string(page), 3)
|
||||
if len(results) != 3 {
|
||||
t.Fatalf("应解析出 3 条，实际 %d 条: %+v", len(results), results)
|
||||
}
|
||||
for i, r := range results {
|
||||
if !strings.HasPrefix(r.URL, "http") {
|
||||
t.Errorf("第 %d 条 URL 不是真实地址: %q", i+1, r.URL)
|
||||
}
|
||||
if strings.Contains(r.Title, "http") || strings.Contains(r.Title, "://") {
|
||||
t.Errorf("第 %d 条标题混入了 URL（旧 bug 的典型症状）: %q", i+1, r.Title)
|
||||
}
|
||||
if r.Snippet == "" {
|
||||
t.Errorf("第 %d 条没有摘要（旧 bug 的典型症状）: %+v", i+1, r)
|
||||
}
|
||||
}
|
||||
// 第一条必须与样本里的真实结果一致
|
||||
if results[0].URL != "https://www.deepin.org/" {
|
||||
t.Errorf("第一条 URL 应为 https://www.deepin.org/，实际 %q", results[0].URL)
|
||||
}
|
||||
if !strings.Contains(results[0].Title, "deepin") {
|
||||
t.Errorf("第一条标题不对: %q", results[0].Title)
|
||||
}
|
||||
if len(results[0].Snippet) < 10 || strings.Contains(results[0].Snippet, "://") {
|
||||
t.Errorf("第一条摘要不对（应是有内容的文本）: %q", results[0].Snippet)
|
||||
}
|
||||
}
|
||||
|
||||
// 块内嵌套 <li>（deep links）时不能截断 —— 旧的 `<li class="b_algo"(?s)(.*?)</li>` 会在此翻车
|
||||
func TestParseBingResultsNestedLiKeepsResult(t *testing.T) {
|
||||
page := `<ol id="b_results"><li class="b_algo" data-id iid=SERP.1>` +
|
||||
`<h2><a href="https://a.example/x" h="ID=SERP,1">真标题</a></h2>` +
|
||||
`<div class="b_caption"><p class="b_lineclamp2">真摘要</p></div>` +
|
||||
`<div><ul><li><a href="https://sub.example/deeplink">子链接</a></li></ul></div>` +
|
||||
`</li><li class="b_algo"><h2><a href="https://b.example/y">第二条</a></h2>` +
|
||||
`<p class="b_lineclamp3">摘要二</p></li></ol>`
|
||||
rs := parseBingResults(page, 5)
|
||||
if len(rs) != 2 {
|
||||
t.Fatalf("应解析 2 条，实际 %d 条: %+v", len(rs), rs)
|
||||
}
|
||||
if rs[0].URL != "https://a.example/x" || rs[0].Title != "真标题" || rs[0].Snippet != "真摘要" {
|
||||
t.Errorf("第一条解析错误: %+v", rs[0])
|
||||
}
|
||||
if rs[1].Title != "第二条" || rs[1].Snippet != "摘要二" {
|
||||
t.Errorf("第二条（无 b_caption，摘要走 b_lineclamp3）解析错误: %+v", rs[1])
|
||||
}
|
||||
}
|
||||
|
||||
func TestBingRealURLDecodesRedirectWrapper(t *testing.T) {
|
||||
// Bing 跳转包装：/ck/a?...&u=a1<base64url>
|
||||
wrapped := "/ck/a?!&&p=abc&u=a1aHR0cHM6Ly93d3cuZGVlcGluLm9yZy96aC9EZWVwaW4v&ntb=1"
|
||||
if got := bingRealURL(wrapped); got != "https://www.deepin.org/zh/Deepin/" {
|
||||
t.Errorf("未解开跳转包装: %q", got)
|
||||
}
|
||||
if got := bingRealURL("https://direct.example/p"); got != "https://direct.example/p" {
|
||||
t.Errorf("直链不应被改动: %q", got)
|
||||
}
|
||||
// 解不开时保守返回原值，不能返回空
|
||||
bad := "/ck/a?u=a1!!!!"
|
||||
if got := bingRealURL(bad); got == "" {
|
||||
t.Errorf("解不开时应保留原值，实际返回空")
|
||||
}
|
||||
}
|
||||
|
||||
// roundTripFunc 把任意请求转给本地测试服务器，从而离线测 bingSearch 的完整路径
|
||||
type roundTripFunc func(*http.Request) (*http.Response, error)
|
||||
|
||||
func (f roundTripFunc) RoundTrip(r *http.Request) (*http.Response, error) { return f(r) }
|
||||
|
||||
func TestBingSearchReportsParseFailureInsteadOfEmptyResult(t *testing.T) {
|
||||
var seenURL string
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
_, _ = w.Write([]byte("<html><body>no result blocks here</body></html>"))
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
p := &Plugin{name: "browser", client: &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
|
||||
seenURL = r.URL.String()
|
||||
return srv.Client().Transport.RoundTrip(&http.Request{
|
||||
Method: r.Method, URL: mustParseURL(t, srv.URL), Header: r.Header, Body: r.Body,
|
||||
})
|
||||
})}}
|
||||
|
||||
if _, err := p.bingSearch("任意查询", 5); err == nil {
|
||||
t.Fatal("解析不出结果时必须报错，而不是伪装成「没有结果」")
|
||||
} else if !strings.Contains(err.Error(), "未解析出结果") {
|
||||
t.Errorf("错误信息应说明是解析失败: %v", err)
|
||||
}
|
||||
// 数据源必须是 cn.bing.com（www.bing.com 对程序化请求回 302，拿不到结果块）
|
||||
if !strings.Contains(seenURL, "cn.bing.com") {
|
||||
t.Errorf("应请求 cn.bing.com，实际 %q", seenURL)
|
||||
}
|
||||
if strings.Contains(seenURL, "www.bing.com") {
|
||||
t.Errorf("不应再请求 www.bing.com: %q", seenURL)
|
||||
}
|
||||
}
|
||||
|
||||
// 正常路径：能解析出结果时返回结果且不报错
|
||||
func TestBingSearchParsesFixtureThroughClient(t *testing.T) {
|
||||
page, err := os.ReadFile("testdata/bing_cn.html")
|
||||
if err != nil {
|
||||
t.Fatalf("读取夹具失败: %v", err)
|
||||
}
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
w.Header().Set("Content-Type", "text/html; charset=utf-8")
|
||||
_, _ = w.Write(page)
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
p := &Plugin{name: "browser", client: &http.Client{Transport: roundTripFunc(func(r *http.Request) (*http.Response, error) {
|
||||
return srv.Client().Transport.RoundTrip(&http.Request{
|
||||
Method: r.Method, URL: mustParseURL(t, srv.URL), Header: r.Header, Body: r.Body,
|
||||
})
|
||||
})}}
|
||||
|
||||
results, err := p.bingSearch("deepin", 2)
|
||||
if err != nil {
|
||||
t.Fatalf("应成功，实际 %v", err)
|
||||
}
|
||||
if len(results) != 2 {
|
||||
t.Fatalf("应返回 2 条（count 生效），实际 %d", len(results))
|
||||
}
|
||||
if results[0].Snippet == "" {
|
||||
t.Errorf("摘要不应为空: %+v", results[0])
|
||||
}
|
||||
}
|
||||
|
||||
func mustParseURL(t *testing.T, raw string) *url.URL {
|
||||
t.Helper()
|
||||
u, err := url.Parse(raw)
|
||||
if err != nil {
|
||||
t.Fatalf("解析测试 URL 失败: %v", err)
|
||||
}
|
||||
return u
|
||||
}
|
||||
1
example/browser/testdata/bing_cn.html
vendored
1
example/browser/testdata/bing_cn.html
vendored
File diff suppressed because one or more lines are too long
@ -1,57 +1,13 @@
|
||||
# calendar · 日历事件
|
||||
# calendar
|
||||
|
||||
事件管理：支持**重复事件**与**多档提醒**。
|
||||
calendar plugin
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `calendar_event_add` | 添加事件 |
|
||||
| `calendar_event_list` | 列出即将到来的事件（含日期、时间、重复规则） |
|
||||
| `calendar_event_update` | 更新事件（**只改传入的字段**；会重置提醒状态） |
|
||||
| `calendar_event_delete` | 删除事件（连带**该事件及之后的所有重复实例**） |
|
||||
| `calendar_today` | 今日事件 + 倒计时 |
|
||||
| `calendar_week` | 本周事件，按天分组 |
|
||||
| `calendar_month` | 月历网格，带事件标记点 |
|
||||
| `calendar_search` | 按关键词搜标题 / 地点 / 备注 |
|
||||
|
||||
`calendar_event_add` 的时间格式：`YYYY-MM-DD HH:MM`；只给 `YYYY-MM-DD` 表示全天事件。
|
||||
|
||||
## 重复规则
|
||||
|
||||
`repeat` 取值：
|
||||
|
||||
| 值 | 含义 |
|
||||
|---|---|
|
||||
| `none` | 不重复 |
|
||||
| `daily` | 每天 |
|
||||
| `weekday` | 每个工作日 |
|
||||
| `weekly` | 每周 |
|
||||
| `biweekly` | 每两周 |
|
||||
| `monthly` | 每月 |
|
||||
| `yearly` | 每年 |
|
||||
| `lunar_yearly` | **按农历年**（生日、传统节日用） |
|
||||
|
||||
`lunar_yearly` 是刻意加的：农历节日按公历写死会逐年偏移。
|
||||
|
||||
## 提醒
|
||||
|
||||
`remind_before` 单位是**分钟**，可给多个、逗号分隔：
|
||||
|
||||
```
|
||||
15,60,1440 # 提前 15 分钟 + 1 小时 + 1 天
|
||||
0 或留空 # 不提醒
|
||||
```
|
||||
|
||||
到点通过 `InjectInterruptText` 注入提醒，带 `NoMemory: true` ——
|
||||
提醒是瞬时信号，不是记忆内容。通道 `calendar` 同样声明为 NoMemory。
|
||||
|
||||
## 存储
|
||||
|
||||
事件存为 JSON，插件重启后保留。
|
||||
|
||||
## 构建
|
||||
## Build
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
plugindev build
|
||||
```
|
||||
|
||||
## Install
|
||||
|
||||
Upload the .hmap file through the Plugin Manager API.
|
||||
|
||||
@ -15,31 +15,31 @@ import (
|
||||
)
|
||||
|
||||
const (
|
||||
RepeatNone = "none"
|
||||
RepeatDaily = "daily"
|
||||
RepeatWeekday = "weekday"
|
||||
RepeatWeekly = "weekly"
|
||||
RepeatBiweekly = "biweekly"
|
||||
RepeatMonthly = "monthly"
|
||||
RepeatYearly = "yearly"
|
||||
RepeatNone = "none"
|
||||
RepeatDaily = "daily"
|
||||
RepeatWeekday = "weekday"
|
||||
RepeatWeekly = "weekly"
|
||||
RepeatBiweekly = "biweekly"
|
||||
RepeatMonthly = "monthly"
|
||||
RepeatYearly = "yearly"
|
||||
RepeatLunarYearly = "lunar_yearly"
|
||||
)
|
||||
|
||||
type CalendarEvent struct {
|
||||
ID string `json:"id"`
|
||||
Title string `json:"title"`
|
||||
StartTime string `json:"start_time"`
|
||||
EndTime string `json:"end_time,omitempty"`
|
||||
AllDay bool `json:"all_day,omitempty"`
|
||||
Location string `json:"location,omitempty"`
|
||||
Note string `json:"note,omitempty"`
|
||||
Reminds []int `json:"reminds,omitempty"`
|
||||
RemindAt []int64 `json:"remind_at,omitempty"`
|
||||
Repeat string `json:"repeat,omitempty"`
|
||||
ParentID string `json:"parent_id,omitempty"`
|
||||
Lunar bool `json:"lunar,omitempty"`
|
||||
LunarMonth int `json:"lunar_month,omitempty"`
|
||||
LunarDay int `json:"lunar_day,omitempty"`
|
||||
ID string `json:"id"`
|
||||
Title string `json:"title"`
|
||||
StartTime string `json:"start_time"`
|
||||
EndTime string `json:"end_time,omitempty"`
|
||||
AllDay bool `json:"all_day,omitempty"`
|
||||
Location string `json:"location,omitempty"`
|
||||
Note string `json:"note,omitempty"`
|
||||
Reminds []int `json:"reminds,omitempty"`
|
||||
RemindAt []int64 `json:"remind_at,omitempty"`
|
||||
Repeat string `json:"repeat,omitempty"`
|
||||
ParentID string `json:"parent_id,omitempty"`
|
||||
Lunar bool `json:"lunar,omitempty"`
|
||||
LunarMonth int `json:"lunar_month,omitempty"`
|
||||
LunarDay int `json:"lunar_day,omitempty"`
|
||||
}
|
||||
|
||||
type Plugin struct {
|
||||
@ -276,9 +276,6 @@ func nextLunarYearly(targetMonth, targetDay int, after time.Time) (time.Time, bo
|
||||
func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
p.sdk = s
|
||||
|
||||
// 入站通道：本插件用 "calendar" 通道注入输入（见 Inject* 调用），
|
||||
// 输入侧必须显式登记 —— 否则"把该 inputch 划给驻留子"会报 `inputch 未注册`。
|
||||
_ = s.RegisterInputChannel("calendar", sdk.ChannelDef{NoMemory: true})
|
||||
dataDirVal, err := s.Settings().GetCore("core.daemon.data_dir")
|
||||
if err != nil || dataDirVal == "" {
|
||||
dataDirVal = "."
|
||||
@ -362,7 +359,7 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
s.RegisterTool(tp+"today", sdk.ToolDef{
|
||||
Name: tp + "today", Description: "Show today's events with countdown.",
|
||||
Parameters: map[string]interface{}{
|
||||
"type": "object",
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{},
|
||||
},
|
||||
}, p.handleToday)
|
||||
@ -370,7 +367,7 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
s.RegisterTool(tp+"week", sdk.ToolDef{
|
||||
Name: tp + "week", Description: "Show this week's events grouped by day.",
|
||||
Parameters: map[string]interface{}{
|
||||
"type": "object",
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{},
|
||||
},
|
||||
}, p.handleWeek)
|
||||
@ -523,8 +520,7 @@ func (p *Plugin) checkReminders() {
|
||||
p.mu.Unlock()
|
||||
|
||||
for _, msg := range injectMsgs {
|
||||
// NoMemory：日程到点提醒，不是记忆内容。
|
||||
p.sdk.InjectInterruptTextOpts("calendar", "calendar", msg, sdk.InjectOptions{NoMemory: true})
|
||||
p.sdk.InjectInterruptText("calendar", "calendar", msg)
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@ -1,100 +0,0 @@
|
||||
# 联网检索插件（HomeAgent）
|
||||
|
||||
给 agent 补上**真正的信息检索**能力：检索交给本地 SearXNG（多引擎聚合、结构化 JSON），
|
||||
并补上「读完前 K 篇再回答」的深检索。
|
||||
|
||||
## 为什么需要它（背景）
|
||||
|
||||
agent 原本只有 `browser_*` 那套浏览器工具，联网检索实际只有 `browser_search` 一个入口，而它是
|
||||
**「抓 Bing HTML + 正则解析」**：
|
||||
|
||||
| 缺陷 | 实测结果 |
|
||||
|---|---|
|
||||
| 标题取的是结果块里**第一个 `<a>`** | 拿到的是 Bing 的「来源行」而非标题 → `deepin.orghttps://www.deepin.org` |
|
||||
| 摘要正则 `<div class="b_caption">.*?<p>` | 对现代 Bing **命中 0/10**（摘要已迁到 `p.b_lineclamp*`）→ 结果**完全没有摘要** |
|
||||
| 用 `www.bing.com` | 程序化请求直接 302；`cn.bing.com` 才返回 10 个结果块 |
|
||||
| 单引擎、无兜底、无去重、无站点读取 | 模型只能反复换词重搜（日志里 8 秒 6 连击） |
|
||||
|
||||
结果就是日志里那句用户反馈：**「你的搜索能力好像不太行啊」**。
|
||||
|
||||
## 依赖：本地 SearXNG（由本插件托管）
|
||||
|
||||
插件会**自己管后端**：
|
||||
|
||||
- **启动时**：探 `healthz`；已在跑就**直接接管**（不重启），没跑就 `docker compose up -d` 并等就绪（上限 6s）
|
||||
- **停止时**：跑 `docker compose stop -t 2` 关闭它
|
||||
|
||||
配置项 `manage_searxng`（默认 true）与 `searxng_dir`（默认 `/root/searxng-agent`）控制这套行为；
|
||||
`stop_searxng_on_exit`（默认 true）设 false 可让后端在插件停止后继续跑（**插件重载频繁时建议设 false**，
|
||||
否则每次重载都会把后端重启一遍）。
|
||||
|
||||
### 生命周期契约（依据内核源码，非猜测）
|
||||
|
||||
| 环节 | 内核行为 |
|
||||
|---|---|
|
||||
| 停止插件 | 发 `plugin.stop` → 插件先跑 **RunStopHandlers（LIFO、幂等）** → 再 `Stop()` → `exit(0)` |
|
||||
| 宽限期 | **5 秒**；未退出则直接 SIGKILL —— 所以关闭动作限时 4s（`searxShutdownBudget`） |
|
||||
| stdin 关闭 | 同样会跑 handlers + `Stop()` |
|
||||
| 崩溃/被 kill | 关闭动作不会执行，后端会留在运行态；下次启动探测到就直接接管（**更安全的失败方向**） |
|
||||
| 自动重启 | `SetAutoRestart(true)` 由注入的 runtime 在 `plugin.start` 后经 `lifecycle.autoRestart` **显式上报**内核 |
|
||||
|
||||
### SearXNG 侧配置
|
||||
|
||||
部署在 **.60**，`127.0.0.1:8888`：
|
||||
|
||||
```
|
||||
/root/searxng-agent/docker-compose.yml # host 网络（要访问宿主 clash）
|
||||
/root/searxng-agent/settings.yml # json 输出 + limiter 关闭 + 出站走 clash
|
||||
```
|
||||
|
||||
两个必须知道的坑：
|
||||
|
||||
1. **`search.formats` 必须含 `json`**，否则 `/search?format=json` 返回 **403**（看起来像网络问题，其实是配置）。
|
||||
2. 该镜像默认 `GRANIAN_PORT=8080`，而 granian 的 `GRANIAN_*` **优先级高于 settings.yml**：
|
||||
.60 上 8080 被 homeagent 占用 → 不改 `SEARXNG_PORT` 就是无休止的 `Address already in use` 崩溃循环。
|
||||
|
||||
实测可用的引擎（2026-09-12）：`duckduckgo`、`brave`、`google cse`；`quark` 时好时坏；
|
||||
`baidu`/`google` 经代理出口触发 CAPTCHA，`sogou` 崩溃，`wikidata` 报 HTTP error（已关）。
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `deepsearch_search` | 联网检索（首选）：标题 + URL + 摘要 + 发布时间，支持 `engines`/`category`/`time_range`/`language`，自动按 URL 去重并按分数排序；会回报**引擎覆盖度与无响应引擎** |
|
||||
| `deepsearch_news` | 新闻检索：`news` 类别 + 默认最近一周；新闻为空时自动回退 general + 时间范围 |
|
||||
| `deepsearch_fetch` | 抓单个网页并抽正文（去脚本/样式/导航），返回标题 + 纯文本，可设截断长度 |
|
||||
| `deepsearch_deep` | **深检索**：检索 → 并行抓前 K 篇正文 → 一次返回「候选清单 + 证据正文」；单篇失败不影响整体 |
|
||||
| `deepsearch_status` | 自检：healthz、json 是否可用、延迟、**哪些引擎真的在返回结果**（检索出问题先跑这个） |
|
||||
|
||||
## 配置项
|
||||
|
||||
| 键 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `searxng_url` | `http://127.0.0.1:8888` | 本地 SearXNG 地址 |
|
||||
| `max_results` | `8` | 默认条数（控制上下文体积） |
|
||||
| `language` | `zh-CN` | 检索语言 |
|
||||
| `safesearch` | `0` | 0 关 / 1 中 / 2 严 |
|
||||
| `request_timeout` | `20` | 单次请求超时（秒） |
|
||||
| `fetch_max_chars` | `4000` | `deepsearch_fetch` 正文上限 |
|
||||
| `proxy` | 空 | 仅作用于本插件直连抓取（搜索出网由 SearXNG 侧负责） |
|
||||
| `user_agent` | Chrome UA | 抓取用 |
|
||||
|
||||
每次调用前重读配置，改完即时生效。
|
||||
|
||||
## 开发与验证
|
||||
|
||||
```bash
|
||||
go test -count=1 -race ./... # 11 项测试（httptest 打桩 SearXNG）
|
||||
|
||||
# 真实后端联调（默认跳过）：跑的就是当初失败的那条查询
|
||||
DEEPSEARCH_LIVE_SEARXNG=http://127.0.0.1:8888 go test -run TestLiveSearxng -v ./...
|
||||
|
||||
hmapdev build # 产出 dist/deep_search_bundle.hmap
|
||||
```
|
||||
|
||||
## 已知边界
|
||||
|
||||
- **知乎等站点对直连抓取返回 403**（反爬），`deepsearch_deep` 会如实标注该篇抓取失败并继续；
|
||||
这类页面请改用浏览器工具（`browser_navigate` + `browser_render`）。
|
||||
- 引擎可用性随出口 IP 与目标站点风控变化；`deepsearch_status` 与每次结果里的「覆盖度」行就是给这个用的。
|
||||
- 未做正文去重/相似度合并：同一事件的多篇转载会各占一条（摘要已能区分）。
|
||||
@ -1,21 +0,0 @@
|
||||
module deepsearch-plugin
|
||||
|
||||
go 1.25.0
|
||||
|
||||
require gitcode.com/JianFeeeee/homeagent-sdk v0.0.0
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
replace gitcode.com/JianFeeeee/homeagent-sdk => ../../
|
||||
@ -1,81 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"os"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// 真实后端联调（默认跳过，需显式指定地址）：
|
||||
//
|
||||
// DEEPSEARCH_LIVE_SEARXNG=http://127.0.0.1:8888 go test -run TestLiveSearxng -v ./...
|
||||
//
|
||||
// 它跑的就是当初失败的场景（日志里那条「你的搜索能力好像不太行啊」对应的查询），
|
||||
// 用来回答一个具体问题：换了后端之后，模型拿到的是不是「带摘要的相关结果」。
|
||||
func TestLiveSearxng(t *testing.T) {
|
||||
base := os.Getenv("DEEPSEARCH_LIVE_SEARXNG")
|
||||
if base == "" {
|
||||
t.Skip("未设置 DEEPSEARCH_LIVE_SEARXNG，跳过真实后端联调")
|
||||
}
|
||||
p := &Plugin{
|
||||
name: "deepsearch",
|
||||
searxURL: strings.TrimRight(base, "/"),
|
||||
maxItems: 6,
|
||||
language: "zh-CN",
|
||||
fetchMax: 1200,
|
||||
userAgent: defaultUA,
|
||||
}
|
||||
p.ensure()
|
||||
|
||||
// 1) 自检
|
||||
st, err := p.handleStatus(map[string]interface{}{})
|
||||
if err != nil {
|
||||
t.Fatalf("status: %v", err)
|
||||
}
|
||||
t.Logf("status: %v", st)
|
||||
|
||||
// 2) 当初失败的那条查询
|
||||
res, err := p.handleSearch(map[string]interface{}{"query": "深度科技 deepin 开发者 被开除"})
|
||||
if err != nil {
|
||||
t.Fatalf("search: %v", err)
|
||||
}
|
||||
txt := res.(map[string]interface{})["content"].(string)
|
||||
t.Logf("检索结果：\n%s", txt)
|
||||
if !strings.Contains(txt, "摘要：") {
|
||||
t.Errorf("结果里应当有摘要（这正是原实现缺失的东西）")
|
||||
}
|
||||
if !strings.Contains(txt, "覆盖：") {
|
||||
t.Errorf("应报告引擎覆盖度")
|
||||
}
|
||||
|
||||
// 3) 正文抓取（取第一条结果的 URL）
|
||||
var firstURL string
|
||||
for _, line := range strings.Split(txt, "\n") {
|
||||
l := strings.TrimSpace(line)
|
||||
if strings.HasPrefix(l, "http") {
|
||||
firstURL = l
|
||||
break
|
||||
}
|
||||
}
|
||||
if firstURL == "" {
|
||||
t.Fatal("未从结果中解析出 URL")
|
||||
}
|
||||
page, err := p.handleFetch(map[string]interface{}{"url": firstURL, "max_chars": float64(600)})
|
||||
if err != nil {
|
||||
t.Logf("抓取 %s 失败（真实站点有反爬/需 JS 属正常）：%v", firstURL, err)
|
||||
} else {
|
||||
body := page.(map[string]interface{})["content"].(string)
|
||||
t.Logf("抓取 %s 正文前 400 字：%s", firstURL, oneLine(body, 400))
|
||||
}
|
||||
|
||||
// 4) 深检索
|
||||
deep, err := p.handleDeep(map[string]interface{}{"query": "统信 UOS 内核工程师 西装 事件", "top_k": float64(2)})
|
||||
if err != nil {
|
||||
t.Fatalf("deep: %v", err)
|
||||
}
|
||||
dTxt := deep.(map[string]interface{})["content"].(string)
|
||||
if !strings.Contains(dTxt, "候选清单") || !strings.Contains(dTxt, "正文证据") {
|
||||
t.Errorf("深检索输出结构不对")
|
||||
}
|
||||
t.Logf("深检索输出前 800 字：\n%s", oneLine(dTxt, 800))
|
||||
}
|
||||
@ -1,17 +0,0 @@
|
||||
{
|
||||
"name": "deepsearch",
|
||||
"name_zh": "联网检索",
|
||||
"name_en": "Deep Search",
|
||||
"version": "1.1.2",
|
||||
"description": "为 agent 提供真正的联网信息检索：本地 SearXNG 聚合多引擎（返回标题/URL/摘要/时间），支持新闻、时间范围、指定引擎；并提供网页正文抽取与「搜索+读前K篇」的深检索",
|
||||
"author": "HomeAgent",
|
||||
"entry": "plugin.bin",
|
||||
"tags": [
|
||||
"search",
|
||||
"web",
|
||||
"searxng",
|
||||
"retrieval",
|
||||
"news"
|
||||
],
|
||||
"targets": "linux/amd64"
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,343 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"net/url"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
func newTestPlugin(t *testing.T, h http.HandlerFunc) (*Plugin, *httptest.Server) {
|
||||
t.Helper()
|
||||
srv := httptest.NewServer(h)
|
||||
t.Cleanup(srv.Close)
|
||||
p := &Plugin{
|
||||
name: "deepsearch",
|
||||
searxURL: srv.URL,
|
||||
maxItems: 5,
|
||||
language: "zh-CN",
|
||||
fetchMax: 1000,
|
||||
userAgent: "test-agent",
|
||||
http: srv.Client(),
|
||||
}
|
||||
return p, srv
|
||||
}
|
||||
|
||||
// 一份贴近真实 SearXNG 的响应：含重复 URL、缺摘要、多引擎、无响应引擎
|
||||
const sampleResponse = `{
|
||||
"query": "deepin 被开除",
|
||||
"results": [
|
||||
{"url":"https://www.zhihu.com/question/1?utm_source=x","title":"网传统信内核开发工程师因没穿西服被开除","content":"截止1月9日最新情况…","engines":["duckduckgo","brave"],"score":9.5,"publishedDate":"2026-09-10T00:00:00"},
|
||||
{"url":"https://www.zhihu.com/question/1","title":"网传统信内核开发工程师因没穿西服被开除（重复项）","content":"重复条目","engines":["brave"],"score":1.0},
|
||||
{"url":"https://www.163.com/dy/article/KIQURODQ.html","title":"离谱！传某信创操作系统大厂因西装开除核心开发者","content":"一位负责Linux内核开发的核心工程师…","engines":["brave","quark"],"score":7.2},
|
||||
{"url":"https://bbs.deepin.org.cn/zh","title":"deepin官方论坛","content":"","engines":["duckduckgo"],"score":2.0}
|
||||
],
|
||||
"answers": [],
|
||||
"suggestions": ["deepin 王勇 离职"],
|
||||
"unresponsive_engines": [["baidu","CAPTCHA"],["sogou","unexpected crash"]],
|
||||
"timings": {"search": 1.2}
|
||||
}`
|
||||
|
||||
// 1) 检索：去重 + 按分数排序 + 摘要/覆盖度输出
|
||||
func TestSearchDedupAndFormat(t *testing.T) {
|
||||
var gotQuery url.Values
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
if r.URL.Path == "/search" {
|
||||
gotQuery = r.URL.Query()
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
_, _ = w.Write([]byte(sampleResponse))
|
||||
return
|
||||
}
|
||||
http.NotFound(w, r)
|
||||
})
|
||||
res, err := p.handleSearch(map[string]interface{}{"query": "deepin 被开除", "count": float64(5)})
|
||||
if err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
if gotQuery.Get("format") != "json" {
|
||||
t.Errorf("必须要求 json 输出，实际 %q", gotQuery.Get("format"))
|
||||
}
|
||||
// SearXNG 的 /search **不认** count/limit（实测两者都返回同样的条数），
|
||||
// 所以「要几条」必须由插件侧截断 —— 也不要再发这种无意义参数（曾以为它生效过）。
|
||||
if gotQuery.Get("limit") != "" || gotQuery.Get("count") != "" {
|
||||
t.Errorf("不应依赖 SearXNG 的条数参数（它不认）: %q", gotQuery.Encode())
|
||||
}
|
||||
txt := res.(map[string]interface{})["content"].(string)
|
||||
// utm_source 应被规范化掉，重复项只剩一条
|
||||
if n := strings.Count(txt, "zhihu.com/question/1"); n != 1 {
|
||||
t.Errorf("URL 未正确去重（出现 %d 次）:\n%s", n, txt)
|
||||
}
|
||||
if !strings.Contains(txt, "网传统信内核开发工程师") {
|
||||
t.Errorf("缺少标题: %s", txt)
|
||||
}
|
||||
if !strings.Contains(txt, "摘要：") {
|
||||
t.Errorf("应输出摘要: %s", txt)
|
||||
}
|
||||
if !strings.Contains(txt, "baidu(CAPTCHA)") {
|
||||
t.Errorf("应回报无响应引擎（让模型知道覆盖度）: %s", txt)
|
||||
}
|
||||
if !strings.Contains(txt, "duckduckgo") || !strings.Contains(txt, "quark") {
|
||||
t.Errorf("应回报引擎覆盖: %s", txt)
|
||||
}
|
||||
// 高分条目应排在前面
|
||||
if strings.Index(txt, "统信内核开发工程师") > strings.Index(txt, "离谱！") {
|
||||
t.Errorf("未按分数排序:\n%s", txt)
|
||||
}
|
||||
}
|
||||
|
||||
// 2) 403（未开 json）必须给出可操作提示，而不是裸错误
|
||||
func TestSearchForbiddenHint(t *testing.T) {
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
w.WriteHeader(http.StatusForbidden)
|
||||
_, _ = w.Write([]byte("Forbidden"))
|
||||
})
|
||||
_, err := p.handleSearch(map[string]interface{}{"query": "x"})
|
||||
if err == nil {
|
||||
t.Fatal("应返回错误")
|
||||
}
|
||||
msg := err.Error()
|
||||
if !strings.Contains(msg, "403") || !strings.Contains(msg, "formats") {
|
||||
t.Errorf("403 提示应指向 json/limiter 配置，实际: %s", msg)
|
||||
}
|
||||
}
|
||||
|
||||
// 3) 空结果：要给出原因与下一步建议
|
||||
func TestSearchEmptyHint(t *testing.T) {
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
_, _ = w.Write([]byte(`{"query":"x","results":[],"suggestions":["换个词"],"unresponsive_engines":[["google","CAPTCHA"]]}`))
|
||||
})
|
||||
res, err := p.handleSearch(map[string]interface{}{"query": "x"})
|
||||
if err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
txt := res.(map[string]interface{})["content"].(string)
|
||||
for _, want := range []string{"未返回结果", "google(CAPTCHA)", "换个词", "deepsearch_news"} {
|
||||
if !strings.Contains(txt, want) {
|
||||
t.Errorf("空结果提示缺少 %q: %s", want, txt)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 4) 新闻：应带 categories=news 与 time_range=week；新闻为空时回退 general
|
||||
func TestNewsParamsAndFallback(t *testing.T) {
|
||||
var calls []url.Values
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
calls = append(calls, r.URL.Query())
|
||||
if r.URL.Query().Get("categories") == "news" {
|
||||
_, _ = w.Write([]byte(`{"query":"n","results":[]}`))
|
||||
return
|
||||
}
|
||||
_, _ = w.Write([]byte(`{"query":"n","results":[{"url":"https://a.com/1","title":"回退结果","content":"内容","engines":["brave"],"score":1}]}`))
|
||||
})
|
||||
res, err := p.handleNews(map[string]interface{}{"query": "某事"})
|
||||
if err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
if len(calls) != 2 {
|
||||
t.Fatalf("新闻为空时应回退 general，实际调用 %d 次", len(calls))
|
||||
}
|
||||
if calls[0].Get("categories") != "news" || calls[0].Get("time_range") != "week" {
|
||||
t.Errorf("首次应为 news + week，实际 categories=%q time_range=%q", calls[0].Get("categories"), calls[0].Get("time_range"))
|
||||
}
|
||||
if tmp := res.(map[string]interface{})["content"].(string); !strings.Contains(tmp, "回退结果") {
|
||||
t.Errorf("回退结果未被采用: %s", tmp)
|
||||
}
|
||||
}
|
||||
|
||||
// 5) 正文抽取：去脚本/样式/导航，保留 article
|
||||
func TestFetchExtractsArticle(t *testing.T) {
|
||||
page := `<!doctype html><html><head><title>测试标题 - 站点</title>
|
||||
<style>.x{color:red}</style><script>var secret="SHOULD_NOT_APPEAR";</script></head>
|
||||
<body><nav>导航链接</nav><article>
|
||||
<p>第一段正文，包含关键事实。</p><p>第二段正文。</p>
|
||||
</article><footer>页脚</footer></body></html>`
|
||||
var srvURL string
|
||||
p, srv := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
w.Header().Set("Content-Type", "text/html; charset=utf-8")
|
||||
_, _ = w.Write([]byte(page))
|
||||
})
|
||||
srvURL = srv.URL
|
||||
// 注意：不要用 example.com 之类真实域名——本机 DNS/proxy 会把它们转走，测试会飘
|
||||
res, err := p.handleFetch(map[string]interface{}{"url": srvURL + "/a"})
|
||||
if err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
txt := res.(map[string]interface{})["content"].(string)
|
||||
if !strings.Contains(txt, "第一段正文") {
|
||||
t.Errorf("正文丢失: %s", txt)
|
||||
}
|
||||
if strings.Contains(txt, "SHOULD_NOT_APPEAR") {
|
||||
t.Errorf("脚本内容不应出现: %s", txt)
|
||||
}
|
||||
if strings.Contains(txt, "导航链接") || strings.Contains(txt, "页脚") {
|
||||
t.Errorf("导航/页脚应被剥离: %s", txt)
|
||||
}
|
||||
if !strings.Contains(txt, "测试标题") {
|
||||
t.Errorf("标题应被提取: %s", txt)
|
||||
}
|
||||
}
|
||||
|
||||
// 6) 深检索：候选 + 正文证据；单篇失败不应导致整体失败
|
||||
func TestDeepSearch(t *testing.T) {
|
||||
var srvURL string // 处理函数先于 server 存在，故用闭包变量回填
|
||||
p, srv := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
switch r.URL.Path {
|
||||
case "/search":
|
||||
_, _ = w.Write([]byte(`{"query":"d","results":[
|
||||
{"url":"` + srvURL + `/ok1","title":"好文一","content":"摘要一","engines":["brave"],"score":3},
|
||||
{"url":"` + srvURL + `/bad","title":"打不开的","content":"摘要二","engines":["brave"],"score":2},
|
||||
{"url":"` + srvURL + `/ok2","title":"好文二","content":"摘要三","engines":["brave"],"score":1}]}`))
|
||||
case "/ok1", "/ok2":
|
||||
w.Header().Set("Content-Type", "text/html")
|
||||
_, _ = w.Write([]byte("<html><body><article><p>正文内容 " + r.URL.Path + "</p></article></body></html>"))
|
||||
case "/bad":
|
||||
w.WriteHeader(http.StatusForbidden)
|
||||
default:
|
||||
http.NotFound(w, r)
|
||||
}
|
||||
})
|
||||
srvURL = srv.URL
|
||||
res, err := p.handleDeep(map[string]interface{}{"query": "d", "top_k": float64(3), "max_chars": float64(500)})
|
||||
if err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
txt := res.(map[string]interface{})["content"].(string)
|
||||
for _, want := range []string{"候选清单", "正文证据", "正文内容 /ok1", "正文内容 /ok2", "抓取失败"} {
|
||||
if !strings.Contains(txt, want) {
|
||||
t.Errorf("深检索输出缺少 %q:\n%s", want, txt)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 7) 自检：健康检查 + 探测检索 + 引擎覆盖统计
|
||||
func TestStatusReportsEngines(t *testing.T) {
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
if r.URL.Path == "/healthz" {
|
||||
_, _ = w.Write([]byte("OK"))
|
||||
return
|
||||
}
|
||||
_, _ = w.Write([]byte(sampleResponse))
|
||||
})
|
||||
res, err := p.handleStatus(map[string]interface{}{})
|
||||
if err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
m := res.(map[string]interface{})
|
||||
if m["healthz"] != 200 {
|
||||
t.Errorf("healthz 应为 200，实际 %v", m["healthz"])
|
||||
}
|
||||
if m["search_ok"] != true {
|
||||
t.Errorf("search_ok 应为 true：%v", m["search_ok"])
|
||||
}
|
||||
engs, ok := m["engines_returning_results"].(map[string]int)
|
||||
if !ok || engs["brave"] == 0 || engs["quark"] == 0 {
|
||||
t.Errorf("引擎统计不正确: %#v", m["engines_returning_results"])
|
||||
}
|
||||
}
|
||||
|
||||
// 8) 摘要压成一行并按字符截断（避免巨长摘要吃掉上下文）
|
||||
func TestOneLineTruncate(t *testing.T) {
|
||||
got := oneLine("第一行\n第二行\t第三行", 5)
|
||||
if strings.Contains(got, "\n") {
|
||||
t.Errorf("应为单行: %q", got)
|
||||
}
|
||||
if r := []rune(got); len(r) != 6 { // 5 字符 + 省略号
|
||||
t.Errorf("截断长度不符: %q (%d runes)", got, len(r))
|
||||
}
|
||||
}
|
||||
|
||||
// 9) 正文抽取长度上限生效
|
||||
func TestHtmlToTextTruncation(t *testing.T) {
|
||||
long := strings.Repeat("字", 5000)
|
||||
_, text := htmlToText("<html><body><article><p>"+long+"</p></article></body></html>", 100)
|
||||
if !strings.Contains(text, "已截断") {
|
||||
t.Errorf("超长正文应被截断: %d", len([]rune(text)))
|
||||
}
|
||||
}
|
||||
|
||||
// 10) 非 http(s) 协议应被拒绝
|
||||
func TestFetchRejectsBadScheme(t *testing.T) {
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {})
|
||||
if _, err := p.handleFetch(map[string]interface{}{"url": "file:///etc/passwd"}); err == nil {
|
||||
t.Fatal("file:// 应被拒绝")
|
||||
}
|
||||
if _, err := p.handleFetch(map[string]interface{}{"url": "javascript:alert(1)"}); err == nil {
|
||||
t.Fatal("javascript: 应被拒绝")
|
||||
}
|
||||
}
|
||||
|
||||
// 11) raw 模式返回结构化 JSON（排查用）
|
||||
func TestSearchRawMode(t *testing.T) {
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
_, _ = w.Write([]byte(sampleResponse))
|
||||
})
|
||||
res, err := p.handleSearch(map[string]interface{}{"query": "q", "raw": true})
|
||||
if err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
m, ok := res.(*searxResponse)
|
||||
if !ok {
|
||||
t.Fatalf("raw 应返回结构化响应，实际 %T", res)
|
||||
}
|
||||
if len(m.Results) != 4 {
|
||||
t.Errorf("结果数应为 4（raw 不去重），实际 %d", len(m.Results))
|
||||
}
|
||||
if _, err := json.Marshal(m); err != nil {
|
||||
t.Errorf("结构化结果应可序列化: %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// 13) 条数截断：SearXNG 不认条数参数，插件必须自己截，并且**如实说明**给了几条
|
||||
func TestSearchTruncatesToCountAndSaysSo(t *testing.T) {
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
_, _ = w.Write([]byte(sampleResponse)) // 4 条，去重后 3 条
|
||||
})
|
||||
res, err := p.handleSearch(map[string]interface{}{"query": "deepin", "count": float64(2)})
|
||||
if err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
txt := res.(map[string]interface{})["content"].(string)
|
||||
|
||||
// 必须明确区分「命中几条」与「返回几条」：写成「命中 N 条」而实际给了 M<N 条，
|
||||
// 模型会把 N 当成拿到手的条数（实测被 agent 当成事实报给用户）。
|
||||
if !strings.Contains(txt, "命中 3 条，返回前 2 条") {
|
||||
t.Errorf("应如实说明命中数与返回数:\n%s", txt)
|
||||
}
|
||||
// 按 score 排序后的前两条：zhihu(9.5)、163(7.2)；第三条 bbs.deepin(2.0) 必须被截掉
|
||||
if !strings.Contains(txt, "统信内核开发工程师") || !strings.Contains(txt, "离谱！") {
|
||||
t.Errorf("前两条（按分数）应在:\n%s", txt)
|
||||
}
|
||||
if strings.Contains(txt, "deepin官方论坛") {
|
||||
t.Errorf("第 3 条（score 最低）超出了 count=2，不该出现:\n%s", txt)
|
||||
}
|
||||
// 条目行数也要正好 2 条（防「头部说 2 条、正文还是全量」）
|
||||
if n := strings.Count(txt, "\n http"); n != 2 {
|
||||
t.Errorf("正文应恰好 2 条，实际 %d 条:\n%s", n, txt)
|
||||
}
|
||||
}
|
||||
|
||||
// 14) 条数上限：不因为模型要 200 条就真给 200 条
|
||||
func TestLimitResultsCapsAndDefaults(t *testing.T) {
|
||||
p := &Plugin{name: "deepsearch", maxItems: 8}
|
||||
many := make([]searxResult, 30)
|
||||
for i := range many {
|
||||
many[i] = searxResult{URL: "https://e.test/", Title: "t"}
|
||||
}
|
||||
if got := len(p.limitResults(map[string]interface{}{}, many)); got != 8 {
|
||||
t.Errorf("未指定 count 时应取配置的 max_items=8，实际 %d", got)
|
||||
}
|
||||
if got := len(p.limitResults(map[string]interface{}{"count": float64(3)}, many)); got != 3 {
|
||||
t.Errorf("count=3 应返回 3 条，实际 %d", got)
|
||||
}
|
||||
if got := len(p.limitResults(map[string]interface{}{"count": float64(200)}, many)); got != maxSearchResults {
|
||||
t.Errorf("超过上限应收敛到 %d 条，实际 %d", maxSearchResults, got)
|
||||
}
|
||||
// 结果比 count 少时不能造数据
|
||||
few := many[:2]
|
||||
if got := len(p.limitResults(map[string]interface{}{"count": float64(5)}, few)); got != 2 {
|
||||
t.Errorf("结果不足时应原样返回，实际 %d", got)
|
||||
}
|
||||
}
|
||||
@ -1,164 +0,0 @@
|
||||
package main
|
||||
|
||||
// SearXNG 生命周期托管：插件启动时拉起搜索后端，插件停止时关闭它。
|
||||
//
|
||||
// 契约依据（内核侧 internal/plugin/proc/*，已逐行核对）：
|
||||
// - 内核停止插件：发 `plugin.stop` → 插件先跑 RunStopHandlers（LIFO、幂等）→ 再 Stop() → exit(0)
|
||||
// - 若插件未在 stopGracePeriod（**5 秒**）内退出，内核直接 SIGKILL
|
||||
// - stdin 关闭（内核消失）同样会跑 handlers + Stop()
|
||||
//
|
||||
// 因此这里的关闭动作必须**有界**：searxShutdownBudget 取 4s，留 1s 余量。
|
||||
//
|
||||
// 归属规则（谁拉起谁关）：**只有本插件真正执行了 `docker compose up -d` 的实例才算「我们起的」**。
|
||||
// 探活发现已在运行的实例只「接管」——不认领关闭责任。否则同一台机器上的第二个实例
|
||||
// （E2E 测试拉起的插件、另一个 daemon）退出时会把生产后端一起带走：实测就是这条把
|
||||
// 线上搜索服务反复关停的（测试实例用默认配置，测试结束就 `docker compose stop`）。
|
||||
// 若插件是被 kill -9 / OOM 带走的，关闭动作不会执行 —— SearXNG 会留在运行态；
|
||||
// 下次 Start 探测到它在跑就直接接管，这是更安全的失败方向。
|
||||
|
||||
import (
|
||||
"context"
|
||||
"log"
|
||||
"net/http"
|
||||
"os/exec"
|
||||
"time"
|
||||
)
|
||||
|
||||
const (
|
||||
cfgManageSearx = "manage_searxng"
|
||||
cfgSearxDir = "searxng_dir"
|
||||
cfgStopOnExit = "stop_searxng_on_exit"
|
||||
|
||||
defaultSearxDir = "/root/searxng-agent"
|
||||
|
||||
searxProbeTimeout = 1500 * time.Millisecond // 单次 healthz 探测
|
||||
searxUpBudget = 20 * time.Second // docker compose up -d 的上限（正常 1s 内返回）
|
||||
searxReadyBudget = 6 * time.Second // up 之后等 healthz 就绪的上限
|
||||
searxShutdownBudget = 4 * time.Second // 必须 < 内核 5s 宽限期
|
||||
)
|
||||
|
||||
// searxBudget 把四个时间预算收拢，便于单测注入短值（否则测试要真等就绪窗口）。
|
||||
type searxBudget struct {
|
||||
probe time.Duration
|
||||
up time.Duration
|
||||
ready time.Duration
|
||||
shutdown time.Duration
|
||||
}
|
||||
|
||||
func (p *Plugin) budget() searxBudget {
|
||||
b := p.bud
|
||||
if b.probe == 0 {
|
||||
b.probe = searxProbeTimeout
|
||||
}
|
||||
if b.up == 0 {
|
||||
b.up = searxUpBudget
|
||||
}
|
||||
if b.ready == 0 {
|
||||
b.ready = searxReadyBudget
|
||||
}
|
||||
if b.shutdown == 0 {
|
||||
b.shutdown = searxShutdownBudget
|
||||
}
|
||||
return b
|
||||
}
|
||||
|
||||
// cmdRunner 抽出来是为了让生命周期逻辑可单测：注入假执行器，不起真容器。
|
||||
type cmdRunner func(ctx context.Context, dir, name string, args ...string) (string, error)
|
||||
|
||||
func defaultRunner(ctx context.Context, dir, name string, args ...string) (string, error) {
|
||||
cmd := exec.CommandContext(ctx, name, args...)
|
||||
cmd.Dir = dir
|
||||
out, err := cmd.CombinedOutput()
|
||||
return string(out), err
|
||||
}
|
||||
|
||||
// searxReachable 探测搜索后端是否可用（只看 healthz，不发检索请求）。
|
||||
func (p *Plugin) searxReachable(timeout time.Duration) bool {
|
||||
if p.searxURL == "" {
|
||||
return false
|
||||
}
|
||||
base := p.http
|
||||
if base == nil {
|
||||
base = &http.Client{}
|
||||
}
|
||||
cl := *base // 复制一份，避免改到共享 client 的超时
|
||||
cl.Timeout = timeout
|
||||
req, err := http.NewRequest(http.MethodGet, p.searxURL+"/healthz", nil)
|
||||
if err != nil {
|
||||
return false
|
||||
}
|
||||
req.Header.Set("User-Agent", p.userAgent)
|
||||
resp, err := cl.Do(req)
|
||||
if err != nil {
|
||||
return false
|
||||
}
|
||||
defer resp.Body.Close()
|
||||
return resp.StatusCode < 400
|
||||
}
|
||||
|
||||
// ensureSearxng 在插件启动时确保搜索后端在跑；已在跑则直接接管，不重启。
|
||||
func (p *Plugin) ensureSearxng() {
|
||||
b := p.budget()
|
||||
if !p.manageSearx {
|
||||
log.Printf("[%s] 未启用 SearXNG 托管（manage_searxng=false），假定 %s 由外部维护", p.name, p.searxURL)
|
||||
return
|
||||
}
|
||||
if p.searxReachable(b.probe) {
|
||||
// 只接管，不认领：不是我们拉起来的，就不能由我们关掉
|
||||
log.Printf("[%s] SearXNG 已在运行（%s），直接接管（不认领关闭责任）", p.name, p.searxURL)
|
||||
return
|
||||
}
|
||||
ctx, cancel := context.WithTimeout(context.Background(), b.up)
|
||||
out, err := p.run(ctx, p.searxDir, "docker", "compose", "up", "-d")
|
||||
cancel()
|
||||
if err != nil {
|
||||
log.Printf("[%s] 拉起 SearXNG 失败（dir=%s，请检查 manage_searxng/searxng_dir 配置）: %v；输出: %s",
|
||||
p.name, p.searxDir, err, oneLine(out, 300))
|
||||
return
|
||||
}
|
||||
log.Printf("[%s] 已执行 docker compose up -d（%s）：%s", p.name, p.searxDir, oneLine(out, 200))
|
||||
|
||||
deadline := time.Now().Add(b.ready)
|
||||
for time.Now().Before(deadline) {
|
||||
if p.searxReachable(800 * time.Millisecond) {
|
||||
log.Printf("[%s] SearXNG 就绪", p.name)
|
||||
p.markSearxOwned()
|
||||
return
|
||||
}
|
||||
time.Sleep(600 * time.Millisecond)
|
||||
}
|
||||
log.Printf("[%s] SearXNG 已启动但 %s 内未就绪；首次检索会自动等待", p.name, b.ready)
|
||||
p.markSearxOwned()
|
||||
}
|
||||
|
||||
func (p *Plugin) markSearxOwned() {
|
||||
p.searxMu.Lock()
|
||||
p.searxOwned = true
|
||||
p.searxMu.Unlock()
|
||||
}
|
||||
|
||||
// shutdownSearxng 关闭搜索后端。幂等，且有界（内核宽限期 5s，这里最多 4s）。
|
||||
func (p *Plugin) shutdownSearxng() {
|
||||
b := p.budget()
|
||||
p.searxMu.Lock()
|
||||
owned := p.searxOwned
|
||||
p.searxOwned = false
|
||||
p.searxMu.Unlock()
|
||||
|
||||
if !owned {
|
||||
return // 不是我们拉起来的 / 已经关过
|
||||
}
|
||||
if !p.manageSearx || !p.stopOnExit {
|
||||
log.Printf("[%s] 保留 SearXNG 运行（stop_searxng_on_exit=false）", p.name)
|
||||
return
|
||||
}
|
||||
ctx, cancel := context.WithTimeout(context.Background(), b.shutdown)
|
||||
defer cancel()
|
||||
out, err := p.run(ctx, p.searxDir, "docker", "compose", "stop", "-t", "2")
|
||||
if err != nil {
|
||||
// 故意只记日志：这里再重试就会拖过内核宽限期，被 SIGKILL 更糟
|
||||
log.Printf("[%s] 关闭 SearXNG 失败（忽略）: %v；输出: %s", p.name, err, oneLine(out, 200))
|
||||
return
|
||||
}
|
||||
log.Printf("[%s] 已关闭 SearXNG", p.name)
|
||||
}
|
||||
@ -1,223 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"context"
|
||||
"errors"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"strings"
|
||||
"sync"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
type fakeCall struct {
|
||||
dir string
|
||||
name string
|
||||
args []string
|
||||
}
|
||||
|
||||
func (c fakeCall) String() string { return c.name + " " + strings.Join(c.args, " ") }
|
||||
|
||||
// newFakeRunner 记录调用并返回预设结果
|
||||
func newFakeRunner(calls *[]fakeCall, out string, err error) cmdRunner {
|
||||
var mu sync.Mutex
|
||||
return func(ctx context.Context, dir, name string, args ...string) (string, error) {
|
||||
mu.Lock()
|
||||
*calls = append(*calls, fakeCall{dir: dir, name: name, args: args})
|
||||
mu.Unlock()
|
||||
return out, err
|
||||
}
|
||||
}
|
||||
|
||||
// fastBudget 把就绪窗口压到毫秒级，避免单测真等
|
||||
func fastBudget() searxBudget {
|
||||
return searxBudget{
|
||||
probe: 50 * time.Millisecond,
|
||||
up: time.Second,
|
||||
ready: 200 * time.Millisecond,
|
||||
shutdown: time.Second,
|
||||
}
|
||||
}
|
||||
|
||||
// 1) 后端没跑 → 应执行 docker compose up -d，并认领关闭责任
|
||||
func TestEnsureSearxngStartsWhenUnreachable(t *testing.T) {
|
||||
var calls []fakeCall
|
||||
p := &Plugin{
|
||||
name: "deepsearch", searxURL: "http://127.0.0.1:1", searxDir: "/tmp/fake-searx",
|
||||
manageSearx: true, stopOnExit: true, userAgent: "test",
|
||||
bud: fastBudget(), run: newFakeRunner(&calls, "Container searxng-agent Started", nil),
|
||||
}
|
||||
p.ensureSearxng()
|
||||
|
||||
if len(calls) != 1 {
|
||||
t.Fatalf("应恰好拉起一次，实际 %d 次：%v", len(calls), calls)
|
||||
}
|
||||
got := calls[0]
|
||||
if got.name != "docker" || strings.Join(got.args, " ") != "compose up -d" {
|
||||
t.Errorf("命令不对：%s", got)
|
||||
}
|
||||
if got.dir != "/tmp/fake-searx" {
|
||||
t.Errorf("工作目录应为配置的 compose 目录，实际 %q", got.dir)
|
||||
}
|
||||
if !p.searxOwned {
|
||||
t.Error("既然是我们拉起的，就应认领关闭责任")
|
||||
}
|
||||
}
|
||||
|
||||
// 2) 后端已在跑 → 不重启，**且不认领关闭责任**
|
||||
//
|
||||
// 这条是关键：同一台机器上会有第二个实例（E2E 测试拉起的插件、另一个 daemon）。
|
||||
// 如果「接管」也算「我拥有」，任一实例退出就会把生产后端关掉 —— 线上实测就是
|
||||
// 测试实例在 teardown 时 `docker compose stop`，把搜索服务反复关停。
|
||||
func TestEnsureSearxngAdoptsRunningBackendWithoutOwning(t *testing.T) {
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
if r.URL.Path == "/healthz" {
|
||||
_, _ = w.Write([]byte("OK"))
|
||||
return
|
||||
}
|
||||
http.NotFound(w, r)
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
var calls []fakeCall
|
||||
p := &Plugin{
|
||||
name: "deepsearch", searxURL: srv.URL, searxDir: "/tmp/fake-searx",
|
||||
manageSearx: true, stopOnExit: true, userAgent: "test",
|
||||
bud: fastBudget(), run: newFakeRunner(&calls, "", nil),
|
||||
}
|
||||
p.ensureSearxng()
|
||||
|
||||
if len(calls) != 0 {
|
||||
t.Errorf("已在跑就不该重启它，实际执行了：%v", calls)
|
||||
}
|
||||
if p.searxOwned {
|
||||
t.Error("不是我们拉起的，就不能认领关闭责任（否则退出时会带走别人的后端）")
|
||||
}
|
||||
}
|
||||
|
||||
// 2b) 接管的实例退出时，一个 docker 命令都不能发
|
||||
func TestAdoptedBackendSurvivesShutdown(t *testing.T) {
|
||||
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
|
||||
_, _ = w.Write([]byte("OK"))
|
||||
}))
|
||||
defer srv.Close()
|
||||
|
||||
var calls []fakeCall
|
||||
p := &Plugin{
|
||||
name: "deepsearch", searxURL: srv.URL, searxDir: "/tmp/fake-searx",
|
||||
manageSearx: true, stopOnExit: true, userAgent: "test",
|
||||
bud: fastBudget(), run: newFakeRunner(&calls, "", nil),
|
||||
}
|
||||
p.ensureSearxng()
|
||||
if err := p.Stop(); err != nil {
|
||||
t.Fatalf("Stop: %v", err)
|
||||
}
|
||||
if len(calls) != 0 {
|
||||
t.Errorf("接管来的后端在退出时必须留着，实际执行了：%v", calls)
|
||||
}
|
||||
}
|
||||
|
||||
// 3) 关掉托管 → 完全不碰 docker
|
||||
func TestEnsureSearxngDisabled(t *testing.T) {
|
||||
var calls []fakeCall
|
||||
p := &Plugin{
|
||||
name: "deepsearch", searxURL: "http://127.0.0.1:1", searxDir: "/tmp/fake-searx",
|
||||
manageSearx: false, stopOnExit: true, userAgent: "test",
|
||||
bud: fastBudget(), run: newFakeRunner(&calls, "", nil),
|
||||
}
|
||||
p.ensureSearxng()
|
||||
if len(calls) != 0 || p.searxOwned {
|
||||
t.Errorf("manage_searxng=false 时不该有任何动作：calls=%v owned=%v", calls, p.searxOwned)
|
||||
}
|
||||
}
|
||||
|
||||
// 4) 拉起失败不能让插件起不来（记日志即可）
|
||||
func TestEnsureSearxngFailureNonFatal(t *testing.T) {
|
||||
var calls []fakeCall
|
||||
p := &Plugin{
|
||||
name: "deepsearch", searxURL: "http://127.0.0.1:1", searxDir: "/tmp/fake-searx",
|
||||
manageSearx: true, stopOnExit: true, userAgent: "test",
|
||||
bud: fastBudget(), run: newFakeRunner(&calls, "Cannot connect to the Docker daemon", errors.New("exit status 1")),
|
||||
}
|
||||
p.ensureSearxng() // 不应 panic
|
||||
if p.searxOwned {
|
||||
t.Error("没拉起来就不该认领关闭责任（否则停止时会去关一个不是我们起的服务）")
|
||||
}
|
||||
}
|
||||
|
||||
// 5) 停止：关掉我们拉起的后端，且幂等
|
||||
func TestShutdownStopsOwnedBackend(t *testing.T) {
|
||||
var calls []fakeCall
|
||||
runner := newFakeRunner(&calls, "ok", nil)
|
||||
p := &Plugin{
|
||||
name: "deepsearch", searxURL: "http://127.0.0.1:1", searxDir: "/tmp/fake-searx",
|
||||
manageSearx: true, stopOnExit: true, userAgent: "test",
|
||||
bud: fastBudget(), run: runner,
|
||||
}
|
||||
p.ensureSearxng()
|
||||
calls = nil
|
||||
|
||||
p.shutdownSearxng()
|
||||
if len(calls) != 1 {
|
||||
t.Fatalf("应执行一次 compose stop，实际 %v", calls)
|
||||
}
|
||||
if got := strings.Join(calls[0].args, " "); !strings.HasPrefix(got, "compose stop") {
|
||||
t.Errorf("停止命令不对：%s", got)
|
||||
}
|
||||
if p.searxOwned {
|
||||
t.Error("停止后应清掉认领标记")
|
||||
}
|
||||
|
||||
p.shutdownSearxng() // 幂等：不应再调一次
|
||||
if len(calls) != 1 {
|
||||
t.Errorf("重复停止应无副作用，实际 %v", calls)
|
||||
}
|
||||
}
|
||||
|
||||
// 6) 不是我们拉起的 → 停止时不许动它
|
||||
func TestShutdownSkippedWhenNotOwned(t *testing.T) {
|
||||
var calls []fakeCall
|
||||
p := &Plugin{
|
||||
name: "deepsearch", searxDir: "/tmp/fake-searx", manageSearx: true, stopOnExit: true,
|
||||
bud: fastBudget(), run: newFakeRunner(&calls, "", nil),
|
||||
}
|
||||
p.shutdownSearxng()
|
||||
if len(calls) != 0 {
|
||||
t.Errorf("不该去停一个我们没起的服务：%v", calls)
|
||||
}
|
||||
}
|
||||
|
||||
// 7) 配了「停止时保留」→ 认领过也不关
|
||||
func TestShutdownKeepsBackendWhenConfigured(t *testing.T) {
|
||||
var calls []fakeCall
|
||||
p := &Plugin{
|
||||
name: "deepsearch", searxURL: "http://127.0.0.1:1", searxDir: "/tmp/fake-searx",
|
||||
manageSearx: true, stopOnExit: false, userAgent: "test",
|
||||
bud: fastBudget(), run: newFakeRunner(&calls, "", nil),
|
||||
}
|
||||
p.ensureSearxng()
|
||||
calls = nil
|
||||
p.shutdownSearxng()
|
||||
if len(calls) != 0 {
|
||||
t.Errorf("stop_searxng_on_exit=false 时不应关闭：%v", calls)
|
||||
}
|
||||
}
|
||||
|
||||
// 8) Stop() 自身也要收尾（内核 stdin 关闭路径不会走 stop handler 的注册顺序之外）
|
||||
func TestStopTriggersShutdown(t *testing.T) {
|
||||
var calls []fakeCall
|
||||
p := &Plugin{
|
||||
name: "deepsearch", searxURL: "http://127.0.0.1:1", searxDir: "/tmp/fake-searx",
|
||||
manageSearx: true, stopOnExit: true, userAgent: "test",
|
||||
bud: fastBudget(), run: newFakeRunner(&calls, "", nil),
|
||||
}
|
||||
p.ensureSearxng()
|
||||
calls = nil
|
||||
if err := p.Stop(); err != nil {
|
||||
t.Fatalf("Stop 返回错误: %v", err)
|
||||
}
|
||||
if len(calls) != 1 {
|
||||
t.Errorf("Stop 应触发一次关闭，实际 %v", calls)
|
||||
}
|
||||
}
|
||||
@ -1,49 +0,0 @@
|
||||
# editdoc · Office 文档编辑
|
||||
|
||||
编辑 `.docx` / `.xlsx` / `.pptx` 内容：查找替换、改单元格、插行。
|
||||
|
||||
> ⚠️ **版本说明**：本目录是 **v1.0.0**，只有 `edit_document` 一个工具。
|
||||
> 线上部署的 v2.0.0（全能办公版，支持新建/读取/转换 docx·xlsx·pptx·md·csv·txt）
|
||||
> **源码尚未公开**，本文档不描述那些能力。参见 `plugin.json` 的 `version`。
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `edit_document` | 编辑文档内容，**编辑后原文件被覆盖** |
|
||||
|
||||
参数：
|
||||
|
||||
| 参数 | 说明 |
|
||||
|---|---|
|
||||
| `file` | 文档路径（必填） |
|
||||
| `operation` | `replace_text`（查找替换）/ `set_cell`（设置单元格）/ `insert_row`（插入行）（必填） |
|
||||
| `target` | 要查找的文本（`replace_text` 用） |
|
||||
| `replacement` | 替换为的文本（`replace_text` 用） |
|
||||
| `sheet` | 工作表名（xlsx 可选） |
|
||||
| `row` | 行号（`set_cell` / `insert_row` 用） |
|
||||
| `col` | 列号（`set_cell` 用） |
|
||||
| `value` | 单元格值（`set_cell` 用） |
|
||||
|
||||
编辑前建议先读一遍内容确认目标文本 —— 查找替换是**全文件覆盖写**，没有撤销。
|
||||
|
||||
## 配置项
|
||||
|
||||
| 键 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `script_path` | 空 | `edit_doc.py` 的绝对路径。留空则用插件可执行文件同目录下的 `edit_doc.py` |
|
||||
| `venv_python` | 空 | 执行 `edit_doc.py` 的 Python 解释器（建议用 venv 里的）。**必须配置，留空会报错** |
|
||||
|
||||
## 工作原理
|
||||
|
||||
本插件是 Go 写的薄壳：把参数序列化成 JSON，交给 Python 脚本 `edit_doc.py` 执行实际文档操作。
|
||||
文档解析依赖 Python 侧的库（python-docx / openpyxl / python-pptx 之类），所以：
|
||||
|
||||
- **需要自备 `edit_doc.py`**：它不在本目录里。
|
||||
- 用 `venv_python` 指向装了这些库的解释器，避免污染系统 Python。
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
```
|
||||
@ -1,44 +0,0 @@
|
||||
# files · 沙箱文件操作
|
||||
|
||||
读写与编辑文件，**全部操作限制在沙箱目录内**。
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `files_read` | 读文件内容，支持 `offset` / `limit` 读大文件 |
|
||||
| `files_write` | 写文件，**自动创建父目录** |
|
||||
| `files_edit` | 按精确字符串替换改文件 |
|
||||
| `files_ls` | 列目录（目录名带 `/` 后缀） |
|
||||
|
||||
`files_edit` 用 `edits[]` 传多组替换，每组 `{old, new}`：
|
||||
|
||||
- 每个 `old` 必须在**原文件**中**恰好出现一次** —— 不唯一会报错，避免改错地方。
|
||||
- 所有替换都针对**原内容**匹配，不要在同一个 `edits` 里写相互重叠的改动。
|
||||
|
||||
## 配置项
|
||||
|
||||
| 键 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `dir` | 空 | 允许访问的根目录。留空用默认沙箱（主数据目录下的 `files_sandbox`）。**不建议设为 `/`** |
|
||||
|
||||
## 沙箱实现
|
||||
|
||||
路径校验不止一次，是两道：
|
||||
|
||||
1. **规范化后判断**：`filepath.Abs` + `filepath.Clean`，再用 `withinSandbox`
|
||||
检查结果是否在根目录之下（`/` 作为特例放行）。
|
||||
2. **解析符号链接后再判断**：`filepath.EvalSymlinks` 求出真实路径，**再查一次**沙箱。
|
||||
|
||||
第 2 步是关键：只做第 1 步的话，沙箱内一个指向外部的软链接就能绕过限制
|
||||
（`.../sandbox/link -> /etc`）。报错文案也区分了这两种情况
|
||||
（`path outside sandbox` vs `path escapes sandbox via symlink`）。
|
||||
|
||||
对不存在的路径（`write` 会用到），求真实路径时只对已存在的部分做 `EvalSymlinks`，
|
||||
其余保留为未创建的尾部。
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
```
|
||||
@ -1,16 +1,13 @@
|
||||
# luademo
|
||||
|
||||
Lua 插件全功能示例，展示 Lua SDK 的完整能力面（对齐 SDK 1.3.0）：
|
||||
Lua 插件全功能示例，展示 v0.8.0 Lua SDK 的完整能力面：
|
||||
|
||||
- **工具注册**：`no_memory` + `context_policy` + `cleaner`（记忆计算层过滤）
|
||||
- **工具注册**：`no_memory` + `cleaner`（记忆计算层过滤）
|
||||
- **阶段钩子**：`register_stage(stage, handler, scope)`，`own_tools` 与全局作用域
|
||||
- **通道**：`register_output_channel` / `register_input_channel` / `unregister_output_channel`（def 支持 no_memory/context_policy/cleaner）
|
||||
- **注入**：`inject_text` / `inject_interrupt` / `inject_text_no_memory`、`*_opts`（no_memory/context_policy/cleaner_name/priority）、`inject_input_sync`、`inject_*_media`、`set_tool_blocks`
|
||||
- **数据类 API**：`sdk.memory.*`（含 sentence_text/media_digests）、`sdk.doc.*`（含 insert_with_media）、`sdk.knowledge.*`、`sdk.text_memory.*`（含 attachments）、`sdk.llm.*`、`sdk.settings.*`、`sdk.social.*`、`sdk.events.*`、`sdk.plugin_mgr.*`
|
||||
- **通道**：`register_output_channel` / `register_input_channel`（def 支持 no_memory/cleaner）
|
||||
- **数据类 API**：`sdk.memory.*`、`sdk.doc.*`、`sdk.knowledge.*`、`sdk.text_memory.*`、`sdk.llm.*`、`sdk.settings.*`、`sdk.social.*`
|
||||
- **其他**：`register_api`、`set_auto_restart`
|
||||
|
||||
> `luademo_probe_v2` 巡检 1.1/1.2/1.3 新增面。它**故意不调用** `inject_input_sync`：工具 handler 在 LLM 回合内运行，同步注入会自己等自己（死锁）。
|
||||
|
||||
## 本地独立测试
|
||||
|
||||
```bash
|
||||
@ -20,7 +17,7 @@ lua main.lua # 使用 sdk.lua mock，不依赖内核
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
plugindev build
|
||||
```
|
||||
|
||||
## 安装
|
||||
|
||||
@ -67,65 +67,6 @@ function plugin.start(sdk)
|
||||
return { content = res }
|
||||
end)
|
||||
|
||||
-- 工具：1.1/1.2/1.3 新增能力巡检（媒体块 / 注入标志位 / 事件 / 动态通道注销）
|
||||
-- 注意：故意不在这里调用 sdk.inject_input_sync——工具handler 运行在 LLM 回合内，
|
||||
-- 同步注入会等本轮回复，等于自己等自己（死锁）。同步注入只适合事件回调等外部入口。
|
||||
sdk.register_tool("luademo_probe_v2", {
|
||||
description = "Exercise media blocks, inject opts, events and channel unregister",
|
||||
parameters = { type = "object", properties = {} },
|
||||
no_memory = true,
|
||||
context_policy = "prune",
|
||||
}, function(args)
|
||||
local res = {}
|
||||
|
||||
-- 多模态：设置下一轮 tool message 携带的内容块
|
||||
sdk.set_tool_blocks({
|
||||
{ type = "text", text = "luademo media block" },
|
||||
{ type = "image_url", image_url = { url = "https://example.com/x.png", detail = "low" } },
|
||||
})
|
||||
res.set_tool_blocks = "ok"
|
||||
|
||||
-- 注入标志位（零值 opts 与旧三参数等价）
|
||||
sdk.inject_text_opts("luademo", "luademo_in", "opts inject", {
|
||||
no_memory = true, context_policy = "prune",
|
||||
})
|
||||
res.inject_text_opts = "ok"
|
||||
|
||||
-- 带媒体的中断注入
|
||||
sdk.inject_interrupt_media("luademo", "luademo_in", "media inject", {
|
||||
{ type = "audio_url", audio_url = { url = "https://example.com/a.mp3" } },
|
||||
})
|
||||
res.inject_interrupt_media = "ok"
|
||||
|
||||
-- 媒体入记忆：三元组带原句，文档带附件
|
||||
local _, merr = sdk.memory.commit({{
|
||||
subject = "luademo", relation = "shows", object = "image",
|
||||
sentence_text = "luademo shows an image", media_digests = {},
|
||||
}})
|
||||
res.memory_commit_with_sentence = { err = merr }
|
||||
local _, derr = sdk.doc.insert_with_media(
|
||||
{ id = "luademo-media", title = "media", content = "with attachment" },
|
||||
{ { mime = "image/png", name = "x.png", data = "aGVsbG8=" } })
|
||||
res.doc_insert_with_media = { err = derr }
|
||||
|
||||
-- 事件订阅（返回取消订阅函数）
|
||||
local unsub = sdk.events.subscribe("agent_output", function(evt)
|
||||
sdk.log("info", "luademo event: " .. tostring(evt.type))
|
||||
end)
|
||||
res.events_subscribe = type(unsub)
|
||||
if unsub then unsub() end
|
||||
|
||||
-- 插件管理（只读查询）
|
||||
res.plugin_mgr_loaded = type(sdk.plugin_mgr.list_loaded())
|
||||
|
||||
-- 动态输出通道注销
|
||||
sdk.register_output_channel("luademo_dyn", 0, "dynamic", {}, function(a) return { ok = true } end)
|
||||
local _, uerr = sdk.unregister_output_channel("luademo_dyn")
|
||||
res.unregister = { err = uerr }
|
||||
|
||||
return { content = res }
|
||||
end)
|
||||
|
||||
-- 阶段钩子：own_tools 作用域（仅本插件工具被调用时触发）
|
||||
sdk.register_stage("before_toolcall", function(ctx)
|
||||
local calls = ctx.tool_calls or {}
|
||||
|
||||
@ -1,413 +1,67 @@
|
||||
-- HomeAgent Lua Plugin SDK
|
||||
-- Interface contract between Lua plugins and HomeAgent kernel.
|
||||
-- !impl functions are replaced by Go implementations at runtime.
|
||||
-- Standalone/debug: pure Lua mock implementations are used.
|
||||
-- Usage: local sdk = require("sdk")
|
||||
|
||||
-- HomeAgent Lua Plugin SDK (standalone mock)
|
||||
sdk = {}
|
||||
|
||||
-- !impl
|
||||
-- level: "debug" | "info" | "warn" | "error"
|
||||
function sdk.log(level, msg)
|
||||
print("[lua-plugin] " .. tostring(level) .. ": " .. tostring(msg))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- def: { description="...", parameters={...}, no_memory=true/false, cleaner=function(text)->text }
|
||||
-- handler: function(args) -> result
|
||||
function sdk.register_tool(name, def, handler)
|
||||
print("[lua-plugin] register_tool: " .. tostring(name))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- stage: "on_input" | "pre_action" | "post_action" | ...
|
||||
-- scope: nil/"global" (默认) | "own_tools"（仅 before_toolcall/after_toolcall 且工具属于本插件时触发）
|
||||
function sdk.register_stage(stage, handler, scope)
|
||||
print("[lua-plugin] register_stage: " .. tostring(stage) .. " scope=" .. tostring(scope))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.register_api(name)
|
||||
print("[lua-plugin] register_api: " .. tostring(name))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- def: { no_memory=true/false, cleaner=function(text)->text }
|
||||
-- handler: function(args) -> result
|
||||
function sdk.register_output_channel(name, caps, desc, def, handler)
|
||||
print("[lua-plugin] register_output_channel: " .. tostring(name))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- def: { no_memory=true/false, cleaner=function(text)->text }
|
||||
function sdk.register_input_channel(name, def)
|
||||
print("[lua-plugin] register_input_channel: " .. tostring(name))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.get_setting(key)
|
||||
return nil
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.set_setting(key, value)
|
||||
print("[lua-plugin] set_setting: " .. tostring(key))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_text(source, channel, text)
|
||||
print("[lua-plugin] inject_text: " .. tostring(source) .. "/" .. tostring(channel))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_interrupt(source, channel, text)
|
||||
print("[lua-plugin] inject_interrupt: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_text_no_memory(source, channel, text)
|
||||
print("[lua-plugin] inject_text_no_memory: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- opts: { no_memory=bool, context_policy="none"|"prune", cleaner_name=string, priority="L1".."L3" }
|
||||
-- 零值/缺省 = 记入记忆 + 不裁剪（与三参数版本等价）。
|
||||
function sdk.inject_text_opts(source, channel, text, opts)
|
||||
print("[lua-plugin] inject_text_opts: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_interrupt_opts(source, channel, text, opts)
|
||||
print("[lua-plugin] inject_interrupt_opts: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- 同步注入在 Lua 插件中**不可用**：会等本轮回复，而本轮正持有插件锁 ⇒ 必然自锁。
|
||||
-- 真实内核里恒返回 (nil, err)；这里返回同样的错误，避免离线测试误以为可用。
|
||||
function sdk.inject_input_sync(source, channel, text)
|
||||
return nil, "同步注入在 Lua 插件中不可用：请在事件回调/外部入口用 inject_text/inject_interrupt；确需同步等待请改用 Go 插件。"
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_input_sync_opts(source, channel, text, opts)
|
||||
return nil, "同步注入在 Lua 插件中不可用：请在事件回调/外部入口用 inject_text/inject_interrupt；确需同步等待请改用 Go 插件。"
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- blocks: ContentBlock 数组，见 sdk.inject_input_media。
|
||||
-- 设置下一轮 tool message 携带的多模态内容块（模型据此看图/听音频）。
|
||||
function sdk.set_tool_blocks(blocks)
|
||||
print("[lua-plugin] set_tool_blocks: " .. tostring(blocks and #blocks or 0))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- blocks 每项：{ type="text", text="..." }
|
||||
-- | { type="image_url", image_url={ url="...", detail="high" } }
|
||||
-- | { type="audio_url", audio_url={ url="..." } }
|
||||
function sdk.inject_input_media(source, channel, text, blocks)
|
||||
print("[lua-plugin] inject_input_media: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_input_media_opts(source, channel, text, blocks, opts)
|
||||
print("[lua-plugin] inject_input_media_opts: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- 同 sdk.inject_input_sync：Lua 中不可用。
|
||||
function sdk.inject_input_media_sync(source, channel, text, blocks)
|
||||
return nil, "同步注入在 Lua 插件中不可用：请在事件回调/外部入口用 inject_input_media；确需同步等待请改用 Go 插件。"
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_input_media_sync_opts(source, channel, text, blocks, opts)
|
||||
return nil, "同步注入在 Lua 插件中不可用：请在事件回调/外部入口用 inject_input_media_opts；确需同步等待请改用 Go 插件。"
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_interrupt_media(source, channel, text, blocks)
|
||||
print("[lua-plugin] inject_interrupt_media: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_interrupt_media_opts(source, channel, text, blocks, opts)
|
||||
print("[lua-plugin] inject_interrupt_media_opts: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- 注销输出通道（随资源生灭的动态通道，如远程设备）。返回 (nil, err)。
|
||||
function sdk.unregister_output_channel(name) return nil, nil end
|
||||
|
||||
-- !impl
|
||||
-- enabled: true/false，崩溃时内核自动拉起
|
||||
function sdk.set_auto_restart(enabled)
|
||||
print("[lua-plugin] set_auto_restart: " .. tostring(enabled))
|
||||
end
|
||||
|
||||
-- ============ graph memory ============
|
||||
-- !impl
|
||||
function sdk.log(level, msg) print("[lua-plugin] " .. tostring(level) .. ": " .. tostring(msg)) end
|
||||
function sdk.register_tool(name, def, handler) print("[lua-plugin] register_tool: " .. tostring(name)) end
|
||||
function sdk.register_stage(stage, handler, scope) print("[lua-plugin] register_stage: " .. tostring(stage) .. " scope=" .. tostring(scope)) end
|
||||
function sdk.register_api(name) print("[lua-plugin] register_api: " .. tostring(name)) end
|
||||
function sdk.register_output_channel(name, caps, desc, def, handler) print("[lua-plugin] register_output_channel: " .. tostring(name)) end
|
||||
function sdk.register_input_channel(name, def) print("[lua-plugin] register_input_channel: " .. tostring(name)) end
|
||||
function sdk.get_setting(key) return nil end
|
||||
function sdk.set_setting(key, value) print("[lua-plugin] set_setting: " .. tostring(key)) end
|
||||
function sdk.inject_text(source, channel, text) print("[lua-plugin] inject_text: " .. tostring(source)) end
|
||||
function sdk.inject_interrupt(source, channel, text) print("[lua-plugin] inject_interrupt: " .. tostring(source)) end
|
||||
function sdk.inject_text_no_memory(source, channel, text) print("[lua-plugin] inject_text_no_memory: " .. tostring(source)) end
|
||||
function sdk.set_auto_restart(enabled) print("[lua-plugin] set_auto_restart: " .. tostring(enabled)) end
|
||||
sdk.memory = {}
|
||||
-- !impl
|
||||
-- query: string, depth: number -> {entities={...}, relations={...}}
|
||||
function sdk.memory.recall(query, depth) return {entities={}, relations={}} end
|
||||
-- !impl
|
||||
-- triples: { {subject=, relation=, object=, [confidence=], [sentence_text=]} } -> err
|
||||
function sdk.memory.commit(triples) return nil end
|
||||
-- !impl
|
||||
function sdk.memory.introspect() return {} end
|
||||
-- !impl
|
||||
function sdk.memory.merge(source, target) return 0 end
|
||||
-- !impl
|
||||
-- criteria: {key=value}, hard: boolean
|
||||
function sdk.memory.purge(criteria, hard) return 0 end
|
||||
|
||||
-- ============ document memory ============
|
||||
-- !impl
|
||||
sdk.doc = {}
|
||||
-- !impl
|
||||
function sdk.doc.query(text, top_k) return {} end
|
||||
-- !impl
|
||||
-- doc: { id=, title=, content= }
|
||||
function sdk.doc.insert(doc) return nil end
|
||||
-- !impl
|
||||
-- attachments 每项：{ digest=, mime=, name=, data=<base64> }
|
||||
function sdk.doc.insert_with_media(doc, attachments) return nil end
|
||||
-- !impl
|
||||
function sdk.doc.remove(id) return nil end
|
||||
-- !impl
|
||||
function sdk.doc.stats() return {} end
|
||||
|
||||
-- ============ knowledge ============
|
||||
-- !impl
|
||||
sdk.knowledge = {}
|
||||
-- !impl
|
||||
function sdk.knowledge.search(query, limit) return {} end
|
||||
-- !impl
|
||||
function sdk.knowledge.add(tag, content) return nil end
|
||||
-- !impl
|
||||
function sdk.knowledge.list() return {} end
|
||||
|
||||
-- ============ text memory ============
|
||||
-- !impl
|
||||
sdk.text_memory = {}
|
||||
-- !impl
|
||||
-- evt: { timestamp=, role=, content=, channel= }
|
||||
function sdk.text_memory.append(evt) return nil end
|
||||
|
||||
-- ============ llm ============
|
||||
-- !impl
|
||||
sdk.llm = {}
|
||||
-- !impl
|
||||
function sdk.llm.list_sources() return {} end
|
||||
-- !impl
|
||||
function sdk.llm.set_source(name) return nil end
|
||||
-- !impl
|
||||
function sdk.llm.current_source() return nil end
|
||||
|
||||
-- ============ social (只读) ============
|
||||
-- !impl
|
||||
sdk.social = {}
|
||||
-- !impl
|
||||
function sdk.social.get_person(name) return {} end
|
||||
-- !impl
|
||||
function sdk.social.get_network(name, depth) return {} end
|
||||
-- !impl
|
||||
function sdk.social.get_trait(name, trait) return {value=nil, found=false} end
|
||||
-- !impl
|
||||
function sdk.social.get_relations(name) return {} end
|
||||
-- !impl
|
||||
function sdk.social.list_persons() return {} end
|
||||
|
||||
-- ============ settings (作用域变体) ============
|
||||
-- !impl
|
||||
sdk.settings = {}
|
||||
-- !impl
|
||||
function sdk.settings.get_core(key) return nil end
|
||||
-- !impl
|
||||
function sdk.settings.set_core(key, value) return nil end
|
||||
-- !impl
|
||||
function sdk.settings.list_core(prefix) return {} end
|
||||
-- !impl
|
||||
function sdk.settings.get_plugin(plugin, key) return nil end
|
||||
-- !impl
|
||||
function sdk.settings.set_plugin(plugin, key, value) return nil end
|
||||
-- !impl
|
||||
function sdk.settings.list_plugin(plugin, prefix) return {} end
|
||||
-- !impl
|
||||
function sdk.settings.list(prefix) return {} end
|
||||
-- !impl
|
||||
-- def: { key=, type=, display_name=, description=, category=, options=, default=,
|
||||
-- min=, max=, step=, required=, secret= }
|
||||
function sdk.settings.register_def(def) return nil end
|
||||
-- !impl
|
||||
function sdk.settings.defs(prefix) return {} end
|
||||
-- !impl
|
||||
function sdk.settings.dump() return {} end
|
||||
-- !impl
|
||||
function sdk.settings.plugins() return {} end
|
||||
|
||||
-- ============ events（只读订阅） ============
|
||||
-- !impl
|
||||
-- subscribe(event_type, handler) -> unsubscribe()
|
||||
-- handler 收到 { type=, source=, timestamp=, payload= }；
|
||||
-- 回调在其内核事件发布 goroutine 上执行，只做轻量转发，不可阻塞（Lua 单状态 + 互斥锁）。
|
||||
sdk.events = {}
|
||||
function sdk.events.subscribe(event_type, handler)
|
||||
print("[lua-plugin] events.subscribe: " .. tostring(event_type))
|
||||
return function() end
|
||||
end
|
||||
|
||||
-- ============ plugin_mgr ============
|
||||
-- !impl
|
||||
sdk.plugin_mgr = {}
|
||||
function sdk.plugin_mgr.reload_one(name) return nil end
|
||||
function sdk.plugin_mgr.list_loaded() return {} end
|
||||
function sdk.plugin_mgr.is_disabled(name) return false end
|
||||
|
||||
-- json utils (pure Lua)
|
||||
sdk.json = {}
|
||||
|
||||
function sdk.json.encode(val)
|
||||
local ok, result = pcall(function()
|
||||
local function _encode(v)
|
||||
local t = type(v)
|
||||
if t == "string" then
|
||||
local s = v:gsub('\\', '\\\\'):gsub('"', '\\"'):gsub('\n', '\\n'):gsub('\r', '\\r'):gsub('\t', '\\t')
|
||||
return '"' .. s .. '"'
|
||||
elseif t == "number" then
|
||||
return tostring(v)
|
||||
elseif t == "boolean" then
|
||||
return tostring(v)
|
||||
elseif t == "table" then
|
||||
local keys = {}
|
||||
local is_array = true
|
||||
local maxn = 0
|
||||
for k in pairs(v) do
|
||||
keys[#keys + 1] = k
|
||||
if type(k) ~= "number" or k < 1 or k ~= math.floor(k) then
|
||||
is_array = false
|
||||
end
|
||||
if type(k) == "number" and k > maxn then maxn = k end
|
||||
end
|
||||
if is_array and #keys >= maxn then
|
||||
local parts = {}
|
||||
for i = 1, maxn do
|
||||
parts[#parts + 1] = _encode(v[i])
|
||||
end
|
||||
return "[" .. table.concat(parts, ",") .. "]"
|
||||
else
|
||||
local parts = {}
|
||||
for _, k in ipairs(keys) do
|
||||
parts[#parts + 1] = _encode(tostring(k)) .. ":" .. _encode(v[k])
|
||||
end
|
||||
return "{" .. table.concat(parts, ",") .. "}"
|
||||
end
|
||||
else
|
||||
return "null"
|
||||
end
|
||||
end
|
||||
return _encode(val)
|
||||
end)
|
||||
if ok then return result end
|
||||
if type(val) == "string" then return '"' .. val:gsub('"', '\\"'):gsub('\n', '\\n') .. '"'
|
||||
elseif type(val) == "number" or type(val) == "boolean" then return tostring(val)
|
||||
elseif type(val) == "table" then local parts, i = {}, 1
|
||||
for k, v in pairs(val) do parts[i] = sdk.json.encode(k) .. ":" .. sdk.json.encode(v); i = i + 1 end
|
||||
return "{" .. table.concat(parts, ",") .. "}" end
|
||||
return "null"
|
||||
end
|
||||
|
||||
function sdk.json.decode(str)
|
||||
local ok, result = pcall(function()
|
||||
local pos, _end = 1, #str
|
||||
local function skip()
|
||||
while pos <= _end and str:sub(pos, pos):match("%s") do pos = pos + 1 end
|
||||
end
|
||||
local function parse()
|
||||
skip()
|
||||
if pos > _end then return nil end
|
||||
local c = str:sub(pos, pos)
|
||||
if c == '"' then
|
||||
local s = {}
|
||||
pos = pos + 1
|
||||
while pos <= _end do
|
||||
local ch = str:sub(pos, pos)
|
||||
if ch == '"' then
|
||||
pos = pos + 1
|
||||
return table.concat(s)
|
||||
elseif ch == '\\' then
|
||||
pos = pos + 1
|
||||
local n = str:sub(pos, pos)
|
||||
if n == '"' then s[#s+1] = '"'
|
||||
elseif n == '\\' then s[#s+1] = '\\'
|
||||
elseif n == '/' then s[#s+1] = '/'
|
||||
elseif n == 'b' then s[#s+1] = '\b'
|
||||
elseif n == 'f' then s[#s+1] = '\f'
|
||||
elseif n == 'n' then s[#s+1] = '\n'
|
||||
elseif n == 'r' then s[#s+1] = '\r'
|
||||
elseif n == 't' then s[#s+1] = '\t'
|
||||
elseif n == 'u' then
|
||||
local hex = str:sub(pos+1, pos+4)
|
||||
pos = pos + 4
|
||||
s[#s+1] = utf8 and utf8.char(tonumber(hex, 16)) or '?'
|
||||
end
|
||||
pos = pos + 1
|
||||
else
|
||||
s[#s+1] = ch
|
||||
pos = pos + 1
|
||||
end
|
||||
end
|
||||
return table.concat(s)
|
||||
elseif c == 't' then pos = pos + 4; return true
|
||||
elseif c == 'f' then pos = pos + 5; return false
|
||||
elseif c == 'n' then pos = pos + 4; return nil
|
||||
elseif c == '{' then
|
||||
pos = pos + 1; skip()
|
||||
local t = {}
|
||||
if str:sub(pos, pos) == '}' then pos = pos + 1; return t end
|
||||
while true do
|
||||
skip(); local k = parse(); skip()
|
||||
if str:sub(pos, pos) == ':' then pos = pos + 1 end
|
||||
skip(); t[k] = parse(); skip()
|
||||
local sep = str:sub(pos, pos)
|
||||
if sep == '}' then pos = pos + 1; return t end
|
||||
if sep == ',' then pos = pos + 1 end
|
||||
end
|
||||
elseif c == '[' then
|
||||
pos = pos + 1; skip()
|
||||
local t = {}
|
||||
if str:sub(pos, pos) == ']' then pos = pos + 1; return t end
|
||||
local idx = 1
|
||||
while true do
|
||||
skip(); t[idx] = parse(); idx = idx + 1; skip()
|
||||
local sep = str:sub(pos, pos)
|
||||
if sep == ']' then pos = pos + 1; return t end
|
||||
if sep == ',' then pos = pos + 1 end
|
||||
end
|
||||
else
|
||||
local s, e = str:find('^[-%d%.eE]+', pos)
|
||||
if s then
|
||||
local num = tonumber(str:sub(s, e))
|
||||
pos = e + 1
|
||||
return num
|
||||
end
|
||||
return nil
|
||||
end
|
||||
end
|
||||
return parse()
|
||||
end)
|
||||
if ok then return result end
|
||||
return nil
|
||||
end
|
||||
|
||||
-- http utils
|
||||
function sdk.json.decode(str) local ok, fn = pcall(load, "return " .. str); if ok then return fn() end; return nil end
|
||||
sdk.http = {}
|
||||
|
||||
-- !impl
|
||||
function sdk.http.get(url)
|
||||
print("[lua-plugin] http.get: " .. tostring(url))
|
||||
return {status=200, body='{"mock":true}', headers={}}
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.http.post(url, body, content_type)
|
||||
print("[lua-plugin] http.post: " .. tostring(url))
|
||||
return {status=200, body='{"mock":true}', headers={}}
|
||||
end
|
||||
|
||||
function sdk.http.get(url) print("[lua-plugin] http.get: " .. tostring(url)); return {status=200, body='{"mock":true}', headers={}} end
|
||||
function sdk.http.post(url, body, ct) print("[lua-plugin] http.post: " .. tostring(url)); return {status=200, body='{"mock":true}', headers={}} end
|
||||
return sdk
|
||||
|
||||
@ -1,43 +0,0 @@
|
||||
# memo · 待办与备忘录
|
||||
|
||||
两类条目，行为**刻意不同**：
|
||||
|
||||
| 类型 | 用途 | 是否主动提醒 |
|
||||
|---|---|---|
|
||||
| **待办**（todo） | 有截止概念、需要被催的事 | ✅ 会 |
|
||||
| **备忘录**（memo） | 纯记事，供以后查阅 | ❌ 不会 |
|
||||
|
||||
分开的理由：把"提醒我"和"记一下"混成一类，要么备忘录天天弹、要么待办被忘掉。
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `memo_todo_add` | 添加待办（会被主动提醒） |
|
||||
| `memo_todo_complete` | 标记待办完成（不再提醒） |
|
||||
| `memo_todo_list` | 列出未完成待办（含 ID、内容、创建时间） |
|
||||
| `memo_todo_delete` | 删除待办（含已完成的） |
|
||||
| `memo_memo_create` | 创建备忘录（纯记事，不提醒） |
|
||||
| `memo_memo_list` | 列出全部备忘录 |
|
||||
| `memo_memo_delete` | 删除备忘录 |
|
||||
|
||||
> 工具名前缀取自插件名（`p.tp`），上面按默认的 `memo_` 写法列出。
|
||||
|
||||
## 提醒机制
|
||||
|
||||
- 后台 **每 5 分钟**检查一次未完成待办数；有则通过 `InjectInterruptText` 注入一条
|
||||
「注意，你还有 N 条待办未完成，请检查」。
|
||||
- 注入带 **`NoMemory: true`** —— 这是定时提醒，不是记忆内容，不该进向量化。
|
||||
- 通道声明为 **`NoMemory`**（`RegisterInputChannel(p.name, ChannelDef{NoMemory:true})`），
|
||||
理由同上：提醒是瞬时信号。
|
||||
- 另有 `StagePreAction` 钩子，在每轮动作前参与。
|
||||
|
||||
## 存储
|
||||
|
||||
条目落在数据目录的 `todos.json`，插件重启后仍在。
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
```
|
||||
@ -48,9 +48,6 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
s.SetAutoRestart(true)
|
||||
p.sdk = s
|
||||
p.tp = p.name + "_"
|
||||
// 入站通道：本插件用 p.name 通道注入输入（见 Inject* 调用），
|
||||
// 输入侧必须显式登记 —— 否则"把该 inputch 划给驻留子"会报 `inputch 未注册`。
|
||||
_ = s.RegisterInputChannel(p.name, sdk.ChannelDef{NoMemory: true})
|
||||
|
||||
dataDirVal, err := s.Settings().GetCore("core.daemon.data_dir")
|
||||
if err != nil || dataDirVal == "" {
|
||||
@ -295,9 +292,8 @@ func (p *Plugin) periodicCheck() {
|
||||
continue
|
||||
}
|
||||
if p.sdk != nil {
|
||||
// NoMemory：这是定时提醒，不是记忆内容。
|
||||
p.sdk.InjectInterruptTextOpts(p.name, p.name,
|
||||
fmt.Sprintf("注意，你还有%d条待办未完成，请检查", n), sdk.InjectOptions{NoMemory: true})
|
||||
p.sdk.InjectInterruptText(p.name, p.name,
|
||||
fmt.Sprintf("注意，你还有%d条待办未完成，请检查", n))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
@ -1,30 +0,0 @@
|
||||
# music · 音乐搜索
|
||||
|
||||
按关键词搜歌、按 ID 查歌词（数据来自网易云音乐公开接口）。
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `music_search` | 按关键词搜歌，返回歌曲列表（含歌曲 ID） |
|
||||
| `music_lyrics` | 按歌曲 ID 取歌词 |
|
||||
|
||||
典型两段式用法：先 `music_search` 拿 ID，再 `music_lyrics` 取词。
|
||||
|
||||
## 实现要点
|
||||
|
||||
- 请求打的是 `https://music.163.com/api/...`，并固定带上 `Referer: https://music.163.com/` ——
|
||||
该接口对缺少来源头的请求会拒绝。
|
||||
- 是**只读**插件：不下载音频、不写本地文件，因此没有需要清理的副作用。
|
||||
|
||||
## 已知边界
|
||||
|
||||
- 依赖第三方（网易云）公开接口，其可用性与返回结构不受本插件控制；
|
||||
接口变动时可能返回空列表，而不是报错。
|
||||
- 仅覆盖"搜索 + 歌词"，不含播放地址解析。
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
```
|
||||
@ -1,40 +0,0 @@
|
||||
# ocr · 图片文字识别
|
||||
|
||||
从图片里提取文字（中英文），基于 [Tesseract](https://github.com/tesseract-ocr/tesseract) OCR 引擎。
|
||||
|
||||
## 前置依赖
|
||||
|
||||
需要系统里装有 `tesseract` 可执行文件：
|
||||
|
||||
```bash
|
||||
# Debian/Ubuntu
|
||||
apt install tesseract-ocr tesseract-ocr-chi-sim
|
||||
```
|
||||
|
||||
中文识别需要 `chi_sim` 语言包；缺它时中文会识别成乱码而非报错。
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `ocr_ocr_image` | 对图片做 OCR，返回识别文本 |
|
||||
|
||||
参数：
|
||||
|
||||
| 参数 | 说明 |
|
||||
|---|---|
|
||||
| `image_url` | 图片的 HTTP/HTTPS 地址（与 `image_data` 二选一） |
|
||||
| `image_data` | 图片的 base64 数据，**不含** `data:image/...` 前缀（与 `image_url` 二选一） |
|
||||
| `language` | 识别语言，默认 `chi_sim+eng`；可选 `chi_sim` / `eng` / `chi_sim+eng` |
|
||||
|
||||
## 实现要点
|
||||
|
||||
- 传入的图先落到临时目录，OCR 完 `defer os.RemoveAll` 清掉，不残留。
|
||||
- 调用参数固定 `--psm 3`（全自动页面分割），适合截图与常规排版图片；对单行小图或竖排文本效果会下降。
|
||||
- **`Cleaner`**：工具返回的是 JSON（含 `text`、`language` 等字段），进记忆计算前只取 `text` 正文 —— 否则 JSON 结构本身会参与向量化。
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
```
|
||||
@ -1,47 +0,0 @@
|
||||
# plugindev — 插件开发工具链（Agent 可调用）
|
||||
|
||||
把 SDK 的 `hmapdev` 封装成插件，让 **Agent 自己**走完「新建插件 → 构建 → 安装」全流程，
|
||||
不需要人来敲命令行：
|
||||
|
||||
```
|
||||
plugindev_init 生成工程骨架（等价 hmapdev init <name> [--lua]）
|
||||
↓ 改 plugin.go
|
||||
plugindev_build 构建打包（等价在该目录 hmapdev build）→ dist/*.hmap
|
||||
↓
|
||||
plugin_install 安装（用 path 指向刚构建出的 .hmap，overwrite=true 表示原地更新）
|
||||
↓
|
||||
plgreload 重载生效
|
||||
```
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 参数 | 说明 |
|
||||
|---|---|---|
|
||||
| `plugindev_status` | — | hmapdev 是否可用/版本/当前 SDK 版本与路径/工作区；**排查"为什么不能构建"先用它** |
|
||||
| `plugindev_init` | `name`、`lang`(go/lua)、`dir` | 生成工程骨架；插件名必须 `[a-zA-Z0-9_-]{1,64}` |
|
||||
| `plugindev_build` | `dir`、`target` | 在工程目录构建打包；产物路径会在返回里给出 |
|
||||
| `plugindev_sdk` | `action`、`version`、`from` | SDK 版本管理（list/current/path/latest/install/use）；`from` 可指向本地 SDK 源码 |
|
||||
| `plugindev_projects` | — | 列出工作区里已有工程与产物 |
|
||||
|
||||
## 配置
|
||||
|
||||
| 键 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `hmapdev_path` | 自动查找 | 依次尝试：本配置项 → PATH → `/usr/local/bin/hmapdev` → `/root/go/bin/hmapdev` |
|
||||
| `workspace_dir` | `<data_dir>/plugindev` | `plugindev_init` 生成工程的默认目录 |
|
||||
| `build_timeout_sec` | 600 | 单次 hmapdev 调用超时 |
|
||||
|
||||
## 前置：装 hmapdev
|
||||
|
||||
```bash
|
||||
cd <sdk-repo>/tools/hmapdev && go build -buildvcs=false -o /usr/local/bin/hmapdev .
|
||||
hmapdev version
|
||||
```
|
||||
|
||||
## 安全边界（都在实现里，不只写在文档里）
|
||||
|
||||
- 只 exec **hmapdev 一个可执行文件**，不接受任意命令、不做 shell 拼接；
|
||||
- `plugindev_build` 只接受含 `plg.json` 的目录（"看起来是插件工程"才构建），
|
||||
避免把这个工具变成对任意目录跑构建；
|
||||
- 子进程全部带超时，输出**截断**后才返回（构建日志动辄几百 KB，直接回灌会撑爆模型上下文）；
|
||||
- 工程名约束与内核/上游对"进工具名的标识符"的规则一致（`[a-zA-Z0-9_-]{1,64}`）。
|
||||
@ -1,7 +0,0 @@
|
||||
module plugindev
|
||||
|
||||
go 1.25.0
|
||||
|
||||
require gitcode.com/JianFeeeee/homeagent-sdk v0.0.0
|
||||
|
||||
replace gitcode.com/JianFeeeee/homeagent-sdk => ../../
|
||||
@ -1,11 +0,0 @@
|
||||
//go:build !windows || !cgo
|
||||
|
||||
package main
|
||||
|
||||
import (
|
||||
sdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
|
||||
)
|
||||
|
||||
func NewPlugin(name string, config map[string]interface{}) (sdk.Plugin, error) {
|
||||
return NewPluginFactory(name, config)
|
||||
}
|
||||
@ -1,19 +0,0 @@
|
||||
{
|
||||
"name": "plugindev",
|
||||
"name_zh": "插件开发工具链",
|
||||
"name_en": "Plugin Dev Toolchain",
|
||||
"version": "1.0.0",
|
||||
"description": "把 hmapdev 工具链封装成 Agent 可调用的工具：脚手架生成插件工程、构建打包 .hmap、管理 SDK 版本。配合 plugin_install 即可让 Agent 自己做完「新建插件 → 构建 → 安装」全流程。",
|
||||
"author": "HomeAgent",
|
||||
"entry": "plugin.so",
|
||||
"tags": [
|
||||
"plugindev",
|
||||
"toolchain",
|
||||
"developer"
|
||||
],
|
||||
"targets": "linux/amd64",
|
||||
"outdir": "dist",
|
||||
"bundle": true,
|
||||
"replaces": {},
|
||||
"source_dirs": []
|
||||
}
|
||||
@ -1,455 +0,0 @@
|
||||
package main
|
||||
|
||||
// plugindev：把 SDK 的 hmapdev 工具链封装成 Agent 可调用的插件。
|
||||
//
|
||||
// 为什么需要它：hmapdev 是"给人和 CI 用"的命令行工具。做成插件后，Agent 能自己：
|
||||
// plugindev_init（脚手架）→ plugindev_build（构建出 .hmap）→ plugin_install（安装）→ plgreload
|
||||
// 也就是"让 Agent 自己写/改/装插件"这条链不需要人来敲命令。
|
||||
//
|
||||
// 安全边界（都在实现里落实，不只写在描述里）：
|
||||
// - 只有 **hmapdev 一个可执行文件**会被 exec（不接受任意命令/参数拼接）；
|
||||
// - `plugindev_build` 只接受"看起来是插件工程"的目录（含 plg.json），
|
||||
// 避免把一个 `hmapdev build` 变成对任意目录的操作；
|
||||
// - `plugindev_init` 生成的工程名必须满足 `[a-zA-Z0-9_-]{1,64}`（与 LLM 函数名
|
||||
// 同一套约束 —— 插件名会进 `output_send__<通道>` 之类的工具名）；
|
||||
// - 所有子进程都有超时，输出截断后再返回（防止把几十 MB 构建日志灌进模型上下文）。
|
||||
|
||||
import (
|
||||
"context"
|
||||
"fmt"
|
||||
"log"
|
||||
"os"
|
||||
"os/exec"
|
||||
"path/filepath"
|
||||
"regexp"
|
||||
"sort"
|
||||
"strings"
|
||||
"time"
|
||||
|
||||
"gitcode.com/JianFeeeee/homeagent-sdk/sdk"
|
||||
)
|
||||
|
||||
const (
|
||||
defaultBuildTimeout = 10 * time.Minute
|
||||
maxOutputChars = 6000
|
||||
)
|
||||
|
||||
// namePattern 与内核/上游对"会进工具名的标识符"的约束一致。
|
||||
var namePattern = regexp.MustCompile(`^[a-zA-Z0-9_-]{1,64}$`)
|
||||
|
||||
type Plugin struct {
|
||||
name string
|
||||
sdk *sdk.PluginSDK
|
||||
|
||||
hmapdev string // 解析到的 hmapdev 可执行文件路径
|
||||
workspace string // 默认工作区（生成的工程落在这里）
|
||||
timeout time.Duration // 单次 hmapdev 调用的超时
|
||||
}
|
||||
|
||||
func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, error) {
|
||||
return &Plugin{name: name}, nil
|
||||
}
|
||||
|
||||
func (p *Plugin) Name() string { return p.name }
|
||||
|
||||
func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
p.sdk = s
|
||||
s.SetAutoRestart(true)
|
||||
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{
|
||||
Key: "hmapdev_path", Type: "string", DisplayName: "hmapdev 路径",
|
||||
Description: "插件开发工具链可执行文件路径。留空则按 PATH → /usr/local/bin/hmapdev → /root/go/bin/hmapdev 查找",
|
||||
Category: p.name,
|
||||
})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{
|
||||
Key: "workspace_dir", Type: "string", DisplayName: "工程工作区",
|
||||
Description: "plugindev_init 生成工程的默认目录。留空则用 <data_dir>/plugindev",
|
||||
Category: p.name,
|
||||
})
|
||||
s.Settings().RegisterDef(sdk.ConfigDef{
|
||||
Key: "build_timeout_sec", Default: 600, Type: "int", DisplayName: "构建超时（秒）",
|
||||
Description: "单次 hmapdev 调用的超时上限",
|
||||
Category: p.name,
|
||||
})
|
||||
|
||||
p.hmapdev = p.resolveHmapdev()
|
||||
p.workspace = p.resolveWorkspace()
|
||||
p.timeout = defaultBuildTimeout
|
||||
if v, _ := s.Settings().Get("build_timeout_sec"); v != nil {
|
||||
if n, ok := toInt(v); ok && n > 0 {
|
||||
p.timeout = time.Duration(n) * time.Second
|
||||
}
|
||||
}
|
||||
|
||||
s.RegisterTool("plugindev_status", sdk.ToolDef{
|
||||
Name: "plugindev_status",
|
||||
Description: "查看插件开发工具链状态：hmapdev 是否可用、版本、当前 SDK 版本与路径、工程工作区目录。排查\"为什么不能构建插件\"时先用它。",
|
||||
Parameters: map[string]interface{}{"type": "object", "properties": map[string]interface{}{}},
|
||||
}, p.handleStatus)
|
||||
|
||||
s.RegisterTool("plugindev_init", sdk.ToolDef{
|
||||
Name: "plugindev_init",
|
||||
Description: "生成一个新的插件工程骨架（等价于 `hmapdev init <name> [--lua]`）。生成后在返回的目录里改 plugin.go，再用 plugindev_build 构建。",
|
||||
Parameters: map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"name": map[string]interface{}{
|
||||
"type": "string",
|
||||
"description": "插件名（也是工程目录名）：只允许字母数字下划线短横，长度 1-64。例：my_plugin",
|
||||
},
|
||||
"lang": map[string]interface{}{
|
||||
"type": "string", "description": "go（默认）或 lua",
|
||||
},
|
||||
"dir": map[string]interface{}{
|
||||
"type": "string", "description": "在哪个目录下生成（默认工作区）。必须是已存在的目录",
|
||||
},
|
||||
},
|
||||
"required": []string{"name"},
|
||||
},
|
||||
}, p.handleInit)
|
||||
|
||||
s.RegisterTool("plugindev_build", sdk.ToolDef{
|
||||
Name: "plugindev_build",
|
||||
Description: "构建并打包一个插件工程（等价于在该工程目录里执行 `hmapdev build [target]`），产物是 dist/*.hmap。构建成功后用 plugin_install 安装（本地路径）。",
|
||||
Parameters: map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"dir": map[string]interface{}{
|
||||
"type": "string", "description": "插件工程目录（必须含 plg.json）",
|
||||
},
|
||||
"target": map[string]interface{}{
|
||||
"type": "string", "description": "构建目标，留空 = native（当前平台）。例：linux/amd64",
|
||||
},
|
||||
},
|
||||
"required": []string{"dir"},
|
||||
},
|
||||
}, p.handleBuild)
|
||||
|
||||
s.RegisterTool("plugindev_sdk", sdk.ToolDef{
|
||||
Name: "plugindev_sdk",
|
||||
Description: "管理插件 SDK 版本（hmapdev sdk 子命令）：list 列出已安装、current 当前版本、path 当前路径、latest 远端最新、install 安装某版本（可用 from 指定本地源码目录）、use 切换版本。构建插件报\"SDK 缺少某能力\"时用它升级 SDK。",
|
||||
Parameters: map[string]interface{}{
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{
|
||||
"action": map[string]interface{}{
|
||||
"type": "string", "description": "list | current | path | latest | install | use",
|
||||
},
|
||||
"version": map[string]interface{}{
|
||||
"type": "string", "description": "install/use 的版本号，如 v1.3.0",
|
||||
},
|
||||
"from": map[string]interface{}{
|
||||
"type": "string", "description": "install 时用本地 SDK 源码目录（开发中的 SDK 用这个）",
|
||||
},
|
||||
},
|
||||
"required": []string{"action"},
|
||||
},
|
||||
}, p.handleSDK)
|
||||
|
||||
s.RegisterTool("plugindev_projects", sdk.ToolDef{
|
||||
Name: "plugindev_projects",
|
||||
Description: "列出工作区里已有的插件工程（名字、版本、是否已构建出 dist 产物），用于接续之前的开发。",
|
||||
Parameters: map[string]interface{}{"type": "object", "properties": map[string]interface{}{}},
|
||||
}, p.handleProjects)
|
||||
|
||||
log.Printf("[plugindev] 就绪：hmapdev=%s 工作区=%s", fallback(p.hmapdev, "(未找到)"), p.workspace)
|
||||
return nil
|
||||
}
|
||||
|
||||
func (p *Plugin) Stop() error { return nil }
|
||||
|
||||
// ---------------- 工具实现 ----------------
|
||||
|
||||
func (p *Plugin) handleStatus(args map[string]interface{}) (interface{}, error) {
|
||||
out := map[string]interface{}{
|
||||
"hmapdev": fallback(p.hmapdev, ""),
|
||||
"workspace": p.workspace,
|
||||
}
|
||||
if p.hmapdev == "" {
|
||||
out["available"] = false
|
||||
out["hint"] = "未找到 hmapdev。请安装：go build -o /usr/local/bin/hmapdev <sdk>/tools/hmapdev"
|
||||
return out, nil
|
||||
}
|
||||
out["available"] = true
|
||||
if txt, err := p.run(nil, ""); err == nil {
|
||||
out["version"] = strings.TrimSpace(txt)
|
||||
} else {
|
||||
out["error"] = err.Error()
|
||||
}
|
||||
if txt, err := p.run([]string{"sdk", "current"}, ""); err == nil {
|
||||
out["sdk_current"] = strings.TrimSpace(txt)
|
||||
}
|
||||
if txt, err := p.run([]string{"sdk", "path"}, ""); err == nil {
|
||||
out["sdk_path"] = strings.TrimSpace(txt)
|
||||
}
|
||||
return out, nil
|
||||
}
|
||||
|
||||
func (p *Plugin) handleInit(args map[string]interface{}) (interface{}, error) {
|
||||
name, _ := args["name"].(string)
|
||||
name = strings.TrimSpace(name)
|
||||
if !namePattern.MatchString(name) {
|
||||
return map[string]interface{}{
|
||||
"error": "插件名只允许 [a-zA-Z0-9_-]，长度 1-64（它会进 LLM 工具名，违规会让整条请求被上游拒绝）",
|
||||
}, nil
|
||||
}
|
||||
dir, _ := args["dir"].(string)
|
||||
if dir == "" {
|
||||
dir = p.workspace
|
||||
}
|
||||
if st, err := os.Stat(dir); err != nil || !st.IsDir() {
|
||||
return map[string]interface{}{"error": fmt.Sprintf("目录不存在: %s", dir)}, nil
|
||||
}
|
||||
cmd := []string{"init", name}
|
||||
if lang, _ := args["lang"].(string); strings.EqualFold(lang, "lua") {
|
||||
cmd = append(cmd, "--lua")
|
||||
}
|
||||
txt, err := p.run(cmd, dir)
|
||||
res := map[string]interface{}{"output": txt, "project_dir": filepath.Join(dir, name)}
|
||||
if err != nil {
|
||||
res["error"] = err.Error()
|
||||
}
|
||||
return res, nil
|
||||
}
|
||||
|
||||
func (p *Plugin) handleBuild(args map[string]interface{}) (interface{}, error) {
|
||||
dir, _ := args["dir"].(string)
|
||||
if dir == "" {
|
||||
return map[string]interface{}{"error": "dir 不能为空"}, nil
|
||||
}
|
||||
abs, err := filepath.Abs(dir)
|
||||
if err != nil {
|
||||
return map[string]interface{}{"error": err.Error()}, nil
|
||||
}
|
||||
// 只在"插件工程"里构建：必须存在 plg.json。这样这个工具不会变成对任意目录跑构建。
|
||||
manifest := filepath.Join(abs, "plg.json")
|
||||
if _, err := os.Stat(manifest); err != nil {
|
||||
return map[string]interface{}{
|
||||
"error": fmt.Sprintf("%s 不是插件工程（缺 plg.json）；用 plugindev_init 先建一个", abs),
|
||||
}, nil
|
||||
}
|
||||
cmd := []string{"build"}
|
||||
if target, _ := args["target"].(string); strings.TrimSpace(target) != "" {
|
||||
cmd = append(cmd, strings.TrimSpace(target))
|
||||
}
|
||||
txt, runErr := p.run(cmd, abs)
|
||||
res := map[string]interface{}{"output": txt, "project_dir": abs}
|
||||
if pkgs := listHmap(filepath.Join(abs, "dist")); len(pkgs) > 0 {
|
||||
res["artifacts"] = pkgs
|
||||
res["next"] = "用 plugin_install 安装本地产物（path 指向上面 artifacts 里的 .hmap），然后 plgreload"
|
||||
}
|
||||
if runErr != nil {
|
||||
res["error"] = runErr.Error()
|
||||
}
|
||||
return res, nil
|
||||
}
|
||||
|
||||
func (p *Plugin) handleSDK(args map[string]interface{}) (interface{}, error) {
|
||||
action, _ := args["action"].(string)
|
||||
action = strings.TrimSpace(action)
|
||||
switch action {
|
||||
case "list", "current", "path", "latest":
|
||||
txt, err := p.run([]string{"sdk", action}, "")
|
||||
res := map[string]interface{}{"output": txt}
|
||||
if err != nil {
|
||||
res["error"] = err.Error()
|
||||
}
|
||||
return res, nil
|
||||
case "install":
|
||||
version, _ := args["version"].(string)
|
||||
from, _ := args["from"].(string)
|
||||
cmd := []string{"sdk", "install"}
|
||||
if strings.TrimSpace(from) != "" {
|
||||
cmd = append(cmd, "--from", strings.TrimSpace(from))
|
||||
}
|
||||
if strings.TrimSpace(version) != "" {
|
||||
cmd = append(cmd, strings.TrimSpace(version))
|
||||
} else if strings.TrimSpace(from) == "" {
|
||||
cmd = append(cmd, "latest")
|
||||
}
|
||||
txt, err := p.run(cmd, "")
|
||||
res := map[string]interface{}{"output": txt}
|
||||
if err != nil {
|
||||
res["error"] = err.Error()
|
||||
}
|
||||
return res, nil
|
||||
case "use":
|
||||
version, _ := args["version"].(string)
|
||||
if strings.TrimSpace(version) == "" {
|
||||
return map[string]interface{}{"error": "use 需要 version"}, nil
|
||||
}
|
||||
txt, err := p.run([]string{"sdk", "use", strings.TrimSpace(version)}, "")
|
||||
res := map[string]interface{}{"output": txt}
|
||||
if err != nil {
|
||||
res["error"] = err.Error()
|
||||
}
|
||||
return res, nil
|
||||
default:
|
||||
return map[string]interface{}{"error": "action 只能是 list/current/path/latest/install/use"}, nil
|
||||
}
|
||||
}
|
||||
|
||||
func (p *Plugin) handleProjects(args map[string]interface{}) (interface{}, error) {
|
||||
entries, err := os.ReadDir(p.workspace)
|
||||
if err != nil {
|
||||
return map[string]interface{}{"error": err.Error(), "workspace": p.workspace}, nil
|
||||
}
|
||||
var out []map[string]interface{}
|
||||
for _, e := range entries {
|
||||
if !e.IsDir() {
|
||||
continue
|
||||
}
|
||||
dir := filepath.Join(p.workspace, e.Name())
|
||||
projects := []string{dir}
|
||||
// 有些工程会被生成到子目录里（hmapdev init 支持指定目录），这里只看一层
|
||||
for _, sub := range projects {
|
||||
if _, err := os.Stat(filepath.Join(sub, "plg.json")); err != nil {
|
||||
continue
|
||||
}
|
||||
item := map[string]interface{}{"name": e.Name(), "dir": sub}
|
||||
if v := readPlgVersion(filepath.Join(sub, "plg.json")); v != "" {
|
||||
item["version"] = v
|
||||
}
|
||||
if pkgs := listHmap(filepath.Join(sub, "dist")); len(pkgs) > 0 {
|
||||
item["artifacts"] = pkgs
|
||||
}
|
||||
out = append(out, item)
|
||||
}
|
||||
}
|
||||
sort.Slice(out, func(i, j int) bool { return out[i]["name"].(string) < out[j]["name"].(string) })
|
||||
return map[string]interface{}{"workspace": p.workspace, "projects": out}, nil
|
||||
}
|
||||
|
||||
// ---------------- 基础设施 ----------------
|
||||
|
||||
// run 执行一次 hmapdev。args 为空时执行 `hmapdev version`（用于探活）。
|
||||
func (p *Plugin) run(args []string, dir string) (string, error) {
|
||||
if p.hmapdev == "" {
|
||||
return "", fmt.Errorf("未找到 hmapdev 可执行文件")
|
||||
}
|
||||
ctx, cancel := context.WithTimeout(context.Background(), p.timeout)
|
||||
defer cancel()
|
||||
cmd := exec.CommandContext(ctx, p.hmapdev, args...)
|
||||
if dir != "" {
|
||||
cmd.Dir = dir
|
||||
}
|
||||
// 继承环境（Go 工具链需要 GOCACHE/GOPATH/PATH 等）。
|
||||
out, err := cmd.CombinedOutput()
|
||||
txt := truncateOutput(string(out))
|
||||
if ctx.Err() == context.DeadlineExceeded {
|
||||
return txt, fmt.Errorf("hmapdev %s 超时（%s）", strings.Join(args, " "), p.timeout)
|
||||
}
|
||||
if err != nil {
|
||||
return txt, fmt.Errorf("hmapdev %s 失败: %v", strings.Join(args, " "), err)
|
||||
}
|
||||
return txt, nil
|
||||
}
|
||||
|
||||
// resolveHmapdev 依次尝试：配置项 → PATH → 常见安装位置。
|
||||
func (p *Plugin) resolveHmapdev() string {
|
||||
if v, _ := p.sdk.Settings().Get("hmapdev_path"); v != nil {
|
||||
if s, _ := v.(string); strings.TrimSpace(s) != "" {
|
||||
if _, err := os.Stat(strings.TrimSpace(s)); err == nil {
|
||||
return strings.TrimSpace(s)
|
||||
}
|
||||
}
|
||||
}
|
||||
if path, err := exec.LookPath("hmapdev"); err == nil {
|
||||
return path
|
||||
}
|
||||
for _, cand := range []string{"/usr/local/bin/hmapdev", "/root/go/bin/hmapdev"} {
|
||||
if _, err := os.Stat(cand); err == nil {
|
||||
return cand
|
||||
}
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
// resolveWorkspace：配置项 → <data_dir>/plugindev → ./plugindev。
|
||||
func (p *Plugin) resolveWorkspace() string {
|
||||
if v, _ := p.sdk.Settings().Get("workspace_dir"); v != nil {
|
||||
if s, _ := v.(string); strings.TrimSpace(s) != "" {
|
||||
ws := strings.TrimSpace(s)
|
||||
_ = os.MkdirAll(ws, 0o755)
|
||||
return ws
|
||||
}
|
||||
}
|
||||
if v, err := p.sdk.Settings().GetCore("core.daemon.data_dir"); err == nil {
|
||||
if dd, _ := v.(string); dd != "" {
|
||||
ws := filepath.Join(dd, "plugindev")
|
||||
_ = os.MkdirAll(ws, 0o755)
|
||||
return ws
|
||||
}
|
||||
}
|
||||
ws := "plugindev"
|
||||
_ = os.MkdirAll(ws, 0o755)
|
||||
return ws
|
||||
}
|
||||
|
||||
// truncateOutput 截断长输出：构建日志动辄几百 KB，直接返回会灌爆模型上下文。
|
||||
func truncateOutput(s string) string {
|
||||
if len(s) <= maxOutputChars {
|
||||
return s
|
||||
}
|
||||
head := s[:maxOutputChars/2]
|
||||
tail := s[len(s)-maxOutputChars/2:]
|
||||
return fmt.Sprintf("%s\n…（输出被截断，共 %d 字节）…\n%s", head, len(s), tail)
|
||||
}
|
||||
|
||||
// listHmap 列出目录下的 .hmap 产物（按名字排序，稳定输出）。
|
||||
func listHmap(dir string) []string {
|
||||
entries, err := os.ReadDir(dir)
|
||||
if err != nil {
|
||||
return nil
|
||||
}
|
||||
var out []string
|
||||
for _, e := range entries {
|
||||
if e.IsDir() || !strings.HasSuffix(e.Name(), ".hmap") {
|
||||
continue
|
||||
}
|
||||
out = append(out, filepath.Join(dir, e.Name()))
|
||||
}
|
||||
sort.Strings(out)
|
||||
return out
|
||||
}
|
||||
|
||||
func readPlgVersion(path string) string {
|
||||
b, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
return ""
|
||||
}
|
||||
s := string(b)
|
||||
i := strings.Index(s, `"version"`)
|
||||
if i < 0 {
|
||||
return ""
|
||||
}
|
||||
rest := s[i:]
|
||||
j := strings.Index(rest, ":")
|
||||
if j < 0 {
|
||||
return ""
|
||||
}
|
||||
rest = strings.TrimSpace(rest[j+1:])
|
||||
rest = strings.TrimPrefix(rest, `"`)
|
||||
if k := strings.Index(rest, `"`); k > 0 {
|
||||
return rest[:k]
|
||||
}
|
||||
return ""
|
||||
}
|
||||
|
||||
func toInt(v interface{}) (int, bool) {
|
||||
switch n := v.(type) {
|
||||
case int:
|
||||
return n, true
|
||||
case int64:
|
||||
return int(n), true
|
||||
case float64:
|
||||
return int(n), true
|
||||
}
|
||||
return 0, false
|
||||
}
|
||||
|
||||
func fallback(s, def string) string {
|
||||
if strings.TrimSpace(s) == "" {
|
||||
return def
|
||||
}
|
||||
return s
|
||||
}
|
||||
@ -1,167 +0,0 @@
|
||||
# qq · QQ 消息桥接
|
||||
|
||||
通过 [NapCat](https://github.com/NapNeko/NapCatQQ) 把 QQ 接成 HomeAgent 的一个 IO 通道：
|
||||
让 agent 收发 QQ 消息、读群/好友信息、传文件。
|
||||
|
||||
> ⚠️ 这是**安全敏感**插件：它让外部 QQ 用户能触达 agent 的工具。
|
||||
> 本文档的「权限模型」一节请务必读完。
|
||||
|
||||
## 通道与钩子
|
||||
|
||||
| 类型 | 名称 | 说明 |
|
||||
|---|---|---|
|
||||
| 出站 | `qq` | `CapText` + `CapFile` + `CapImage` + `CapAudio`；发消息/文件给 QQ |
|
||||
| 入站 | `qq` | `NoMemory: true` + `Cleaner` + `RecallPolicy: None` |
|
||||
|
||||
四个阶段钩子（全部 `StageScopeGlobal`）：
|
||||
|
||||
| 钩子 | 作用 |
|
||||
|---|---|
|
||||
| `on_input` | 把本轮 QQ 身份**绑到帧上** |
|
||||
| `before_toolcall` | 权限门：逐个工具判断是否放行 |
|
||||
| `post_action` | 清掉被拒绝时模型已经吐出的废话 |
|
||||
| `after_output` | 收尾时清理插件全局身份 |
|
||||
|
||||
## 工具（20 个）
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `qq_get_message` | 按 `message_id` 取消息正文、发送者、附件 |
|
||||
| `qq_get_history` | 取群/私聊最近历史消息 |
|
||||
| `qq_list_chats` | 会话列表（按最新消息排序，带未读数与摘要） |
|
||||
| `qq_mark_read` | 把某会话未读数清零 |
|
||||
| `qq_send_file` | 发文件/图片（私聊或群聊） |
|
||||
| `qq_get_groups` | 群列表，可按关键词搜 |
|
||||
| `qq_get_friends` | 好友列表，可按昵称/备注搜 |
|
||||
| `qq_get_recent_contacts` | 最近有消息的联系人与群 |
|
||||
| `qq_resolve_name` / `qq_resolve_nickname` | 名字 ↔ QQ 号互查 |
|
||||
| `qq_get_group_member_info` | 群成员信息 |
|
||||
| `qq_group_manage` | 群综合管理（见下） |
|
||||
| `qq_friend_action` | 好友操作 |
|
||||
| `qq_get_group_files` | 群文件列表 |
|
||||
| `qq_download_file` / `qq_upload_group_file` / `qq_get_download_tasks` | 文件传输与任务 |
|
||||
| `qq_read_document` | 读 QQ 传来的文档 |
|
||||
| `qq_video_download` | 下载视频 |
|
||||
| `qq_send_like` | 点赞 |
|
||||
|
||||
`qq_group_manage` 一个工具承载多种操作（`command` 参数）：
|
||||
`leave` 退群、`kick` 踢人、`ban`/`unban` 禁言解禁、`rename` 改名、`mute-all` 全员禁言、
|
||||
`set-card` 设名片、`set-admin` 设管理、`set-title` 设头衔、`member-list`、`group-info`、
|
||||
`msg-history`、`recall` 撤回、`pin-msg` 精华、`list-files`、`pending-requests`、`folder-create` 等。
|
||||
|
||||
**破坏性操作**（`leave`/`kick`/`ban`/`unban`/`rename`/`mute-all`/`set-card`/`set-admin`/
|
||||
`set-title`/`recall`/`pin-msg`/`folder-create`）**必须显式传 `confirm: true`**。
|
||||
|
||||
## 权限模型
|
||||
|
||||
这是本插件最重要的部分。
|
||||
|
||||
### 身份分级
|
||||
|
||||
| 身份 | 权限 |
|
||||
|---|---|
|
||||
| **owner**（Bot 所有者） | 私聊或群聊均**完整放行** |
|
||||
| **普通 QQ 用户** | 只放行白名单内的工具 |
|
||||
|
||||
### 身份必须「绑帧」，不能只存插件全局
|
||||
|
||||
源码注释记录了两个真实故障，这就是绑帧的原因：
|
||||
|
||||
1. **中断抢占后身份丢失**：中断会抢占当前轮、把现场压栈。中断轮收尾时
|
||||
`after_output` 会清空插件**全局**身份；随后外层被恢复（`resumeTask` 复用同一帧、
|
||||
**不重跑 `on_input`**）。若身份只存全局，恢复后的外层就是"无身份"，
|
||||
`before_toolcall` 在 `!auth.active` 处直接返回 —— **整个权限门失效**。
|
||||
2. **运行中到达的消息改写身份**：新消息会调 `activateAuthContext` 改写全局身份，
|
||||
把**正在跑的那一轮**换成另一方的身份（换高=越权，换低=误拒）。
|
||||
|
||||
帧上的 `Extra` 随帧一起压栈/恢复，正好是"这一轮的身份"。
|
||||
|
||||
### 合并取最小权限
|
||||
|
||||
多来源被内核合并到同一推理时，权限**取交集**而非并集：
|
||||
|
||||
```go
|
||||
p.auth.owner = p.auth.owner && next.owner
|
||||
```
|
||||
|
||||
防的是"非所有者请求 + 随后所有者消息"意外把前一个请求提权。
|
||||
|
||||
### 硬私有工具
|
||||
|
||||
非所有者**一律拒绝**（不看白名单），按前缀拦截：
|
||||
`calendar_`、`email_`、`mail_`、`agentmail_`、`memory_`、`knowledge_`、`device_`、
|
||||
`devicectl_`、`terminal_`、`shell_`、`command_`、`exec_`、`filesystem_`、`agentfs_`、
|
||||
`config_`、`settings_`、`plugin_`、`plugins_`，
|
||||
外加 `read_file`、`write_file`、`edit_file`、`delete_file`、`list_files`、`run_command`、
|
||||
`homeagent_config`、`homeagent_restart`、`output_send__email`、`output_send__mail`。
|
||||
|
||||
### 参数与会话一致性校验
|
||||
|
||||
光看工具名不够，还要检查**参数指向的会话与当前身份一致**，否则可以拿别人的
|
||||
`message_id` 去读别处内容：
|
||||
|
||||
- 带 `message_id` 的工具：该 ID 必须属于当前 QQ 会话（`lookupMsgRef` 校验 peer 与群/私聊类型）。
|
||||
- `get_group_member_info` / `get_group_files`：`group_id` 必须是**当前群**。
|
||||
|
||||
### 频率与重复控制
|
||||
|
||||
| 键 | 作用 |
|
||||
|---|---|
|
||||
| `max_qq_tool_calls` | 单轮工具调用上限 |
|
||||
| `max_qq_output_calls` | 单轮输出调用上限 |
|
||||
| `max_duplicate_qq_send` | 重复发送上限，防刷屏 |
|
||||
| `batch_window_ms` / `batch_max_ms` | 消息合批窗口 |
|
||||
|
||||
被拒时只允许**发一次权鉴说明**，之后锁止本轮剩余工具调用
|
||||
（`clearDeniedResponse` 再把模型已写出的内容清掉，避免输出里带一堆"我不能…"）。
|
||||
|
||||
## 配置项
|
||||
|
||||
### 连接
|
||||
|
||||
| 键 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `napcat_url` | — | NapCat 服务地址 |
|
||||
| `listen` | — | 本插件 HTTP 监听地址 |
|
||||
| `webhook_token` | — | webhook 校验令牌 |
|
||||
|
||||
### 身份与准入
|
||||
|
||||
| 键 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `owner` | 空 | Bot 所有者 QQ 列表（逗号分隔），拥有完整权限 |
|
||||
| `admin` | 空 | **旧配置名**，`owner` 为空时作为所有者列表（兼容用） |
|
||||
| `dm_policy` | `open` | 私聊策略：`open` / `allowlist` / `disabled` |
|
||||
| `allow_from` | 空 | 私聊白名单（QQ 号，逗号分隔） |
|
||||
| `group_policy` | `open` | 群聊策略：`open` / `allowlist` / `disabled` |
|
||||
| `group_allow_from` | 空 | 群白名单 |
|
||||
| `private_tool_allowlist` | 空 | 私聊下非所有者可用的工具 |
|
||||
| `group_tool_allowlists` | 空 | 按群配置的工具白名单 |
|
||||
|
||||
### 文件与转发
|
||||
|
||||
| 键 | 说明 |
|
||||
|---|---|
|
||||
| `files_dir` | 本地文件目录 |
|
||||
| `remote_dir` | 供 NapCat 容器访问的目录（发文件前先复制到这里） |
|
||||
| `agentfs_dir` | agent 文件系统目录 |
|
||||
| `forward_rules` | JSON 数组，每项 `{group_id,host,port,password,template}`：匹配的群消息经 **RCON** 转发到 Minecraft；`template` 支持 `{nickname}` / `{message}` 占位 |
|
||||
|
||||
## 部署前提
|
||||
|
||||
需要**自行部署 NapCat**（本插件不含 QQ 协议实现，只是 NapCat 的客户端）。
|
||||
发文件前会先把文件复制到 `remote_dir`，因为 NapCat 通常在容器里，看不到宿主任意路径。
|
||||
|
||||
## 测试
|
||||
|
||||
```bash
|
||||
go test -count=1 -race ./...
|
||||
```
|
||||
|
||||
含权限门与绑帧的回归测试。改动权限相关代码后务必跑 `-race`。
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
```
|
||||
@ -2,7 +2,7 @@
|
||||
"name": "qq",
|
||||
"name_zh": "QQ消息",
|
||||
"name_en": "qq",
|
||||
"version": "1.4.1",
|
||||
"version": "1.2.0",
|
||||
"description": "QQ 消息收发插件，通过 NapCat 协议桥接",
|
||||
"author": "HomeAgent",
|
||||
"entry": "plugin.so",
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,433 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
|
||||
"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)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 降权（本轮无法精确匹配可信 OneBot 事件 ⇒ auth={active:true}、无 peer、非 owner）时，
|
||||
// **输出仍必须放行**：发到哪个会话由 agent 自己给的 meta 决定，
|
||||
// 不该被「当前会话身份」挡住。现场：被子的中断唤醒的一轮里，父带齐 meta 也发不出去
|
||||
// （报「可信 QQ 会话身份不完整」）。
|
||||
//
|
||||
// 反之，**读取类**工具在降权时仍受当前会话限制 —— 那才是真的不能跨会话读。
|
||||
func TestDowngradedAuthStillAllowsQQOutput(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
p.auth = qqAuthContext{active: true}
|
||||
p.privateToolAllowlist = []string{"output_send__qq", "qq_get_history"}
|
||||
p.groupToolAllowlists = map[int64][]string{0: {"output_send__qq", "qq_get_history"}}
|
||||
|
||||
ctx := toolCallContext("output_send__qq", map[string]interface{}{
|
||||
"payload": "带齐 meta 的主动发送",
|
||||
"type": "text",
|
||||
"meta": `{"user_id":2198972886}`,
|
||||
})
|
||||
if err := p.beforeToolcall(ctx); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if ctx.Response != nil {
|
||||
t.Fatalf("降权时输出被拒: %s", *ctx.Response)
|
||||
}
|
||||
|
||||
ctx2 := toolCallContext("qq_get_history", map[string]interface{}{"group_id": 1027993713})
|
||||
if err := p.beforeToolcall(ctx2); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if ctx2.Response == nil || !strings.Contains(*ctx2.Response, "可信 QQ 会话身份不完整") {
|
||||
t.Fatalf("读取类工具在降权时应被当前会话限制挡住: %#v", ctx2.Response)
|
||||
}
|
||||
}
|
||||
|
||||
// ---- 消息合并（debounce）----
|
||||
|
||||
// collectInterrupts 用注入钩子收集中断文本（避免测试依赖真实 SDK）。
|
||||
func collectInterrupts(p *Plugin) *[]string {
|
||||
got := []string{}
|
||||
p.injectHook = func(s, _ string) { got = append(got, s) }
|
||||
return &got
|
||||
}
|
||||
|
||||
func TestConsecutiveMessagesFromSameSenderAreBatched(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
got := collectInterrupts(p)
|
||||
p.batchWindow = 20 * time.Millisecond
|
||||
p.batchMax = time.Second
|
||||
|
||||
for i := 0; i < 3; i++ {
|
||||
p.enqueueInterrupt("private", 10001, 0, int64(100+i), "小明", "单条", false, false)
|
||||
}
|
||||
time.Sleep(120 * time.Millisecond)
|
||||
|
||||
if len(*got) != 1 {
|
||||
t.Fatalf("同一发送者连发 3 条应合并成 1 次中断，实际 %d 次: %#v", len(*got), *got)
|
||||
}
|
||||
if !strings.Contains((*got)[0], "3 条消息") {
|
||||
t.Fatalf("合并中断应说明一共几条，实际: %s", (*got)[0])
|
||||
}
|
||||
// 三个 message_id 都要带上，模型才能取全
|
||||
for _, id := range []string{"100", "101", "102"} {
|
||||
if !strings.Contains((*got)[0], id) {
|
||||
t.Fatalf("合并中断漏了 message_id=%s: %s", id, (*got)[0])
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestDifferentSendersAreNotBatchedTogether(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
got := collectInterrupts(p)
|
||||
p.batchWindow = 20 * time.Millisecond
|
||||
p.batchMax = time.Second
|
||||
|
||||
p.enqueueInterrupt("private", 10001, 0, 1, "小明", "a", false, false)
|
||||
p.enqueueInterrupt("private", 10002, 0, 2, "小红", "b", false, false)
|
||||
time.Sleep(120 * time.Millisecond)
|
||||
|
||||
if len(*got) != 2 {
|
||||
t.Fatalf("不同发送者不该合并，应有 2 次中断，实际 %d: %#v", len(*got), *got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestBatchWindowZeroFallsBackToPerMessage(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
got := collectInterrupts(p)
|
||||
p.batchWindow = 0
|
||||
|
||||
for i := 0; i < 3; i++ {
|
||||
p.enqueueInterrupt("private", 10001, 0, int64(i), "小明", "原文", false, false)
|
||||
}
|
||||
if len(*got) != 3 {
|
||||
t.Fatalf("关闭合并时应逐条投递（3 次），实际 %d: %#v", len(*got), *got)
|
||||
}
|
||||
}
|
||||
|
||||
func TestSingleMessageKeepsOriginalText(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
got := collectInterrupts(p)
|
||||
p.batchWindow = 20 * time.Millisecond
|
||||
p.batchMax = time.Second
|
||||
|
||||
p.enqueueInterrupt("group", 10001, 20002, 7, "小明", "单条原文", true, false)
|
||||
time.Sleep(120 * time.Millisecond)
|
||||
|
||||
if len(*got) != 1 || (*got)[0] != "单条原文" {
|
||||
t.Fatalf("单条消息应沿用原文（含所有者前缀），实际 %#v", *got)
|
||||
}
|
||||
}
|
||||
|
||||
// Bot 所有者/管理员的消息给 L2，普通人的给 L1 —— 否则所有者的话会被路人
|
||||
// 的 L1 闲聊抢占/挤到队尾。
|
||||
func TestOwnerMessagesGetHigherInterruptLevel(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
got := []string{}
|
||||
p.injectHook = func(text, level string) { got = append(got, text+"|"+level) }
|
||||
p.batchWindow = 20 * time.Millisecond
|
||||
p.batchMax = time.Second
|
||||
|
||||
p.enqueueInterrupt("private", 1, 0, 1, "owner", "owner-msg", true, false)
|
||||
p.enqueueInterrupt("private", 2, 0, 2, "someone", "other-msg", false, false)
|
||||
time.Sleep(120 * time.Millisecond)
|
||||
|
||||
joined := strings.Join(got, ",")
|
||||
if !strings.Contains(joined, "owner-msg|L2") {
|
||||
t.Fatalf("所有者消息应为 L2，实际 %q", joined)
|
||||
}
|
||||
if !strings.Contains(joined, "other-msg|L1") {
|
||||
t.Fatalf("普通人消息应为 L1，实际 %q", joined)
|
||||
}
|
||||
}
|
||||
|
||||
// 身份必须绑在帧上：中断抢占当前轮、中断轮收尾清空插件全局身份之后，
|
||||
// 外层轮被恢复（resumeTask 复用同一帧、不重跑 onInput）时权限门不能整体失效。
|
||||
func TestAuthSurvivesInterruptPreemptionOfAnotherTurn(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
|
||||
// 中断轮（Bot 所有者）跑完：afterOutput 会清掉插件全局身份。
|
||||
inner := &sdk.StageContext{Extra: map[string]interface{}{
|
||||
qqAuthExtraKey: qqAuthContext{active: true, owner: true, userID: 2198972886},
|
||||
}}
|
||||
if err := p.afterOutputAuthContext(inner); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if p.auth.active {
|
||||
t.Fatal("收尾后插件全局身份应为空（复现恢复前状态）")
|
||||
}
|
||||
|
||||
// 外层轮（非所有者群成员）恢复后继续调工具：仍须按非所有者拦下私人资源工具。
|
||||
frame := &sdk.StageContext{
|
||||
Extra: map[string]interface{}{qqAuthExtraKey: qqAuthContext{active: true, userID: 10001, groupID: 20002, isGroup: true}},
|
||||
ToolCalls: []sdk.ToolCall{{Name: "calendar_list"}},
|
||||
}
|
||||
if err := p.beforeToolcall(frame); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if frame.Response == nil || !strings.Contains(*frame.Response, "私人资源工具") {
|
||||
t.Fatalf("中断恢复后权限门失效（整体放行）: %#v", frame.Response)
|
||||
}
|
||||
}
|
||||
|
||||
// 运行中到达的新消息会改写插件全局身份；正在跑的那一轮必须不受影响。
|
||||
func TestMidTurnMessageDoesNotChangeRunningTurnAuth(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
|
||||
frame := &sdk.StageContext{
|
||||
Extra: map[string]interface{}{qqAuthExtraKey: qqAuthContext{active: true, owner: true, userID: 2198972886}},
|
||||
ToolCalls: []sdk.ToolCall{{Name: "calendar_list"}},
|
||||
}
|
||||
// 路人的群消息在所有者轮运行中到达。
|
||||
p.activateAuthContext(4242, 10001, 20002, true)
|
||||
if p.auth.owner {
|
||||
t.Fatal("到达事件应改写全局身份（复现场景）")
|
||||
}
|
||||
|
||||
if err := p.beforeToolcall(frame); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if frame.Response != nil {
|
||||
t.Fatalf("在跑的所有者轮被到达消息篡改: %s", *frame.Response)
|
||||
}
|
||||
}
|
||||
|
||||
// 合并中断正文里的整批 message_id 都要消费掉，并在帧上绑定身份。
|
||||
func TestBatchInterruptConsumesAllMessageIDs(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
p.authByMessageID = map[int64]qqAuthContext{
|
||||
100: {active: true, owner: true, userID: 2198972886},
|
||||
101: {active: true, owner: true, userID: 2198972886},
|
||||
}
|
||||
ctx := &sdk.StageContext{
|
||||
RawMessage: "来自「老板」的私聊短时间内连续发来 2 条消息(message_id=100,101, user_id=2198972886)。",
|
||||
Extra: map[string]interface{}{"input_source": "qq"},
|
||||
}
|
||||
if err := p.onInputAuthContext(ctx); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !p.auth.owner {
|
||||
t.Fatalf("合并中断未恢复所有者身份: %+v", p.auth)
|
||||
}
|
||||
if len(p.authByMessageID) != 0 {
|
||||
t.Fatalf("同批 message_id 未全部清理: %v", p.authByMessageID)
|
||||
}
|
||||
if auth, ok := authOnFrame(ctx); !ok || !auth.owner {
|
||||
t.Fatalf("身份未绑定到帧上: %+v ok=%v", auth, ok)
|
||||
}
|
||||
}
|
||||
|
||||
// 非 QQ 来源（webui/timer 等）的帧上绑空身份：权限门对这些轮整体关闭。
|
||||
func TestNonQQFrameBindsInactiveAuth(t *testing.T) {
|
||||
p := newPermissionTestPlugin(t)
|
||||
p.auth = qqAuthContext{active: true, owner: true, userID: 2198972886}
|
||||
|
||||
ctx := &sdk.StageContext{
|
||||
RawMessage: "webui 里的提问",
|
||||
Extra: map[string]interface{}{"input_source": "webui"},
|
||||
ToolCalls: []sdk.ToolCall{{Name: "calendar_list"}},
|
||||
}
|
||||
if err := p.onInputAuthContext(ctx); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := p.beforeToolcall(ctx); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if ctx.Response != nil {
|
||||
t.Fatalf("非 QQ 轮不应被 QQ 权限门拦: %s", *ctx.Response)
|
||||
}
|
||||
}
|
||||
@ -1,53 +0,0 @@
|
||||
# recoverydiag · 快速检查 / 崩溃取证
|
||||
|
||||
给 guard 与 failback 用的**确定性诊断工具集**。
|
||||
|
||||
设计基调（源码原话）：**返回结论而非原文，确定性检出，不消耗 LLM token。**
|
||||
崩溃后最忌讳的是把几万行日志塞进模型上下文让它"看看"，那既慢又不可靠 ——
|
||||
这里每个工具都在本地算出结论再返回。
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `recoverydiag_diag_triage` | 快速分诊：按退出码 / 信号 / 存活状态粗分类别（进程死亡 vs 配置类不可达 vs 正常） |
|
||||
| `recoverydiag_diag_db` | config.db 完整性（`PRAGMA integrity_check`）+ LLM 源解析校验（`core.llm.sources.*` 必备字段），逐项 ok/fail |
|
||||
| `recoverydiag_diag_log_scan` | 在日志目录的时间窗内统计已知错误签名（panic / OOM / 网络不可达 / provider 失败 / sql / 致命）出现次数，给出主导结论 |
|
||||
| `recoverydiag_diag_delta` | 对比 baseline（上次 good 快照/目录）与现状，列出 created / modified / deleted 清单与摘要，判定"改了什么" |
|
||||
| `recoverydiag_diag_loc` | 综合前四项结论，按**因果强度正交排序**定位根因并给出推荐恢复动作 |
|
||||
|
||||
## 用法顺序
|
||||
|
||||
```
|
||||
diag_triage → diag_db → diag_log_scan → diag_delta → diag_loc
|
||||
（各自独立，可只跑需要的） （要传前四项的结论）
|
||||
```
|
||||
|
||||
`diag_loc` 需要你把它余下的结论**作为参数传进去**（`triage` / `db` / `log` / `delta` 四个对象），
|
||||
它不自己去调 —— 这样它只做归因，不重复执行。
|
||||
|
||||
## 配置项
|
||||
|
||||
| 键 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `db_check_cmd` | `auto` | `diag_db` 用的 `sqlite3` 命令。留空=auto：可用时用 sqlite3，缺失则回退读内核 Settings |
|
||||
| `recovery_kb_dir` | 空 | `diag_loc` 结论 JSON 的落盘目录。缺省 `<data_dir>/recovery_kb` |
|
||||
|
||||
## 不注册通道与钩子
|
||||
|
||||
本插件**只提供工具**，不订阅输入、不挂阶段钩子 —— 它是被 guard 或 agent 主动调用的，
|
||||
不做后台干预。
|
||||
|
||||
## 测试
|
||||
|
||||
```bash
|
||||
go test -count=1 ./...
|
||||
```
|
||||
|
||||
`diag_test.go` 覆盖各诊断项的判定逻辑。
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
```
|
||||
@ -1,44 +1,13 @@
|
||||
# rss · RSS/Atom 订阅监控
|
||||
# rss
|
||||
|
||||
订阅 RSS/Atom 源，**有新文章时主动通知** agent（不必每轮去问）。
|
||||
rss plugin
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `rss_subscribe` | 订阅一个 RSS/Atom 源 |
|
||||
| `rss_unsubscribe` | 取消订阅 |
|
||||
| `rss_list` | 列出全部订阅 |
|
||||
| `rss_check_now` | 立即检查所有源（不等轮询周期） |
|
||||
|
||||
## 配置项
|
||||
|
||||
| 键 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `poll_interval` | `30` | 默认轮询间隔（**分钟**） |
|
||||
|
||||
订阅时可对单个源覆盖间隔。
|
||||
|
||||
## 通知机制
|
||||
|
||||
- 后台按各自间隔轮询（默认 30 分钟）。
|
||||
- 发现新条目时通过 `InjectInterruptText` 注入，格式形如
|
||||
`📡 <源标题> (<URL>) — N 篇新文章:` 后跟条目。
|
||||
- 注入带 **`NoMemory: true`**，通道 `rss` 也声明为 `NoMemory` ——
|
||||
订阅推送是信号不是知识，不该进向量化挤掉别的记忆。
|
||||
|
||||
## 实现要点
|
||||
|
||||
- **订阅时就记下全部已有 GUID**：`handleSubscribe` 会把抓取到的历史条目
|
||||
一次性标为 `seenGUIDs`，所以**订阅一个源不会把它的历史文章全部推送一遍**。
|
||||
只有订阅之后新出现的条目才通知。这是避免刷屏的关键。
|
||||
- **去重按「源 URL + GUID」**：不同源可能用相同 GUID，只用 GUID 会互相误判。
|
||||
GUID 缺失时回退用 `link`；两者都缺则跳过该条。
|
||||
- `seenGUIDs` 有清理逻辑，不会无限增长。
|
||||
- 解析用 [gofeed](https://github.com/mmcdole/gofeed)（`v1.4.0`）。
|
||||
|
||||
## 构建
|
||||
## Build
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
plugindev build
|
||||
```
|
||||
|
||||
## Install
|
||||
|
||||
Upload the .hmap file through the Plugin Manager API.
|
||||
|
||||
@ -104,9 +104,6 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
s.SetAutoRestart(true)
|
||||
p.sdk = s
|
||||
p.client = &http.Client{Timeout: 30 * time.Second}
|
||||
// 入站通道：本插件用 "rss" 通道注入输入（见 Inject* 调用），
|
||||
// 输入侧必须显式登记 —— 否则"把该 inputch 划给驻留子"会报 `inputch 未注册`。
|
||||
_ = s.RegisterInputChannel("rss", sdk.ChannelDef{NoMemory: true})
|
||||
p.fp = gofeed.NewParser()
|
||||
p.stopCh = make(chan struct{})
|
||||
p.seenGUIDs = make(map[string]bool)
|
||||
@ -161,7 +158,7 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
s.RegisterTool(tp+"list", sdk.ToolDef{
|
||||
Name: tp + "list", Description: "List all subscribed feeds",
|
||||
Parameters: map[string]interface{}{
|
||||
"type": "object",
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{},
|
||||
},
|
||||
}, p.handleList)
|
||||
@ -170,7 +167,7 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
Name: tp + "check_now", Description: "Manually check all feeds for new articles now",
|
||||
NoMemory: true,
|
||||
Parameters: map[string]interface{}{
|
||||
"type": "object",
|
||||
"type": "object",
|
||||
"properties": map[string]interface{}{},
|
||||
},
|
||||
}, p.handleCheckNow)
|
||||
@ -303,10 +300,7 @@ func (p *Plugin) checkFeed(sub FeedSub) {
|
||||
lines = append(lines, line)
|
||||
}
|
||||
|
||||
// 中断注入是「系统通知」，NoMemory 写明意图：这类提醒不参与记忆计算，
|
||||
// 原文仍进上下文（模型当轮看得到）。
|
||||
p.sdk.InjectInterruptTextOpts("rss", "rss", strings.Join(lines, "\n"),
|
||||
sdk.InjectOptions{NoMemory: true})
|
||||
p.sdk.InjectInterruptText("rss", "rss", strings.Join(lines, "\n"))
|
||||
p.saveData()
|
||||
}
|
||||
|
||||
@ -448,7 +442,7 @@ func (p *Plugin) loadData() {
|
||||
return
|
||||
}
|
||||
var data struct {
|
||||
Feeds []FeedSub `json:"feeds"`
|
||||
Feeds []FeedSub `json:"feeds"`
|
||||
SeenGUIDs map[string]bool `json:"seen"`
|
||||
}
|
||||
if json.Unmarshal(b, &data) != nil {
|
||||
@ -466,7 +460,7 @@ func (p *Plugin) saveData() {
|
||||
p.mu.RLock()
|
||||
defer p.mu.RUnlock()
|
||||
data := struct {
|
||||
Feeds []FeedSub `json:"feeds"`
|
||||
Feeds []FeedSub `json:"feeds"`
|
||||
SeenGUIDs map[string]bool `json:"seen"`
|
||||
}{
|
||||
Feeds: p.feeds,
|
||||
@ -491,6 +485,8 @@ func (p *Plugin) cleanupData() {
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
|
||||
// atomicWriteJSON 原子写 JSON：先写临时文件再 rename，避免进程崩溃截断数据文件。
|
||||
func atomicWriteJSON(path string, data []byte) error {
|
||||
tmp := path + ".tmp"
|
||||
|
||||
@ -1,48 +0,0 @@
|
||||
# sanitizer · 文本清洗
|
||||
|
||||
**不注册任何工具**，只挂三个阶段钩子，在 Agent 全链路上洗掉两类污染：
|
||||
|
||||
1. **坏字节**：坏 UTF-8、`U+FFFD`（替换符）、ANSI 转义序列
|
||||
2. **思维泄漏**：LLM 输出里残留的工具调用标记
|
||||
|
||||
## 为什么需要它
|
||||
|
||||
坏字节会**被 LLM 复读**。一次工具返回乱码（比如源码里带 ANSI 颜色码、或二进制片段被当文本读出来），
|
||||
这些字节会进上下文，之后模型每次生成都可能把它抄一遍 —— 越滚越脏。
|
||||
在每个入口洗掉，比事后清理便宜得多。
|
||||
|
||||
思维泄漏则是另一种：模型有时把 `<tool_call>...</tool_call>` 这类内部标记直接写进正文，
|
||||
用户就看到一堆不该出现的 XML。
|
||||
|
||||
## 挂载的三个阶段
|
||||
|
||||
| 阶段 | 处理对象 | 作用 |
|
||||
|---|---|---|
|
||||
| `on_input` | `ctx.RawMessage` | 洗用户输入，脏字节不进后续链路 |
|
||||
| `after_toolcall` | `ctx.ToolResults` | 洗工具结果，**坏字节不进 LLM 上下文** |
|
||||
| `post_action` | `ctx.LLMText` | 洗模型输出：先清思维泄漏，再清乱码 |
|
||||
|
||||
每次有改动都打一行日志（`cleaned N bytes`），便于确认它真的在工作而不是静默失败。
|
||||
|
||||
## 识别哪些泄漏形态
|
||||
|
||||
按正则匹配多种标记写法，覆盖不同模型家族的习惯：
|
||||
|
||||
- `<tool_call>…</tool_call>`、`<invoke>…</invoke>`、`<tool>…</tool>`
|
||||
- `<function>…</function>`
|
||||
- 上述标记包在 ```xml / ```json 代码块里的形态
|
||||
- 中文括号变体：`【tool_call】…【/tool_call】`
|
||||
|
||||
## 实现要点
|
||||
|
||||
- 依赖 **ABI v2 的 stage 写回能力**：插件对 `StageContext` 的修改会同步回内核。
|
||||
在 v1 上改了不生效。
|
||||
- 读写 `StageContext` 时按约定加 `ctx.Lock()`。
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
go build -buildmode=plugin -o sanitizer.so .
|
||||
```
|
||||
|
||||
或经 `hmapdev build` 打包为 `.hmap`。
|
||||
@ -1,77 +0,0 @@
|
||||
# vanblog · VanBlog 博客管理
|
||||
|
||||
用管理 API 操作 [VanBlog](https://vanblog.mereith.com/) 开源博客系统：
|
||||
文章增删改查、分类标签、草稿发布、备份导出等。
|
||||
|
||||
## 配置项
|
||||
|
||||
| 键 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `url` | `https://blog.jianfgit.xyz` | VanBlog 站点基地址 |
|
||||
| `token` | 空 | 管理员 API Token（长期令牌，从后台「Token 管理」创建） |
|
||||
| `reset_token` | 空 | 用于 `auth/restore` 重置管理员密码的**特殊** Token |
|
||||
|
||||
`token` 与 `reset_token` 都是 `password` 类型（界面遮蔽）。
|
||||
|
||||
## 工具（28 个）
|
||||
|
||||
### 文章
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `vanblog_list_articles` | 列文章，支持分页与搜索 |
|
||||
| `vanblog_get_article` | 取单篇完整内容 |
|
||||
| `vanblog_create_article` | 新建（`title` 与 `category` 必填） |
|
||||
| `vanblog_update_article` | 更新（**只传要改的字段**） |
|
||||
| `vanblog_delete_article` | 删除（**软删除**） |
|
||||
| `vanblog_search_articles` | 按链接搜索文章 |
|
||||
|
||||
### 草稿
|
||||
|
||||
`vanblog_manage_drafts`：`list` / `get` / `create` / `update` / `delete` / **`publish`**
|
||||
|
||||
### 内容组织
|
||||
|
||||
| 工具 | 命令 |
|
||||
|---|---|
|
||||
| `vanblog_manage_categories` | `list` / `get` / `create` / `update` / `delete` |
|
||||
| `vanblog_manage_tags` | `list` / `get` / `rename` / `delete` |
|
||||
|
||||
### 站点与运维
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `vanblog_manage_site` / `_settings` / `_menu` / `_social` / `_links` | 站点配置类 |
|
||||
| `vanblog_manage_about` / `_pages` | 关于页与自定义页面 |
|
||||
| `vanblog_manage_images` | 图床管理 |
|
||||
| `vanblog_manage_rewards` | 赞赏配置 |
|
||||
| `vanblog_manage_backup` | 备份 |
|
||||
| `vanblog_manage_caddy` | Caddy 配置 |
|
||||
| `vanblog_manage_isr` | ISR 增量静态渲染 |
|
||||
| `vanblog_manage_pipelines` | 流水线 |
|
||||
| `vanblog_manage_collaborators` | 协作者 |
|
||||
| `vanblog_manage_tokens` | Token 管理 |
|
||||
| `vanblog_get_analysis` / `_logs` / `_meta` | 统计、日志、元信息 |
|
||||
| `vanblog_auth` | 认证相关（含 `restore` 重置密码） |
|
||||
|
||||
> 工具名前缀取自插件名（`tp`），上面按默认 `vanblog_` 列出。
|
||||
|
||||
## 实现要点
|
||||
|
||||
- 走的是 VanBlog 的管理 API（`/api/admin/...`），所以必须配 **admin token**，
|
||||
不是前台只读接口。
|
||||
- `update_article` 是**部分更新**：只传想改的字段，没传的保持不变。
|
||||
（不要为了改标题而把正文一起传一遍。）
|
||||
- `delete_article` 是**软删除**，内容仍在，可在后台恢复。
|
||||
- 早期版本把 token 放在内核配置（`plugin.vanblog.token`）里，
|
||||
现在会**自动迁移**到插件配置，迁移后清空内核侧取值。
|
||||
|
||||
## 前置
|
||||
|
||||
需要一个可访问的 VanBlog 实例，并在后台创建一个长期 Token。
|
||||
|
||||
## 构建
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
```
|
||||
@ -1,81 +0,0 @@
|
||||
# Vikunja 插件（HomeAgent）
|
||||
|
||||
把 [Vikunja](https://vikunja.io) 待办/任务管理接入 HomeAgent：用自然语言查任务、建任务、改期、完成、看板拖动、指派、评论、时间跟踪、导入数据等。
|
||||
|
||||
## 配置项（全部可在插件配置界面修改）
|
||||
|
||||
| 键 | 类型 | 默认 | 说明 |
|
||||
|---|---|---|---|
|
||||
| `url` | string | `https://vikunja.jianfgit.xyz` | 站点根地址，**不带** `/api` |
|
||||
| `token` | password(secret) | 空 | **必填**。Vikunja → 设置 → API Tokens 生成（`tk_` 开头）。令牌的权限范围决定本插件能力上限：勾全范围即为完整能力 |
|
||||
| `api_version` | select | `v2` | `v2`（推荐，标准 REST，含时间跟踪等新能力）或 `v1`（用于 v2 暂未提供的端点） |
|
||||
| `default_project_id` | string | 空 | 新建任务未指定项目时落到这里；留空则必须显式指定 |
|
||||
| `max_items` | int | `25` | 列表类工具的默认条数，控制上下文体积 |
|
||||
| `compact_output` | bool | `true` | 任务/项目/标签列表只返回关键字段；关闭则返回 Vikunja 完整对象 |
|
||||
| `timeout_seconds` | int | `20` | 单次 HTTP 超时 |
|
||||
| `verify_tls` | bool | `true` | 自签证书站点可关闭（不建议） |
|
||||
|
||||
配置在**每次工具调用前重新读取**，因此换了 token 不必重启插件。
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 能力 |
|
||||
|---|---|
|
||||
| `vikunja_status` | 连接/配置自检：地址、token 对应的用户、API 版本、服务器能力、CalDAV 地址 |
|
||||
| `vikunja_tasks` | 列任务：按项目、完成状态、截止（today/this_week/overdue/no_due）、关键词、原生 filter 表达式 |
|
||||
| `vikunja_task_get` / `task_create` / `task_update` / `task_done` / `task_delete` | 任务增删改查（`task_update` 只传要改的字段） |
|
||||
| `vikunja_task_bulk` | 批量改完成状态/项目/优先级/截止/标签 |
|
||||
| `vikunja_task_assignees` / `task_labels` / `task_comments` / `task_relations` / `task_attachments` | 指派、标签、评论、关联（子任务/依赖/相关）、附件（支持上传本地文件） |
|
||||
| `vikunja_projects` / `project_views` | 项目增删改查、归档；视图与看板桶（把任务移入桶＝看板拖动） |
|
||||
| `vikunja_labels` / `filters` | 标签、保存的筛选器（Saved Filter） |
|
||||
| `vikunja_teams` / `sharing` | 团队与成员；项目分享（用户/团队授权、链接分享含密码） |
|
||||
| `vikunja_notifications` / `subscriptions` / `webhooks` | 通知、订阅、Webhook 管理 |
|
||||
| `vikunja_time_entries` | 时间跟踪（**仅 v2**）：补录/修改/删除、开始与停止计时器 |
|
||||
| `vikunja_migrate` | 从 TickTick/WeKan/CSV/Planka/Vikunja 文件（v2）与 Todoist/Trello/微软待办（v1）导入 |
|
||||
| `vikunja_user` / `vikunja_admin` | 当前账号（设置、登录会话、API Token）与实例管理（用户增删/提权/停用/改密、项目归属转移，需实例管理员） |
|
||||
| `vikunja_reactions` | 任务/评论的表情回应 |
|
||||
| `vikunja_api` | **通用直通**：调任意端点，未封装的能力走这里（可强制指定 v1/v2），保证能力无死角 |
|
||||
|
||||
## v1 / v2 差异（已按实例自带规范逐条核对）
|
||||
|
||||
插件默认 v2，并自动处理下列差异：
|
||||
|
||||
| 操作 | v1 | v2 |
|
||||
|---|---|---|
|
||||
| 建任务 | `PUT /projects/{id}/tasks` | `POST /projects/{id}/tasks` |
|
||||
| 改任务 | `POST /tasks/{id}`（必须整对象 → 插件自动取回-合并-提交） | `PATCH /tasks/{id}`（merge-patch，只发变更字段；被拒则回落取回-合并-PUT） |
|
||||
| 搜索参数 | `?s=` | `?q=` |
|
||||
| 加标签 | `PUT`（Label 对象） | `POST`（`{"label_id":N}`） |
|
||||
| 批量改 | `POST /tasks/bulk` | `PUT /tasks/bulk` |
|
||||
| 时间跟踪 | 不支持 | `/time-entries`（`end_time` 为 null 即计时中；停止用 `/time-entries/timer/stop`） |
|
||||
| 导入 | Todoist / Trello / 微软待办 | TickTick / WeKan / CSV / Planka / Vikunja 文件 |
|
||||
|
||||
> 官方路线：v1 仍支持但新端点只进 v2，3.0 弃用、4.0 移除。除“导入”外建议一律用 v2。
|
||||
|
||||
## 开发与构建
|
||||
|
||||
```bash
|
||||
cd third_party/homeagent-sdk/example/vikunja
|
||||
|
||||
go test -count=1 -race ./... # 16 项测试（httptest 打桩，不需要真 token）
|
||||
hmapdev build # 产出 dist/vikunja_bundle.hmap
|
||||
```
|
||||
|
||||
`go.mod` 里的 `replace` 把 SDK 指向仓库内的 `third_party/homeagent-sdk`，因此无需联网拉私有模块。
|
||||
|
||||
### 部署到运行实例
|
||||
|
||||
`.hmap` 包内是 `plugin.json` + `plugin.bin.<os>.<arch>`，安装时按运行平台重命名入口文件：
|
||||
|
||||
```bash
|
||||
unzip -o dist/vikunja_bundle.hmap -d /home/newqqagent/plugins/vikunja
|
||||
cd /home/newqqagent/plugins/vikunja && mv plugin.bin.linux.amd64 plugin.bin
|
||||
# 然后重载插件（或重启 homeagent.service）
|
||||
```
|
||||
|
||||
## 已知边界
|
||||
|
||||
- **附件下载**未单独封装：`task_attachments` 支持列出/上传/删除，下载请用 `vikunja_api` 访问附件 URL。
|
||||
- **链接分享的字段**（`right`/`password`）按 Vikunja 版本语义透传；如遇 4xx，可直接用 `raw` 参数传完整 JSON。
|
||||
- **批量改标签**的 `fields` 结构以 `BulkTask` 为准，未在真实实例上验证过（缺少可用 token），如有偏差请用 `vikunja_api` 直通。
|
||||
- CalDAV 是客户端协议，插件只提供地址（`vikunja_status` 里的 `caldav_url`），不做 CalDAV 同步。
|
||||
@ -1,15 +0,0 @@
|
||||
module vikunja-plugin
|
||||
|
||||
go 1.25.0
|
||||
|
||||
require gitcode.com/JianFeeeee/homeagent-sdk v0.0.0
|
||||
|
||||
// 与同目录其它示例一致：SDK 指向仓库内的 vendored 副本
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
replace gitcode.com/JianFeeeee/homeagent-sdk => ../../
|
||||
@ -1,17 +0,0 @@
|
||||
{
|
||||
"name": "vikunja",
|
||||
"name_zh": "Vikunja 待办",
|
||||
"name_en": "Vikunja",
|
||||
"version": "1.0.1",
|
||||
"description": "Vikunja 待办/任务管理：任务增删改查、项目与看板桶、标签、指派、评论、关联、附件、保存筛选器、团队与分享、通知、订阅、Webhook、时间跟踪、数据导入、实例管理；并附通用 API 直通工具兜底",
|
||||
"author": "HomeAgent",
|
||||
"entry": "plugin.bin",
|
||||
"tags": [
|
||||
"vikunja",
|
||||
"todo",
|
||||
"task",
|
||||
"gtd",
|
||||
"productivity"
|
||||
],
|
||||
"targets": "linux/amd64"
|
||||
}
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,523 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"io"
|
||||
"net/http"
|
||||
"net/http/httptest"
|
||||
"strings"
|
||||
"testing"
|
||||
"time"
|
||||
)
|
||||
|
||||
// newTestPlugin 构造一个不依赖 sdk 的插件实例，指向 httptest 服务。
|
||||
// ensure() 在 sdk==nil 时会保留已设置的字段，因此可以这样直接测处理器。
|
||||
func newTestPlugin(t *testing.T, h http.HandlerFunc) (*Plugin, *httptest.Server) {
|
||||
t.Helper()
|
||||
srv := httptest.NewServer(h)
|
||||
t.Cleanup(srv.Close)
|
||||
p := &Plugin{
|
||||
name: "vikunja",
|
||||
baseURL: srv.URL,
|
||||
token: "tk_test",
|
||||
apiVer: "v2",
|
||||
maxItems: 5,
|
||||
compact: true,
|
||||
http: srv.Client(),
|
||||
}
|
||||
return p, srv
|
||||
}
|
||||
|
||||
func mustJSON(t *testing.T, v interface{}) []byte {
|
||||
t.Helper()
|
||||
b, err := json.Marshal(v)
|
||||
if err != nil {
|
||||
t.Fatalf("marshal: %v", err)
|
||||
}
|
||||
return b
|
||||
}
|
||||
|
||||
// 1) 列表：v2 用 q= 搜索，且 filter 会带上默认 done 条件
|
||||
func TestTasksListV2(t *testing.T) {
|
||||
var gotQuery string
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
gotQuery = r.URL.RawQuery
|
||||
if r.Header.Get("Authorization") != "Bearer tk_test" {
|
||||
t.Errorf("缺少 Bearer 头: %q", r.Header.Get("Authorization"))
|
||||
}
|
||||
w.Header().Set("Content-Type", "application/json")
|
||||
_, _ = w.Write([]byte(`[{"id":1,"title":"写周报","done":false,"project_id":3,"due_date":"2026-09-13T10:00:00Z","labels":[{"title":"工作"}],"assignees":[{"username":"jianf"}]}]`))
|
||||
})
|
||||
res, err := p.handleTasksList(map[string]interface{}{"search": "周报", "limit": float64(5)})
|
||||
if err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
if !strings.Contains(gotQuery, "q=%E5%91%A8%E6%8A%A5") {
|
||||
t.Errorf("v2 应使用 q= 搜索，实际 query=%s", gotQuery)
|
||||
}
|
||||
if strings.Contains(gotQuery, "s=") {
|
||||
t.Errorf("v2 不应使用 s=，实际 query=%s", gotQuery)
|
||||
}
|
||||
if !strings.Contains(gotQuery, "per_page=5") {
|
||||
t.Errorf("per_page 未生效: %s", gotQuery)
|
||||
}
|
||||
if !strings.Contains(gotQuery, "filter=done+%3D+false") && !strings.Contains(gotQuery, "filter=done%20%3D%20false") {
|
||||
t.Errorf("默认应过滤未完成，实际 filter 片段: %s", gotQuery)
|
||||
}
|
||||
m, ok := res.(map[string]interface{})
|
||||
if !ok {
|
||||
t.Fatalf("结果应为 map，实际 %T", res)
|
||||
}
|
||||
if m["count"].(int) != 1 {
|
||||
t.Errorf("count 应为 1，实际 %v", m["count"])
|
||||
}
|
||||
tasks := m["tasks"].([]interface{})
|
||||
tk := tasks[0].(map[string]interface{})
|
||||
if _, ok := tk["labels"].([]string); !ok {
|
||||
t.Errorf("标签应被投影成名称数组，实际 %T", tk["labels"])
|
||||
}
|
||||
if _, ok := tk["description"]; ok {
|
||||
t.Errorf("精简输出不应出现 description")
|
||||
}
|
||||
}
|
||||
|
||||
// 2) 列表：v1 用 s= 搜索
|
||||
func TestTasksListV1SearchParam(t *testing.T) {
|
||||
var gotQuery string
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
gotQuery = r.URL.RawQuery
|
||||
_, _ = w.Write([]byte(`[]`))
|
||||
})
|
||||
p.apiVer = "v1"
|
||||
if _, err := p.handleTasksList(map[string]interface{}{"search": "abc"}); err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
if !strings.Contains(gotQuery, "s=abc") {
|
||||
t.Errorf("v1 应使用 s= 搜索，实际 %s", gotQuery)
|
||||
}
|
||||
if strings.Contains(gotQuery, "q=") {
|
||||
t.Errorf("v1 不应出现 q=，实际 %s", gotQuery)
|
||||
}
|
||||
}
|
||||
|
||||
// 3) 建任务：v1=PUT、v2=POST（同路径，方法不同）
|
||||
func TestTaskCreateMethodByVersion(t *testing.T) {
|
||||
for _, tc := range []struct {
|
||||
ver string
|
||||
method string
|
||||
}{
|
||||
{"v1", http.MethodPut},
|
||||
{"v2", http.MethodPost},
|
||||
} {
|
||||
var gotMethod, gotPath string
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
gotMethod, gotPath = r.Method, r.URL.Path
|
||||
_, _ = w.Write([]byte(`{"id":42,"title":"买菜"}`))
|
||||
})
|
||||
p.apiVer = tc.ver
|
||||
if _, err := p.handleTaskCreate(map[string]interface{}{"project_id": "3", "title": "买菜"}); err != nil {
|
||||
t.Fatalf("[%s] err: %v", tc.ver, err)
|
||||
}
|
||||
if gotMethod != tc.method {
|
||||
t.Errorf("[%s] 期望 %s，实际 %s", tc.ver, tc.method, gotMethod)
|
||||
}
|
||||
if gotPath != "/api/"+tc.ver+"/projects/3/tasks" {
|
||||
t.Errorf("[%s] 路径错误: %s", tc.ver, gotPath)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 4) 改任务（v2）：走 merge-patch，只发变更字段
|
||||
func TestTaskUpdateV2MergePatch(t *testing.T) {
|
||||
var method, ctype string
|
||||
var body map[string]interface{}
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
method = r.Method
|
||||
ctype = r.Header.Get("Content-Type")
|
||||
raw, _ := io.ReadAll(r.Body)
|
||||
_ = json.Unmarshal(raw, &body)
|
||||
_, _ = w.Write([]byte(`{"id":7,"done":true}`))
|
||||
})
|
||||
if _, err := p.handleTaskUpdate(map[string]interface{}{"id": "7", "done": true}); err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
if method != http.MethodPatch {
|
||||
t.Errorf("v2 应用 PATCH，实际 %s", method)
|
||||
}
|
||||
if !strings.Contains(ctype, "merge-patch") {
|
||||
t.Errorf("应使用 merge-patch 内容类型，实际 %s", ctype)
|
||||
}
|
||||
if len(body) != 1 || body["done"] != true {
|
||||
t.Errorf("只应发送变更字段，实际 %v", body)
|
||||
}
|
||||
}
|
||||
|
||||
// 5) 改任务（v2）回退：merge-patch 被拒 → 取回-合并-PUT
|
||||
func TestTaskUpdateV2FallbackToMergePut(t *testing.T) {
|
||||
var calls []string
|
||||
var putBody map[string]interface{}
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
calls = append(calls, r.Method+" "+r.URL.Path)
|
||||
switch {
|
||||
case r.Method == http.MethodPatch:
|
||||
w.WriteHeader(http.StatusUnsupportedMediaType)
|
||||
_, _ = w.Write([]byte(`{"code":9,"message":"unsupported media type"}`))
|
||||
case r.Method == http.MethodGet:
|
||||
_, _ = w.Write([]byte(`{"id":7,"title":"旧标题","done":false,"priority":1}`))
|
||||
case r.Method == http.MethodPut:
|
||||
raw, _ := io.ReadAll(r.Body)
|
||||
_ = json.Unmarshal(raw, &putBody)
|
||||
_, _ = w.Write([]byte(`{"id":7,"title":"新标题","done":false,"priority":1}`))
|
||||
default:
|
||||
t.Errorf("意外请求: %s %s", r.Method, r.URL.Path)
|
||||
}
|
||||
})
|
||||
if _, err := p.handleTaskUpdate(map[string]interface{}{"id": "7", "title": "新标题"}); err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
want := []string{"PATCH /api/v2/tasks/7", "GET /api/v2/tasks/7", "PUT /api/v2/tasks/7"}
|
||||
if len(calls) != len(want) {
|
||||
t.Fatalf("调用序列不符: %v", calls)
|
||||
}
|
||||
for i := range want {
|
||||
if calls[i] != want[i] {
|
||||
t.Errorf("第 %d 步期望 %s，实际 %s", i+1, want[i], calls[i])
|
||||
}
|
||||
}
|
||||
if putBody["title"] != "新标题" {
|
||||
t.Errorf("合并后的 body 应含新标题，实际 %v", putBody)
|
||||
}
|
||||
if putBody["priority"] != float64(1) {
|
||||
t.Errorf("合并必须保留原有字段（priority），实际 %v", putBody)
|
||||
}
|
||||
}
|
||||
|
||||
// 6) 改任务（v1）：没有 merge-patch，必须取回-合并-POST
|
||||
func TestTaskUpdateV1FetchMergePost(t *testing.T) {
|
||||
var calls []string
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
calls = append(calls, r.Method+" "+r.URL.Path)
|
||||
if r.Method == http.MethodGet {
|
||||
_, _ = w.Write([]byte(`{"id":9,"title":"旧","priority":2}`))
|
||||
return
|
||||
}
|
||||
_, _ = w.Write([]byte(`{"id":9,"title":"新","priority":2}`))
|
||||
})
|
||||
p.apiVer = "v1"
|
||||
if _, err := p.handleTaskUpdate(map[string]interface{}{"id": "9", "title": "新"}); err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
want := []string{"GET /api/v1/tasks/9", "POST /api/v1/tasks/9"}
|
||||
if len(calls) != 2 || calls[0] != want[0] || calls[1] != want[1] {
|
||||
t.Fatalf("v1 应为 GET→POST，实际 %v", calls)
|
||||
}
|
||||
}
|
||||
|
||||
// 7) 错误映射：401 提示检查 token
|
||||
func TestErrorHint401(t *testing.T) {
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
w.WriteHeader(http.StatusUnauthorized)
|
||||
_, _ = w.Write([]byte(`{"code":11,"message":"invalid token"}`))
|
||||
})
|
||||
_, err := p.handleTasksList(map[string]interface{}{})
|
||||
if err == nil {
|
||||
t.Fatal("应返回错误")
|
||||
}
|
||||
msg := err.Error()
|
||||
if !strings.Contains(msg, "401") || !strings.Contains(msg, "code=11") {
|
||||
t.Errorf("错误信息应含状态码与 Vikunja code，实际 %s", msg)
|
||||
}
|
||||
if !strings.Contains(msg, "token") {
|
||||
t.Errorf("401 应给出 token 提示，实际 %s", msg)
|
||||
}
|
||||
}
|
||||
|
||||
// 8) 未配置 token 时应给出可操作提示，而不是发出无凭据请求
|
||||
func TestMissingToken(t *testing.T) {
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
t.Error("未配置 token 时不应发请求")
|
||||
})
|
||||
p.token = ""
|
||||
_, err := p.handleTasksList(map[string]interface{}{})
|
||||
if err == nil || !strings.Contains(err.Error(), "vikunja.token") {
|
||||
t.Fatalf("应提示配置项名，实际 %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// 9) 导入：Todoist 必须走 v1（即使插件默认是 v2）
|
||||
func TestMigrateUsesV1ForTodoist(t *testing.T) {
|
||||
var path string
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
path = r.URL.Path
|
||||
_, _ = w.Write([]byte(`{"ok":true}`))
|
||||
})
|
||||
if _, err := p.handleMigrate(map[string]interface{}{"action": "start", "source": "todoist", "code": "abc"}); err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
if path != "/api/v1/migration/todoist/migrate" {
|
||||
t.Errorf("Todoist 导入必须走 v1，实际 %s", path)
|
||||
}
|
||||
}
|
||||
|
||||
// 10) 导入：WeKan 走 v2
|
||||
func TestMigrateUsesV2ForWekan(t *testing.T) {
|
||||
var path, method string
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
path, method = r.URL.Path, r.Method
|
||||
_, _ = w.Write([]byte(`{"ok":true}`))
|
||||
})
|
||||
if _, err := p.handleMigrate(map[string]interface{}{"action": "start", "source": "wekan"}); err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
if path != "/api/v2/migration/wekan/migrate" || method != http.MethodPost {
|
||||
t.Errorf("WeKan 应走 v2 POST，实际 %s %s", method, path)
|
||||
}
|
||||
}
|
||||
|
||||
// 11) 时间跟踪：秒数换算成 end_time；计时开始则不带 end_time
|
||||
func TestTimeEntrySecondsBecomesEndTime(t *testing.T) {
|
||||
var body map[string]interface{}
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
raw, _ := io.ReadAll(r.Body)
|
||||
_ = json.Unmarshal(raw, &body)
|
||||
_, _ = w.Write([]byte(`{"id":1}`))
|
||||
})
|
||||
start := "2026-09-12T10:00:00+08:00"
|
||||
if _, err := p.handleTimeEntries(map[string]interface{}{
|
||||
"action": "create", "task_id": "5", "seconds": float64(600),
|
||||
"start_time": start,
|
||||
}); err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
// 判据不写死字符串：按时区无关的方式比较两个时间点
|
||||
sStart, err := time.Parse(time.RFC3339, start)
|
||||
if err != nil {
|
||||
t.Fatalf("case 自身时间写错: %v", err)
|
||||
}
|
||||
gotEnd, ok := body["end_time"].(string)
|
||||
if !ok {
|
||||
t.Fatalf("应有 end_time，实际 %v", body["end_time"])
|
||||
}
|
||||
tEnd, err := time.Parse(time.RFC3339, gotEnd)
|
||||
if err != nil {
|
||||
t.Fatalf("end_time 不是 RFC3339: %q", gotEnd)
|
||||
}
|
||||
if diff := tEnd.Sub(sStart); diff != 10*time.Minute {
|
||||
t.Errorf("end_time 应由 start_time+600s 推出，实际差值 %v", diff)
|
||||
}
|
||||
if _, ok := body["seconds"]; ok {
|
||||
t.Errorf("TimeEntry 没有 seconds 字段，不应发送：%v", body)
|
||||
}
|
||||
|
||||
body = nil
|
||||
if _, err := p.handleTimeEntries(map[string]interface{}{"action": "timer_start", "task_id": "5"}); err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
v, present := body["end_time"]
|
||||
if !present || v != nil {
|
||||
t.Errorf("计时开始应显式 end_time=null（live timer），实际 %v", body)
|
||||
}
|
||||
}
|
||||
|
||||
// 12) 时间跟踪在 v1 下应给出明确不可用提示
|
||||
func TestTimeEntryUnavailableOnV1(t *testing.T) {
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {})
|
||||
p.apiVer = "v1"
|
||||
_, err := p.handleTimeEntries(map[string]interface{}{"action": "list"})
|
||||
if err == nil || !strings.Contains(err.Error(), "v2") {
|
||||
t.Fatalf("v1 下应提示改用 v2，实际 %v", err)
|
||||
}
|
||||
}
|
||||
|
||||
// 13) 标签：v1 收 Label 对象、v2 收 label_id
|
||||
func TestLabelBodyByVersion(t *testing.T) {
|
||||
var body map[string]interface{}
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
raw, _ := io.ReadAll(r.Body)
|
||||
_ = json.Unmarshal(raw, &body)
|
||||
_, _ = w.Write([]byte(`{}`))
|
||||
})
|
||||
if _, err := p.handleTaskLabels(map[string]interface{}{"action": "add", "id": "1", "label_id": "5"}); err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
if body["label_id"] != float64(5) {
|
||||
t.Errorf("v2 应发送 label_id，实际 %v", body)
|
||||
}
|
||||
|
||||
body = nil
|
||||
p.apiVer = "v1"
|
||||
if _, err := p.handleTaskLabels(map[string]interface{}{"action": "add", "id": "1", "label_id": "5"}); err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
if body["id"] != float64(5) {
|
||||
t.Errorf("v1 应发送 Label 对象(id)，实际 %v", body)
|
||||
}
|
||||
}
|
||||
|
||||
// 14) 时间字符串容忍：today / +3d / ISO
|
||||
func TestNormalizeTime(t *testing.T) {
|
||||
for _, in := range []string{"today", "tomorrow", "+3d", "2026-09-12 18:00", "2026-09-12T18:00:00+08:00"} {
|
||||
got := normalizeTime(in)
|
||||
s, ok := got.(string)
|
||||
if !ok {
|
||||
t.Fatalf("%s: 期望字符串，实际 %T", in, got)
|
||||
}
|
||||
if _, err := time.Parse(time.RFC3339, s); err != nil {
|
||||
t.Errorf("%s → %s 不是 RFC3339: %v", in, s, err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 15) 通用直通：可指定 api_version，method 大小写不敏感
|
||||
func TestRawAPI(t *testing.T) {
|
||||
var method, path string
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
method, path = r.Method, r.URL.Path
|
||||
_, _ = w.Write([]byte(`[]`))
|
||||
})
|
||||
if _, err := p.handleRawAPI(map[string]interface{}{"method": "get", "path": "projects", "api_version": "v1"}); err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
if method != http.MethodGet || path != "/api/v1/projects" {
|
||||
t.Errorf("直通参数未生效: %s %s", method, path)
|
||||
}
|
||||
}
|
||||
|
||||
// 16) 精简输出可关闭（关闭时返回原样）
|
||||
func TestCompactToggle(t *testing.T) {
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
_, _ = w.Write([]byte(`[{"id":1,"title":"t","description":"很长的描述","done":false}]`))
|
||||
})
|
||||
p.compact = false
|
||||
res, err := p.handleTasksList(map[string]interface{}{})
|
||||
if err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
arr, ok := res.([]interface{})
|
||||
if !ok {
|
||||
t.Fatalf("关闭精简后应原样返回数组，实际 %T", res)
|
||||
}
|
||||
if _, ok := arr[0].(map[string]interface{})["description"]; !ok {
|
||||
t.Errorf("关闭精简后应保留 description")
|
||||
}
|
||||
}
|
||||
|
||||
// ── 回归：JSON body 里的 ID 必须是数字（线上实测的 422 缺口）────────────
|
||||
//
|
||||
// vikunja v2.6.0 实测（2026-09-12）：
|
||||
// {"project_id":"1"} → 422 expected integer at body.project_id
|
||||
// {"user_id":"1"} → 422 expected integer at body.user_id
|
||||
// {"username":"jianf"} → 422 unexpected property at body.username
|
||||
// 旧实现把 argID() 的字符串直接塞进 body，assignee 还额外带 username，
|
||||
// 于是「建任务」「指派」在 v2 下必定失败 —— 只有真调用才暴露，单测没盖到。
|
||||
|
||||
func TestTaskCreateSendsNumericProjectID(t *testing.T) {
|
||||
var body map[string]interface{}
|
||||
var raw []byte
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
raw, _ = io.ReadAll(r.Body)
|
||||
_ = json.Unmarshal(raw, &body)
|
||||
_, _ = w.Write([]byte(`{"id":42,"title":"买菜"}`))
|
||||
})
|
||||
// project_id 传 float64 —— 这正是 SDK 从 JSON 解出来的真实类型
|
||||
if _, err := p.handleTaskCreate(map[string]interface{}{"project_id": float64(3), "title": "买菜"}); err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
if _, ok := body["project_id"].(float64); !ok {
|
||||
t.Errorf("project_id 必须是 JSON 数字，实际 %T=%v", body["project_id"], body["project_id"])
|
||||
}
|
||||
if strings.Contains(string(raw), `"project_id":"`) {
|
||||
t.Errorf("出现字符串型 project_id（v2 会 422 expected integer）: %s", raw)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAssigneeAddResolvesUsernameToNumericUserID(t *testing.T) {
|
||||
var body map[string]interface{}
|
||||
var raw []byte
|
||||
var calls []string
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
calls = append(calls, r.Method+" "+r.URL.Path)
|
||||
switch r.URL.Path {
|
||||
case "/api/v2/users":
|
||||
if r.URL.Query().Get("q") != "alice" {
|
||||
t.Errorf("v2 用户搜索应用 q=，实际 query=%q", r.URL.RawQuery)
|
||||
}
|
||||
_, _ = w.Write([]byte(`[{"id":7,"username":"alice"},{"id":9,"username":"alice2"}]`))
|
||||
case "/api/v2/tasks/1/assignees":
|
||||
raw, _ = io.ReadAll(r.Body)
|
||||
_ = json.Unmarshal(raw, &body)
|
||||
w.WriteHeader(http.StatusCreated)
|
||||
_, _ = w.Write([]byte(`{"user_id":7}`))
|
||||
default:
|
||||
t.Errorf("意外请求: %s %s", r.Method, r.URL.Path)
|
||||
}
|
||||
})
|
||||
if _, err := p.handleTaskAssignees(map[string]interface{}{"id": "1", "action": "add", "user": "alice"}); err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
if len(calls) != 2 {
|
||||
t.Fatalf("应先查用户再指派，实际调用: %v", calls)
|
||||
}
|
||||
if n, ok := body["user_id"].(float64); !ok || int(n) != 7 {
|
||||
t.Errorf("user_id 必须是数字 7，实际 %T=%v", body["user_id"], body["user_id"])
|
||||
}
|
||||
if _, ok := body["username"]; ok {
|
||||
t.Errorf("v2 不接受 username 字段（422 unexpected property）: %s", raw)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAssigneeAddNumericUserSkipsLookup(t *testing.T) {
|
||||
var calls []string
|
||||
var body map[string]interface{}
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
calls = append(calls, r.Method+" "+r.URL.Path)
|
||||
if r.URL.Path == "/api/v2/users" {
|
||||
t.Errorf("传数字 ID 时不该再查用户表")
|
||||
}
|
||||
raw, _ := io.ReadAll(r.Body)
|
||||
_ = json.Unmarshal(raw, &body)
|
||||
w.WriteHeader(http.StatusCreated)
|
||||
_, _ = w.Write([]byte(`{"user_id":7}`))
|
||||
})
|
||||
if _, err := p.handleTaskAssignees(map[string]interface{}{"id": "1", "action": "add", "user": "7"}); err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
if len(calls) != 1 {
|
||||
t.Errorf("应只有一次请求，实际: %v", calls)
|
||||
}
|
||||
if n, ok := body["user_id"].(float64); !ok || int(n) != 7 {
|
||||
t.Errorf("user_id 应为数字 7，实际 %T=%v", body["user_id"], body["user_id"])
|
||||
}
|
||||
}
|
||||
|
||||
func TestAssigneeRemoveUsesResolvedNumericPath(t *testing.T) {
|
||||
var gotPath string
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
switch r.URL.Path {
|
||||
case "/api/v2/users":
|
||||
_, _ = w.Write([]byte(`[{"id":7,"username":"alice"}]`))
|
||||
default:
|
||||
gotPath = r.Method + " " + r.URL.Path
|
||||
w.WriteHeader(http.StatusNoContent)
|
||||
}
|
||||
})
|
||||
if _, err := p.handleTaskAssignees(map[string]interface{}{"id": "1", "action": "remove", "user": "alice"}); err != nil {
|
||||
t.Fatalf("err: %v", err)
|
||||
}
|
||||
if gotPath != "DELETE /api/v2/tasks/1/assignees/7" {
|
||||
t.Errorf("移除应用解析出的数字 ID，实际 %q", gotPath)
|
||||
}
|
||||
}
|
||||
|
||||
func TestAssigneeAddUnknownUserGivesReadableError(t *testing.T) {
|
||||
p, _ := newTestPlugin(t, func(w http.ResponseWriter, r *http.Request) {
|
||||
_, _ = w.Write([]byte(`[{"id":7,"username":"bob"}]`))
|
||||
})
|
||||
_, err := p.handleTaskAssignees(map[string]interface{}{"id": "1", "action": "add", "user": "alice"})
|
||||
if err == nil {
|
||||
t.Fatal("找不到用户时必须报错，而不是发出一个注定 422 的请求")
|
||||
}
|
||||
if !strings.Contains(err.Error(), "找不到用户") || !strings.Contains(err.Error(), "bob") {
|
||||
t.Errorf("错误信息应说明找不到并给出相近候选: %v", err)
|
||||
}
|
||||
}
|
||||
@ -1,33 +1,13 @@
|
||||
# weather · 天气查询
|
||||
# weather
|
||||
|
||||
给 agent 补上天气查询能力（基于 [wttr.in](https://wttr.in)，无需 API Key）。
|
||||
weather plugin
|
||||
|
||||
## 工具
|
||||
|
||||
| 工具 | 说明 |
|
||||
|---|---|
|
||||
| `weather_current` | 查询某城市当前天气 |
|
||||
| `weather_forecast` | 查询未来几天预报 |
|
||||
| `weather_set_location` | 设置默认城市 |
|
||||
|
||||
`weather_current` / `weather_forecast` 都接受 `location`（城市名，如 `Beijing`、`Shanghai`）；
|
||||
省略时用配置里的默认城市。`weather_current` 另有 `units`：`metric`（摄氏，默认）或 `imperial`（华氏）。
|
||||
|
||||
## 配置项
|
||||
|
||||
| 键 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `default_location` | 空 | 默认城市名。留空则每次调用都必须传 `location` |
|
||||
|
||||
## 实现要点
|
||||
|
||||
- **`NoMemory: true`**：天气是外部实时数据，对记忆计算无长期价值，跳过向量化与关键词提取（原文仍保留在对话里）。
|
||||
- **`Cleaner`**：输出参与记忆计算前先过滤，只保留摘要行 —— 天气查询会反复出现，全文进记忆会挤占上下文预算，而"上周三北京多少度"通常并不需要召回。
|
||||
|
||||
## 构建
|
||||
## Build
|
||||
|
||||
```bash
|
||||
hmapdev build
|
||||
plugindev build
|
||||
```
|
||||
|
||||
产出 `.hmap` 后经 Plugin Manager API 安装。
|
||||
## Install
|
||||
|
||||
Upload the .hmap file through the Plugin Manager API.
|
||||
|
||||
31
meta/meta.go
31
meta/meta.go
@ -28,27 +28,12 @@ var (
|
||||
// 存量插件不需要改一行也不需要重编：新增方法由**插件调用、内核实现**，
|
||||
// 不调就不受影响。想用新字段的插件重编即可。
|
||||
//
|
||||
// 1.2.0：注入行为的记忆/裁剪标志位。**全部是新增，无签名变更**：
|
||||
// - InjectOptions{NoMemory, ContextPolicy}
|
||||
// - IOInjector 的六个 *Opts 变体（排队/中断/同步/带媒体各一对）
|
||||
// - ChannelDef.ContextPolicy（顺带给 ChannelDef 补上 JSON tag：
|
||||
// 它要跨进程传给内核，而 Cleaner 是函数必须忽略；无 tag 时只能
|
||||
// 手写字段白名单，新增字段会被静默丢掉）
|
||||
// 语义：零值 InjectOptions 与旧的三参数方法完全等价（记入记忆 +
|
||||
// 不裁剪），因此存量插件不需要改一行也不需要重编。
|
||||
// 裁剪（ContextPolicy=prune）必须显式声明——它会归档丢弃低相关事件。
|
||||
// ❗发布分支上此值是**本条发布线的 SDK 定版**；main 上则是下一个未发布中版本
|
||||
// （见 核心仓 docs/git-branching.md §2.1 与 §七.1）。
|
||||
//
|
||||
// ❗main 分支上此值是**下一个未发布中版本**；已发布的值看对应的
|
||||
// release/vX.Y.x 分支与 tag（见 核心仓 docs/git-branching.md §2.1 与 §七.1）。
|
||||
//
|
||||
// 现为 1.4.0：1.3.0 已随核心的正式 tag `v1.3.0` 定版并发版（本仓 tag v1.3.0、
|
||||
// release/v1.3.x 承载它），该号从此归发布线所有，main 遂推进到下一个未发布中版本。
|
||||
//
|
||||
// ❗本仓**不发 patch tag**（§七.1）：一个中版本只发一次 `vX.Y.0`，核心的 1.3.x
|
||||
// 后续 patch **不伴随 SDK 发版** —— patch 位恒为 `.0`，带非零 patch 的 SDK tag
|
||||
// 都是错的。（2026-09-13 曾误发 `v1.3.1`，已撤回；`v1.2.1` 是同一类历史遗留。）
|
||||
//
|
||||
Version = "1.4.0"
|
||||
// 本分支定版 1.1.0，服务整条核心 1.1.x 线（1.1.0、1.1.1、…）：
|
||||
// patch 位恒为 .0，核心的 bugfix 不碰公开接口，SDK 号没有理由跟着动。
|
||||
Version = "1.1.0"
|
||||
|
||||
// Commit 是构建时的 Git commit hash。
|
||||
Commit = "unknown"
|
||||
@ -59,7 +44,7 @@ var (
|
||||
// SDKName 是 SDK 名称。
|
||||
SDKName = "HomeAgent SDK"
|
||||
|
||||
// CoreModule 是核心仓的 Go module path，供 hmapdev 生成 go.mod 时使用。
|
||||
// CoreModule 是核心仓的 Go module path，供 plugindev 生成 go.mod 时使用。
|
||||
CoreModule = "gitcode.com/JianFeeeee/HomeAgent"
|
||||
|
||||
// CoreVersion 是此 SDK 所兼容的最低核心版本。
|
||||
@ -71,10 +56,6 @@ var (
|
||||
// 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"
|
||||
)
|
||||
|
||||
|
||||
@ -1,150 +0,0 @@
|
||||
#!/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,13 +5,6 @@ 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:-}"
|
||||
|
||||
@ -35,7 +28,7 @@ case "$TARGET" in
|
||||
;;
|
||||
*)
|
||||
echo "Unknown target: $TARGET"
|
||||
echo "Usage: $0 [native|linux/amd64|linux/arm64|darwin/amd64|darwin/arm64|windows/amd64|all] [all|hmapdev|examples]"
|
||||
echo "Usage: $0 [native|linux/amd64|linux/arm64|darwin/amd64|darwin/arm64|windows/amd64|all] [all|plugindev]"
|
||||
exit 1
|
||||
esac
|
||||
|
||||
@ -49,12 +42,12 @@ export CGO_ENABLED=0
|
||||
|
||||
mkdir -p "$BUILD_DIR"
|
||||
|
||||
build_hmapdev() {
|
||||
local src="tools/hmapdev"
|
||||
local out="$BUILD_DIR/hmapdev${SUFFIX:+_$SUFFIX}"
|
||||
build_plugindev() {
|
||||
local src="tools/plugindev"
|
||||
local out="$BUILD_DIR/plugindev${SUFFIX:+_$SUFFIX}"
|
||||
if [ "$GOOS" = "windows" ]; then out="${out}.exe"; fi
|
||||
|
||||
echo "[BUILD] hmapdev ${GOOS:-linux}/${GOARCH:-amd64} → $out"
|
||||
echo "[BUILD] plugindev ${GOOS:-linux}/${GOARCH:-amd64} → $out"
|
||||
cd "$PROJECT_ROOT/$src"
|
||||
"$GO" build -trimpath -ldflags "-X gitcode.com/JianFeeeee/homeagent-sdk/meta.Version=${VERSION}" \
|
||||
-o "$out" .
|
||||
@ -62,47 +55,9 @@ build_hmapdev() {
|
||||
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)
|
||||
# 工具链必须先建完：示例用它来构建（同源保证协议一致）。
|
||||
build_hmapdev
|
||||
build_examples
|
||||
;;
|
||||
hmapdev) build_hmapdev ;;
|
||||
examples) build_examples ;;
|
||||
all|plugindev) build_plugindev ;;
|
||||
*)
|
||||
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 "• hmapdev.exe — 插件开发工具"
|
||||
${NSD_CreateLabel} 15u 20u 100% 12u "• plugindev.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 "hmapdev.exe"
|
||||
File "plugindev.exe"
|
||||
|
||||
DetailPrint "创建快捷方式..."
|
||||
CreateDirectory "$SMPROGRAMS\${PRODUCT_NAME}"
|
||||
CreateShortCut "$SMPROGRAMS\${PRODUCT_NAME}\hmapdev.lnk" "$INSTDIR\hmapdev.exe" "" "$INSTDIR\hmapdev.exe" 0
|
||||
CreateShortCut "$SMPROGRAMS\${PRODUCT_NAME}\plugindev.lnk" "$INSTDIR\plugindev.exe" "" "$INSTDIR\plugindev.exe" 0
|
||||
|
||||
DetailPrint "配置环境变量..."
|
||||
; Add to system PATH
|
||||
@ -93,23 +93,23 @@ Section "Install" SEC_INSTALL
|
||||
DetailPrint "Git 已安装: $1"
|
||||
${Else}
|
||||
DetailPrint "未检测到 Git，将跳过 SDK 自动下载"
|
||||
DetailPrint "安装完成后请手动运行: hmapdev sdk install ${SDK_VERSION}"
|
||||
DetailPrint "安装完成后请手动运行: plugindev sdk install ${SDK_VERSION}"
|
||||
${EndIf}
|
||||
|
||||
${If} $hasGit == "1"
|
||||
DetailPrint "正在下载 SDK ${SDK_VERSION}..."
|
||||
nsExec::ExecToStack '"$INSTDIR\hmapdev.exe" sdk install ${SDK_VERSION}'
|
||||
nsExec::ExecToStack '"$INSTDIR\plugindev.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\hmapdev.exe" sdk use ${SDK_VERSION}'
|
||||
nsExec::Exec '"$INSTDIR\plugindev.exe" sdk use ${SDK_VERSION}'
|
||||
Pop $0
|
||||
${Else}
|
||||
DetailPrint "SDK 下载失败 (错误码: $0)"
|
||||
DetailPrint "请手动运行: hmapdev sdk install ${SDK_VERSION}"
|
||||
DetailPrint "请手动运行: plugindev sdk install ${SDK_VERSION}"
|
||||
${EndIf}
|
||||
${EndIf}
|
||||
|
||||
@ -126,10 +126,10 @@ SectionEnd
|
||||
|
||||
Section "Uninstall"
|
||||
Delete "$INSTDIR\Uninstall.exe"
|
||||
Delete "$INSTDIR\hmapdev.exe"
|
||||
Delete "$INSTDIR\plugindev.exe"
|
||||
RMDir /r "$INSTDIR\sdk"
|
||||
RMDir "$INSTDIR"
|
||||
Delete "$SMPROGRAMS\${PRODUCT_NAME}\hmapdev.lnk"
|
||||
Delete "$SMPROGRAMS\${PRODUCT_NAME}\plugindev.lnk"
|
||||
RMDir "$SMPROGRAMS\${PRODUCT_NAME}"
|
||||
DeleteRegValue HKLM "SYSTEM\CurrentControlSet\Control\Session Manager\Environment" "HOMEAGENT_SDK_DIR"
|
||||
DeleteRegKey HKLM "Software\Microsoft\CurrentVersion\Uninstall\${PRODUCT_NAME}"
|
||||
|
||||
@ -1,147 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# 为 SDK 仓的 example 插件批量打 .hmap 包，产出可直接随 release 发布的插件包。
|
||||
#
|
||||
# 背景：release 此前只发 homed/waiter 二进制与 hmapdev 工具链，**不发插件包**。
|
||||
# 用户要用某个插件，得自己装 Go 1.25、拉依赖、装 hmapdev、逐个 build —— 这是
|
||||
# 「开箱即用」名不副实的根源。本脚本把这一步前置到发布流程里。
|
||||
#
|
||||
# 用法：
|
||||
# ./build_plugin_bundles.sh # 全部 example
|
||||
# ./build_plugin_bundles.sh weather qq memo # 指定插件
|
||||
# OUT=../dist/plugins ./build_plugin_bundles.sh
|
||||
#
|
||||
# 环境：
|
||||
# HMAPDEV hmapdev 可执行文件（默认取 PATH 上的 hmapdev）
|
||||
# OUT 产物目录。默认取**内核仓**的 dist/plugins（upload_assets.py 认这个位置），
|
||||
# 以便直接随 release 发布；不在内核仓内时回退到 SDK 仓的 dist/plugins。
|
||||
# JOBS 并行度（默认 CPU 核数）
|
||||
set -euo pipefail
|
||||
|
||||
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
|
||||
SDK_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
|
||||
|
||||
# 默认产物落到内核仓的 dist/plugins。判定方式：从 SDK 目录向上找“含 internal/ 与
|
||||
# go.mod”的目录（即内核仓根），找不到就用 SDK 仓自己的 dist/plugins。
|
||||
# 为何不写死 ../../：SDK 仓在主仓里是 third_party/homeagent-sdk，但也可以被单独
|
||||
# clone 出来，写死相对路径会把产物丢到仓外或 third_party/dist。
|
||||
default_out() {
|
||||
local d="$SDK_DIR"
|
||||
for _ in 1 2 3 4; do
|
||||
d="$(cd "$d/.." && pwd)"
|
||||
if [ -f "$d/go.mod" ] && [ -d "$d/internal" ]; then
|
||||
echo "$d/dist/plugins"; return
|
||||
fi
|
||||
done
|
||||
echo "$SDK_DIR/dist/plugins"
|
||||
}
|
||||
|
||||
EX_DIR="$SDK_DIR/example"
|
||||
OUT="${OUT:-$(default_out)}"
|
||||
HMAPDEV="${HMAPDEV:-hmapdev}"
|
||||
|
||||
command -v "$HMAPDEV" >/dev/null 2>&1 || {
|
||||
echo "error: 找不到 hmapdev（设 HMAPDEV=/path/to/hmapdev 或用 'hmapdev sdk install' 装）" >&2
|
||||
exit 1
|
||||
}
|
||||
|
||||
mkdir -p "$OUT"
|
||||
|
||||
# 收集候选插件：有 plg.json 才可构建
|
||||
all=()
|
||||
for d in "$EX_DIR"/*/; do
|
||||
n="$(basename "$d")"
|
||||
[ -f "$d/plg.json" ] || continue
|
||||
all+=("$n")
|
||||
done
|
||||
|
||||
# 参数指定则取交集（并校验名字有效，避免拼错静默跳过）
|
||||
if [ "$#" -gt 0 ]; then
|
||||
want=("$@")
|
||||
sel=()
|
||||
for w in "${want[@]}"; do
|
||||
found=""
|
||||
for n in "${all[@]}"; do [ "$n" = "$w" ] && found=1 && break; done
|
||||
[ -n "$found" ] || { echo "error: 未知插件 '$w'（可用: ${all[*]}）" >&2; exit 1; }
|
||||
sel+=("$w")
|
||||
done
|
||||
all=("${sel[@]}")
|
||||
fi
|
||||
|
||||
echo "=== 打包 ${#all[@]} 个插件 → $OUT ==="
|
||||
echo " hmapdev: $("$HMAPDEV" --version 2>/dev/null | head -1 || echo "$HMAPDEV")"
|
||||
|
||||
build_one() {
|
||||
local name="$1"
|
||||
local dir="$EX_DIR/$name"
|
||||
local log="$OUT/.$name.log"
|
||||
|
||||
# hmapdev build 必须在插件目录内跑（它读当前目录的 plg.json）
|
||||
if ! (cd "$dir" && "$HMAPDEV" build >"$log" 2>&1); then
|
||||
echo " ✗ $name 构建失败（见 $log）"
|
||||
return 1
|
||||
fi
|
||||
|
||||
# 产物有三种形态，不能只认 _bundle.hmap：
|
||||
# 1) <name>_bundle.hmap 多平台 bundle（plg.json 里 bundle: true）
|
||||
# 2) <name>_<os>_<arch>.hmap 单平台（bundle 关掉时，如 qq）
|
||||
# 3) <name>_lua.hmap Lua 插件（不编译 Go，如 luademo）
|
||||
#
|
||||
# 注意用 if 而非 `[ -z ] && found=$(ls...)`：在 set -e 下，
|
||||
# 一次 ls 无匹配就会让整个子 shell 直接退出，根本走不到后面的兜底。
|
||||
local found=""
|
||||
local cand
|
||||
for pat in "$dir"/dist/*_bundle.hmap "$dir"/dist/*.hmap "$dir"/*_bundle.hmap; do
|
||||
if [ -z "$found" ]; then
|
||||
cand="$(ls -t $pat 2>/dev/null | head -1 || true)"
|
||||
[ -n "$cand" ] && found="$cand"
|
||||
fi
|
||||
done
|
||||
if [ -z "$found" ]; then
|
||||
echo " ✗ $name 未产出 .hmap（见 $log）"
|
||||
return 1
|
||||
fi
|
||||
|
||||
cp -f "$found" "$OUT/"
|
||||
local sz bn
|
||||
bn="$(basename "$found")"
|
||||
sz="$(stat -c%s "$OUT/$bn" 2>/dev/null || stat -f%z "$OUT/$bn")"
|
||||
# 标注形态：单平台/Lua 包与多平台 bundle 不同，发布时要能一眼看出
|
||||
local tag=""
|
||||
case "$bn" in
|
||||
*_bundle.hmap) tag="bundle" ;;
|
||||
*_lua.hmap) tag="lua " ;;
|
||||
*) tag="单平台" ;;
|
||||
esac
|
||||
printf " ✓ %-16s %7.1f MB %s\n" "$name" "$(echo "$sz" | awk '{print $1/1048576}')" "$tag"
|
||||
rm -f "$log"
|
||||
}
|
||||
|
||||
fail=0
|
||||
pids=()
|
||||
for n in "${all[@]}"; do
|
||||
# 有 nproc 就限并发，没有就串行
|
||||
if command -v nproc >/dev/null 2>&1; then
|
||||
while [ "$(jobs -rp | wc -l)" -ge "${JOBS:-$(nproc)}" ]; do wait -n 2>/dev/null || true; done
|
||||
fi
|
||||
( build_one "$n" ) &
|
||||
pids+=($!)
|
||||
done
|
||||
for p in "${pids[@]}"; do wait "$p" || fail=$((fail+1)); done
|
||||
|
||||
echo
|
||||
echo "=== 产出 ==="
|
||||
ls -la "$OUT"/*.hmap 2>/dev/null | awk '{printf " %-46s %8.1f MB\n", $9, $5/1048576}' || echo " （无）"
|
||||
|
||||
# 汇总校验和，便于随 release 一起发布与验证
|
||||
if ls "$OUT"/*.hmap >/dev/null 2>&1; then
|
||||
( cd "$OUT" && sha256sum ./*.hmap > SHA256SUMS.plugins )
|
||||
echo
|
||||
echo "=== 校验和 → $OUT/SHA256SUMS.plugins ==="
|
||||
cat "$OUT/SHA256SUMS.plugins" | sed 's/^/ /'
|
||||
fi
|
||||
|
||||
if [ "$fail" -gt 0 ]; then
|
||||
echo
|
||||
echo "error: $fail 个插件构建失败" >&2
|
||||
exit 1
|
||||
fi
|
||||
@ -1,38 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
# 同步 Lua SDK mock 的单一事实源到各副本。
|
||||
#
|
||||
# 事实源：sdk/lua/sdk.lua（本仓）
|
||||
# 副本：
|
||||
# - tools/hmapdev/assets/sdk.lua 工具链内嵌回退（hmapdev init --lua 无 SDK 时用）
|
||||
# - example/luademo/sdk.lua 示例插件的离线测试副本
|
||||
# - <core>/internal/lua/sdk/sdk.lua 内核内嵌副本（本仓被 vendored 到
|
||||
# <core>/third_party/homeagent-sdk 时自动识别；独立 clone 时跳过）
|
||||
#
|
||||
# 为什么要有它：三份 sdk.lua 曾各自漂移，出现「mock 有、内核没有」的静默失配。
|
||||
# 改 mock 只改事实源，然后跑这个脚本；内核仓另有契约测试比对。
|
||||
set -euo pipefail
|
||||
|
||||
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
|
||||
SRC="$ROOT/sdk/lua/sdk.lua"
|
||||
|
||||
[ -f "$SRC" ] || { echo "error: canonical sdk.lua not found: $SRC" >&2; exit 1; }
|
||||
|
||||
copy() {
|
||||
local dst="$1"
|
||||
mkdir -p "$(dirname "$dst")"
|
||||
cp "$SRC" "$dst"
|
||||
echo " synced -> $dst"
|
||||
}
|
||||
|
||||
copy "$ROOT/tools/hmapdev/assets/sdk.lua"
|
||||
copy "$ROOT/example/luademo/sdk.lua"
|
||||
|
||||
# 被内核仓 vendored 时（本仓位于 <core>/third_party/homeagent-sdk）同步内核副本。
|
||||
CORE_COPY="$ROOT/../../internal/lua/sdk/sdk.lua"
|
||||
if [ -d "$ROOT/../../internal" ]; then
|
||||
copy "$(cd "$(dirname "$CORE_COPY")" && pwd)/sdk.lua"
|
||||
else
|
||||
echo " note: core repo not vendored next to this checkout, skipping core copy"
|
||||
fi
|
||||
|
||||
echo "Lua SDK mock synced."
|
||||
413
sdk/lua/sdk.lua
413
sdk/lua/sdk.lua
@ -1,413 +0,0 @@
|
||||
-- HomeAgent Lua Plugin SDK
|
||||
-- Interface contract between Lua plugins and HomeAgent kernel.
|
||||
-- !impl functions are replaced by Go implementations at runtime.
|
||||
-- Standalone/debug: pure Lua mock implementations are used.
|
||||
-- Usage: local sdk = require("sdk")
|
||||
|
||||
sdk = {}
|
||||
|
||||
-- !impl
|
||||
-- level: "debug" | "info" | "warn" | "error"
|
||||
function sdk.log(level, msg)
|
||||
print("[lua-plugin] " .. tostring(level) .. ": " .. tostring(msg))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- def: { description="...", parameters={...}, no_memory=true/false, cleaner=function(text)->text }
|
||||
-- handler: function(args) -> result
|
||||
function sdk.register_tool(name, def, handler)
|
||||
print("[lua-plugin] register_tool: " .. tostring(name))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- stage: "on_input" | "pre_action" | "post_action" | ...
|
||||
-- scope: nil/"global" (默认) | "own_tools"（仅 before_toolcall/after_toolcall 且工具属于本插件时触发）
|
||||
function sdk.register_stage(stage, handler, scope)
|
||||
print("[lua-plugin] register_stage: " .. tostring(stage) .. " scope=" .. tostring(scope))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.register_api(name)
|
||||
print("[lua-plugin] register_api: " .. tostring(name))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- def: { no_memory=true/false, cleaner=function(text)->text }
|
||||
-- handler: function(args) -> result
|
||||
function sdk.register_output_channel(name, caps, desc, def, handler)
|
||||
print("[lua-plugin] register_output_channel: " .. tostring(name))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- def: { no_memory=true/false, cleaner=function(text)->text }
|
||||
function sdk.register_input_channel(name, def)
|
||||
print("[lua-plugin] register_input_channel: " .. tostring(name))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.get_setting(key)
|
||||
return nil
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.set_setting(key, value)
|
||||
print("[lua-plugin] set_setting: " .. tostring(key))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_text(source, channel, text)
|
||||
print("[lua-plugin] inject_text: " .. tostring(source) .. "/" .. tostring(channel))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_interrupt(source, channel, text)
|
||||
print("[lua-plugin] inject_interrupt: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_text_no_memory(source, channel, text)
|
||||
print("[lua-plugin] inject_text_no_memory: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- opts: { no_memory=bool, context_policy="none"|"prune", cleaner_name=string, priority="L1".."L3" }
|
||||
-- 零值/缺省 = 记入记忆 + 不裁剪（与三参数版本等价）。
|
||||
function sdk.inject_text_opts(source, channel, text, opts)
|
||||
print("[lua-plugin] inject_text_opts: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_interrupt_opts(source, channel, text, opts)
|
||||
print("[lua-plugin] inject_interrupt_opts: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- 同步注入在 Lua 插件中**不可用**：会等本轮回复，而本轮正持有插件锁 ⇒ 必然自锁。
|
||||
-- 真实内核里恒返回 (nil, err)；这里返回同样的错误，避免离线测试误以为可用。
|
||||
function sdk.inject_input_sync(source, channel, text)
|
||||
return nil, "同步注入在 Lua 插件中不可用：请在事件回调/外部入口用 inject_text/inject_interrupt；确需同步等待请改用 Go 插件。"
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_input_sync_opts(source, channel, text, opts)
|
||||
return nil, "同步注入在 Lua 插件中不可用：请在事件回调/外部入口用 inject_text/inject_interrupt；确需同步等待请改用 Go 插件。"
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- blocks: ContentBlock 数组，见 sdk.inject_input_media。
|
||||
-- 设置下一轮 tool message 携带的多模态内容块（模型据此看图/听音频）。
|
||||
function sdk.set_tool_blocks(blocks)
|
||||
print("[lua-plugin] set_tool_blocks: " .. tostring(blocks and #blocks or 0))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- blocks 每项：{ type="text", text="..." }
|
||||
-- | { type="image_url", image_url={ url="...", detail="high" } }
|
||||
-- | { type="audio_url", audio_url={ url="..." } }
|
||||
function sdk.inject_input_media(source, channel, text, blocks)
|
||||
print("[lua-plugin] inject_input_media: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_input_media_opts(source, channel, text, blocks, opts)
|
||||
print("[lua-plugin] inject_input_media_opts: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- 同 sdk.inject_input_sync：Lua 中不可用。
|
||||
function sdk.inject_input_media_sync(source, channel, text, blocks)
|
||||
return nil, "同步注入在 Lua 插件中不可用：请在事件回调/外部入口用 inject_input_media；确需同步等待请改用 Go 插件。"
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_input_media_sync_opts(source, channel, text, blocks, opts)
|
||||
return nil, "同步注入在 Lua 插件中不可用：请在事件回调/外部入口用 inject_input_media_opts；确需同步等待请改用 Go 插件。"
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_interrupt_media(source, channel, text, blocks)
|
||||
print("[lua-plugin] inject_interrupt_media: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_interrupt_media_opts(source, channel, text, blocks, opts)
|
||||
print("[lua-plugin] inject_interrupt_media_opts: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- 注销输出通道（随资源生灭的动态通道，如远程设备）。返回 (nil, err)。
|
||||
function sdk.unregister_output_channel(name) return nil, nil end
|
||||
|
||||
-- !impl
|
||||
-- enabled: true/false，崩溃时内核自动拉起
|
||||
function sdk.set_auto_restart(enabled)
|
||||
print("[lua-plugin] set_auto_restart: " .. tostring(enabled))
|
||||
end
|
||||
|
||||
-- ============ graph memory ============
|
||||
-- !impl
|
||||
sdk.memory = {}
|
||||
-- !impl
|
||||
-- query: string, depth: number -> {entities={...}, relations={...}}
|
||||
function sdk.memory.recall(query, depth) return {entities={}, relations={}} end
|
||||
-- !impl
|
||||
-- triples: { {subject=, relation=, object=, [confidence=], [sentence_text=]} } -> err
|
||||
function sdk.memory.commit(triples) return nil end
|
||||
-- !impl
|
||||
function sdk.memory.introspect() return {} end
|
||||
-- !impl
|
||||
function sdk.memory.merge(source, target) return 0 end
|
||||
-- !impl
|
||||
-- criteria: {key=value}, hard: boolean
|
||||
function sdk.memory.purge(criteria, hard) return 0 end
|
||||
|
||||
-- ============ document memory ============
|
||||
-- !impl
|
||||
sdk.doc = {}
|
||||
-- !impl
|
||||
function sdk.doc.query(text, top_k) return {} end
|
||||
-- !impl
|
||||
-- doc: { id=, title=, content= }
|
||||
function sdk.doc.insert(doc) return nil end
|
||||
-- !impl
|
||||
-- attachments 每项：{ digest=, mime=, name=, data=<base64> }
|
||||
function sdk.doc.insert_with_media(doc, attachments) return nil end
|
||||
-- !impl
|
||||
function sdk.doc.remove(id) return nil end
|
||||
-- !impl
|
||||
function sdk.doc.stats() return {} end
|
||||
|
||||
-- ============ knowledge ============
|
||||
-- !impl
|
||||
sdk.knowledge = {}
|
||||
-- !impl
|
||||
function sdk.knowledge.search(query, limit) return {} end
|
||||
-- !impl
|
||||
function sdk.knowledge.add(tag, content) return nil end
|
||||
-- !impl
|
||||
function sdk.knowledge.list() return {} end
|
||||
|
||||
-- ============ text memory ============
|
||||
-- !impl
|
||||
sdk.text_memory = {}
|
||||
-- !impl
|
||||
-- evt: { timestamp=, role=, content=, channel= }
|
||||
function sdk.text_memory.append(evt) return nil end
|
||||
|
||||
-- ============ llm ============
|
||||
-- !impl
|
||||
sdk.llm = {}
|
||||
-- !impl
|
||||
function sdk.llm.list_sources() return {} end
|
||||
-- !impl
|
||||
function sdk.llm.set_source(name) return nil end
|
||||
-- !impl
|
||||
function sdk.llm.current_source() return nil end
|
||||
|
||||
-- ============ social (只读) ============
|
||||
-- !impl
|
||||
sdk.social = {}
|
||||
-- !impl
|
||||
function sdk.social.get_person(name) return {} end
|
||||
-- !impl
|
||||
function sdk.social.get_network(name, depth) return {} end
|
||||
-- !impl
|
||||
function sdk.social.get_trait(name, trait) return {value=nil, found=false} end
|
||||
-- !impl
|
||||
function sdk.social.get_relations(name) return {} end
|
||||
-- !impl
|
||||
function sdk.social.list_persons() return {} end
|
||||
|
||||
-- ============ settings (作用域变体) ============
|
||||
-- !impl
|
||||
sdk.settings = {}
|
||||
-- !impl
|
||||
function sdk.settings.get_core(key) return nil end
|
||||
-- !impl
|
||||
function sdk.settings.set_core(key, value) return nil end
|
||||
-- !impl
|
||||
function sdk.settings.list_core(prefix) return {} end
|
||||
-- !impl
|
||||
function sdk.settings.get_plugin(plugin, key) return nil end
|
||||
-- !impl
|
||||
function sdk.settings.set_plugin(plugin, key, value) return nil end
|
||||
-- !impl
|
||||
function sdk.settings.list_plugin(plugin, prefix) return {} end
|
||||
-- !impl
|
||||
function sdk.settings.list(prefix) return {} end
|
||||
-- !impl
|
||||
-- def: { key=, type=, display_name=, description=, category=, options=, default=,
|
||||
-- min=, max=, step=, required=, secret= }
|
||||
function sdk.settings.register_def(def) return nil end
|
||||
-- !impl
|
||||
function sdk.settings.defs(prefix) return {} end
|
||||
-- !impl
|
||||
function sdk.settings.dump() return {} end
|
||||
-- !impl
|
||||
function sdk.settings.plugins() return {} end
|
||||
|
||||
-- ============ events（只读订阅） ============
|
||||
-- !impl
|
||||
-- subscribe(event_type, handler) -> unsubscribe()
|
||||
-- handler 收到 { type=, source=, timestamp=, payload= }；
|
||||
-- 回调在其内核事件发布 goroutine 上执行，只做轻量转发，不可阻塞（Lua 单状态 + 互斥锁）。
|
||||
sdk.events = {}
|
||||
function sdk.events.subscribe(event_type, handler)
|
||||
print("[lua-plugin] events.subscribe: " .. tostring(event_type))
|
||||
return function() end
|
||||
end
|
||||
|
||||
-- ============ plugin_mgr ============
|
||||
-- !impl
|
||||
sdk.plugin_mgr = {}
|
||||
function sdk.plugin_mgr.reload_one(name) return nil end
|
||||
function sdk.plugin_mgr.list_loaded() return {} end
|
||||
function sdk.plugin_mgr.is_disabled(name) return false end
|
||||
|
||||
-- json utils (pure Lua)
|
||||
sdk.json = {}
|
||||
|
||||
function sdk.json.encode(val)
|
||||
local ok, result = pcall(function()
|
||||
local function _encode(v)
|
||||
local t = type(v)
|
||||
if t == "string" then
|
||||
local s = v:gsub('\\', '\\\\'):gsub('"', '\\"'):gsub('\n', '\\n'):gsub('\r', '\\r'):gsub('\t', '\\t')
|
||||
return '"' .. s .. '"'
|
||||
elseif t == "number" then
|
||||
return tostring(v)
|
||||
elseif t == "boolean" then
|
||||
return tostring(v)
|
||||
elseif t == "table" then
|
||||
local keys = {}
|
||||
local is_array = true
|
||||
local maxn = 0
|
||||
for k in pairs(v) do
|
||||
keys[#keys + 1] = k
|
||||
if type(k) ~= "number" or k < 1 or k ~= math.floor(k) then
|
||||
is_array = false
|
||||
end
|
||||
if type(k) == "number" and k > maxn then maxn = k end
|
||||
end
|
||||
if is_array and #keys >= maxn then
|
||||
local parts = {}
|
||||
for i = 1, maxn do
|
||||
parts[#parts + 1] = _encode(v[i])
|
||||
end
|
||||
return "[" .. table.concat(parts, ",") .. "]"
|
||||
else
|
||||
local parts = {}
|
||||
for _, k in ipairs(keys) do
|
||||
parts[#parts + 1] = _encode(tostring(k)) .. ":" .. _encode(v[k])
|
||||
end
|
||||
return "{" .. table.concat(parts, ",") .. "}"
|
||||
end
|
||||
else
|
||||
return "null"
|
||||
end
|
||||
end
|
||||
return _encode(val)
|
||||
end)
|
||||
if ok then return result end
|
||||
return "null"
|
||||
end
|
||||
|
||||
function sdk.json.decode(str)
|
||||
local ok, result = pcall(function()
|
||||
local pos, _end = 1, #str
|
||||
local function skip()
|
||||
while pos <= _end and str:sub(pos, pos):match("%s") do pos = pos + 1 end
|
||||
end
|
||||
local function parse()
|
||||
skip()
|
||||
if pos > _end then return nil end
|
||||
local c = str:sub(pos, pos)
|
||||
if c == '"' then
|
||||
local s = {}
|
||||
pos = pos + 1
|
||||
while pos <= _end do
|
||||
local ch = str:sub(pos, pos)
|
||||
if ch == '"' then
|
||||
pos = pos + 1
|
||||
return table.concat(s)
|
||||
elseif ch == '\\' then
|
||||
pos = pos + 1
|
||||
local n = str:sub(pos, pos)
|
||||
if n == '"' then s[#s+1] = '"'
|
||||
elseif n == '\\' then s[#s+1] = '\\'
|
||||
elseif n == '/' then s[#s+1] = '/'
|
||||
elseif n == 'b' then s[#s+1] = '\b'
|
||||
elseif n == 'f' then s[#s+1] = '\f'
|
||||
elseif n == 'n' then s[#s+1] = '\n'
|
||||
elseif n == 'r' then s[#s+1] = '\r'
|
||||
elseif n == 't' then s[#s+1] = '\t'
|
||||
elseif n == 'u' then
|
||||
local hex = str:sub(pos+1, pos+4)
|
||||
pos = pos + 4
|
||||
s[#s+1] = utf8 and utf8.char(tonumber(hex, 16)) or '?'
|
||||
end
|
||||
pos = pos + 1
|
||||
else
|
||||
s[#s+1] = ch
|
||||
pos = pos + 1
|
||||
end
|
||||
end
|
||||
return table.concat(s)
|
||||
elseif c == 't' then pos = pos + 4; return true
|
||||
elseif c == 'f' then pos = pos + 5; return false
|
||||
elseif c == 'n' then pos = pos + 4; return nil
|
||||
elseif c == '{' then
|
||||
pos = pos + 1; skip()
|
||||
local t = {}
|
||||
if str:sub(pos, pos) == '}' then pos = pos + 1; return t end
|
||||
while true do
|
||||
skip(); local k = parse(); skip()
|
||||
if str:sub(pos, pos) == ':' then pos = pos + 1 end
|
||||
skip(); t[k] = parse(); skip()
|
||||
local sep = str:sub(pos, pos)
|
||||
if sep == '}' then pos = pos + 1; return t end
|
||||
if sep == ',' then pos = pos + 1 end
|
||||
end
|
||||
elseif c == '[' then
|
||||
pos = pos + 1; skip()
|
||||
local t = {}
|
||||
if str:sub(pos, pos) == ']' then pos = pos + 1; return t end
|
||||
local idx = 1
|
||||
while true do
|
||||
skip(); t[idx] = parse(); idx = idx + 1; skip()
|
||||
local sep = str:sub(pos, pos)
|
||||
if sep == ']' then pos = pos + 1; return t end
|
||||
if sep == ',' then pos = pos + 1 end
|
||||
end
|
||||
else
|
||||
local s, e = str:find('^[-%d%.eE]+', pos)
|
||||
if s then
|
||||
local num = tonumber(str:sub(s, e))
|
||||
pos = e + 1
|
||||
return num
|
||||
end
|
||||
return nil
|
||||
end
|
||||
end
|
||||
return parse()
|
||||
end)
|
||||
if ok then return result end
|
||||
return nil
|
||||
end
|
||||
|
||||
-- http utils
|
||||
sdk.http = {}
|
||||
|
||||
-- !impl
|
||||
function sdk.http.get(url)
|
||||
print("[lua-plugin] http.get: " .. tostring(url))
|
||||
return {status=200, body='{"mock":true}', headers={}}
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.http.post(url, body, content_type)
|
||||
print("[lua-plugin] http.post: " .. tostring(url))
|
||||
return {status=200, body='{"mock":true}', headers={}}
|
||||
end
|
||||
|
||||
return sdk
|
||||
@ -49,17 +49,15 @@ type TextMemoryAPI interface {
|
||||
//
|
||||
// 两个方向共用一个类型：
|
||||
// - 写入（InsertWithMedia）：给 Data + MIME 就是新内容；只给 Digest 则是引用已有内容。
|
||||
// - 读出（Query）：内核只填 Digest/MIME，**不回 Data**——
|
||||
// - 读出（Query）：内核只填 Digest/MIME/Description，**不回 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"`
|
||||
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 TextEvent struct {
|
||||
@ -76,8 +74,8 @@ type DocMemoryAPI interface {
|
||||
Insert(doc *Doc) error
|
||||
// InsertWithMedia 写入文档并关联媒体。attachments 里带 Data 的会落进
|
||||
// 内容寻址存储（相同字节只存一份），只带 Digest 的直接引用已有内容。
|
||||
// 媒体成为文档直接持有的一等记忆块：文档向量会融合它们的原生向量，
|
||||
// 因此图片按自己的向量被召回，不依赖任何生成的描述文本。
|
||||
// 插件无需自己拼标记：内核会把 `[mime <短 digest>] <描述>` 补进 Content，
|
||||
// 让向量检索和后续蒸馏都能看到这份媒体。
|
||||
InsertWithMedia(doc *Doc, attachments []MediaAttachment) error
|
||||
Remove(id string)
|
||||
Stats() map[string]interface{}
|
||||
|
||||
297
sdk/plugin.go
297
sdk/plugin.go
@ -35,113 +35,12 @@ 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
|
||||
}
|
||||
|
||||
// 召回策略：决定一次工具调用/输入/注入是否据其内容**召回**（注入）相关记忆。
|
||||
//
|
||||
// 与 ContextPolicy **正交**：ContextPolicy 管「裁剪」（把低相关 L0 事件归档），
|
||||
// RecallPolicy 管「召回」（把 L2/L3 的相关记忆注入本轮）。两者默认值刻意相反——
|
||||
// 裁剪是破坏性的，默认关（必须显式声明）；召回是只读增量、日常对话本就需要，
|
||||
// 默认 auto（输入/注入），仅**工具**默认 none（工具输出多为噪声，按需声明）。
|
||||
const (
|
||||
RecallPolicyNone = "none"
|
||||
RecallPolicyAuto = "auto"
|
||||
)
|
||||
|
||||
// ValidRecallPolicy 校验召回策略取值；空串按调用面取默认值。
|
||||
func ValidRecallPolicy(policy string) bool {
|
||||
switch policy {
|
||||
case "", RecallPolicyNone, RecallPolicyAuto:
|
||||
return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
// InjectOptions 声明一次注入行为在记忆层与上下文层的表现。
|
||||
//
|
||||
// 零值 = 记入记忆 + 不裁剪上下文，与历史行为（三参数注入方法）完全一致，
|
||||
// 因此调用方只有在确实需要改变行为时才需要填它。
|
||||
//
|
||||
// 为什么注入也要这两个标志：注入的内容来源千差万别——轮询到的频道消息
|
||||
// 属于真实对话（该记），而“任务还在跑”“连接已重连”这类提醒不该污染记忆，
|
||||
// 也不该把上下文按它的内容裁一遍。按调用点声明比按通道一刀切准确。
|
||||
//
|
||||
// NoMemory: 此次注入不参与记忆计算（向量化/关键词提取/蒸馏），原文仍留在上下文
|
||||
// ContextPolicy: 此次注入后是否依据（清洗后的）内容裁剪上下文；默认不裁剪。
|
||||
// RecallPolicy: 此次注入是否依据（清洗后的）内容召回相关记忆；默认 auto（召回）。
|
||||
//
|
||||
// 中断注入也允许声明 prune——它同样会携带内容进入上下文。
|
||||
//
|
||||
// CleanerName: 此次注入的内容用哪个**已注册的通道 cleaner** 清洗。
|
||||
//
|
||||
// 空串 = 按注入的 source 查通道定义（既有行为）。
|
||||
// 为什么要能显式指定：注入的 source 未必是注册过的输入通道名，
|
||||
// 而注入内容往往带 ANSI/JSON 包装，需要清洗后才是有效内容；
|
||||
// 不指定就只能退到「按 source 查不到就不清洗」。
|
||||
type InjectOptions struct {
|
||||
NoMemory bool
|
||||
ContextPolicy string
|
||||
// RecallPolicy 声明此次注入是否据其内容召回相关记忆。
|
||||
// 空串 = 默认（输入/注入 auto，即保持既有「每条输入都召回」的行为）；
|
||||
// RecallPolicyNone 显式关闭（如中断通知的 meta 文本不该据它召回）。
|
||||
RecallPolicy string
|
||||
CleanerName string
|
||||
|
||||
// Priority 声明**中断注入**的优先级（仅 InjectInterrupt* 有意义）。
|
||||
//
|
||||
// 取值 PriorityL1..PriorityL4；空等同 L1（默认级）。
|
||||
// L4 只有**内核级插件**能用（见 PriorityL4 注释）；外部插件的 L4 会被夹到 L3。
|
||||
//
|
||||
// 排队注入（InjectText*/InjectInputSync）没有级别：它们本就是“不需及时处理”
|
||||
// 的那一类，可被任何中断打断。
|
||||
Priority string
|
||||
}
|
||||
|
||||
// 中断优先级取值。
|
||||
//
|
||||
// L1..L3 任何插件都可声明；**L4 只有内核级插件**（编译期内置插件，
|
||||
// 如 cli/webui/timer）才能声明——它用于实现真正的“立即打断”能力，
|
||||
// 例如 WebUI 的终止按钮。外部插件（走 proc 桥）声明 L4 会被内核夹到 L3。
|
||||
const (
|
||||
PriorityL1 = "L1"
|
||||
PriorityL2 = "L2"
|
||||
PriorityL3 = "L3"
|
||||
// PriorityL4 仅内核级（内置）插件可用；外部插件声明会被夹到 L3。
|
||||
PriorityL4 = "L4"
|
||||
)
|
||||
|
||||
// ChannelDef 描述通道在记忆计算层的行为，与 ToolDef.NoMemory/Cleaner 语义一致。
|
||||
// NoMemory: 此通道输入/输出不参与记忆计算（向量化/关键词提取/蒸馏），但原文保留在上下文中
|
||||
// Cleaner: 计算层过滤函数，不改原文；仅在向量化/jieba/蒸馏/存档提取关键词时调用
|
||||
// ContextPolicy: 此通道的输入到达后是否据此裁剪上下文，默认 none（不裁剪）
|
||||
// RecallPolicy: 此通道的输入到达后是否据此召回相关记忆，默认 auto（召回）
|
||||
//
|
||||
// JSON tag 是必需的：通道定义要跨进程传给内核，而 Cleaner 是函数（必须忽略）。
|
||||
// 没有 tag 时既无法整体 marshal（func 不支持），又会诱使调用方手写字段白名单——
|
||||
// 那样新增字段会被静默丢掉。
|
||||
type ChannelDef struct {
|
||||
NoMemory bool `json:"no_memory,omitempty"`
|
||||
Cleaner func(string) string `json:"-"`
|
||||
ContextPolicy string `json:"context_policy,omitempty"`
|
||||
// RecallPolicy 见 InjectOptions.RecallPolicy；空串等价 auto（保持既有行为）。
|
||||
RecallPolicy string `json:"recall_policy,omitempty"`
|
||||
NoMemory bool
|
||||
Cleaner func(string) string
|
||||
}
|
||||
|
||||
// StageContext provides context for stage handlers.
|
||||
@ -201,17 +100,12 @@ 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/蒸馏时调用
|
||||
ContextPolicy string `json:"context_policy,omitempty"` // 上下文策略：""(默认，不裁剪) / ContextPolicyNone / ContextPolicyPrune
|
||||
// RecallPolicy 声明此工具输出是否触发一次记忆召回（注入）。
|
||||
// ""(默认 none) / RecallPolicyNone / RecallPolicyAuto。
|
||||
// 默认 none：多数工具输出是噪声；需要「取回真实内容后据它召回」的工具（如 qq_get_message）应显式声明 auto。
|
||||
RecallPolicy string `json:"recall_policy,omitempty"`
|
||||
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/蒸馏时调用
|
||||
}
|
||||
|
||||
// IOInjector provides methods for injecting input and interrupts into the agent pipeline.
|
||||
@ -230,17 +124,6 @@ type IOInjector interface {
|
||||
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.
|
||||
@ -316,13 +199,6 @@ type InputChannelRegistrar func(name string, def ChannelDef) error
|
||||
// OutputChannelRegistrar registers an output channel that the output_send tool can use.
|
||||
type OutputChannelRegistrar func(name string, caps int, desc string, def ChannelDef, handler ToolHandler) error
|
||||
|
||||
// OutputChannelUnregistrar 注销一个输出通道。
|
||||
//
|
||||
// 为什么需要它：输出通道不止有"启动时注册一次"的静态通道，还有**随外部资源生灭**的
|
||||
// 动态通道 —— 典型是远程设备：`device/<id>` 只在设备在线期间存在，设备掉线后
|
||||
// 必须注销，否则 output_list_channels 会一直列着它、模型会往一个死通道发消息。
|
||||
type OutputChannelUnregistrar func(name string) error
|
||||
|
||||
// Output capability flags
|
||||
const (
|
||||
CapText = 1
|
||||
@ -335,23 +211,22 @@ const (
|
||||
// PluginSDK is the main API surface provided to plugins at runtime.
|
||||
// It wraps tool registration, settings, memory, knowledge, LLM, and IO injection.
|
||||
type PluginSDK struct {
|
||||
name string
|
||||
regTool ToolRegistrar
|
||||
regStage StageRegistrar
|
||||
regAPI APIRegistrar
|
||||
regOutput OutputChannelRegistrar
|
||||
regOutputUnreg OutputChannelUnregistrar
|
||||
regInput InputChannelRegistrar
|
||||
io IOInjector
|
||||
mem MemoryAPI
|
||||
textMem TextMemoryAPI
|
||||
docMem DocMemoryAPI
|
||||
know KnowledgeAPI
|
||||
llm LLMAPI
|
||||
sett SettingsAPI
|
||||
social SocialAPI
|
||||
events EventSubscriber
|
||||
plgMgr PluginMgrAPI
|
||||
name string
|
||||
regTool ToolRegistrar
|
||||
regStage StageRegistrar
|
||||
regAPI APIRegistrar
|
||||
regOutput OutputChannelRegistrar
|
||||
regInput InputChannelRegistrar
|
||||
io IOInjector
|
||||
mem MemoryAPI
|
||||
textMem TextMemoryAPI
|
||||
docMem DocMemoryAPI
|
||||
know KnowledgeAPI
|
||||
llm LLMAPI
|
||||
sett SettingsAPI
|
||||
social SocialAPI
|
||||
events EventSubscriber
|
||||
plgMgr PluginMgrAPI
|
||||
|
||||
// apiMu 保护上面这些由内核注入的 API 字段，以及 autoRestart。
|
||||
//
|
||||
@ -507,20 +382,7 @@ func (s *PluginSDK) RegisterPluginAPI(name string) error {
|
||||
}
|
||||
|
||||
// RegisterOutputChannel registers an output channel that the output_send tool can route to.
|
||||
//
|
||||
// 与 RegisterInputChannel 的分工：本函数声明**出站**（output_send__<name> 的回复发给谁）；
|
||||
// 入站（谁会往 <name> 注入输入）是另一件事，用 RegisterInputChannel 声明。
|
||||
// 若该通道同时也是你的注入入口，两个都要登记。
|
||||
//
|
||||
// name: channel name (e.g. "qq", "webui")。
|
||||
//
|
||||
// ❗**命名约束**：内核会把通道名拼进 LLM 的函数名（`output_send__<name>`），
|
||||
// 而上游对函数名的规范是 `^[a-zA-Z0-9_-]{1,64}$`。违反的后果不是"这个工具不可用"，
|
||||
// 而是**整条请求被上游 400 拒绝**（`Invalid 'tools[N].function.name'`），
|
||||
// 网关的 auto tier 会全链条失败 —— 表现成"整个 agent 不说话了"。
|
||||
// 所以通道名只能用 `[A-Za-z0-9_-]`，且总长要留出 `output_send__`（13 字符）的余量。
|
||||
// 若通道名来自外部输入（设备自报 id 之类），请**在插件侧派生一个合规且唯一的名字**，
|
||||
// 而不是把原始值直接当通道名。
|
||||
// name: channel name (e.g. "qq", "webui")
|
||||
// caps: bitmask of supported output capabilities (CapText, CapFile, etc.)
|
||||
// desc: description of the channel, expected meta format, and type enum
|
||||
// def: 通道在记忆计算层的行为（NoMemory/Cleaner）
|
||||
@ -535,27 +397,7 @@ func (s *PluginSDK) RegisterOutputChannel(name string, caps int, desc string, de
|
||||
return nil
|
||||
}
|
||||
|
||||
// UnregisterOutputChannel 注销一个输出通道（动态通道随资源生灭时必须调用）。
|
||||
func (s *PluginSDK) UnregisterOutputChannel(name string) error {
|
||||
s.apiMu.RLock()
|
||||
reg := s.regOutputUnreg
|
||||
s.apiMu.RUnlock()
|
||||
if reg != nil {
|
||||
return reg(name)
|
||||
}
|
||||
return nil
|
||||
}
|
||||
|
||||
// RegisterInputChannel registers an input channel with its memory behavior.
|
||||
//
|
||||
// 契约：**凡是用 InjectText*/InjectInput*/InjectInterrupt*(source, "<name>", ...)
|
||||
// 注入的通道名，都应当在这里登记**。inputch 是内核里最基本的**输入路由单位**：
|
||||
// 只有登记过的通道才能在 inputch 登记表里出现，父 agent 才能"把某个 inputch 划给驻留子"；
|
||||
// 没登记就划分会直接失败（`inputch 未注册`）。
|
||||
//
|
||||
// 只登记输出通道（RegisterOutputChannel）而没登记输入通道时，内核会兜底登记同名
|
||||
// inputch 并打告警日志 —— 兜底只为兼容老插件，新插件请显式登记。
|
||||
//
|
||||
// def.NoMemory: 此通道输入不参与记忆计算
|
||||
// def.Cleaner: 计算层对输入文本清洗后（不改原文）再向量化/提关键词
|
||||
func (s *PluginSDK) RegisterInputChannel(name string, def ChannelDef) error {
|
||||
@ -577,13 +419,6 @@ func (s *PluginSDK) SetOutputChannelRegistrar(r OutputChannelRegistrar) {
|
||||
s.apiMu.Unlock()
|
||||
}
|
||||
|
||||
// SetOutputChannelUnregistrar sets the output channel unregistrar (called by the core at startup).
|
||||
func (s *PluginSDK) SetOutputChannelUnregistrar(r OutputChannelUnregistrar) {
|
||||
s.apiMu.Lock()
|
||||
s.regOutputUnreg = r
|
||||
s.apiMu.Unlock()
|
||||
}
|
||||
|
||||
// SetInputChannelRegistrar sets the input channel registrar (called by the core at startup).
|
||||
func (s *PluginSDK) SetInputChannelRegistrar(r InputChannelRegistrar) {
|
||||
s.apiMu.Lock()
|
||||
@ -669,94 +504,54 @@ func (s *PluginSDK) injector() IOInjector {
|
||||
}
|
||||
|
||||
// InjectInterruptText injects a text interrupt that can preempt current LLM processing.
|
||||
// 等价于 InjectInterruptTextOpts(..., InjectOptions{})：记入记忆、不裁剪。
|
||||
func (s *PluginSDK) InjectInterruptText(source, channel, text string) {
|
||||
s.InjectInterruptTextOpts(source, channel, text, InjectOptions{})
|
||||
if io := s.injector(); io != nil {
|
||||
io.InjectInterruptText(source, channel, text)
|
||||
}
|
||||
}
|
||||
|
||||
// InjectText injects a text message into the agent pipeline.
|
||||
// 等价于 InjectTextOpts(..., InjectOptions{})：记入记忆、不裁剪。
|
||||
func (s *PluginSDK) InjectText(source, channel, text string) {
|
||||
s.InjectTextOpts(source, channel, text, InjectOptions{})
|
||||
if io := s.injector(); io != nil {
|
||||
io.InjectText(source, channel, text)
|
||||
}
|
||||
}
|
||||
|
||||
// InjectTextNoMemory injects a text message without generating memory.
|
||||
// 等价于 InjectTextOpts(..., InjectOptions{NoMemory: true})。
|
||||
func (s *PluginSDK) InjectTextNoMemory(source, channel, text string) {
|
||||
s.InjectTextOpts(source, channel, text, InjectOptions{NoMemory: true})
|
||||
if io := s.injector(); io != nil {
|
||||
io.InjectTextNoMemory(source, channel, text)
|
||||
}
|
||||
}
|
||||
|
||||
// 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 {
|
||||
return s.InjectInputSyncOpts(source, channel, text, InjectOptions{})
|
||||
io := s.injector()
|
||||
if io == nil {
|
||||
return ""
|
||||
}
|
||||
return io.InjectInputSync(source, channel, text)
|
||||
}
|
||||
|
||||
// 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{})
|
||||
if io := s.injector(); io != nil {
|
||||
io.InjectInputMedia(source, channel, text, blocks)
|
||||
}
|
||||
}
|
||||
|
||||
// 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 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)
|
||||
}
|
||||
return io.InjectInputMediaSync(source, channel, text, blocks)
|
||||
}
|
||||
|
||||
// InjectInterruptMedia 注入带媒体内容块的中断，可抢占当前 LLM 处理。
|
||||
@ -775,12 +570,8 @@ func (s *PluginSDK) SetToolBlocks(blocks []ContentBlock) {
|
||||
}
|
||||
}
|
||||
|
||||
// SetAutoRestart 设置插件崩溃后内核是否自动重启它。
|
||||
// SetAutoRestart 设置插件是否允许内核自动重启（崩溃后自动重载）。
|
||||
// 默认 true。如果插件有无法恢复的状态（如外部连接），应设为 false。
|
||||
//
|
||||
// 重启是有限度的：线性退避（第 n 次等 n×1s，即 1s→2s→3s），
|
||||
// 且同一 5 分钟窗口内第 4 次崩溃就停下不再拉起（详见 README）。
|
||||
// 注意这与「重载」（换 plugin.bin 后重新加载）是两回事。
|
||||
func (s *PluginSDK) SetAutoRestart(enabled bool) {
|
||||
s.apiMu.Lock()
|
||||
s.autoRestart = enabled
|
||||
|
||||
@ -43,7 +43,6 @@ type injectCall struct {
|
||||
channel string
|
||||
text string
|
||||
blocks []ContentBlock
|
||||
opts InjectOptions // 调用点声明的记忆/裁剪行为
|
||||
}
|
||||
|
||||
func (r *recordingInjector) record(c injectCall) {
|
||||
@ -94,41 +93,6 @@ func (r *recordingInjector) InjectInterruptMedia(s, c, t string, b []ContentBloc
|
||||
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()
|
||||
@ -499,10 +463,11 @@ func TestStress_MediaTypesJSONRoundTripAtScale(t *testing.T) {
|
||||
data[i] = byte(i * 7 % 256)
|
||||
}
|
||||
att := MediaAttachment{
|
||||
Digest: strings.Repeat("a", 64),
|
||||
MIME: "image/png",
|
||||
Data: data,
|
||||
Name: "图片-名字 with space & 符号.png",
|
||||
Digest: strings.Repeat("a", 64),
|
||||
MIME: "image/png",
|
||||
Data: data,
|
||||
Name: "图片-名字 with space & 符号.png",
|
||||
Description: "一张紫蓝红三色带图，含 emoji 🎨 与换行\n第二行",
|
||||
}
|
||||
b, err := json.Marshal(att)
|
||||
if err != nil {
|
||||
@ -520,7 +485,7 @@ func TestStress_MediaTypesJSONRoundTripAtScale(t *testing.T) {
|
||||
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 {
|
||||
if back.Name != att.Name || back.Description != att.Description || back.MIME != att.MIME || back.Digest != att.Digest {
|
||||
t.Fatalf("size=%d 元数据往返不一致: %+v", n, back)
|
||||
}
|
||||
}
|
||||
|
||||
@ -1,413 +0,0 @@
|
||||
-- HomeAgent Lua Plugin SDK
|
||||
-- Interface contract between Lua plugins and HomeAgent kernel.
|
||||
-- !impl functions are replaced by Go implementations at runtime.
|
||||
-- Standalone/debug: pure Lua mock implementations are used.
|
||||
-- Usage: local sdk = require("sdk")
|
||||
|
||||
sdk = {}
|
||||
|
||||
-- !impl
|
||||
-- level: "debug" | "info" | "warn" | "error"
|
||||
function sdk.log(level, msg)
|
||||
print("[lua-plugin] " .. tostring(level) .. ": " .. tostring(msg))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- def: { description="...", parameters={...}, no_memory=true/false, cleaner=function(text)->text }
|
||||
-- handler: function(args) -> result
|
||||
function sdk.register_tool(name, def, handler)
|
||||
print("[lua-plugin] register_tool: " .. tostring(name))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- stage: "on_input" | "pre_action" | "post_action" | ...
|
||||
-- scope: nil/"global" (默认) | "own_tools"（仅 before_toolcall/after_toolcall 且工具属于本插件时触发）
|
||||
function sdk.register_stage(stage, handler, scope)
|
||||
print("[lua-plugin] register_stage: " .. tostring(stage) .. " scope=" .. tostring(scope))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.register_api(name)
|
||||
print("[lua-plugin] register_api: " .. tostring(name))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- def: { no_memory=true/false, cleaner=function(text)->text }
|
||||
-- handler: function(args) -> result
|
||||
function sdk.register_output_channel(name, caps, desc, def, handler)
|
||||
print("[lua-plugin] register_output_channel: " .. tostring(name))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- def: { no_memory=true/false, cleaner=function(text)->text }
|
||||
function sdk.register_input_channel(name, def)
|
||||
print("[lua-plugin] register_input_channel: " .. tostring(name))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.get_setting(key)
|
||||
return nil
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.set_setting(key, value)
|
||||
print("[lua-plugin] set_setting: " .. tostring(key))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_text(source, channel, text)
|
||||
print("[lua-plugin] inject_text: " .. tostring(source) .. "/" .. tostring(channel))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_interrupt(source, channel, text)
|
||||
print("[lua-plugin] inject_interrupt: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_text_no_memory(source, channel, text)
|
||||
print("[lua-plugin] inject_text_no_memory: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- opts: { no_memory=bool, context_policy="none"|"prune", cleaner_name=string, priority="L1".."L3" }
|
||||
-- 零值/缺省 = 记入记忆 + 不裁剪（与三参数版本等价）。
|
||||
function sdk.inject_text_opts(source, channel, text, opts)
|
||||
print("[lua-plugin] inject_text_opts: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_interrupt_opts(source, channel, text, opts)
|
||||
print("[lua-plugin] inject_interrupt_opts: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- 同步注入在 Lua 插件中**不可用**：会等本轮回复，而本轮正持有插件锁 ⇒ 必然自锁。
|
||||
-- 真实内核里恒返回 (nil, err)；这里返回同样的错误，避免离线测试误以为可用。
|
||||
function sdk.inject_input_sync(source, channel, text)
|
||||
return nil, "同步注入在 Lua 插件中不可用：请在事件回调/外部入口用 inject_text/inject_interrupt；确需同步等待请改用 Go 插件。"
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_input_sync_opts(source, channel, text, opts)
|
||||
return nil, "同步注入在 Lua 插件中不可用：请在事件回调/外部入口用 inject_text/inject_interrupt；确需同步等待请改用 Go 插件。"
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- blocks: ContentBlock 数组，见 sdk.inject_input_media。
|
||||
-- 设置下一轮 tool message 携带的多模态内容块（模型据此看图/听音频）。
|
||||
function sdk.set_tool_blocks(blocks)
|
||||
print("[lua-plugin] set_tool_blocks: " .. tostring(blocks and #blocks or 0))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- blocks 每项：{ type="text", text="..." }
|
||||
-- | { type="image_url", image_url={ url="...", detail="high" } }
|
||||
-- | { type="audio_url", audio_url={ url="..." } }
|
||||
function sdk.inject_input_media(source, channel, text, blocks)
|
||||
print("[lua-plugin] inject_input_media: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_input_media_opts(source, channel, text, blocks, opts)
|
||||
print("[lua-plugin] inject_input_media_opts: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- 同 sdk.inject_input_sync：Lua 中不可用。
|
||||
function sdk.inject_input_media_sync(source, channel, text, blocks)
|
||||
return nil, "同步注入在 Lua 插件中不可用：请在事件回调/外部入口用 inject_input_media；确需同步等待请改用 Go 插件。"
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_input_media_sync_opts(source, channel, text, blocks, opts)
|
||||
return nil, "同步注入在 Lua 插件中不可用：请在事件回调/外部入口用 inject_input_media_opts；确需同步等待请改用 Go 插件。"
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_interrupt_media(source, channel, text, blocks)
|
||||
print("[lua-plugin] inject_interrupt_media: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.inject_interrupt_media_opts(source, channel, text, blocks, opts)
|
||||
print("[lua-plugin] inject_interrupt_media_opts: " .. tostring(source))
|
||||
end
|
||||
|
||||
-- !impl
|
||||
-- 注销输出通道（随资源生灭的动态通道，如远程设备）。返回 (nil, err)。
|
||||
function sdk.unregister_output_channel(name) return nil, nil end
|
||||
|
||||
-- !impl
|
||||
-- enabled: true/false，崩溃时内核自动拉起
|
||||
function sdk.set_auto_restart(enabled)
|
||||
print("[lua-plugin] set_auto_restart: " .. tostring(enabled))
|
||||
end
|
||||
|
||||
-- ============ graph memory ============
|
||||
-- !impl
|
||||
sdk.memory = {}
|
||||
-- !impl
|
||||
-- query: string, depth: number -> {entities={...}, relations={...}}
|
||||
function sdk.memory.recall(query, depth) return {entities={}, relations={}} end
|
||||
-- !impl
|
||||
-- triples: { {subject=, relation=, object=, [confidence=], [sentence_text=]} } -> err
|
||||
function sdk.memory.commit(triples) return nil end
|
||||
-- !impl
|
||||
function sdk.memory.introspect() return {} end
|
||||
-- !impl
|
||||
function sdk.memory.merge(source, target) return 0 end
|
||||
-- !impl
|
||||
-- criteria: {key=value}, hard: boolean
|
||||
function sdk.memory.purge(criteria, hard) return 0 end
|
||||
|
||||
-- ============ document memory ============
|
||||
-- !impl
|
||||
sdk.doc = {}
|
||||
-- !impl
|
||||
function sdk.doc.query(text, top_k) return {} end
|
||||
-- !impl
|
||||
-- doc: { id=, title=, content= }
|
||||
function sdk.doc.insert(doc) return nil end
|
||||
-- !impl
|
||||
-- attachments 每项：{ digest=, mime=, name=, data=<base64> }
|
||||
function sdk.doc.insert_with_media(doc, attachments) return nil end
|
||||
-- !impl
|
||||
function sdk.doc.remove(id) return nil end
|
||||
-- !impl
|
||||
function sdk.doc.stats() return {} end
|
||||
|
||||
-- ============ knowledge ============
|
||||
-- !impl
|
||||
sdk.knowledge = {}
|
||||
-- !impl
|
||||
function sdk.knowledge.search(query, limit) return {} end
|
||||
-- !impl
|
||||
function sdk.knowledge.add(tag, content) return nil end
|
||||
-- !impl
|
||||
function sdk.knowledge.list() return {} end
|
||||
|
||||
-- ============ text memory ============
|
||||
-- !impl
|
||||
sdk.text_memory = {}
|
||||
-- !impl
|
||||
-- evt: { timestamp=, role=, content=, channel= }
|
||||
function sdk.text_memory.append(evt) return nil end
|
||||
|
||||
-- ============ llm ============
|
||||
-- !impl
|
||||
sdk.llm = {}
|
||||
-- !impl
|
||||
function sdk.llm.list_sources() return {} end
|
||||
-- !impl
|
||||
function sdk.llm.set_source(name) return nil end
|
||||
-- !impl
|
||||
function sdk.llm.current_source() return nil end
|
||||
|
||||
-- ============ social (只读) ============
|
||||
-- !impl
|
||||
sdk.social = {}
|
||||
-- !impl
|
||||
function sdk.social.get_person(name) return {} end
|
||||
-- !impl
|
||||
function sdk.social.get_network(name, depth) return {} end
|
||||
-- !impl
|
||||
function sdk.social.get_trait(name, trait) return {value=nil, found=false} end
|
||||
-- !impl
|
||||
function sdk.social.get_relations(name) return {} end
|
||||
-- !impl
|
||||
function sdk.social.list_persons() return {} end
|
||||
|
||||
-- ============ settings (作用域变体) ============
|
||||
-- !impl
|
||||
sdk.settings = {}
|
||||
-- !impl
|
||||
function sdk.settings.get_core(key) return nil end
|
||||
-- !impl
|
||||
function sdk.settings.set_core(key, value) return nil end
|
||||
-- !impl
|
||||
function sdk.settings.list_core(prefix) return {} end
|
||||
-- !impl
|
||||
function sdk.settings.get_plugin(plugin, key) return nil end
|
||||
-- !impl
|
||||
function sdk.settings.set_plugin(plugin, key, value) return nil end
|
||||
-- !impl
|
||||
function sdk.settings.list_plugin(plugin, prefix) return {} end
|
||||
-- !impl
|
||||
function sdk.settings.list(prefix) return {} end
|
||||
-- !impl
|
||||
-- def: { key=, type=, display_name=, description=, category=, options=, default=,
|
||||
-- min=, max=, step=, required=, secret= }
|
||||
function sdk.settings.register_def(def) return nil end
|
||||
-- !impl
|
||||
function sdk.settings.defs(prefix) return {} end
|
||||
-- !impl
|
||||
function sdk.settings.dump() return {} end
|
||||
-- !impl
|
||||
function sdk.settings.plugins() return {} end
|
||||
|
||||
-- ============ events（只读订阅） ============
|
||||
-- !impl
|
||||
-- subscribe(event_type, handler) -> unsubscribe()
|
||||
-- handler 收到 { type=, source=, timestamp=, payload= }；
|
||||
-- 回调在其内核事件发布 goroutine 上执行，只做轻量转发，不可阻塞（Lua 单状态 + 互斥锁）。
|
||||
sdk.events = {}
|
||||
function sdk.events.subscribe(event_type, handler)
|
||||
print("[lua-plugin] events.subscribe: " .. tostring(event_type))
|
||||
return function() end
|
||||
end
|
||||
|
||||
-- ============ plugin_mgr ============
|
||||
-- !impl
|
||||
sdk.plugin_mgr = {}
|
||||
function sdk.plugin_mgr.reload_one(name) return nil end
|
||||
function sdk.plugin_mgr.list_loaded() return {} end
|
||||
function sdk.plugin_mgr.is_disabled(name) return false end
|
||||
|
||||
-- json utils (pure Lua)
|
||||
sdk.json = {}
|
||||
|
||||
function sdk.json.encode(val)
|
||||
local ok, result = pcall(function()
|
||||
local function _encode(v)
|
||||
local t = type(v)
|
||||
if t == "string" then
|
||||
local s = v:gsub('\\', '\\\\'):gsub('"', '\\"'):gsub('\n', '\\n'):gsub('\r', '\\r'):gsub('\t', '\\t')
|
||||
return '"' .. s .. '"'
|
||||
elseif t == "number" then
|
||||
return tostring(v)
|
||||
elseif t == "boolean" then
|
||||
return tostring(v)
|
||||
elseif t == "table" then
|
||||
local keys = {}
|
||||
local is_array = true
|
||||
local maxn = 0
|
||||
for k in pairs(v) do
|
||||
keys[#keys + 1] = k
|
||||
if type(k) ~= "number" or k < 1 or k ~= math.floor(k) then
|
||||
is_array = false
|
||||
end
|
||||
if type(k) == "number" and k > maxn then maxn = k end
|
||||
end
|
||||
if is_array and #keys >= maxn then
|
||||
local parts = {}
|
||||
for i = 1, maxn do
|
||||
parts[#parts + 1] = _encode(v[i])
|
||||
end
|
||||
return "[" .. table.concat(parts, ",") .. "]"
|
||||
else
|
||||
local parts = {}
|
||||
for _, k in ipairs(keys) do
|
||||
parts[#parts + 1] = _encode(tostring(k)) .. ":" .. _encode(v[k])
|
||||
end
|
||||
return "{" .. table.concat(parts, ",") .. "}"
|
||||
end
|
||||
else
|
||||
return "null"
|
||||
end
|
||||
end
|
||||
return _encode(val)
|
||||
end)
|
||||
if ok then return result end
|
||||
return "null"
|
||||
end
|
||||
|
||||
function sdk.json.decode(str)
|
||||
local ok, result = pcall(function()
|
||||
local pos, _end = 1, #str
|
||||
local function skip()
|
||||
while pos <= _end and str:sub(pos, pos):match("%s") do pos = pos + 1 end
|
||||
end
|
||||
local function parse()
|
||||
skip()
|
||||
if pos > _end then return nil end
|
||||
local c = str:sub(pos, pos)
|
||||
if c == '"' then
|
||||
local s = {}
|
||||
pos = pos + 1
|
||||
while pos <= _end do
|
||||
local ch = str:sub(pos, pos)
|
||||
if ch == '"' then
|
||||
pos = pos + 1
|
||||
return table.concat(s)
|
||||
elseif ch == '\\' then
|
||||
pos = pos + 1
|
||||
local n = str:sub(pos, pos)
|
||||
if n == '"' then s[#s+1] = '"'
|
||||
elseif n == '\\' then s[#s+1] = '\\'
|
||||
elseif n == '/' then s[#s+1] = '/'
|
||||
elseif n == 'b' then s[#s+1] = '\b'
|
||||
elseif n == 'f' then s[#s+1] = '\f'
|
||||
elseif n == 'n' then s[#s+1] = '\n'
|
||||
elseif n == 'r' then s[#s+1] = '\r'
|
||||
elseif n == 't' then s[#s+1] = '\t'
|
||||
elseif n == 'u' then
|
||||
local hex = str:sub(pos+1, pos+4)
|
||||
pos = pos + 4
|
||||
s[#s+1] = utf8 and utf8.char(tonumber(hex, 16)) or '?'
|
||||
end
|
||||
pos = pos + 1
|
||||
else
|
||||
s[#s+1] = ch
|
||||
pos = pos + 1
|
||||
end
|
||||
end
|
||||
return table.concat(s)
|
||||
elseif c == 't' then pos = pos + 4; return true
|
||||
elseif c == 'f' then pos = pos + 5; return false
|
||||
elseif c == 'n' then pos = pos + 4; return nil
|
||||
elseif c == '{' then
|
||||
pos = pos + 1; skip()
|
||||
local t = {}
|
||||
if str:sub(pos, pos) == '}' then pos = pos + 1; return t end
|
||||
while true do
|
||||
skip(); local k = parse(); skip()
|
||||
if str:sub(pos, pos) == ':' then pos = pos + 1 end
|
||||
skip(); t[k] = parse(); skip()
|
||||
local sep = str:sub(pos, pos)
|
||||
if sep == '}' then pos = pos + 1; return t end
|
||||
if sep == ',' then pos = pos + 1 end
|
||||
end
|
||||
elseif c == '[' then
|
||||
pos = pos + 1; skip()
|
||||
local t = {}
|
||||
if str:sub(pos, pos) == ']' then pos = pos + 1; return t end
|
||||
local idx = 1
|
||||
while true do
|
||||
skip(); t[idx] = parse(); idx = idx + 1; skip()
|
||||
local sep = str:sub(pos, pos)
|
||||
if sep == ']' then pos = pos + 1; return t end
|
||||
if sep == ',' then pos = pos + 1 end
|
||||
end
|
||||
else
|
||||
local s, e = str:find('^[-%d%.eE]+', pos)
|
||||
if s then
|
||||
local num = tonumber(str:sub(s, e))
|
||||
pos = e + 1
|
||||
return num
|
||||
end
|
||||
return nil
|
||||
end
|
||||
end
|
||||
return parse()
|
||||
end)
|
||||
if ok then return result end
|
||||
return nil
|
||||
end
|
||||
|
||||
-- http utils
|
||||
sdk.http = {}
|
||||
|
||||
-- !impl
|
||||
function sdk.http.get(url)
|
||||
print("[lua-plugin] http.get: " .. tostring(url))
|
||||
return {status=200, body='{"mock":true}', headers={}}
|
||||
end
|
||||
|
||||
-- !impl
|
||||
function sdk.http.post(url, body, content_type)
|
||||
print("[lua-plugin] http.post: " .. tostring(url))
|
||||
return {status=200, body='{"mock":true}', headers={}}
|
||||
end
|
||||
|
||||
return sdk
|
||||
@ -1,35 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"os"
|
||||
"os/exec"
|
||||
"path/filepath"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// TestCheckLuaSyntax 钉住 Lua 打包前的语法预检：语法错必须被拒。
|
||||
// 没有 lua/luac 的构建机跳过（预检按设计降级为警告）。
|
||||
func TestCheckLuaSyntax(t *testing.T) {
|
||||
if _, err := exec.LookPath("luac"); err != nil {
|
||||
if _, err := exec.LookPath("lua"); err != nil {
|
||||
t.Skip("no lua/luac in PATH")
|
||||
}
|
||||
}
|
||||
dir := t.TempDir()
|
||||
|
||||
good := filepath.Join(dir, "good.lua")
|
||||
if err := os.WriteFile(good, []byte("local x = 1\nreturn x\n"), 0644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := checkLuaSyntax(good); err != nil {
|
||||
t.Fatalf("valid Lua rejected: %v", err)
|
||||
}
|
||||
|
||||
bad := filepath.Join(dir, "bad.lua")
|
||||
if err := os.WriteFile(bad, []byte("function broken(\n"), 0644); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if err := checkLuaSyntax(bad); err == nil {
|
||||
t.Fatal("invalid Lua accepted; syntax check is not effective")
|
||||
}
|
||||
}
|
||||
@ -1,80 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"io"
|
||||
"os"
|
||||
"runtime"
|
||||
|
||||
"gitcode.com/JianFeeeee/homeagent-sdk/meta"
|
||||
)
|
||||
|
||||
func main() {
|
||||
if len(os.Args) < 2 {
|
||||
help()
|
||||
return
|
||||
}
|
||||
switch os.Args[1] {
|
||||
case "init":
|
||||
cmdInit(os.Args[2:])
|
||||
case "build":
|
||||
cmdBuild(os.Args[2:])
|
||||
case "clean":
|
||||
cmdClean(os.Args[2:])
|
||||
case "debug":
|
||||
cmdDebug(os.Args[2:])
|
||||
case "sdk":
|
||||
cmdSDK(os.Args[2:])
|
||||
case "version", "-v", "--version":
|
||||
printVersion()
|
||||
default:
|
||||
help()
|
||||
}
|
||||
}
|
||||
|
||||
// printVersion 输出工具链自身的版本身份。
|
||||
//
|
||||
// 为何必须有：此前工具链不报版本，而插件产物与内核是**协议绑定**的——
|
||||
// 手里是哪一版工具链、能不能配当前内核，只能靠翻文件名或猜。
|
||||
// 版本号来自 meta.Version（与 SDK 发布同源，由 -ldflags -X 注入）；
|
||||
// lnflags 未注入时它是源码里的默认值，此时提示它可能是开发构建。
|
||||
func printVersion() {
|
||||
printVersionTo(os.Stdout)
|
||||
}
|
||||
|
||||
// printVersionTo 把版本身份写到 w（抽出来是为了能被测试钉住）。
|
||||
func printVersionTo(w io.Writer) {
|
||||
fmt.Fprintf(w, "hmapdev %s\n", meta.Version)
|
||||
fmt.Fprintf(w, " SDK 模块: %s\n", "gitcode.com/JianFeeeee/homeagent-sdk")
|
||||
if meta.Commit != "" && meta.Commit != "unknown" {
|
||||
fmt.Fprintf(w, " 构建提交: %s\n", meta.Commit)
|
||||
}
|
||||
if meta.BuildTime != "" && meta.BuildTime != "unknown" {
|
||||
fmt.Fprintf(w, " 构建时间: %s\n", meta.BuildTime)
|
||||
}
|
||||
fmt.Fprintf(w, " 构建用 Go: %s\n", runtime.Version())
|
||||
fmt.Fprintf(w, " 可执行文件: %s\n", os.Args[0])
|
||||
}
|
||||
|
||||
func help() {
|
||||
fmt.Print(`HomeAgent Plugin Dev Tool
|
||||
|
||||
Usage:
|
||||
hmapdev version Print toolchain version
|
||||
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
|
||||
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)
|
||||
--target Target OS/arch (e.g. linux/amd64), repeatable
|
||||
--lua Create Lua plugin (for init)
|
||||
--type Project type: "remotedevice" (for init)
|
||||
-t Alias for --type
|
||||
`)
|
||||
}
|
||||
@ -1,57 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"gitcode.com/JianFeeeee/homeagent-sdk/meta"
|
||||
)
|
||||
|
||||
// 工具链必须能报出自己的版本。
|
||||
//
|
||||
// 为什么值得钉住：插件产物与内核是协议绑定的，「手里是哪一版工具链」直接决定
|
||||
// 产物能不能建链；此前既没有 version 子命令，`-ldflags -X meta.Version` 也因为
|
||||
// meta 包没被链接而**静默无效**（表现为报不出任何版本）。
|
||||
func TestPrintVersionReportsInjectedVersion(t *testing.T) {
|
||||
origVersion, origCommit := meta.Version, meta.Commit
|
||||
defer func() { meta.Version, meta.Commit = origVersion, origCommit }()
|
||||
|
||||
// 模拟 -ldflags 注入后的取值
|
||||
meta.Version = "9.9.9"
|
||||
meta.Commit = "deadbee"
|
||||
|
||||
var buf bytes.Buffer
|
||||
printVersionTo(&buf)
|
||||
out := buf.String()
|
||||
|
||||
if !strings.Contains(out, "9.9.9") {
|
||||
t.Fatalf("版本号未出现在输出里（-X 注入会失效）:\n%s", out)
|
||||
}
|
||||
if !strings.Contains(out, "hmapdev") {
|
||||
t.Fatalf("输出里没有工具名:\n%s", out)
|
||||
}
|
||||
if !strings.Contains(out, "deadbee") {
|
||||
t.Fatalf("提交号未出现在输出里:\n%s", out)
|
||||
}
|
||||
if !strings.Contains(out, "HomeAgent") && !strings.Contains(out, "homeagent-sdk") {
|
||||
t.Fatalf("输出里没有 SDK 模块标识:\n%s", out)
|
||||
}
|
||||
}
|
||||
|
||||
// 未注入时（源码默认值）也必须能报——否则开发构建和发版构建长得一样。
|
||||
func TestPrintVersionWorksWithoutInjection(t *testing.T) {
|
||||
origCommit, origBuildTime := meta.Commit, meta.BuildTime
|
||||
defer func() { meta.Commit, meta.BuildTime = origCommit, origBuildTime }()
|
||||
meta.Commit, meta.BuildTime = "unknown", "unknown"
|
||||
|
||||
var buf bytes.Buffer
|
||||
printVersionTo(&buf)
|
||||
out := buf.String()
|
||||
if !strings.Contains(out, meta.Version) {
|
||||
t.Fatalf("未注入时应报出源码默认版本 %q:\n%s", meta.Version, out)
|
||||
}
|
||||
if strings.Contains(out, "unknown") {
|
||||
t.Fatalf("unknown 字段不应出现在输出里（噪声）:\n%s", out)
|
||||
}
|
||||
}
|
||||
@ -1,135 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"sort"
|
||||
"strconv"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// sdkVersionEntry 是本地 SDK 存储里的一个版本。
|
||||
//
|
||||
// Dir 是存储目录名（历史上有 "v0.8.0" 与 "1.2.0" 两种写法都出现过，所以
|
||||
// 目录名与规范化版本号要分开存），Version 是去掉 v 前缀的 x.y.z。
|
||||
type sdkVersionEntry struct {
|
||||
Dir string
|
||||
Version string
|
||||
}
|
||||
|
||||
// normalizeSDKVersion 去掉常见的前缀写法，得到 x.y.z。
|
||||
func normalizeSDKVersion(v string) string {
|
||||
return strings.TrimPrefix(strings.TrimSpace(v), "v")
|
||||
}
|
||||
|
||||
// parseSDKVersion 解析 x.y.z / x.y（后者补 0）。
|
||||
func parseSDKVersion(v string) (maj, min, patch int, ok bool) {
|
||||
v = normalizeSDKVersion(v)
|
||||
parts := strings.Split(v, ".")
|
||||
if len(parts) < 2 || len(parts) > 3 {
|
||||
return 0, 0, 0, false
|
||||
}
|
||||
nums := make([]int, 0, 3)
|
||||
for _, p := range parts {
|
||||
n, err := strconv.Atoi(p)
|
||||
if err != nil || n < 0 {
|
||||
return 0, 0, 0, false
|
||||
}
|
||||
nums = append(nums, n)
|
||||
}
|
||||
for len(nums) < 3 {
|
||||
nums = append(nums, 0)
|
||||
}
|
||||
return nums[0], nums[1], nums[2], true
|
||||
}
|
||||
|
||||
// compareSDKVersion 比较两个 x.y.z（a<b 返回 -1，相等 0，a>b 返回 1）。
|
||||
func compareSDKVersion(a, b string) int {
|
||||
amaj, amin, apat, aok := parseSDKVersion(a)
|
||||
bmaj, bmin, bpat, bok := parseSDKVersion(b)
|
||||
if !aok || !bok {
|
||||
return strings.Compare(normalizeSDKVersion(a), normalizeSDKVersion(b))
|
||||
}
|
||||
for _, d := range [][2]int{{amaj, bmaj}, {amin, bmin}, {apat, bpat}} {
|
||||
switch {
|
||||
case d[0] < d[1]:
|
||||
return -1
|
||||
case d[0] > d[1]:
|
||||
return 1
|
||||
}
|
||||
}
|
||||
return 0
|
||||
}
|
||||
|
||||
// listInstalledSDKs 列出存储里已安装的 SDK，按版本升序。
|
||||
func listInstalledSDKs() []sdkVersionEntry {
|
||||
store := sdkStore()
|
||||
entries, err := os.ReadDir(store)
|
||||
if err != nil {
|
||||
return nil
|
||||
}
|
||||
var out []sdkVersionEntry
|
||||
for _, e := range entries {
|
||||
if !e.IsDir() {
|
||||
continue
|
||||
}
|
||||
name := e.Name()
|
||||
if name == "current" || strings.HasPrefix(name, ".") {
|
||||
continue
|
||||
}
|
||||
v := normalizeSDKVersion(name)
|
||||
if _, _, _, ok := parseSDKVersion(v); !ok {
|
||||
continue // 非版本目录（用户放别的东西进去时不误判）
|
||||
}
|
||||
out = append(out, sdkVersionEntry{Dir: name, Version: v})
|
||||
}
|
||||
sort.Slice(out, func(i, j int) bool { return compareSDKVersion(out[i].Version, out[j].Version) < 0 })
|
||||
return out
|
||||
}
|
||||
|
||||
// ResolveSDKForProject 按项目声明的 SDK 版本（plg.json 的 "sdk" 字段）在本地存储里定位 SDK。
|
||||
//
|
||||
// 声明必须是**完整版本号**（x.y.z，如 "1.2.0"）：SDK 的版本纪律是「跟随内核中版本，
|
||||
// patch 位恒为 .0」（内核的 patch 不碰公开接口 → SDK 不跟版），所以一条内核线
|
||||
// 只对应一个 SDK 版本号，写 "1.2" 这种区间写法既不必要、又容易让人以为
|
||||
// 「同一条线里还能挑不同 SDK」。工具链直接拒它，顺便把这条规矩说清楚。
|
||||
//
|
||||
// 找不到时必须报**可执行**的错误：列出已装版本 + 可直接粘贴的安装命令 ——
|
||||
// 只说 "not found" 会让人以为是工具链坏了。
|
||||
func ResolveSDKForProject(declared string) (dir, version string, err error) {
|
||||
declared = normalizeSDKVersion(declared)
|
||||
if strings.Count(declared, ".") != 2 {
|
||||
return "", "", fmt.Errorf(
|
||||
"plg.json 的 sdk 字段 %q 必须是完整版本号（如 \"1.2.0\"）——\n"+
|
||||
" SDK 版本跟随内核中版本、patch 位恒为 .0，一条内核线只有一个 SDK 版本", declared)
|
||||
}
|
||||
maj, min, pat, ok := parseSDKVersion(declared)
|
||||
if !ok {
|
||||
return "", "", fmt.Errorf("plg.json 的 sdk 字段 %q 不是合法版本号（写法：\"1.2.0\"）", declared)
|
||||
}
|
||||
|
||||
installed := listInstalledSDKs()
|
||||
for i := range installed {
|
||||
e := installed[i]
|
||||
emaj, emin, epat, _ := parseSDKVersion(e.Version)
|
||||
if emaj == maj && emin == min && epat == pat {
|
||||
return filepath.Join(sdkStore(), e.Dir), e.Version, nil
|
||||
}
|
||||
}
|
||||
|
||||
// 未命中：给出可执行的下一步
|
||||
var have []string
|
||||
for _, e := range installed {
|
||||
have = append(have, e.Version)
|
||||
}
|
||||
avail := "（存储里还没有任何 SDK）"
|
||||
if len(have) > 0 {
|
||||
avail = "已安装：" + strings.Join(have, ", ")
|
||||
}
|
||||
return "", "", fmt.Errorf(
|
||||
"项目声明 sdk=%s，但本地 SDK 存储里没有这个版本；%s\n"+
|
||||
" 安装：hmapdev sdk install v%s\n"+
|
||||
" 查看：hmapdev sdk list",
|
||||
declared, avail, declared)
|
||||
}
|
||||
@ -1,103 +0,0 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"os"
|
||||
"path/filepath"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// withSDKStore 把 SDK 存储指到临时目录（sdkStore 读 HOME），并造出给定版本目录。
|
||||
func withSDKStore(t *testing.T, versions ...string) {
|
||||
t.Helper()
|
||||
home := t.TempDir()
|
||||
t.Setenv("HOME", home)
|
||||
store := filepath.Join(home, ".homeagent", sdkDirName)
|
||||
if err := os.MkdirAll(store, 0755); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
for _, v := range versions {
|
||||
if err := os.MkdirAll(filepath.Join(store, v), 0755); err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 项目声明中版本 → 挑该接口线里最新的补丁；声明完整版本 → 精确命中。
|
||||
//
|
||||
// 为什么允许中版本是关键判据：patch 位只含工具链/打包修复（接口不变），
|
||||
// 让项目声明 "1.2" 而不是死钉 "1.2.0"，才能既跟得上工具链修复又不跨接口线。
|
||||
func TestResolveSDKForProject(t *testing.T) {
|
||||
t.Run("区间写法（1.2）被拒并说明版本纪律", func(t *testing.T) {
|
||||
// 判据：SDK 的 patch 位恒为 .0 → 一条内核线只有一个 SDK 版本，
|
||||
// 区间写法会让人误以为「同一条线里还能挑版本」，所以直接拒。
|
||||
withSDKStore(t, "1.2.0")
|
||||
_, _, err := ResolveSDKForProject("1.2")
|
||||
if err == nil {
|
||||
t.Fatal("1.2 这种区间写法应被拒绝")
|
||||
}
|
||||
for _, want := range []string{"完整版本号", "patch 位恒为 .0"} {
|
||||
if !strings.Contains(err.Error(), want) {
|
||||
t.Fatalf("拒绝理由里应说清规矩（缺少 %q）: %v", want, err)
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("完整版本精确命中", func(t *testing.T) {
|
||||
withSDKStore(t, "1.2.0", "1.3.0")
|
||||
_, ver, err := ResolveSDKForProject("1.2.0")
|
||||
if err != nil || ver != "1.2.0" {
|
||||
t.Fatalf("精确命中失败: ver=%s err=%v", ver, err)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("存储目录带 v 前缀也能命中", func(t *testing.T) {
|
||||
withSDKStore(t, "v1.2.0")
|
||||
dir, ver, err := ResolveSDKForProject("1.2.0")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if ver != "1.2.0" || !strings.HasSuffix(dir, "v1.2.0") {
|
||||
t.Fatalf("带 v 前缀的目录名未被识别: dir=%s ver=%s", dir, ver)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("未命中要给出可执行命令与已装清单", func(t *testing.T) {
|
||||
withSDKStore(t, "1.2.0")
|
||||
_, _, err := ResolveSDKForProject("2.0.0")
|
||||
if err == nil {
|
||||
t.Fatal("应报错")
|
||||
}
|
||||
msg := err.Error()
|
||||
for _, want := range []string{"sdk=2.0.0", "hmapdev sdk install", "hmapdev sdk list", "1.2.0"} {
|
||||
if !strings.Contains(msg, want) {
|
||||
t.Fatalf("错误信息缺少 %q（要可执行，不能只说 not found）:\n%s", want, msg)
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("空存储也能给出安装指引", func(t *testing.T) {
|
||||
withSDKStore(t)
|
||||
_, _, err := ResolveSDKForProject("1.2.0")
|
||||
if err == nil || !strings.Contains(err.Error(), "hmapdev sdk install v1.2.0") {
|
||||
t.Fatalf("空存储时应提示装哪个版本: %v", err)
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("非法声明直接拒绝", func(t *testing.T) {
|
||||
withSDKStore(t, "1.2.0")
|
||||
for _, bad := range []string{"abc", "1", "1.2", "1.2.3.4", "-1.2.0"} {
|
||||
if _, _, err := ResolveSDKForProject(bad); err == nil {
|
||||
t.Fatalf("非法版本 %q 应被拒绝（宁可报错也不许当通配符）", bad)
|
||||
}
|
||||
}
|
||||
})
|
||||
|
||||
t.Run("非版本目录不参与匹配", func(t *testing.T) {
|
||||
withSDKStore(t, "1.2.0", "backup-old", ".hidden", "current")
|
||||
_, ver, err := ResolveSDKForProject("1.2.0")
|
||||
if err != nil || ver != "1.2.0" {
|
||||
t.Fatalf("杂项目录不应干扰: ver=%s err=%v", ver, err)
|
||||
}
|
||||
})
|
||||
}
|
||||
@ -20,15 +20,6 @@ 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")
|
||||
@ -75,50 +66,10 @@ func cmdBuild(args []string) {
|
||||
}
|
||||
|
||||
if plg.IsLua() {
|
||||
// Lua 插件不经过 Go 编译，但也必须做两件与纪律相关的事：
|
||||
// 1) 记录「用哪版 SDK 语义写的」——否则新 API 在旧内核上只会静默缺失；
|
||||
// 2) 打包前做语法预检——否则语法错会被原样包进 .hmap，到内核加载时才暴露。
|
||||
if root := tryActiveSDKRoot(); root != "" {
|
||||
plg.ResolvedSDK = normalizeSDKVersion(readMetaVersion(root))
|
||||
}
|
||||
if err := checkLuaSyntax("main.lua"); err != nil {
|
||||
fmt.Printf(" error: %v\n", err)
|
||||
// 直接退出而非置 buildFailed：Lua 分支不进入后面的收尾统计，
|
||||
// 早期 return 会让调用方拿到 0 退出码。
|
||||
os.Exit(1)
|
||||
}
|
||||
buildTarget(plg, "lua", outDir, "")
|
||||
return
|
||||
}
|
||||
|
||||
// 项目可在 plg.json 里声明 sdk（中版本或完整版本，如 "1.2" / "1.2.1"）；
|
||||
// 显式 --sdk-path / plg.json 的 sdk_path 优先 —— 那是直指源码目录，
|
||||
// 常用于本机改 SDK 的联调场景。
|
||||
if sdkPath == "" && strings.TrimSpace(plg.SDK) != "" {
|
||||
dir, ver, err := ResolveSDKForProject(plg.SDK)
|
||||
if err != nil {
|
||||
fmt.Printf("error: %v\n", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
sdkPath, plg.ResolvedSDK = dir, ver
|
||||
fmt.Printf("[hmapdev] SDK %s（项目声明 sdk=%s）\n", ver, plg.SDK)
|
||||
} else if sdkPath != "" && plg.ResolvedSDK == "" {
|
||||
// 走的是显式路径：尽力记录它是哪版（读不到就不记，不因此失败）
|
||||
plg.ResolvedSDK = normalizeSDKVersion(readMetaVersion(sdkPath))
|
||||
}
|
||||
|
||||
// SDK 能力前置校验：proc 桥的模板（z_proc_gen.go）会透传 InjectOptions.Priority，
|
||||
// 而旧版 SDK 没有这个字段。不校验的话，用户看到的是 z_proc_gen.go 里两条
|
||||
// "opts.Priority undefined" 编译错误——错误信息指向生成物，完全看不出是 SDK 版本问题。
|
||||
if sdkPath != "" && !sdkHasInjectPriority(sdkPath) {
|
||||
fmt.Printf("error: 当前 SDK（%s）缺少 sdk.InjectOptions.Priority\n", plg.ResolvedSDK)
|
||||
fmt.Printf(" 子进程模式（proc 桥）的模板需要它来透传注入优先级 L1-L4。\n")
|
||||
fmt.Printf(" 解决办法（二选一）：\n")
|
||||
fmt.Printf(" 1) 升级 SDK：hmapdev sdk install <含该能力的版本> && hmapdev sdk use <版本>\n")
|
||||
fmt.Printf(" 2) 用本地 SDK 源码：hmapdev sdk install --from /path/to/homeagent-sdk\n")
|
||||
os.Exit(1)
|
||||
}
|
||||
|
||||
// Ensure go.mod exists with correct SDK path
|
||||
sdkModule := ensureGoMod(plg, sdkPath)
|
||||
|
||||
@ -141,18 +92,11 @@ func cmdBuild(args []string) {
|
||||
|
||||
if bundle || len(targets) == 0 {
|
||||
buildBundle(plg, outDir, sdkPath)
|
||||
} else {
|
||||
for _, t := range targets {
|
||||
buildTarget(plg, t, outDir, sdkPath)
|
||||
}
|
||||
return
|
||||
}
|
||||
|
||||
// 以非零码退出：调用方（批量重编、CI、发版脚本）靠退出码判成败。
|
||||
// 以前这里直接 return，失败也退 0，于是「构建失败」只能靠人翻日志发现——
|
||||
// 实测中就因此把一次部分失败当成了全绿。
|
||||
if buildFailed {
|
||||
fmt.Println("error: 至少一个目标构建失败（详见上面日志）")
|
||||
os.Exit(1)
|
||||
for _, t := range targets {
|
||||
buildTarget(plg, t, outDir, sdkPath)
|
||||
}
|
||||
}
|
||||
|
||||
@ -161,33 +105,13 @@ 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"},
|
||||
}
|
||||
|
||||
// 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
|
||||
{"windows/amd64", "plugin.bin.windows.amd64"},
|
||||
}
|
||||
|
||||
func buildBundle(plg *PlgConfig, outDir string, sdkPath string) {
|
||||
@ -198,7 +122,6 @@ 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()
|
||||
@ -209,15 +132,9 @@ 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
|
||||
}
|
||||
|
||||
@ -234,10 +151,7 @@ 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})
|
||||
@ -266,30 +180,6 @@ func buildBundle(plg *PlgConfig, outDir string, sdkPath string) {
|
||||
// 这是 entry 字段唯一仍在使用的用途：Go 插件不再看 entry 值，一律产出 plugin.bin。
|
||||
func (p *PlgConfig) IsLua() bool { return p.Entry == luaEntryFile }
|
||||
|
||||
// checkLuaSyntax 在打包前对 Lua 源码做语法预检。
|
||||
//
|
||||
// 为什么不只是“能做就做”：Lua 分支不经过编译器，语法错会被原样包进 .hmap，
|
||||
// 直到内核加载时才报错，且错误现场是内核日志而不是构建日志。
|
||||
// 有 luac 用 luac -p（只解析不执行）；只有 lua 时用 loadfile 同样只解析；
|
||||
// 两者都没有才降级为警告，不阻断构建（构建机可以没有 Lua 解释器）。
|
||||
func checkLuaSyntax(path string) error {
|
||||
if bin, err := exec.LookPath("luac"); err == nil {
|
||||
if out, err := exec.Command(bin, "-p", path).CombinedOutput(); err != nil {
|
||||
return fmt.Errorf("lua syntax check failed (%s): %s", path, strings.TrimSpace(string(out)))
|
||||
}
|
||||
return nil
|
||||
}
|
||||
if bin, err := exec.LookPath("lua"); err == nil {
|
||||
script := fmt.Sprintf("local f,e=loadfile(%q); if not f then io.stderr:write(e) os.exit(1) end", path)
|
||||
if out, err := exec.Command(bin, "-e", script).CombinedOutput(); err != nil {
|
||||
return fmt.Errorf("lua syntax check failed (%s): %s", path, strings.TrimSpace(string(out)))
|
||||
}
|
||||
return nil
|
||||
}
|
||||
fmt.Println(" note: lua/luac not found, skipping syntax check")
|
||||
return nil
|
||||
}
|
||||
|
||||
func readPlgJSON(path string) (*PlgConfig, error) {
|
||||
data, err := os.ReadFile(path)
|
||||
if err != nil {
|
||||
@ -333,10 +223,6 @@ func writePluginJSON(plg *PlgConfig, platforms []string, entry string) {
|
||||
if len(plg.Tags) > 0 {
|
||||
m["tags"] = plg.Tags
|
||||
}
|
||||
// 记录「用哪版 SDK 编的」：插件产物与内核协议绑定，出问题时这是第一个要看的字段。
|
||||
if plg.ResolvedSDK != "" {
|
||||
m["sdk"] = plg.ResolvedSDK
|
||||
}
|
||||
data, _ := json.MarshalIndent(m, "", " ")
|
||||
os.WriteFile("plugin.json", data, 0644)
|
||||
}
|
||||
@ -438,28 +324,7 @@ func ensureGoMod(plg *PlgConfig, sdkPath string) string {
|
||||
}
|
||||
keep = append(keep, line)
|
||||
}
|
||||
// 同步 require 版本：replace 指向 1.2.1 而 require 还写 1.2.0 是自相矛盾的
|
||||
// —— 有人删掉 replace 就会静默退回旧版本去编（`go list -m` 报的也是假版本）。
|
||||
// 以本次真正选中的版本为准改写 require 行。
|
||||
requireChanged := false
|
||||
if v := normalizeSDKVersion(plg.ResolvedSDK); v != "" {
|
||||
want := "require " + sdkModule + " v" + v
|
||||
for i, line := range keep {
|
||||
t := strings.TrimSpace(line)
|
||||
if !strings.HasPrefix(t, "require ") {
|
||||
continue
|
||||
}
|
||||
parts := strings.Fields(t)
|
||||
if len(parts) >= 3 && parts[1] == sdkModule {
|
||||
indent := line[:len(line)-len(strings.TrimLeft(line, " \t"))]
|
||||
if t != want {
|
||||
keep[i] = indent + want
|
||||
requireChanged = true
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
if alreadyExists && !requireChanged {
|
||||
if alreadyExists {
|
||||
return sdkModule
|
||||
}
|
||||
keep = append(keep, replaceLine, "")
|
||||
@ -530,8 +395,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(" hmapdev sdk install latest # 装一份到 ~/.homeagent/hmapdev/sdk\n")
|
||||
fmt.Printf(" hmapdev build --sdk-path <路径> # 或直接指定源码目录\n")
|
||||
fmt.Printf(" plugindev sdk install latest # 装一份到 ~/.homeagent/plugindev/sdk\n")
|
||||
fmt.Printf(" plugindev build --sdk-path <路径> # 或直接指定源码目录\n")
|
||||
}
|
||||
}
|
||||
|
||||
@ -546,12 +411,17 @@ func findLocalSDK(sdkPath string) string {
|
||||
candidates = append(candidates, abs)
|
||||
}
|
||||
}
|
||||
// hmapdev 自身所在位置往上三级（tools/hmapdev/hmapdev → SDK 根）
|
||||
// plugindev 自身所在位置往上三级（tools/plugindev/plugindev → SDK 根）
|
||||
if self, err := os.Executable(); err == nil {
|
||||
candidates = append(candidates, filepath.Dir(filepath.Dir(filepath.Dir(self))))
|
||||
}
|
||||
// hmapdev sdk use 选定的版本（复用 sdkStore()，含改名前的旧目录回退）
|
||||
store := sdkStore()
|
||||
// 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")
|
||||
}
|
||||
}
|
||||
if store != "" {
|
||||
if d, err := os.ReadFile(filepath.Join(store, "current")); err == nil {
|
||||
if ver := strings.TrimSpace(string(d)); ver != "" {
|
||||
@ -595,7 +465,7 @@ func resolveSDKPath(sdkPath string) string {
|
||||
fmt.Printf("error: --sdk-path %q not a valid SDK\n", sdkPath)
|
||||
os.Exit(1)
|
||||
}
|
||||
// Detect from hmapdev's own location (internal dev)
|
||||
// Detect from plugindev's own location (internal dev)
|
||||
self, err := os.Executable()
|
||||
if err == nil {
|
||||
cand := filepath.Dir(filepath.Dir(filepath.Dir(self)))
|
||||
@ -603,8 +473,14 @@ func resolveSDKPath(sdkPath string) string {
|
||||
return cand
|
||||
}
|
||||
}
|
||||
// Active SDK via hmapdev sdk use
|
||||
store := sdkStore()
|
||||
// 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")
|
||||
}
|
||||
}
|
||||
if store != "" {
|
||||
if d, err := os.ReadFile(filepath.Join(store, "current")); err == nil {
|
||||
ver := strings.TrimSpace(string(d))
|
||||
@ -616,7 +492,7 @@ func resolveSDKPath(sdkPath string) string {
|
||||
}
|
||||
}
|
||||
}
|
||||
fmt.Printf("error: cannot locate SDK. Use --sdk-path or 'hmapdev sdk use'\n")
|
||||
fmt.Printf("error: cannot locate SDK. Use --sdk-path or 'plugindev sdk use'\n")
|
||||
os.Exit(1)
|
||||
return ""
|
||||
}
|
||||
@ -668,13 +544,6 @@ 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()
|
||||
@ -693,7 +562,6 @@ 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
|
||||
}
|
||||
|
||||
@ -917,22 +785,3 @@ func linkThirdpart(plg *PlgConfig, target string) func() {
|
||||
os.Remove(importFile)
|
||||
}
|
||||
}
|
||||
|
||||
// sdkHasInjectPriority 报告该 SDK 源码是否已具备 InjectOptions.Priority
|
||||
// （proc 桥透传注入优先级所必需的能力；SDK 开发期与已发布版本可能不一致）。
|
||||
func sdkHasInjectPriority(sdkPath string) bool {
|
||||
data, err := os.ReadFile(filepath.Join(sdkPath, "sdk", "plugin.go"))
|
||||
if err != nil {
|
||||
return true // 读不到就不拦（不在校验范围内）
|
||||
}
|
||||
src := string(data)
|
||||
i := strings.Index(src, "type InjectOptions struct")
|
||||
if i < 0 {
|
||||
return true
|
||||
}
|
||||
seg := src[i:]
|
||||
if j := strings.Index(seg, "\n}"); j > 0 {
|
||||
seg = seg[:j]
|
||||
}
|
||||
return strings.Contains(seg, "Priority")
|
||||
}
|
||||
@ -7,20 +7,13 @@ import (
|
||||
"path/filepath"
|
||||
"strings"
|
||||
|
||||
"gitcode.com/JianFeeeee/homeagent-sdk/tools/hmapdev/yaegi"
|
||||
"github.com/JianFeeeee/homeagent-sdk/tools/plugindev/yaegi"
|
||||
)
|
||||
|
||||
// tmplLuaDebug is the temporary Lua debug script template
|
||||
const tmplLuaDebug = `-- HomeAgent Lua Plugin Debug
|
||||
-- Generated by hmapdev debug --lua
|
||||
-- sdk.lua 优先用激活 SDK 的权威 mock（HMAPDEV_SDK_LUA），否则回退项目内副本，
|
||||
-- 避免拿一份过期的 sdk.lua 调试出“本地能跑、内核报 nil”的假象。
|
||||
local sdk_path = os.getenv("HMAPDEV_SDK_LUA")
|
||||
if sdk_path and sdk_path ~= "" then
|
||||
sdk = dofile(sdk_path)
|
||||
else
|
||||
sdk = require("sdk")
|
||||
end
|
||||
-- Generated by plugindev debug --lua
|
||||
sdk = require("sdk")
|
||||
local ok, plugin = pcall(dofile, "main.lua")
|
||||
if not ok then
|
||||
print("[debug] ERROR loading main.lua: " .. tostring(plugin))
|
||||
@ -122,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 hmapdev build to compile your plugin")
|
||||
fmt.Println(" install Lua 5.1+ or use plugindev build to compile your plugin")
|
||||
os.Exit(1)
|
||||
}
|
||||
|
||||
@ -134,16 +127,6 @@ func debugLua(dir, sdkPath, luaPath string) {
|
||||
fmt.Println("warning: sdk.lua not found, debug SDK mock will not be available")
|
||||
}
|
||||
|
||||
// 优先用激活 SDK 里的权威 mock，避免调试用的是项目里可能过期的副本。
|
||||
env := os.Environ()
|
||||
if root := tryActiveSDKRoot(); root != "" {
|
||||
canonical := filepath.Join(root, "sdk", "lua", "sdk.lua")
|
||||
if _, err := os.Stat(canonical); err == nil {
|
||||
env = append(env, "HMAPDEV_SDK_LUA="+canonical)
|
||||
fmt.Printf("[debug] SDK mock: %s\n", canonical)
|
||||
}
|
||||
}
|
||||
|
||||
// write temporary debug script
|
||||
debugScript := filepath.Join(dir, "_debug.lua")
|
||||
if err := os.WriteFile(debugScript, []byte(tmplLuaDebug), 0644); err != nil {
|
||||
@ -154,7 +137,6 @@ func debugLua(dir, sdkPath, luaPath string) {
|
||||
|
||||
cmd := exec.Command(luaBin, filepath.Base(debugScript))
|
||||
cmd.Dir = dir
|
||||
cmd.Env = env
|
||||
cmd.Stdin = os.Stdin
|
||||
cmd.Stdout = os.Stdout
|
||||
cmd.Stderr = os.Stderr
|
||||
@ -34,18 +34,6 @@ type PlgConfig struct {
|
||||
GoVersion string `json:"go_version,omitempty"`
|
||||
Replaces map[string]string `json:"replaces,omitempty"`
|
||||
SourceDirs []string `json:"source_dirs,omitempty"`
|
||||
|
||||
// SDK 声明本插件针对的 SDK **接口版本**（中版本或完整版本，如 "1.2" / "1.2.1"）。
|
||||
//
|
||||
// 为何需要：工具链存储里可能装有多个 SDK 版本，而插件产物与内核是协议绑定的——
|
||||
// 不给声明就只能猜（旧行为是直接用 current：谁改过 current 就拿谁的版本编，
|
||||
// 出错时表现为莫名其妙的编译错误）。写中版本表示「只要 1.2 这条接口线，
|
||||
// 补丁由工具链挑最新」（patch 只含工具链/打包修复，接口不变，见 README 版本语义）。
|
||||
SDK string `json:"sdk,omitempty"`
|
||||
|
||||
// ResolvedSDK 是本次构建实际选中的 SDK 版本（build 按 SDK 声明解析后回填），
|
||||
// 只写进产物里的 plugin.json，便于事后追溯「这个 .hmap 是哪版 SDK 编的」。
|
||||
ResolvedSDK string `json:"-"`
|
||||
}
|
||||
|
||||
// TargetList parses the Targets string into a slice.
|
||||
@ -75,7 +63,7 @@ type TemplateData struct {
|
||||
// SDKLocalPath 是本机 SDK 源码绝对路径，写入生成的 go.mod 作为 replace 目标。
|
||||
//
|
||||
// 为何必须写：gitcode 的模块不在 proxy.golang.org 上，只 require 一个
|
||||
// 版本号的 go.mod 配上缺失的 go.sum，新用户第一次 `hmapdev build`
|
||||
// 版本号的 go.mod 配上缺失的 go.sum，新用户第一次 `plugindev build`
|
||||
// 必定死在 "missing go.sum entry"，而 `go mod tidy` 又会去公共 proxy 拉
|
||||
// 一个不存在的条目。有了本地 replace，go 完全不需要 go.sum 条目。
|
||||
SDKLocalPath string
|
||||
@ -83,7 +71,7 @@ type TemplateData struct {
|
||||
|
||||
func cmdInit(args []string) {
|
||||
if len(args) < 1 {
|
||||
fmt.Println("Usage: hmapdev init <name> [--lua] [--type remotedevice]")
|
||||
fmt.Println("Usage: plugindev init <name> [--lua] [--type remotedevice]")
|
||||
os.Exit(1)
|
||||
}
|
||||
|
||||
@ -164,22 +152,13 @@ func cmdInit(args []string) {
|
||||
// Detect SDK info for Go plugin go.mod.
|
||||
// 生成的 go.mod 除 require 外还写一条指向本机 SDK 的 replace：
|
||||
// 否则 scaffold 出来的项目第一次 build 必定失败（详见 SDKLocalPath 注释）。
|
||||
if isLua {
|
||||
// Lua 插件也要记录它按哪版 SDK 语义编写：Lua `sdk.*` 是公开契约，
|
||||
// 与内核能力版本挂钩；不写版本就只能靠“调用时才发现是 nil”。
|
||||
if root := tryActiveSDKRoot(); root != "" {
|
||||
data.Plg.SDK = normalizeSDKVersion(readMetaVersion(root))
|
||||
}
|
||||
} else {
|
||||
if !isLua {
|
||||
sdkMod, goVer, sdkRoot, sdkVer := detectSDKInfo()
|
||||
data.ModulePath = name
|
||||
data.GoVersion = goVer
|
||||
data.SDKModule = sdkMod
|
||||
data.SDKVersion = "v" + sdkVer
|
||||
data.SDKLocalPath = strings.ReplaceAll(sdkRoot, "\\", "/")
|
||||
// 声明**完整版本号**：SDK 版本跟随内核中版本、patch 位恒为 .0，
|
||||
// 一条内核线只对应一个 SDK 版本（build 时按此解析，见 ResolveSDKForProject）。
|
||||
data.Plg.SDK = normalizeSDKVersion(sdkVer)
|
||||
}
|
||||
|
||||
if err := os.MkdirAll(dir, 0755); err != nil {
|
||||
@ -193,14 +172,7 @@ func cmdInit(args []string) {
|
||||
// Lua plugins get main.lua + sdk.lua; Go plugins get plugin.go only
|
||||
if isLua {
|
||||
writeTemplate(filepath.Join(dir, "main.lua"), tmplMainLua, data)
|
||||
// sdk.lua 是给 `lua main.lua` 离线测试用的 mock，单一事实源在 SDK 仓的
|
||||
// sdk/lua/sdk.lua；优先从当前激活的 SDK 拷，拷不到才回退内嵌模板。
|
||||
if !copyCanonicalLuaSDK(dir) {
|
||||
if err := os.WriteFile(filepath.Join(dir, "sdk.lua"), []byte(fallbackLuaSDK), 0644); err != nil {
|
||||
fmt.Printf("error: write sdk.lua: %v\n", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
}
|
||||
writeTemplate(filepath.Join(dir, "sdk.lua"), tmplSDKLua, data)
|
||||
} else {
|
||||
writeTemplate(filepath.Join(dir, "plugin.go"), tmplPluginGo, data)
|
||||
}
|
||||
@ -220,44 +192,7 @@ func cmdInit(args []string) {
|
||||
if isLua {
|
||||
fmt.Printf(" cd %s && lua main.lua (standalone test)\n", dir)
|
||||
}
|
||||
fmt.Printf(" cd %s && hmapdev build\n", dir)
|
||||
}
|
||||
|
||||
// activeSDKRoot 返回当前激活 SDK 的根目录，未安装/未激活则报错退出。
|
||||
//
|
||||
// 与 activeSDKRoot（fatal 版）区别：这里只探测，不退出。
|
||||
// Lua 插件的 mock 是“锦上添花”，没装 SDK 不应该阻断 init。
|
||||
func tryActiveSDKRoot() string {
|
||||
store := sdkStore()
|
||||
current := resolveCurrentVersion(store)
|
||||
if current == "" {
|
||||
return ""
|
||||
}
|
||||
root := sdkVersionDir(current)
|
||||
if _, err := os.Stat(root); err != nil {
|
||||
return ""
|
||||
}
|
||||
return root
|
||||
}
|
||||
|
||||
// copyCanonicalLuaSDK 把激活 SDK 的 sdk/lua/sdk.lua 拷进新项目。
|
||||
// 三份 sdk.lua（内核内嵌 / 工具链模板 / 项目副本）各自漂移是本工具链的历史债，
|
||||
// 单一事实源在 SDK 仓，工具链只负责搬运。返回是否成功。
|
||||
func copyCanonicalLuaSDK(dir string) bool {
|
||||
root := tryActiveSDKRoot()
|
||||
if root == "" {
|
||||
return false
|
||||
}
|
||||
src := filepath.Join(root, "sdk", "lua", "sdk.lua")
|
||||
data, err := os.ReadFile(src)
|
||||
if err != nil {
|
||||
return false
|
||||
}
|
||||
if err := os.WriteFile(filepath.Join(dir, "sdk.lua"), data, 0644); err != nil {
|
||||
return false
|
||||
}
|
||||
fmt.Printf(" sdk.lua <- %s\n", src)
|
||||
return true
|
||||
fmt.Printf(" cd %s && plugindev build\n", dir)
|
||||
}
|
||||
|
||||
// detectSDKInfo reads the HomeAgent SDK's go.mod and meta to get module path, go version, and SDK version.
|
||||
@ -14,12 +14,7 @@ import (
|
||||
"time"
|
||||
)
|
||||
|
||||
const sdkDirName = "hmapdev/sdk"
|
||||
|
||||
// legacySDKDirName 是改名前的存储目录。工具链在 1.2.0 从 plugindev 改名 hmapdev；
|
||||
// 已装过旧版的机器上 SDK 仍在旧路径，直接换名会让它找不到已装 SDK
|
||||
// （表现为「没有活动版本」）。新目录不存在而旧目录存在时沿用旧目录。
|
||||
const legacySDKDirName = "plugindev/sdk"
|
||||
const sdkDirName = "plugindev/sdk"
|
||||
|
||||
// sdkStore returns the root directory for stored SDK versions.
|
||||
func sdkStore() string {
|
||||
@ -31,15 +26,7 @@ func sdkStore() string {
|
||||
fmt.Printf("error: cannot determine home directory: %v\n", err)
|
||||
os.Exit(1)
|
||||
}
|
||||
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
|
||||
return filepath.Join(home, ".homeagent", sdkDirName)
|
||||
}
|
||||
|
||||
func sdkCurrentDir() string {
|
||||
@ -58,39 +45,18 @@ func cmdSDK(args []string) {
|
||||
sdkHelp()
|
||||
return
|
||||
}
|
||||
// install --from <本地目录> [version]：用本地 SDK 源码装一个版本并激活。
|
||||
if args[0] == "install" {
|
||||
from := ""
|
||||
rest := []string{}
|
||||
for i := 1; i < len(args); i++ {
|
||||
if args[i] == "--from" && i+1 < len(args) {
|
||||
from = args[i+1]
|
||||
i++
|
||||
continue
|
||||
}
|
||||
rest = append(rest, args[i])
|
||||
}
|
||||
if from != "" {
|
||||
version := ""
|
||||
if len(rest) > 0 && rest[0] != "latest" {
|
||||
version = rest[0]
|
||||
}
|
||||
cmdSDKInstallFromDir(from, version)
|
||||
return
|
||||
}
|
||||
}
|
||||
switch args[0] {
|
||||
case "list":
|
||||
cmdSDKList()
|
||||
case "install":
|
||||
if len(args) < 2 {
|
||||
fmt.Println("Usage: hmapdev sdk install <version>")
|
||||
fmt.Println("Usage: plugindev sdk install <version>")
|
||||
os.Exit(1)
|
||||
}
|
||||
cmdSDKInstall(args[1])
|
||||
case "use":
|
||||
if len(args) < 2 {
|
||||
fmt.Println("Usage: hmapdev sdk use <version>")
|
||||
fmt.Println("Usage: plugindev sdk use <version>")
|
||||
os.Exit(1)
|
||||
}
|
||||
cmdSDKUse(args[1])
|
||||
@ -106,7 +72,7 @@ func cmdSDK(args []string) {
|
||||
}
|
||||
|
||||
func sdkHelp() {
|
||||
fmt.Print(`Usage: hmapdev sdk <command>
|
||||
fmt.Print(`Usage: plugindev sdk <command>
|
||||
|
||||
Manage installed HomeAgent SDK versions.
|
||||
|
||||
@ -119,10 +85,9 @@ Commands:
|
||||
latest Show the latest available version from remote
|
||||
|
||||
Examples:
|
||||
hmapdev sdk install v0.7.1
|
||||
hmapdev sdk install latest
|
||||
hmapdev sdk install v0.7.1
|
||||
hmapdev sdk install --from /path/to/homeagent-sdk # 用本地源码（SDK 开发时用）sdk use v0.7.1
|
||||
plugindev sdk install v0.7.1
|
||||
plugindev sdk install latest
|
||||
plugindev sdk use v0.7.1
|
||||
`)
|
||||
}
|
||||
|
||||
@ -162,55 +127,10 @@ func cmdSDKList() {
|
||||
fmt.Printf(" %s %s\n", mark, v)
|
||||
}
|
||||
if current == "" {
|
||||
fmt.Println("\nNo version active. Use 'hmapdev sdk use <version>' to set one.")
|
||||
fmt.Println("\nNo version active. Use 'plugindev sdk use <version>' to set one.")
|
||||
}
|
||||
}
|
||||
|
||||
// cmdSDKInstallFromDir 从**本地 SDK 源码目录**安装一个版本。
|
||||
//
|
||||
// 为什么需要它：`install` 只能从 Release 归档下载，而 SDK 开发时的新能力
|
||||
// （例如 `InjectOptions.Priority` 这类 proc 桥要透传的字段）往往还没发版 ——
|
||||
// 此时生成出来的插件工程会因为"引用的 SDK 还没有该字段"直接编译失败。
|
||||
// 有 --from 才能"用本地源码当这个版本的 SDK"，边改 SDK 边验证模板工程。
|
||||
func cmdSDKInstallFromDir(src, version string) {
|
||||
store := sdkStore()
|
||||
if err := os.MkdirAll(store, 0755); err != nil {
|
||||
fmt.Printf("error: create SDK store %s: %v\n", store, err)
|
||||
os.Exit(1)
|
||||
}
|
||||
if version == "" {
|
||||
version = readMetaVersion(src)
|
||||
}
|
||||
if version == "" {
|
||||
fmt.Printf("error: cannot determine version from %s/meta/meta.go\n", src)
|
||||
os.Exit(1)
|
||||
}
|
||||
if !strings.HasPrefix(version, "v") {
|
||||
version = "v" + version
|
||||
}
|
||||
if _, err := os.Stat(filepath.Join(src, "go.mod")); err != nil {
|
||||
fmt.Printf("error: %s 看起来不是 SDK 源码目录（缺 go.mod）\n", src)
|
||||
os.Exit(1)
|
||||
}
|
||||
dest := sdkVersionDir(version)
|
||||
_ = os.RemoveAll(dest)
|
||||
if err := copyDir(src, dest); err != nil {
|
||||
fmt.Printf("error: copy %s -> %s: %v\n", src, dest, err)
|
||||
os.Exit(1)
|
||||
}
|
||||
// 源码目录里的开发产物不该带进 store。
|
||||
for _, junk := range []string{".git", "dist", "build"} {
|
||||
_ = os.RemoveAll(filepath.Join(dest, junk))
|
||||
}
|
||||
fmt.Printf("Installed SDK %s from %s\n", version, src)
|
||||
fmt.Printf(" %s\n", dest)
|
||||
if err := os.WriteFile(filepath.Join(store, "current"), []byte(version), 0644); err != nil {
|
||||
fmt.Printf("error: activate %s: %v\n", version, err)
|
||||
os.Exit(1)
|
||||
}
|
||||
fmt.Printf("Activated SDK %s\n", version)
|
||||
}
|
||||
|
||||
// cmdSDKInstall downloads and installs an SDK version from Release archive.
|
||||
func cmdSDKInstall(version string) {
|
||||
store := sdkStore()
|
||||
@ -372,7 +292,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: hmapdev sdk install %s\n", version)
|
||||
fmt.Printf("Install it first: plugindev sdk install %s\n", version)
|
||||
os.Exit(1)
|
||||
}
|
||||
setCurrentVersion(store, version)
|
||||
@ -385,7 +305,7 @@ func cmdSDKPath() {
|
||||
current := resolveCurrentVersion(store)
|
||||
if current == "" {
|
||||
fmt.Println("No active SDK version set.")
|
||||
fmt.Println("Use 'hmapdev sdk use <version>' to set one.")
|
||||
fmt.Println("Use 'plugindev sdk use <version>' to set one.")
|
||||
os.Exit(1)
|
||||
}
|
||||
fmt.Println(sdkVersionDir(current))
|
||||
@ -520,21 +440,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 hmapdev can work
|
||||
// It replaces the old runtime.Caller(0) approach so plugindev 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: hmapdev sdk install latest\n")
|
||||
fmt.Printf(" Or set one: hmapdev sdk use <version>\n")
|
||||
fmt.Printf(" Install one: plugindev sdk install latest\n")
|
||||
fmt.Printf(" Or set one: plugindev 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: hmapdev sdk install %s\n", current)
|
||||
fmt.Printf(" Reinstall: plugindev sdk install %s\n", current)
|
||||
os.Exit(1)
|
||||
}
|
||||
return root
|
||||
@ -587,3 +507,5 @@ func readMetaVersion(sdkRoot string) string {
|
||||
}
|
||||
return "0.0.0"
|
||||
}
|
||||
|
||||
|
||||
@ -1,4 +1,4 @@
|
||||
module gitcode.com/JianFeeeee/homeagent-sdk/tools/hmapdev
|
||||
module github.com/JianFeeeee/homeagent-sdk/tools/plugindev
|
||||
|
||||
go 1.21.0
|
||||
|
||||
49
tools/plugindev/main.go
Normal file
49
tools/plugindev/main.go
Normal file
@ -0,0 +1,49 @@
|
||||
package main
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"os"
|
||||
)
|
||||
|
||||
func main() {
|
||||
if len(os.Args) < 2 {
|
||||
help()
|
||||
return
|
||||
}
|
||||
switch os.Args[1] {
|
||||
case "init":
|
||||
cmdInit(os.Args[2:])
|
||||
case "build":
|
||||
cmdBuild(os.Args[2:])
|
||||
case "clean":
|
||||
cmdClean(os.Args[2:])
|
||||
case "debug":
|
||||
cmdDebug(os.Args[2:])
|
||||
case "sdk":
|
||||
cmdSDK(os.Args[2:])
|
||||
default:
|
||||
help()
|
||||
}
|
||||
}
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
Flags:
|
||||
--outdir Output directory (default: dist)
|
||||
--target Target OS/arch (e.g. linux/amd64), repeatable
|
||||
--lua Create Lua plugin (for init)
|
||||
--type Project type: "remotedevice" (for init)
|
||||
-t Alias for --type
|
||||
`)
|
||||
}
|
||||
@ -56,7 +56,7 @@ const procGenFile = "z_proc_gen.go"
|
||||
// generateProcRuntime 把子进程运行时（平台无关主体 + 两个平台挂载实现）
|
||||
// 写入插件目录，返回清理函数。
|
||||
func generateProcRuntime() (func(), error) {
|
||||
// 清理历史 C ABI 产物：旧版 hmapdev（原名 plugindev）生成过这两个文件，残留下来会与
|
||||
// 清理历史 C ABI 产物：旧版 plugindev 生成过这两个文件，残留下来会与
|
||||
// 本模板的 main 冲突。无需人工清理就能从旧版升级。
|
||||
for _, stale := range []string{"z_bridge_gen.go", "z_entry.c"} {
|
||||
os.Remove(stale)
|
||||
@ -92,9 +92,8 @@ func TestProcTemplate_CoversAllCoreMethods(t *testing.T) {
|
||||
required := []string{
|
||||
// 注册面
|
||||
"tool.register", "stage.register", "output.register", "api.register", "input.register",
|
||||
// IO 注入（io.injectTextNoMem 见下方 deprecated：内核保留为兼容旧二进制，
|
||||
// 当前模板改走 io.injectText + NoMemory 标志位，不再发那个 id）
|
||||
"io.injectText", "io.injectInterrupt", "io.injectInputSync",
|
||||
// IO 注入
|
||||
"io.injectText", "io.injectInterrupt", "io.injectTextNoMem", "io.injectInputSync",
|
||||
"io.setToolBlocks",
|
||||
// 多模态注入（1.1.0 新增）。漏接线的后果是插件调 InjectInputMedia 静默无效果：
|
||||
// 模板不发这个 RPC，内核也就永远收不到，而两边都不报错。
|
||||
@ -132,37 +131,15 @@ 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)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// 模板必须处理内核发来的全部调用（含无法 JSON 序列化的 Cleaner 回调）。
|
||||
// 模板必须处理内核发来的全部 7 个调用（原 C ABI 的 7 个 //export）。
|
||||
func TestProcTemplate_HandlesAllKernelCalls(t *testing.T) {
|
||||
src := loadProcTemplate(t)
|
||||
for _, m := range []string{
|
||||
"handshake",
|
||||
"plugin.init", "plugin.start", "plugin.stop",
|
||||
"tool.invoke", "cleaner.invoke", "stage.invoke", "output.invoke",
|
||||
"tool.invoke", "stage.invoke", "output.invoke",
|
||||
} {
|
||||
if !strings.Contains(src, `case "`+m+`"`) {
|
||||
t.Errorf("模板未处理内核调用 %q", m)
|
||||
@ -170,45 +147,6 @@ 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 一致。
|
||||
//
|
||||
// 字段索引错位是最危险的漂移：插件会读到相邻字段的数据，
|
||||
@ -343,11 +281,10 @@ func TestProcTemplate_DispatchesRequestsConcurrently(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
// 协议与共享内存区域版本/魔数不匹配必须拒绝，不得半兼容运行。
|
||||
// 协议与共享段版本不匹配必须拒绝，不得半兼容运行。
|
||||
func TestProcTemplate_RejectsVersionMismatch(t *testing.T) {
|
||||
src := loadProcTemplate(t)
|
||||
// §13.1 起共享段合并为单一「统一区域」，魔数校验文案随之更新。
|
||||
for _, want := range []string{"协议版本不匹配", "共享段版本不匹配", "统一区域魔数不匹配"} {
|
||||
for _, want := range []string{"协议版本不匹配", "共享段版本不匹配", "共享段魔数不匹配"} {
|
||||
if !strings.Contains(src, want) {
|
||||
t.Errorf("握手应校验并拒绝 %q", want)
|
||||
}
|
||||
@ -1,7 +1,5 @@
|
||||
package main
|
||||
|
||||
import _ "embed"
|
||||
|
||||
// tmplPlgJSON is the plg.json template
|
||||
const tmplPlgJSON = `{
|
||||
"name": "{{.Plg.Name}}",
|
||||
@ -11,7 +9,6 @@ const tmplPlgJSON = `{
|
||||
"description": "{{.Plg.Description}}",
|
||||
"author": "{{.Plg.Author}}",
|
||||
"entry": "{{.Plg.Entry}}",
|
||||
"sdk": "{{.Plg.SDK}}",
|
||||
"tags": [{{range $i, $t := .Plg.Tags}}{{if $i}}, {{end}}"{{$t}}"{{end}}],
|
||||
"targets": "{{.Plg.Targets}}"
|
||||
}
|
||||
@ -51,22 +48,6 @@ func (p *Plugin) Start(s *sdk.PluginSDK) error {
|
||||
DisplayName: "示例配置", Description: "An example configuration key",
|
||||
Category: "{{.Plg.Name}}",
|
||||
})
|
||||
// ---- 通道（channel）：两个方向是分开的两件事 ----
|
||||
//
|
||||
// 入站 inputch ——「谁会往这个通道注入输入」。
|
||||
// 凡是用 s.InjectText*/InjectInput*/InjectInterrupt*(source, "<name>", ...) 注入的通道名，
|
||||
// 都要在这里登记：inputch 是内核最基本的**输入路由单位**，只有登记过的通道
|
||||
// 才能被「划给驻留子（resident sub-agent）」；没登记就划分会失败（inputch 未注册）。
|
||||
// 只登记出站通道时内核会兜底登记同名 inputch **并打告警**（兼容老插件）。
|
||||
chName := p.name
|
||||
_ = s.RegisterInputChannel(chName, sdk.ChannelDef{NoMemory: true})
|
||||
// 出站 output ——「output_send__<name> 的回复发给谁」。
|
||||
// handler 收到 map：payload(string) / type(string) / meta(string|optional)。
|
||||
_ = s.RegisterOutputChannel(chName, sdk.CapText, "示例通道（回复由此返回）",
|
||||
sdk.ChannelDef{NoMemory: true}, func(args map[string]interface{}) (interface{}, error) {
|
||||
return map[string]interface{}{"status": "ok"}, nil
|
||||
})
|
||||
|
||||
tp := p.name + "_"
|
||||
s.RegisterTool(tp+"hello", sdk.ToolDef{
|
||||
Name: tp + "hello",
|
||||
@ -93,28 +74,79 @@ func NewPluginFactory(name string, config map[string]interface{}) (sdk.Plugin, e
|
||||
}
|
||||
`
|
||||
|
||||
// fallbackLuaSDK 是 sdk.lua 的内嵌回退副本（单一事实源为 SDK 仓 sdk/lua/sdk.lua）。
|
||||
//
|
||||
// 为什么不再内联一份手写 mock：三份 sdk.lua（内核内嵌 / 工具链模板 / 项目副本）
|
||||
// 各自漂移过一次，结果就是“mock 有、内核没有”或反过来。改为从 assets/sdk.lua
|
||||
// 内嵌 + 由 SDK 仓同步脚本搬运，并配契约测试守住。
|
||||
//
|
||||
//go:embed assets/sdk.lua
|
||||
var fallbackLuaSDK string
|
||||
const tmplSDKLua = `-- HomeAgent Lua Plugin SDK (standalone mock)
|
||||
sdk = {}
|
||||
function sdk.log(level, msg) print("[lua-plugin] " .. tostring(level) .. ": " .. tostring(msg)) end
|
||||
function sdk.register_tool(name, def, handler) print("[lua-plugin] register_tool: " .. tostring(name)) end
|
||||
function sdk.register_stage(stage, handler, scope) print("[lua-plugin] register_stage: " .. tostring(stage) .. " scope=" .. tostring(scope)) end
|
||||
function sdk.register_api(name) print("[lua-plugin] register_api: " .. tostring(name)) end
|
||||
function sdk.register_output_channel(name, caps, desc, def, handler) print("[lua-plugin] register_output_channel: " .. tostring(name)) end
|
||||
function sdk.register_input_channel(name, def) print("[lua-plugin] register_input_channel: " .. tostring(name)) end
|
||||
function sdk.get_setting(key) return nil end
|
||||
function sdk.set_setting(key, value) print("[lua-plugin] set_setting: " .. tostring(key)) end
|
||||
function sdk.inject_text(source, channel, text) print("[lua-plugin] inject_text: " .. tostring(source)) end
|
||||
function sdk.inject_interrupt(source, channel, text) print("[lua-plugin] inject_interrupt: " .. tostring(source)) end
|
||||
function sdk.inject_text_no_memory(source, channel, text) print("[lua-plugin] inject_text_no_memory: " .. tostring(source)) end
|
||||
function sdk.set_auto_restart(enabled) print("[lua-plugin] set_auto_restart: " .. tostring(enabled)) end
|
||||
sdk.memory = {}
|
||||
function sdk.memory.recall(query, depth) return {entities={}, relations={}} end
|
||||
function sdk.memory.commit(triples) return nil end
|
||||
function sdk.memory.introspect() return {} end
|
||||
function sdk.memory.merge(source, target) return 0 end
|
||||
function sdk.memory.purge(criteria, hard) return 0 end
|
||||
sdk.doc = {}
|
||||
function sdk.doc.query(text, top_k) return {} end
|
||||
function sdk.doc.insert(doc) return nil end
|
||||
function sdk.doc.remove(id) return nil end
|
||||
function sdk.doc.stats() return {} end
|
||||
sdk.knowledge = {}
|
||||
function sdk.knowledge.search(query, limit) return {} end
|
||||
function sdk.knowledge.add(tag, content) return nil end
|
||||
function sdk.knowledge.list() return {} end
|
||||
sdk.text_memory = {}
|
||||
function sdk.text_memory.append(evt) return nil end
|
||||
sdk.llm = {}
|
||||
function sdk.llm.list_sources() return {} end
|
||||
function sdk.llm.set_source(name) return nil end
|
||||
function sdk.llm.current_source() return nil end
|
||||
sdk.social = {}
|
||||
function sdk.social.get_person(name) return {} end
|
||||
function sdk.social.get_network(name, depth) return {} end
|
||||
function sdk.social.get_trait(name, trait) return {value=nil, found=false} end
|
||||
function sdk.social.get_relations(name) return {} end
|
||||
function sdk.social.list_persons() return {} end
|
||||
sdk.settings = {}
|
||||
function sdk.settings.get_core(key) return nil end
|
||||
function sdk.settings.set_core(key, value) return nil end
|
||||
function sdk.settings.list_core(prefix) return {} end
|
||||
function sdk.settings.get_plugin(plugin, key) return nil end
|
||||
function sdk.settings.set_plugin(plugin, key, value) return nil end
|
||||
function sdk.settings.list_plugin(plugin, prefix) return {} end
|
||||
function sdk.settings.list(prefix) return {} end
|
||||
function sdk.settings.register_def(def) return nil end
|
||||
function sdk.settings.defs(prefix) return {} end
|
||||
function sdk.settings.dump() return {} end
|
||||
function sdk.settings.plugins() return {} end
|
||||
sdk.json = {}
|
||||
function sdk.json.encode(val)
|
||||
if type(val) == "string" then return '"' .. val:gsub('"', '\\"'):gsub('\n', '\\n') .. '"'
|
||||
elseif type(val) == "number" or type(val) == "boolean" then return tostring(val)
|
||||
elseif type(val) == "table" then local parts, i = {}, 1
|
||||
for k, v in pairs(val) do parts[i] = sdk.json.encode(k) .. ":" .. sdk.json.encode(v); i = i + 1 end
|
||||
return "{" .. table.concat(parts, ",") .. "}" end
|
||||
return "null"
|
||||
end
|
||||
function sdk.json.decode(str) local ok, fn = pcall(load, "return " .. str); if ok then return fn() end; return nil end
|
||||
sdk.http = {}
|
||||
function sdk.http.get(url) print("[lua-plugin] http.get: " .. tostring(url)); return {status=200, body='{"mock":true}', headers={}} end
|
||||
function sdk.http.post(url, body, ct) print("[lua-plugin] http.post: " .. tostring(url)); return {status=200, body='{"mock":true}', headers={}} end
|
||||
return sdk
|
||||
`
|
||||
|
||||
const tmplMainLua = `-- {{.Plg.Name}} plugin
|
||||
local plugin = { name = "{{.Plg.Name}}" }
|
||||
function plugin.start(sdk)
|
||||
sdk.log("info", "{{.Plg.Name}} starting...")
|
||||
|
||||
-- 通道：入站与出站分开登记。
|
||||
-- 入站 inputch：凡是用 sdk.inject_text/sdk.inject_interrupt(source, "<name>", ...) 注入的通道名
|
||||
-- 都要登记；只有登记过的通道才能被「划给驻留子」（没登记会报 inputch 未注册）。
|
||||
sdk.register_input_channel("{{.Plg.Name}}", { no_memory = true })
|
||||
-- 出站 output：output_send__<name> 的回复由 handler 处理
|
||||
sdk.register_output_channel("{{.Plg.Name}}", 1, "示例通道（回复由此返回）", { no_memory = true },
|
||||
function(args) return { status = "ok" } end)
|
||||
|
||||
sdk.register_tool("{{.Plg.Name}}_hello", {
|
||||
description = "A hello world tool",
|
||||
parameters = { type = "object", properties = {} }
|
||||
@ -479,24 +511,9 @@ const tmplReadme = `# {{.Plg.Name}}
|
||||
## Build
|
||||
|
||||
` + "```bash" + `
|
||||
hmapdev build
|
||||
plugindev build
|
||||
` + "```" + `
|
||||
|
||||
## Channels
|
||||
|
||||
入站与出站是分开登记的两件事：
|
||||
|
||||
| 方向 | API | 用途 |
|
||||
|---|---|---|
|
||||
| 入站 inputch | RegisterInputChannel(name, def) | 声明「谁会往这个通道注入输入」。**凡是用 InjectText*/InjectInput*/InjectInterrupt*(source, "<name>", ...) 注入的通道名都要登记** |
|
||||
| 出站 output | RegisterOutputChannel(name, caps, desc, def, handler) | 声明 output_send__<name> 的回复发给谁；handler 收到 {payload,type,meta} |
|
||||
|
||||
def（ChannelDef）描述该通道在记忆计算层的行为：NoMemory: true = 该通道输入不进记忆；
|
||||
Cleaner = 计算层清洗后再向量化/提关键词（原文不改）。
|
||||
|
||||
> 只登记出站通道、却用同名通道注入输入时，内核会兜底登记同名 inputch 并在日志里告警。
|
||||
> 兜底只为兼容老插件 —— 请显式登记，让「这是入站通道」成为插件的明确意图。
|
||||
|
||||
## Install
|
||||
|
||||
Upload the .hmap file through the Plugin Manager API.
|
||||
@ -25,35 +25,9 @@ import (
|
||||
|
||||
// ---- 协议常量（须与内核 internal/plugin/proc/protocol.go 一致）----
|
||||
|
||||
// procProtocolVersion 必须与内核的 proc.ProtocolVersion 完全一致。
|
||||
//
|
||||
// v2：内核→插件的 payload 改用调用帧（tool/cleaner/output），媒体块改走
|
||||
// blocks_ref。v1 插件只读内联 args，遇上 v2 内核会拿到空参数；反过来 v2
|
||||
// 插件发 blocks_ref，v1 内核也会静默忽略。两边错配都不报错、只是静默失效，
|
||||
// 所以靠这个常量在握手上显式拦下。
|
||||
const procProtocolVersion = 2
|
||||
const procProtocolVersion = 1
|
||||
|
||||
// ---- 统一共享内存区域布局（与内核 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 一致）----
|
||||
// ---- 共享段布局（须与内核 internal/plugin/proc/shm.go 一致）----
|
||||
|
||||
const (
|
||||
shmStageFieldCount = 18
|
||||
@ -98,201 +72,6 @@ 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
|
||||
}
|
||||
// priority 只对中断注入有意义（排队注入没有级别）。
|
||||
if opts.Priority != "" {
|
||||
args["priority"] = opts.Priority
|
||||
}
|
||||
}
|
||||
|
||||
// ---- 全局状态 ----
|
||||
|
||||
var (
|
||||
@ -309,20 +88,15 @@ 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
|
||||
)
|
||||
|
||||
@ -642,14 +416,9 @@ 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, "has_cleaner": def.Cleaner != nil,
|
||||
"name": toolName, "def": def,
|
||||
})
|
||||
},
|
||||
func(stage sdk.Stage, handler sdk.StageHandler) {
|
||||
@ -668,16 +437,10 @@ 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},
|
||||
"has_cleaner": def.Cleaner != nil,
|
||||
"def": map[string]interface{}{"NoMemory": def.NoMemory},
|
||||
})
|
||||
},
|
||||
)
|
||||
@ -691,19 +454,9 @@ 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,
|
||||
// 整个结构体：手写字段白名单会把新增字段静默丢掉
|
||||
// （ChannelDef.Cleaner 已标 json:"-"，可以整体 marshal）。
|
||||
"def": def,
|
||||
"has_cleaner": def.Cleaner != nil,
|
||||
"def": map[string]interface{}{"NoMemory": def.NoMemory},
|
||||
})
|
||||
})
|
||||
return base
|
||||
@ -711,32 +464,17 @@ func buildPluginSDK(name string) *sdk.PluginSDK {
|
||||
|
||||
type procIO struct{}
|
||||
|
||||
// 下面六个三参数方法是 *Opts 变体的零值糖：记入记忆 + 不裁剪。
|
||||
|
||||
func (procIO) InjectText(s, c, t string) {
|
||||
procIO{}.InjectTextOpts(s, c, t, sdk.InjectOptions{})
|
||||
callCoreVoid("io.injectText", map[string]string{"source": s, "channel": c, "text": t})
|
||||
}
|
||||
func (procIO) InjectInterruptText(s, c, t string) {
|
||||
procIO{}.InjectInterruptTextOpts(s, c, t, sdk.InjectOptions{})
|
||||
callCoreVoid("io.injectInterrupt", map[string]string{"source": s, "channel": c, "text": t})
|
||||
}
|
||||
func (procIO) InjectTextNoMemory(s, c, t string) {
|
||||
procIO{}.InjectTextOpts(s, c, t, sdk.InjectOptions{NoMemory: true})
|
||||
callCoreVoid("io.injectTextNoMem", map[string]string{"source": s, "channel": c, "text": t})
|
||||
}
|
||||
func (procIO) InjectInputSync(s, c, t string) string {
|
||||
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)
|
||||
raw, err := callCore("io.injectInputSync", map[string]string{"source": s, "channel": c, "text": t})
|
||||
if err != nil {
|
||||
return ""
|
||||
}
|
||||
@ -747,18 +485,7 @@ func (procIO) InjectInputSyncOpts(s, c, t string, opts sdk.InjectOptions) string
|
||||
return r.Reply
|
||||
}
|
||||
func (procIO) SetToolBlocks(blocks []sdk.ContentBlock) {
|
||||
// 媒体块经共享内存（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 {
|
||||
if err := callCoreVoid("io.setToolBlocks", map[string]interface{}{"blocks": blocks}); err != nil {
|
||||
log.Printf("SetToolBlocks: %v", err)
|
||||
}
|
||||
}
|
||||
@ -766,29 +493,15 @@ func (procIO) SetToolBlocks(blocks []sdk.ContentBlock) {
|
||||
// 带媒体的注入：插件主动发起一轮带图/音频的对话。
|
||||
// 与 SetToolBlocks 的区别是媒体在**本轮**就到模型手上，而不是等下一条 tool message。
|
||||
func (procIO) InjectInputMedia(s, c, t string, blocks []sdk.ContentBlock) {
|
||||
procIO{}.InjectInputMediaOpts(s, c, t, blocks, sdk.InjectOptions{})
|
||||
callCoreVoid("io.injectMedia", map[string]interface{}{
|
||||
"source": s, "channel": c, "text": t, "blocks": blocks,
|
||||
})
|
||||
}
|
||||
|
||||
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)
|
||||
raw, err := callCore("io.injectMediaSync", map[string]interface{}{
|
||||
"source": s, "channel": c, "text": t, "blocks": blocks,
|
||||
})
|
||||
if err != nil {
|
||||
return ""
|
||||
}
|
||||
@ -799,26 +512,10 @@ func (procIO) InjectInputMediaSyncOpts(s, c, t string, blocks []sdk.ContentBlock
|
||||
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) }
|
||||
func (procIO) InjectInterruptMedia(s, c, t string, blocks []sdk.ContentBlock) {
|
||||
callCoreVoid("io.injectInterruptMedia", map[string]interface{}{
|
||||
"source": s, "channel": c, "text": t, "blocks": blocks,
|
||||
})
|
||||
}
|
||||
|
||||
type procMemory struct{}
|
||||
@ -886,19 +583,7 @@ func (procDocMemory) Query(text string, topK int) []*sdk.Doc {
|
||||
return r.Docs
|
||||
}
|
||||
func (procDocMemory) Insert(d *sdk.Doc) error {
|
||||
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}
|
||||
return callCoreVoid("doc.insert", map[string]interface{}{"doc": d})
|
||||
}
|
||||
|
||||
// InsertWithMedia 写入文档并关联媒体。
|
||||
@ -906,28 +591,9 @@ func docInsertArgs(d *sdk.Doc) map[string]interface{} {
|
||||
// 内核会把 `[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)
|
||||
raw, err := callCore("doc.insertWithMedia", map[string]interface{}{
|
||||
"doc": d, "attachments": atts,
|
||||
})
|
||||
if err != nil {
|
||||
return err
|
||||
}
|
||||
@ -966,13 +632,6 @@ 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) {
|
||||
@ -1284,27 +943,10 @@ func handleKernelRequest(req *rpcRequest) {
|
||||
|
||||
case "tool.invoke":
|
||||
var p struct {
|
||||
Name string `json:"name"`
|
||||
Args map[string]interface{} `json:"args"`
|
||||
Frame SharedRef `json:"frame"`
|
||||
ArgsLen uint32 `json:"args_len"`
|
||||
Name string `json:"name"`
|
||||
Args map[string]interface{} `json:"args"`
|
||||
}
|
||||
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()
|
||||
@ -1312,68 +954,12 @@ func handleKernelRequest(req *rpcRequest) {
|
||||
respondErr(req.ID, fmt.Errorf("未注册的工具: %s", p.Name))
|
||||
return
|
||||
}
|
||||
res, err := h(args)
|
||||
res, err := h(p.Args)
|
||||
if err != nil {
|
||||
respondErr(req.ID, err)
|
||||
return
|
||||
}
|
||||
|
||||
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})
|
||||
respond(req.ID, map[string]interface{}{"result": res})
|
||||
|
||||
case "stage.invoke":
|
||||
handleStageInvoke(req)
|
||||
@ -1382,23 +968,8 @@ 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()
|
||||
@ -1407,7 +978,7 @@ func handleKernelRequest(req *rpcRequest) {
|
||||
return
|
||||
}
|
||||
// 同步返回真实结果——内核据此告知模型成功/失败，不再假成功（§9.4）
|
||||
res, err := h(args)
|
||||
res, err := h(p.Args)
|
||||
if err != nil {
|
||||
respondErr(req.ID, err)
|
||||
return
|
||||
@ -1474,10 +1045,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)
|
||||
|
||||
@ -1494,44 +1065,41 @@ func handleHandshake(req *rpcRequest) {
|
||||
pluginName = p.PluginName
|
||||
}
|
||||
|
||||
// 挂载统一共享内存区域。
|
||||
// fd 3 (Unix) / 命名对象 (Windows) 传给插件子进程，包含 SuperBlock +
|
||||
// StageContext + EvtRing 两段。SuperBlock 记录各段的偏移与大小。
|
||||
// 挂载 StageContext 共享段。
|
||||
// 传递机制按平台不同（Unix 用继承的 fd，Windows 用命名段），
|
||||
// 由 z_proc_shm_*.go 承担——本文件保持平台无关。
|
||||
if p.ShmSize > 0 {
|
||||
m, err := attachUnifiedShm(p.ShmSize)
|
||||
m, err := attachStageShm(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[sbOffMagic:]); got != unifiedMagic {
|
||||
respondErr(req.ID, fmt.Errorf("统一区域魔数不匹配（0x%x，期望 0x%x）", got, unifiedMagic))
|
||||
if got := binary.LittleEndian.Uint32(m[shmOffMagic:]); got != shmMagic {
|
||||
respondErr(req.ID, fmt.Errorf("共享段魔数不匹配（0x%x）", got))
|
||||
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()
|
||||
shm = m
|
||||
}
|
||||
|
||||
// 挂载事件环段 + 打开通知句柄（§3.6）
|
||||
if p.EvtRingSize > 0 {
|
||||
er, err := attachEvtRingShm(p.EvtRingSize)
|
||||
if err != nil {
|
||||
respondErr(req.ID, fmt.Errorf("挂载事件环段失败: %w", err))
|
||||
return
|
||||
}
|
||||
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,23 +10,31 @@ import (
|
||||
|
||||
// Unix 侧共享段挂载：内核经 ExtraFiles 传入继承的 fd。
|
||||
//
|
||||
// 统一共享内存区域布局（§13.1）：
|
||||
// fd 布局（与内核 internal/plugin/proc/plugin.go 的 ExtraFiles 顺序一致）：
|
||||
//
|
||||
// fd 3 = 统一区域（SuperBlock + StageContext + EvtRing）
|
||||
// fd 4 = 事件通知（Linux eventfd / macOS pipe 读端）
|
||||
// fd 3 = StageContext 段（memfd / 已 unlink 的临时文件）
|
||||
// fd 4 = 事件环段
|
||||
// fd 5 = 事件通知（Linux eventfd / macOS pipe 读端）
|
||||
//
|
||||
// 继承的 fd 无需文件名，也不残留——这是选 memfd 而非 /dev/shm 的原因。
|
||||
const (
|
||||
fdUnifiedShm = 3
|
||||
fdEvtNotifier = 4
|
||||
fdStageShm = 3
|
||||
fdEvtRingShm = 4
|
||||
fdEvtNotifier = 5
|
||||
)
|
||||
|
||||
// attachUnifiedShm 挂载统一共享内存区域。
|
||||
// attachStageShm 挂载 StageContext 共享段。
|
||||
//
|
||||
// 各进程 mmap 到不同虚拟地址，段内一律用相对偏移而非指针，故仍能正确解引用
|
||||
// （实验 2 已验证父子 mmap 基址不同时偏移解引用正确）。
|
||||
func attachUnifiedShm(size int) ([]byte, error) {
|
||||
return syscall.Mmap(fdUnifiedShm, 0, size,
|
||||
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,
|
||||
syscall.PROT_READ|syscall.PROT_WRITE, syscall.MAP_SHARED)
|
||||
}
|
||||
|
||||
@ -13,7 +13,7 @@ import (
|
||||
|
||||
"github.com/traefik/yaegi/interp"
|
||||
"github.com/traefik/yaegi/stdlib"
|
||||
"gitcode.com/JianFeeeee/homeagent-sdk/tools/hmapdev/yaegi/mocksdk"
|
||||
"github.com/JianFeeeee/homeagent-sdk/tools/plugindev/yaegi/mocksdk"
|
||||
)
|
||||
|
||||
type YaegiDebugger struct {
|
||||
@ -83,52 +83,24 @@ 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:"-"`
|
||||
ContextPolicy string `json:"context_policy,omitempty"`
|
||||
}
|
||||
|
||||
// 上下文策略取值，与公共 SDK 一致。
|
||||
const (
|
||||
ContextPolicyNone = "none"
|
||||
ContextPolicyPrune = "prune"
|
||||
)
|
||||
|
||||
// InjectOptions 与公共 SDK 同构：声明一次注入是否记入记忆、是否据此裁剪上下文、
|
||||
// 以及用哪个已注册的通道 cleaner 清洗注入内容。
|
||||
type InjectOptions struct {
|
||||
NoMemory bool
|
||||
ContextPolicy string
|
||||
CleanerName string
|
||||
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:"-"`
|
||||
}
|
||||
|
||||
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 多模态内容块格式）。
|
||||
@ -419,34 +391,6 @@ 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
|
||||
3
tools/vscode-hmapdev/.gitignore
vendored
3
tools/vscode-hmapdev/.gitignore
vendored
@ -1,3 +0,0 @@
|
||||
node_modules/
|
||||
out/
|
||||
*.vsix
|
||||
@ -1,5 +0,0 @@
|
||||
src/
|
||||
tsconfig.json
|
||||
node_modules/
|
||||
out/test/
|
||||
.gitignore
|
||||
@ -1,69 +0,0 @@
|
||||
# hmapdev — HomeAgent 插件开发 VSCode 扩展
|
||||
|
||||
调试与构建 HomeAgent 插件工程的 IDE 支持：**plg.json 校验、SDK 版本解析、构建/运行、内核日志跟随**。
|
||||
|
||||
## 为什么需要它
|
||||
|
||||
插件的真实形态是「**独立子进程 + 内核侧握手**」，所以插件的三类问题几乎都在 IDE 之外发生：
|
||||
|
||||
1. **编不出来** —— 最常见的原因不是代码，而是项目没声明要用哪版 SDK，工具链拿了存储里的
|
||||
`current`（可能是陈旧的 `v0.8.0`），于是报一堆看不懂的 `undefined: sdk.XXX`；
|
||||
2. **编出来但起不来** —— 产物与内核**协议绑定**（协议版本 + 共享内存魔数），用错工具链编出来的
|
||||
插件会在握手时被拒；
|
||||
3. **起来了但行为不对** —— 真因往往只在内核日志里（建链失败、崩溃重启、工具报错）。
|
||||
|
||||
本扩展把这三件事拉进 IDE：**先把「用哪版 SDK」摆到明面上**，再让构建/运行/看日志变成一条动作链。
|
||||
|
||||
## 功能
|
||||
|
||||
| 功能 | 说明 |
|
||||
|---|---|
|
||||
| **plg.json 诊断** | 必需字段；`sdk` 必须是**完整版本号**（区间写法 `1.2` 会报错并说明「patch 位恒为 .0」）；声明的 SDK 若未安装在本地存储，直接给出 `hmapdev sdk install vX.Y.Z` |
|
||||
| **状态栏** | `插件 · SDK <声明> · hmapdev <版本>`；工具链缺失或工程有错时变红/黄，tooltip 列出已装 SDK |
|
||||
| **构建 / 清理 / 运行** | `hmapdev build`、`build --target all`、`clean`、`debug`（解释执行，快速迭代）——在集成终端里跑，可 Ctrl-C |
|
||||
| **任务（Tasks）** | 同一批动作注册为 `hmapdev` 任务，可绑快捷键、串依赖；带 **Go 问题匹配器**，编译错误进 Problems 面板 |
|
||||
| **跟随内核日志** | 读 `<dataDir>/log` 下最新的 `homed_*.log`，按插件名过滤后持续输出（真正的联调回路） |
|
||||
| **SDK 管理** | 查看工具链版本、列出/安装/切换 SDK 版本（走 QuickPick，不用记命令） |
|
||||
| **JSON 支持** | `plg.json` 的 schema 校验 + 骨架片段 |
|
||||
|
||||
## 安装
|
||||
|
||||
```bash
|
||||
cd tools/vscode-hmapdev
|
||||
npm install
|
||||
npm run compile
|
||||
```
|
||||
|
||||
然后二选一：
|
||||
|
||||
- **开发模式**：在 VSCode 里打开本目录，按 `F5`（Extension Development Host），把插件工程目录作为工作区打开；
|
||||
- **安装到本机**：`npx @vscode/vsce package` 生成 `.vsix`，再 `code --install-extension hmapdev-vscode-0.1.0.vsix`。
|
||||
|
||||
前提：`hmapdev` 在 `PATH` 上（或设置 `hmapdev.path`）。
|
||||
|
||||
## 配置
|
||||
|
||||
| 设置 | 默认 | 说明 |
|
||||
|---|---|---|
|
||||
| `hmapdev.path` | `hmapdev` | 工具链可执行文件路径 |
|
||||
| `hmapdev.kernelDataDir` | 空 | 内核数据目录（`homed -data` 的那个）；填了才能跟随内核日志 |
|
||||
| `hmapdev.diagnoseSdk` | `true` | 是否校验声明的 SDK 是否已安装（需要能执行 hmapdev） |
|
||||
|
||||
## 用法（典型开发回路）
|
||||
|
||||
1. 打开插件工程（含 `plg.json`）→ 状态栏出现 `插件 · SDK <版本> · hmapdev <版本>`；
|
||||
2. 若 `sdk` 报错（未声明 / 区间写法 / 未安装）→ 按提示执行 `hmapdev: 安装 SDK 版本…`，再 `hmapdev: 刷新状态`；
|
||||
3. `hmapdev: 构建插件`（或 `构建（全部目标平台）`）→ 编译错误直接进 Problems；
|
||||
4. 快速验证行为：`hmapdev: 运行插件（解释执行）`；
|
||||
5. 与内核联调：设置 `hmapdev.kernelDataDir` → `hmapdev: 跟随内核日志`，只看本插件的行；
|
||||
6. 改代码 → 重复 3/5。装进内核时记得**与内核同批替换**（协议绑定的产物不支持滚动升级）。
|
||||
|
||||
## 诚实的边界
|
||||
|
||||
- **这不是源码级调试器**：没有断点/单步。插件的 Go 代码要么编译成产物在内核里跑、要么用
|
||||
`hmapdev debug`（yaegi 解释执行）跑，两条路都不提供 DAP 调试会话。本扩展做的是
|
||||
「构建 + 运行 + 看内核日志 + 清单校验」，这也是插件问题实际能被定位的方式。
|
||||
- **Windows 目标**：不支持（协议 2 的统一共享内存区未移植到 Windows，内核侧改走 WSL2），
|
||||
扩展只给提示，不假装能构建。
|
||||
- **`sdk` 字段的语义**：它声明的是**本插件针对的 SDK 版本**（= 接口线），不是内核版本。
|
||||
SDK 版本跟随内核中版本、patch 位恒为 `.0`。
|
||||
59
tools/vscode-hmapdev/package-lock.json
generated
59
tools/vscode-hmapdev/package-lock.json
generated
@ -1,59 +0,0 @@
|
||||
{
|
||||
"name": "hmapdev-vscode",
|
||||
"version": "0.1.0",
|
||||
"lockfileVersion": 3,
|
||||
"requires": true,
|
||||
"packages": {
|
||||
"": {
|
||||
"name": "hmapdev-vscode",
|
||||
"version": "0.1.0",
|
||||
"license": "AGPL-3.0-only",
|
||||
"devDependencies": {
|
||||
"@types/node": "^22.0.0",
|
||||
"@types/vscode": "^1.85.0",
|
||||
"typescript": "^5.6.0"
|
||||
},
|
||||
"engines": {
|
||||
"vscode": "^1.85.0"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/node": {
|
||||
"version": "22.20.2",
|
||||
"resolved": "https://registry.npmmirror.com/@types/node/-/node-22.20.2.tgz",
|
||||
"integrity": "sha512-xlvWf4Vs9n1PEVYwP1n4vvG07M6y8WgvJ2t0vbrWTmijsIHp1cS+uJ2kMIRdY3nHZK0nCYKrPeD171+SzF4/zw==",
|
||||
"dev": true,
|
||||
"license": "MIT",
|
||||
"dependencies": {
|
||||
"undici-types": "~6.21.0"
|
||||
}
|
||||
},
|
||||
"node_modules/@types/vscode": {
|
||||
"version": "1.137.0",
|
||||
"resolved": "https://registry.npmmirror.com/@types/vscode/-/vscode-1.137.0.tgz",
|
||||
"integrity": "sha512-0dc/BBWxkyUsJzXIZ7PkKSalThmS4xiBT+8YEDiWdCefRKHGVV5ZNkM5NB5ULYamallYJujIfncNoXWFlyzL8A==",
|
||||
"dev": true,
|
||||
"license": "MIT"
|
||||
},
|
||||
"node_modules/typescript": {
|
||||
"version": "5.9.3",
|
||||
"resolved": "https://registry.npmmirror.com/typescript/-/typescript-5.9.3.tgz",
|
||||
"integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==",
|
||||
"dev": true,
|
||||
"license": "Apache-2.0",
|
||||
"bin": {
|
||||
"tsc": "bin/tsc",
|
||||
"tsserver": "bin/tsserver"
|
||||
},
|
||||
"engines": {
|
||||
"node": ">=14.17"
|
||||
}
|
||||
},
|
||||
"node_modules/undici-types": {
|
||||
"version": "6.21.0",
|
||||
"resolved": "https://registry.npmmirror.com/undici-types/-/undici-types-6.21.0.tgz",
|
||||
"integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==",
|
||||
"dev": true,
|
||||
"license": "MIT"
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -1,174 +0,0 @@
|
||||
{
|
||||
"name": "hmapdev-vscode",
|
||||
"displayName": "HomeAgent Plugin Dev (hmapdev)",
|
||||
"description": "调试与构建 HomeAgent 插件工程：plg.json 校验、SDK 版本解析、hmapdev 构建/运行、内核日志跟随。",
|
||||
"version": "0.1.0",
|
||||
"publisher": "JianFeeeee",
|
||||
"license": "AGPL-3.0-only",
|
||||
"private": true,
|
||||
"engines": {
|
||||
"vscode": "^1.85.0"
|
||||
},
|
||||
"categories": [
|
||||
"Programming Languages",
|
||||
"Debuggers",
|
||||
"Other"
|
||||
],
|
||||
"main": "./out/extension.js",
|
||||
"activationEvents": [
|
||||
"workspaceContains:plg.json",
|
||||
"workspaceContains:**/plg.json"
|
||||
],
|
||||
"contributes": {
|
||||
"commands": [
|
||||
{
|
||||
"command": "hmapdev.build",
|
||||
"title": "hmapdev: 构建插件"
|
||||
},
|
||||
{
|
||||
"command": "hmapdev.buildAll",
|
||||
"title": "hmapdev: 构建插件（全部目标平台）"
|
||||
},
|
||||
{
|
||||
"command": "hmapdev.clean",
|
||||
"title": "hmapdev: 清理产物"
|
||||
},
|
||||
{
|
||||
"command": "hmapdev.run",
|
||||
"title": "hmapdev: 运行插件（解释执行，快速迭代）"
|
||||
},
|
||||
{
|
||||
"command": "hmapdev.showVersion",
|
||||
"title": "hmapdev: 查看工具链版本"
|
||||
},
|
||||
{
|
||||
"command": "hmapdev.listSdk",
|
||||
"title": "hmapdev: 列出 SDK 版本"
|
||||
},
|
||||
{
|
||||
"command": "hmapdev.installSdk",
|
||||
"title": "hmapdev: 安装 SDK 版本…"
|
||||
},
|
||||
{
|
||||
"command": "hmapdev.useSdk",
|
||||
"title": "hmapdev: 切换当前 SDK 版本…"
|
||||
},
|
||||
{
|
||||
"command": "hmapdev.tailKernelLog",
|
||||
"title": "hmapdev: 跟随内核日志（按插件过滤）"
|
||||
},
|
||||
{
|
||||
"command": "hmapdev.stopTailKernelLog",
|
||||
"title": "hmapdev: 停止跟随内核日志"
|
||||
},
|
||||
{
|
||||
"command": "hmapdev.openPlgJson",
|
||||
"title": "hmapdev: 打开 plg.json"
|
||||
},
|
||||
{
|
||||
"command": "hmapdev.refresh",
|
||||
"title": "hmapdev: 刷新状态（重新探测工具链与 SDK）"
|
||||
}
|
||||
],
|
||||
"configuration": {
|
||||
"title": "HomeAgent Plugin Dev",
|
||||
"properties": {
|
||||
"hmapdev.path": {
|
||||
"type": "string",
|
||||
"default": "hmapdev",
|
||||
"description": "hmapdev 可执行文件路径（默认从 PATH 找）。"
|
||||
},
|
||||
"hmapdev.kernelDataDir": {
|
||||
"type": "string",
|
||||
"default": "",
|
||||
"description": "内核数据目录（homed -data 的那个目录）。填了才能跟随内核日志调试；留空则「跟随内核日志」会先询问。"
|
||||
},
|
||||
"hmapdev.diagnoseSdk": {
|
||||
"type": "boolean",
|
||||
"default": true,
|
||||
"description": "校验 plg.json 里声明的 SDK 版本是否已安装在本地 SDK 存储（需要能执行 hmapdev）。"
|
||||
}
|
||||
}
|
||||
},
|
||||
"taskDefinitions": [
|
||||
{
|
||||
"type": "hmapdev",
|
||||
"required": [
|
||||
"action"
|
||||
],
|
||||
"properties": {
|
||||
"action": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"build",
|
||||
"buildAll",
|
||||
"clean",
|
||||
"run"
|
||||
],
|
||||
"description": "要执行的 hmapdev 动作。"
|
||||
},
|
||||
"cwd": {
|
||||
"type": "string",
|
||||
"description": "插件工程目录（默认取 plg.json 所在目录）。"
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"problemMatchers": [
|
||||
{
|
||||
"name": "hmapdev-go",
|
||||
"owner": "go",
|
||||
"source": "hmapdev",
|
||||
"fileLocation": [
|
||||
"relative",
|
||||
"${workspaceFolder}"
|
||||
],
|
||||
"pattern": [
|
||||
{
|
||||
"regexp": "^(.+\\.go):(\\d+):(\\d+):\\s+(.+)$",
|
||||
"file": 1,
|
||||
"line": 2,
|
||||
"column": 3,
|
||||
"message": 4
|
||||
},
|
||||
{
|
||||
"regexp": "^(.+\\.go):(\\d+):\\s+(.+)$",
|
||||
"file": 1,
|
||||
"line": 2,
|
||||
"message": 3
|
||||
}
|
||||
]
|
||||
}
|
||||
],
|
||||
"languages": [
|
||||
{
|
||||
"id": "json",
|
||||
"filenames": [
|
||||
"plg.json"
|
||||
]
|
||||
}
|
||||
],
|
||||
"jsonValidation": [
|
||||
{
|
||||
"fileMatch": "plg.json",
|
||||
"url": "./schema/plg.schema.json"
|
||||
}
|
||||
],
|
||||
"snippets": [
|
||||
{
|
||||
"language": "json",
|
||||
"path": "./snippets/plg.json.code-snippets"
|
||||
}
|
||||
]
|
||||
},
|
||||
"scripts": {
|
||||
"compile": "tsc -p ./",
|
||||
"watch": "tsc -watch -p ./",
|
||||
"test": "tsc -p ./ && node --test out/test/*.test.js"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@types/node": "^22.0.0",
|
||||
"@types/vscode": "^1.85.0",
|
||||
"typescript": "^5.6.0"
|
||||
}
|
||||
}
|
||||
@ -1,41 +0,0 @@
|
||||
{
|
||||
"$schema": "http://json-schema.org/draft-07/schema#",
|
||||
"title": "HomeAgent 插件清单（plg.json）",
|
||||
"type": "object",
|
||||
"required": ["name", "version", "entry"],
|
||||
"properties": {
|
||||
"name": {
|
||||
"type": "string",
|
||||
"description": "插件名（与目录名一致最省事）"
|
||||
},
|
||||
"name_zh": { "type": "string", "description": "中文显示名" },
|
||||
"name_en": { "type": "string", "description": "英文显示名" },
|
||||
"version": { "type": "string", "description": "插件自身版本号（如 0.1.0），与内核/SDK 版本无关" },
|
||||
"description": { "type": "string" },
|
||||
"author": { "type": "string" },
|
||||
"entry": {
|
||||
"type": "string",
|
||||
"description": "入口产物文件名（子进程模式通常是 plugin.bin；Lua 是 main.lua）"
|
||||
},
|
||||
"sdk": {
|
||||
"type": "string",
|
||||
"pattern": "^v?\\d+\\.\\d+\\.\\d+$",
|
||||
"description": "本插件针对的 SDK 版本，必须是完整版本号（如 1.2.0）。SDK 版本跟随内核中版本、patch 位恒为 .0，一条内核线只有一个 SDK 版本；工具链按此在本地 SDK 存储里选择版本。"
|
||||
},
|
||||
"tags": { "type": "array", "items": { "type": "string" } },
|
||||
"targets": {
|
||||
"type": "string",
|
||||
"description": "目标平台，逗号分隔，如 linux/amd64,darwin/arm64（windows 目标暂不支持插件产物）"
|
||||
},
|
||||
"outdir": { "type": "string", "description": "产物目录（默认 dist）" },
|
||||
"bundle": { "type": "boolean", "description": "是否打包成 .hmap（默认 true）" },
|
||||
"sdk_path": {
|
||||
"type": "string",
|
||||
"description": "直接指定 SDK 源码目录（本机改 SDK 联调时用）；设置后优先于 sdk 字段"
|
||||
},
|
||||
"go_version": { "type": "string" },
|
||||
"replaces": { "type": "object", "additionalProperties": { "type": "string" } },
|
||||
"source_dirs": { "type": "array", "items": { "type": "string" } }
|
||||
},
|
||||
"additionalProperties": true
|
||||
}
|
||||
@ -1,26 +0,0 @@
|
||||
{
|
||||
"plg.json 骨架": {
|
||||
"prefix": "plg",
|
||||
"body": [
|
||||
"{",
|
||||
" \"name\": \"${1:MyPlugin}\",",
|
||||
" \"name_zh\": \"${2:中文名}\",",
|
||||
" \"name_en\": \"${1:MyPlugin}\",",
|
||||
" \"version\": \"0.1.0\",",
|
||||
" \"description\": \"${3:插件说明}\",",
|
||||
" \"author\": \"${4:HomeAgent}\",",
|
||||
" \"entry\": \"plugin.bin\",",
|
||||
" \"sdk\": \"${5:1.2.0}\",",
|
||||
" \"tags\": [\"${1:MyPlugin}\"],",
|
||||
" \"targets\": \"linux/amd64,darwin/arm64\"",
|
||||
"}",
|
||||
"$0"
|
||||
],
|
||||
"description": "plg.json 必需字段骨架（sdk 必须是完整版本号）"
|
||||
},
|
||||
"sdk 字段": {
|
||||
"prefix": "sdk",
|
||||
"body": ["\"sdk\": \"${1:1.2.0}\","],
|
||||
"description": "声明本插件针对的 SDK 版本（完整版本号；patch 位恒为 .0）"
|
||||
}
|
||||
}
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user