release v0.2.1

LICENSE

@@ -0,0 +1,674 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 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 General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+  To protect your rights, we need to prevent others from denying you
+these rights or asking you to surrender the rights.  Therefore, you have
+certain responsibilities if you distribute copies of the software, or if
+you modify it: responsibilities to respect the freedom of others.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must pass on to the recipients the same
+freedoms that you received.  You must make sure that they, too, receive
+or can get the source code.  And you must show them these terms so they
+know their rights.
+
+  Developers that use the GNU GPL protect your rights with two steps:
+(1) assert copyright on the software, and (2) offer you this License
+giving you legal permission to copy, distribute and/or modify it.
+
+  For the developers' and authors' protection, the GPL clearly explains
+that there is no warranty for this free software.  For both users' and
+authors' sake, the GPL requires that modified versions be marked as
+changed, so that their problems will not be attributed erroneously to
+authors of previous versions.
+
+  Some devices are designed to deny users access to install or run
+modified versions of the software inside them, although the manufacturer
+can do so.  This is fundamentally incompatible with the aim of
+protecting users' freedom to change the software.  The systematic
+pattern of such abuse occurs in the area of products for individuals to
+use, which is precisely where it is most unacceptable.  Therefore, we
+have designed this version of the GPL to prohibit the practice for those
+products.  If such problems arise substantially in other domains, we
+stand ready to extend this provision to those domains in future versions
+of the GPL, as needed to protect the freedom of users.
+
+  Finally, every program is threatened constantly by software patents.
+States should not allow patents to restrict development and use of
+software on general-purpose computers, but in those that do, we wish to
+avoid the special danger that patents applied to a free program could
+make it effectively proprietary.  To prevent this, the GPL assures that
+patents cannot be used to render the program non-free.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                       TERMS AND CONDITIONS
+
+  0. Definitions.
+
+  "This License" refers to version 3 of the GNU General Public License.
+
+  "Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+  "The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+  To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+  A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+  To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+  To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+  An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+  1. Source Code.
+
+  The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+  A "Standard Interface" means an interface that either is an official
+standard defined by a recognized standards body, or, in the case of
+interfaces specified for a particular programming language, one that
+is widely used among developers working in that language.
+
+  The "System Libraries" of an executable work include anything, other
+than the work as a whole, that (a) is included in the normal form of
+packaging a Major Component, but which is not part of that Major
+Component, and (b) serves only to enable use of the work with that
+Major Component, or to implement a Standard Interface for which an
+implementation is available to the public in source code form.  A
+"Major Component", in this context, means a major essential component
+(kernel, window system, and so on) of the specific operating system
+(if any) on which the executable work runs, or a compiler used to
+produce the work, or an object code interpreter used to run it.
+
+  The "Corresponding Source" for a work in object code form means all
+the source code needed to generate, install, and (for an executable
+work) run the object code and to modify the work, including scripts to
+control those activities.  However, it does not include the work's
+System Libraries, or general-purpose tools or generally available free
+programs which are used unmodified in performing those activities but
+which are not part of the work.  For example, Corresponding Source
+includes interface definition files associated with source files for
+the work, and the source code for shared libraries and dynamically
+linked subprograms that the work is specifically designed to require,
+such as by intimate data communication or control flow between those
+subprograms and other parts of the work.
+
+  The Corresponding Source need not include anything that users
+can regenerate automatically from other parts of the Corresponding
+Source.
+
+  The Corresponding Source for a work in source code form is that
+same work.
+
+  2. Basic Permissions.
+
+  All rights granted under this License are granted for the term of
+copyright on the Program, and are irrevocable provided the stated
+conditions are met.  This License explicitly affirms your unlimited
+permission to run the unmodified Program.  The output from running a
+covered work is covered by this License only if the output, given its
+content, constitutes a covered work.  This License acknowledges your
+rights of fair use or other equivalent, as provided by copyright law.
+
+  You may make, run and propagate covered works that you do not
+convey, without conditions so long as your license otherwise remains
+in force.  You may convey covered works to others for the sole purpose
+of having them make modifications exclusively for you, or provide you
+with facilities for running those works, provided that you comply with
+the terms of this License in conveying all material for which you do
+not control copyright.  Those thus making or running the covered works
+for you must do so exclusively on your behalf, under your direction
+and control, on terms that prohibit them from making any copies of
+your copyrighted material outside their relationship with you.
+
+  Conveying under any other circumstances is permitted solely under
+the conditions stated below.  Sublicensing is not allowed; section 10
+makes it unnecessary.
+
+  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
+
+  No covered work shall be deemed part of an effective technological
+measure under any applicable law fulfilling obligations under article
+11 of the WIPO copyright treaty adopted on 20 December 1996, or
+similar laws prohibiting or restricting circumvention of such
+measures.
+
+  When you convey a covered work, you waive any legal power to forbid
+circumvention of technological measures to the extent such circumvention
+is effected by exercising rights under this License with respect to
+the covered work, and you disclaim any intention to limit operation or
+modification of the work as a means of enforcing, against the work's
+users, your or third parties' legal rights to forbid circumvention of
+technological measures.
+
+  4. Conveying Verbatim Copies.
+
+  You may convey verbatim copies of the Program's source code as you
+receive it, in any medium, provided that you conspicuously and
+appropriately publish on each copy an appropriate copyright notice;
+keep intact all notices stating that this License and any
+non-permissive terms added in accord with section 7 apply to the code;
+keep intact all notices of the absence of any warranty; and give all
+recipients a copy of this License along with the Program.
+
+  You may charge any price or no price for each copy that you convey,
+and you may offer support or warranty protection for a fee.
+
+  5. Conveying Modified Source Versions.
+
+  You may convey a work based on the Program, or the modifications to
+produce it from the Program, in the form of source code under the
+terms of section 4, provided that you also meet all of these conditions:
+
+    a) The work must carry prominent notices stating that you modified
+    it, and giving a relevant date.
+
+    b) The work must carry prominent notices stating that it is
+    released under this License and any conditions added under section
+    7.  This requirement modifies the requirement in section 4 to
+    "keep intact all notices".
+
+    c) You must license the entire work, as a whole, under this
+    License to anyone who comes into possession of a copy.  This
+    License will therefore apply, along with any applicable section 7
+    additional terms, to the whole of the work, and all its parts,
+    regardless of how they are packaged.  This License gives no
+    permission to license the work in any other way, but it does not
+    invalidate such permission if you have separately received it.
+
+    d) If the work has interactive user interfaces, each must display
+    Appropriate Legal Notices; however, if the Program has interactive
+    interfaces that do not display Appropriate Legal Notices, your
+    work need not make them do so.
+
+  A compilation of a covered work with other separate and independent
+works, which are not by their nature extensions of the covered work,
+and which are not combined with it such as to form a larger program,
+in or on a volume of a storage or distribution medium, is called an
+"aggregate" if the compilation and its resulting copyright are not
+used to limit the access or legal rights of the compilation's users
+beyond what the individual works permit.  Inclusion of a covered work
+in an aggregate does not cause this License to apply to the other
+parts of the aggregate.
+
+  6. Conveying Non-Source Forms.
+
+  You may convey a covered work in object code form under the terms
+of sections 4 and 5, provided that you also convey the
+machine-readable Corresponding Source under the terms of this License,
+in one of these ways:
+
+    a) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by the
+    Corresponding Source fixed on a durable physical medium
+    customarily used for software interchange.
+
+    b) Convey the object code in, or embodied in, a physical product
+    (including a physical distribution medium), accompanied by a
+    written offer, valid for at least three years and valid for as
+    long as you offer spare parts or customer support for that product
+    model, to give anyone who possesses the object code either (1) a
+    copy of the Corresponding Source for all the software in the
+    product that is covered by this License, on a durable physical
+    medium customarily used for software interchange, for a price no
+    more than your reasonable cost of physically performing this
+    conveying of source, or (2) access to copy the
+    Corresponding Source from a network server at no charge.
+
+    c) Convey individual copies of the object code with a copy of the
+    written offer to provide the Corresponding Source.  This
+    alternative is allowed only occasionally and noncommercially, and
+    only if you received the object code with such an offer, in accord
+    with subsection 6b.
+
+    d) Convey the object code by offering access from a designated
+    place (gratis or for a charge), and offer equivalent access to the
+    Corresponding Source in the same way through the same place at no
+    further charge.  You need not require recipients to copy the
+    Corresponding Source along with the object code.  If the place to
+    copy the object code is a network server, the Corresponding Source
+    may be on a different server (operated by you or a third party)
+    that supports equivalent copying facilities, provided you maintain
+    clear directions next to the object code saying where to find the
+    Corresponding Source.  Regardless of what server hosts the
+    Corresponding Source, you remain obligated to ensure that it is
+    available for as long as needed to satisfy these requirements.
+
+    e) Convey the object code using peer-to-peer transmission, provided
+    you inform other peers where the object code and Corresponding
+    Source of the work are being offered to the general public at no
+    charge under subsection 6d.
+
+  A separable portion of the object code, whose source code is excluded
+from the Corresponding Source as a System Library, need not be
+included in conveying the object code work.
+
+  A "User Product" is either (1) a "consumer product", which means any
+tangible personal property which is normally used for personal, family,
+or household purposes, or (2) anything designed or sold for incorporation
+into a dwelling.  In determining whether a product is a consumer product,
+doubtful cases shall be resolved in favor of coverage.  For a particular
+product received by a particular user, "normally used" refers to a
+typical or common use of that class of product, regardless of the status
+of the particular user or of the way in which the particular user
+actually uses, or expects or is expected to use, the product.  A product
+is a consumer product regardless of whether the product has substantial
+commercial, industrial or non-consumer uses, unless such uses represent
+the only significant mode of use of the product.
+
+  "Installation Information" for a User Product means any methods,
+procedures, authorization keys, or other information required to install
+and execute modified versions of a covered work in that User Product from
+a modified version of its Corresponding Source.  The information must
+suffice to ensure that the continued functioning of the modified object
+code is in no case prevented or interfered with solely because
+modification has been made.
+
+  If you convey an object code work under this section in, or with, or
+specifically for use in, a User Product, and the conveying occurs as
+part of a transaction in which the right of possession and use of the
+User Product is transferred to the recipient in perpetuity or for a
+fixed term (regardless of how the transaction is characterized), the
+Corresponding Source conveyed under this section must be accompanied
+by the Installation Information.  But this requirement does not apply
+if neither you nor any third party retains the ability to install
+modified object code on the User Product (for example, the work has
+been installed in ROM).
+
+  The requirement to provide Installation Information does not include a
+requirement to continue to provide support service, warranty, or updates
+for a work that has been modified or installed by the recipient, or for
+the User Product in which it has been modified or installed.  Access to a
+network may be denied when the modification itself materially and
+adversely affects the operation of the network or violates the rules and
+protocols for communication across the network.
+
+  Corresponding Source conveyed, and Installation Information provided,
+in accord with this section must be in a format that is publicly
+documented (and with an implementation available to the public in
+source code form), and must require no special password or key for
+unpacking, reading or copying.
+
+  7. Additional Terms.
+
+  "Additional permissions" are terms that supplement the terms of this
+License by making exceptions from one or more of its conditions.
+Additional permissions that are applicable to the entire Program shall
+be treated as though they were included in this License, to the extent
+that they are valid under applicable law.  If additional permissions
+apply only to part of the Program, that part may be used separately
+under those permissions, but the entire Program remains governed by
+this License without regard to the additional permissions.
+
+  When you convey a copy of a covered work, you may at your option
+remove any additional permissions from that copy, or from any part of
+it.  (Additional permissions may be written to require their own
+removal in certain cases when you modify the work.)  You may place
+additional permissions on material, added by you to a covered work,
+for which you have or can give appropriate copyright permission.
+
+  Notwithstanding any other provision of this License, for material you
+add to a covered work, you may (if authorized by the copyright holders of
+that material) supplement the terms of this License with terms:
+
+    a) Disclaiming warranty or limiting liability differently from the
+    terms of sections 15 and 16 of this License; or
+
+    b) Requiring preservation of specified reasonable legal notices or
+    author attributions in that material or in the Appropriate Legal
+    Notices displayed by works containing it; or
+
+    c) Prohibiting misrepresentation of the origin of that material, or
+    requiring that modified versions of such material be marked in
+    reasonable ways as different from the original version; or
+
+    d) Limiting the use for publicity purposes of names of licensors or
+    authors of the material; or
+
+    e) Declining to grant rights under trademark law for use of some
+    trade names, trademarks, or service marks; or
+
+    f) Requiring indemnification of licensors and authors of that
+    material by anyone who conveys the material (or modified versions of
+    it) with contractual assumptions of liability to the recipient, for
+    any liability that these contractual assumptions directly impose on
+    those licensors and authors.
+
+  All other non-permissive additional terms are considered "further
+restrictions" within the meaning of section 10.  If the Program as you
+received it, or any part of it, contains a notice stating that it is
+governed by this License along with a term that is a further
+restriction, you may remove that term.  If a license document contains
+a further restriction but permits relicensing or conveying under this
+License, you may add to a covered work material governed by the terms
+of that license document, provided that the further restriction does
+not survive such relicensing or conveying.
+
+  If you add terms to a covered work in accord with this section, you
+must place, in the relevant source files, a statement of the
+additional terms that apply to those files, or a notice indicating
+where to find the applicable terms.
+
+  Additional terms, permissive or non-permissive, may be stated in the
+form of a separately written license, or stated as exceptions;
+the above requirements apply either way.
+
+  8. Termination.
+
+  You may not propagate or modify a covered work except as expressly
+provided under this License.  Any attempt otherwise to propagate or
+modify it is void, and will automatically terminate your rights under
+this License (including any patent licenses granted under the third
+paragraph of section 11).
+
+  However, if you cease all violation of this License, then your
+license from a particular copyright holder is reinstated (a)
+provisionally, unless and until the copyright holder explicitly and
+finally terminates your license, and (b) permanently, if the copyright
+holder fails to notify you of the violation by some reasonable means
+prior to 60 days after the cessation.
+
+  Moreover, your license from a particular copyright holder is
+reinstated permanently if the copyright holder notifies you of the
+violation by some reasonable means, this is the first time you have
+received notice of violation of this License (for any work) from that
+copyright holder, and you cure the violation prior to 30 days after
+your receipt of the notice.
+
+  Termination of your rights under this section does not terminate the
+licenses of parties who have received copies or rights from you under
+this License.  If your rights have been terminated and not permanently
+reinstated, you do not qualify to receive new licenses for the same
+material under section 10.
+
+  9. Acceptance Not Required for Having Copies.
+
+  You are not required to accept this License in order to receive or
+run a copy of the Program.  Ancillary propagation of a covered work
+occurring solely as a consequence of using peer-to-peer transmission
+to receive a copy likewise does not require acceptance.  However,
+nothing other than this License grants you permission to propagate or
+modify any covered work.  These actions infringe copyright if you do
+not accept this License.  Therefore, by modifying or propagating a
+covered work, you indicate your acceptance of this License to do so.
+
+  10. Automatic Licensing of Downstream Recipients.
+
+  Each time you convey a covered work, the recipient automatically
+receives a license from the original licensors, to run, modify and
+propagate that work, subject to this License.  You are not responsible
+for enforcing compliance by third parties with this License.
+
+  An "entity transaction" is a transaction transferring control of an
+organization, or substantially all assets of one, or subdividing an
+organization, or merging organizations.  If propagation of a covered
+work results from an entity transaction, each party to that
+transaction who receives a copy of the work also receives whatever
+licenses to the work the party's predecessor in interest had or could
+give under the previous paragraph, plus a right to possession of the
+Corresponding Source of the work from the predecessor in interest, if
+the predecessor has it or can get it with reasonable efforts.
+
+  You may not impose any further restrictions on the exercise of the
+rights granted or affirmed under this License.  For example, you may
+not impose a license fee, royalty, or other charge for exercise of
+rights granted under this License, and you may not initiate litigation
+(including a cross-claim or counterclaim in a lawsuit) alleging that
+any patent claim is infringed by making, using, selling, offering for
+sale, or importing the Program or any portion of it.
+
+  11. Patents.
+
+  A "contributor" is a copyright holder who authorizes use under this
+License of the Program or a work on which the Program is based.  The
+work thus licensed is called the contributor's "contributor version".
+
+  A contributor's "essential patent claims" are all patent claims
+owned or controlled by the contributor, whether already acquired or
+hereafter acquired, that would be infringed by some manner, permitted
+by this License, of making, using, or selling its contributor version,
+but do not include claims that would be infringed only as a
+consequence of further modification of the contributor version.  For
+purposes of this definition, "control" includes the right to grant
+patent sublicenses in a manner consistent with the requirements of
+this License.
+
+  Each contributor grants you a non-exclusive, worldwide, royalty-free
+patent license under the contributor's essential patent claims, to
+make, use, sell, offer for sale, import and otherwise run, modify and
+propagate the contents of its contributor version.
+
+  In the following three paragraphs, a "patent license" is any express
+agreement or commitment, however denominated, not to enforce a patent
+(such as an express permission to practice a patent or covenant not to
+sue for patent infringement).  To "grant" such a patent license to a
+party means to make such an agreement or commitment not to enforce a
+patent against the party.
+
+  If you convey a covered work, knowingly relying on a patent license,
+and the Corresponding Source of the work is not available for anyone
+to copy, free of charge and under the terms of this License, through a
+publicly available network server or other readily accessible means,
+then you must either (1) cause the Corresponding Source to be so
+available, or (2) arrange to deprive yourself of the benefit of the
+patent license for this particular work, or (3) arrange, in a manner
+consistent with the requirements of this License, to extend the patent
+license to downstream recipients.  "Knowingly relying" means you have
+actual knowledge that, but for the patent license, your conveying the
+covered work in a country, or your recipient's use of the covered work
+in a country, would infringe one or more identifiable patents in that
+country that you have reason to believe are valid.
+
+  If, pursuant to or in connection with a single transaction or
+arrangement, you convey, or propagate by procuring conveyance of, a
+covered work, and grant a patent license to some of the parties
+receiving the covered work authorizing them to use, propagate, modify
+or convey a specific copy of the covered work, then the patent license
+you grant is automatically extended to all recipients of the covered
+work and works based on it.
+
+  A patent license is "discriminatory" if it does not include within
+the scope of its coverage, prohibits the exercise of, or is
+conditioned on the non-exercise of one or more of the rights that are
+specifically granted under this License.  You may not convey a covered
+work if you are a party to an arrangement with a third party that is
+in the business of distributing software, under which you make payment
+to the third party based on the extent of your activity of conveying
+the work, and under which the third party grants, to any of the
+parties who would receive the covered work from you, a discriminatory
+patent license (a) in connection with copies of the covered work
+conveyed by you (or copies made from those copies), or (b) primarily
+for and in connection with specific products or compilations that
+contain the covered work, unless you entered into that arrangement,
+or that patent license was granted, prior to 28 March 2007.
+
+  Nothing in this License shall be construed as excluding or limiting
+any implied license or other defenses to infringement that may
+otherwise be available to you under applicable patent law.
+
+  12. No Surrender of Others' Freedom.
+
+  If conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot convey a
+covered work so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you may
+not convey it at all.  For example, if you agree to terms that obligate you
+to collect a royalty for further conveying from those to whom you convey
+the Program, the only way you could satisfy both those terms and this
+License would be to refrain entirely from conveying the Program.
+
+  13. Use with the GNU Affero General Public License.
+
+  Notwithstanding any other provision of this License, you have
+permission to link or combine any covered work with a work licensed
+under version 3 of the GNU Affero General Public License into a single
+combined work, and to convey the resulting work.  The terms of this
+License will continue to apply to the part which is the covered work,
+but the special requirements of the GNU Affero General Public License,
+section 13, concerning interaction through a network will apply to the
+combination as such.
+
+  14. Revised Versions of this License.
+
+  The Free Software Foundation may publish revised and/or new versions of
+the GNU General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+  Each version is given a distinguishing version number.  If the
+Program specifies that a certain numbered version of the GNU General
+Public License "or any later version" applies to it, you have the
+option of following the terms and conditions either of that numbered
+version or of any later version published by the Free Software
+Foundation.  If the Program does not specify a version number of the
+GNU General Public License, you may choose any version ever published
+by the Free Software Foundation.
+
+  If the Program specifies that a proxy can decide which future
+versions of the GNU General Public License can be used, that proxy's
+public statement of acceptance of a version permanently authorizes you
+to choose that version for the Program.
+
+  Later license versions may give you additional or different
+permissions.  However, no additional obligations are imposed on any
+author or copyright holder as a result of your choosing to follow a
+later version.
+
+  15. Disclaimer of Warranty.
+
+  THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
+APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
+HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
+OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
+THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
+IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
+ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
+
+  16. Limitation of Liability.
+
+  IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
+THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
+GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
+USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
+DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
+PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
+EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGES.
+
+  17. Interpretation of Sections 15 and 16.
+
+  If the disclaimer of warranty and limitation of liability provided
+above cannot be given local legal effect according to their terms,
+reviewing courts shall apply local law that most closely approximates
+an absolute waiver of all civil liability in connection with the
+Program, unless a warranty or assumption of liability accompanies a
+copy of the Program in return for a fee.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <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 General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+  If the program does terminal interaction, make it output a short
+notice like this when it starts in an interactive mode:
+
+    <program>  Copyright (C) <year>  <name of author>
+    This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, your program's commands
+might be different; for a GUI interface, you would use an "about box".
+
+  You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU GPL, see
+<https://www.gnu.org/licenses/>.
+
+  The GNU General Public License does not permit incorporating your program
+into proprietary programs.  If your program is a subroutine library, you
+may consider it more useful to permit linking proprietary applications with
+the library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.  But first, please read
+<https://www.gnu.org/licenses/why-not-lgpl.html>.

MANIFEST.json

@@ -1,16 +1,16 @@
 {
   "manifest_version": 1,
   "name": "skill-catalog",
-  "summary": "技能目录站：把对外发布的技能生成一个静态站（能干什么 / 先装什么 / 要配什么 / 依赖谁 / 一条安装命令），生成物不手改页面。",
+  "summary": "技能目录站：把对外发布的技能发布成一个自托管目录站（动态服务从 catalog.json 现渲染，附同源静态快照；能干什么 / 先装什么 / 要配什么 / 依赖谁 / 一条安装命令）。",
   "tier": 1,
   "status": "stable",
-  "version": "f7a6763",
+  "version": "5979776",
   "source": {
     "path": "skills/skill-catalog",
-    "commit": "f7a6763",
+    "commit": "5979776",
-    "describe": "f7a6763",
+    "describe": "5979776",
     "dirty": false,
-    "packed_at": "2026-10-02T01:30:47.222Z"
+    "packed_at": "2026-10-02T06:28:52.768Z"
   },
   "platforms": [
     "darwin",
@@ -21,6 +21,7 @@
   },
   "commands": [
     "build",
+    "serve",
     "preview",
     "deploy",
     "list",
@@ -55,23 +56,22 @@
       "kind": "runtime",
       "name": "node",
       "check": "which node",
-      "note": "生成器；零 npm 依赖"
+      "note": "生成器与动态服务（serve.mjs）；零 npm 依赖"
     },
     {
-      "kind": "runtime",
+      "kind": "binary",
-      "name": "python3",
+      "name": "ssh",
-      "check": "which python3",
+      "note": "部署两跳（relay→host）"
-      "note": "预览用的本地文件服务；部署时的 tar/ssh 走系统命令"
     },
     {
       "kind": "binary",
       "name": "tar",
-      "note": "部署打包（tar）与字体下载/上线自检（curl）"
+      "note": "部署打包（tar -czf）"
     },
     {
       "kind": "binary",
       "name": "curl",
-      "note": "部署打包（tar）与字体下载/上线自检（curl）"
+      "note": "字体下载与上线自检"
     }
   ],
   "config": [
@@ -140,6 +140,9 @@
       },
       "preview": {
         "destructive": false
+      },
+      "serve": {
+        "destructive": false
       }
     },
     "errors": [
@@ -163,23 +166,23 @@
   "files": [
     {
       "path": "REFERENCE.md",
-      "bytes": 7578,
+      "bytes": 11893,
-      "sha256": "759ac4d91bed48ae"
+      "sha256": "c806054f279dcada"
     },
     {
       "path": "SKILL.md",
-      "bytes": 1675,
+      "bytes": 2403,
-      "sha256": "66ae1ca77fa750af"
+      "sha256": "96a3073371298415"
     },
     {
       "path": "VERSION",
       "bytes": 6,
-      "sha256": "80447316529fc620"
+      "sha256": "71015c979ccb0fc8"
     },
     {
       "path": "assets/app.js",
-      "bytes": 4601,
+      "bytes": 5959,
-      "sha256": "78a507c30e6c9cf9"
+      "sha256": "b71e5e72195ac896"
     },
     {
       "path": "assets/favicon.svg",
@@ -188,28 +191,38 @@
     },
     {
       "path": "assets/style.css",
-      "bytes": 16997,
+      "bytes": 18199,
-      "sha256": "dfe35d419987cc81"
+      "sha256": "30fb9ce3372853be"
     },
     {
       "path": "contract.lock.json",
-      "bytes": 616,
+      "bytes": 665,
-      "sha256": "8ad8365c09c32df8"
+      "sha256": "c6382f8fc3c51e72"
     },
     {
       "path": "interface.json",
-      "bytes": 2780,
+      "bytes": 2971,
-      "sha256": "1417b2ba9c473218"
+      "sha256": "b11b6b8159063f4d"
+    },
+    {
+      "path": "scripts/render.mjs",
+      "bytes": 17690,
+      "sha256": "6bc3942aa699352c"
+    },
+    {
+      "path": "scripts/serve.mjs",
+      "bytes": 10875,
+      "sha256": "4d402a4895b0b8d7"
     },
     {
       "path": "scripts/setup-hosting.sh",
-      "bytes": 1366,
+      "bytes": 5019,
-      "sha256": "911b62832db699d6"
+      "sha256": "a09e464174c95a99"
     },
     {
       "path": "scripts/skill-catalog.mjs",
-      "bytes": 37551,
+      "bytes": 26192,
-      "sha256": "7bdd12c1aeea89c5"
+      "sha256": "19c681002e68a1e4"
     }
   ],
   "leak_scan": {

README.md

@@ -1,14 +1,36 @@
 # skill-catalog
 
-技能目录站：把对外发布的技能生成一个静态站（能干什么 / 先装什么 / 要配什么 / 依赖谁 / 一条安装命令），生成物不手改页面。
+技能目录站：把对外发布的技能发布成一个自托管目录站（动态服务从 catalog.json 现渲染，附同源静态快照；能干什么 / 先装什么 / 要配什么 / 依赖谁 / 一条安装命令）。
 
-以 Pi package（技能形态）发布。
+以 Pi package（技能形态）发布。技能本体在 `skills/skill-catalog/`。
-技能本体在 `skills/skill-catalog/`，用法见其 `SKILL.md` 与 `REFERENCE.md`。
+
+- 平台：macOS / Linux
+- 许可：GPL-3.0-or-later（全文见 [LICENSE](LICENSE)）
 
 ## 安装
 
 ```sh
-pi install git:gitea.vhkd.top/pi-hub/skill-catalog.git@v0.1.1
+pi install git:gitea.vhkd.top/pi-hub/skill-catalog.git@v0.2.1
 ```
 
 装完 `pi-skill list` 能看到 `skill-catalog`，`pi-skill skill-catalog check` 会告诉还缺什么。
+
+## 先准备什么
+
+- `node`（运行环境），生成器与动态服务（serve.mjs）；零 npm 依赖
+- `ssh`（命令），部署两跳（relay→host）
+- `tar`（命令），部署打包（tar -czf）
+- `curl`（命令），字体下载与上线自检
+
+## 常用命令
+
+| 命令 | 说明 |
+|---|---|
+| `build` | 生成 dist：catalog.json + assets + serve.mjs + 静态快照（只收录声明了 publish 的技能） |
+| `serve` | 本地跑动态服务：从 catalog.json 现渲染，带 /api/skills 与 /healthz |
+| `preview` | 生成并本地动态预览目录站 |
+| `deploy` | 把 dist 发布到部署目标（relay→host，release + current 切换，systemd 服务自动重启） |
+| `list` | 收录清单与依赖闭包状态 |
+| `check` | 只读自检：收录规则、部署目标与线上健康 |
+
+用法与对外契约见技能内的 `SKILL.md` 与 `REFERENCE.md`。

package.json

@@ -1,5 +1,27 @@
 {
   "name": "skill-catalog",
-  "version": "0.1.1",
+  "version": "0.2.1",
-  "description": "技能目录站：把对外发布的技能生成一个静态站（能干什么 / 先装什么 / 要配什么 / 依赖谁 / 一条安装命令），生成物不手改页面。"
+  "description": "技能目录站：把对外发布的技能发布成一个自托管目录站（动态服务从 catalog.json 现渲染，附同源静态快照；能干什么 / 先装什么 / 要配什么 / 依赖谁 / 一条安装命令）。",
+  "license": "GPL-3.0-or-later",
+  "keywords": [
+    "pi-package",
+    "skill-catalog",
+    "macos",
+    "linux"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://gitea.vhkd.top/pi-hub/skill-catalog.git"
+  },
+  "files": [
+    "skills",
+    "LICENSE",
+    "README.md",
+    "MANIFEST.json"
+  ],
+  "pi": {
+    "skills": [
+      "skills/skill-catalog"
+    ]
+  }
 }

skills/skill-catalog/REFERENCE.md

@@ -7,13 +7,23 @@ skills/*/interface.json（publish / summary / useWhen / commands / requires / co
         + VERSION + contract.lock.json
         │  skill-catalog build
         ▼
-   dist/（index.html + skills/<名字>.html + catalog.json + assets/）   ← 生成物，不手改
+   dist/ = catalog.json + assets/ + serve.mjs + render.mjs（+ 静态快照 index.html / skills/*.html）
         │  skill-catalog deploy（tar 走 relay→host）
         ▼
-   目标机 <deploy_path>/releases/<时间戳>/ ，再切 <deploy_path>/current 软链
+   目标机 <deploy_path>/releases/<时间戳>/ ，再切 <deploy_path>/current 软链（保留最近 5 份）
+        │  systemd 常驻：node current/serve.mjs --root current --port 8788
+        ▼
+   Caddy：pi.vhkd.top → reverse_proxy 127.0.0.1:8788
 ```
 
-`catalog.json` 是同一份数据给机器读的版本；页面只是它的视图。
+- **catalog.json 是唯一数据源**：首页、详情、404 都由 `serve.mjs` 每次请求用 `render.mjs` 现渲染；
+  静态快照与动态服务共用同一份渲染函数，只用于过渡与回退，线上以动态服务为准。
+- **服务端只拿公开快照**：catalog.json + assets + 两个服务端脚本（serve.mjs / render.mjs）；
+  skills 仓库不上服务器。
+- **内容与代码分离生效**：切 `current` 后不用重启就读到新内容（catalog 按 mtime+size 重读）；
+  服务端脚本随 release 走，`deploy` 检测到 systemd 服务在跑就踢一下进程，让它加载新代码重启。
+- **隐私门禁在 build**：生成后对整站跑 `skill-pack` 的泄漏扫描（密钥 / 真实家目录 / 工单号），
+  error 级直接拒绝产出。
 
 ## 1.1 分层（由依赖事实推导，不人为标注）
 
@@ -42,9 +52,24 @@ Hub 的名字按「Hub」取（`pi.vhkd.top`），不按单一资源种类；页
 [pi.dev/packages 画廊](https://pi.dev/packages)（`pi.image`/`pi.video` 可给预览图）。
 自建 Hub 的定位是「中文说明 + 前置依赖 + 分层关系 + 自托管」。
 
+## 1.3 服务路由（serve.mjs）
+
+| 路由 | 说明 |
+|---|---|
+| `GET /`、`/index.html` | 首页（现渲染） |
+| `GET /skills/<名>`、`/skills/<名>.html` | 条目详情（现渲染）；未知 → 404 页 |
+| `GET /api/skills` | 整个 catalog.json（机器可读） |
+| `GET /api/skills/<名>` | 单个条目；未知 → 404 JSON |
+| `GET /healthz` | `{status, skills, generated_at, uptime_s}`；catalog 读不出来 → 503 |
+| `GET /robots.txt`、`/sitemap.xml` | 由 catalog 现生成 |
+| `GET /assets/*` | css/js/字体（字体 24h、其余 10min 缓存；只允许 assets 目录内） |
+| 其它 | 渲染成站内 404 页 |
+
+HTML 一律 `no-cache`，压缩交给 Caddy；`serve.mjs` 只监听 `127.0.0.1`，不直接对外。
+
 ## 2. 收录与依赖
 
-- **收录**：`publish.repo` 存在才收录（发布过才有仓可装）；没有 `VERSION` 的技能会被 warn。
+- **收录**：`publish.repo` 或 `publish.package_repo` 存在才收录（发布过才有仓可装）；没有 `VERSION` 的技能会被 warn。
 - **依赖闭包**：`dependsOn` 里出现**未公开**的技能 → 该技能标「依赖未公开，需自备」，
   不给安装命令（装完跑不起来比不装更糟）。要让它可装，先把它依赖的技能也公开。
 
@@ -58,38 +83,44 @@ Hub 的名字按「Hub」取（`pi.vhkd.top`），不按单一资源种类；页
 | 仓库地址、版本、安装命令 | 运行日志、私有数据文件 |
 
 生成后对整站跑 `skill-pack` 的泄漏扫描（密钥 / 真实家目录 / 工单号），error 级拒绝产出。
+上服务器的只有公开快照，没有 skills 仓库。
 
 ## 4. 配置与托管
 
 配置（`interface.json` 的 `config` 声明，值在 `local/skills/skill-catalog/config.json` 或
 `PI_SKILL_SKILL_CATALOG_<KEY>` 环境变量）：
 
-- `site_url`：站点公开地址（用于 canonical 与分享链接）；
+- `site_url`：站点公开地址（用于 canonical、sitemap 与分享链接）；
 - `deploy_relay` / `deploy_host`：部署两跳（默认 `lightos` → `aliyun-hk`，即 Gitea 那台阿里云香港机）；
 - `deploy_path`：目标目录（必填）。站点按 `releases/<时间戳>` + `current` 软链维护，保留最近 5 份。
 
-**现网事实（2026-10-02）**：站点跑在 Gitea 那台阿里云香港机（本地经 `lightos` 两跳 ssh，
+**现网事实（2026-10-02）**：站点跑在 Gitea 那台阿里云香港机（本地经 `lightos` 两跳 ssh，别名
-别名 `aliyun-hk`，公网 `47.243.111.1:22022`）；部署目录 `<部署目录>`
+`aliyun-hk`）；部署目录 `~/websites/skill-catalog`；服务端口 8788（只监听回环，
-（geekinney 可写）；Caddy 配置 `/etc/caddy/Caddyfile`（systemd `caddy`；改动需 sudo，先 `caddy validate`
+systemd 单元 `pi-hub`）；Caddy 配置 `/etc/caddy/Caddyfile` 里 `pi.vhkd.top` 是
-再 `systemctl reload caddy`）；`vhkd.top` 的 DNS 在万网（hichina）。内容更新只跑 `deploy`，不用动服务器。
+`encode zstd gzip` + `reverse_proxy 127.0.0.1:8788`（systemd `caddy`；改动需 sudo，先
+`caddy validate` 再 `systemctl reload caddy`）；`vhkd.top` 的 DNS 在万网（hichina）。
+内容更新只跑 `skill-catalog deploy`，不用再动服务器。
 
-**坑（实测 2026-10-02）**：站点根放在用户家目录下时，家目录若是 `0700`，Caddy 的 `file_server` 会 **403** ——
+**一次性托管**（目标机 root，幂等）：`scripts/setup-hosting.sh` 把三件事做完，可重复运行：
-证书能签、TLS 也通，只有内容取不到。修法是沿站点根的祖先链补 `o+x`（只给「可穿过」，不给读列表），
-`scripts/setup-hosting.sh` 已内置这一步；用 `namei -l <路径>` 一眼能看出是哪一级卡住。
 
-**托管（一次性，需目标机 root）**：Caddy 加一个站点块，把域名指到 `<deploy_path>/current`：
+1. 确保 Node（≥18）：机器上有就用；没有就装 LTS 到 `~/.local/node`（免 sudo）；
+2. 写 systemd 单元 `/etc/systemd/system/pi-hub.service`：`User=<部署用户>`，`ExecStart` 跑
+   `current/serve.mjs --root current --port 8788 --pidfile <部署目录>/server.pid`，`Restart=always`，
+   然后 `enable --now`；
+3. Caddy 的 `pi.vhkd.top` 站点块改成反代：`encode zstd gzip` + `reverse_proxy 127.0.0.1:8788`
+   （先备份、`caddy validate` 过了才落盘，失败自动回滚）。
 
-```caddyfile
+在部署目标上运行（需要 sudo 时会自己提权；先 `skill-catalog deploy` 把 release 推上去）：
-pi.vhkd.top {
+
-	encode zstd gzip
+```sh
-	root * <部署目录>/current
+bash ~/websites/skill-catalog/setup-hosting.sh
-	file_server
+curl -s https://pi.vhkd.top/healthz
-}
 ```
 
-DNS 加一条 `pi.vhkd.top A 47.243.111.1`（或先不加 DNS，用 IP/路径访问也行）。
+**排障**：`/healthz` 不是 JSON 或站点 502 → `systemctl status pi-hub`、`journalctl -u pi-hub -n 50`；
-改完 `caddy validate --config /etc/caddy/Caddyfile --adapter caddyfile && systemctl reload caddy`。
+端口占用看 `ss -ltnp | grep 8788`；回退只需 `ln -sfn releases/<旧戳> <部署目录>/current`。
-之后内容更新只走 `skill-catalog deploy`，不需要再动服务器。
+（历史坑：若退回 `file_server` 静态托管，站点根在家目录下时家目录若是 `0700`，Caddy 会 **403**，
+要沿站点根的祖先链补 `o+x`；用 `namei -l <路径>` 一眼能看出是哪一级卡住。）
 
 ## 4.1 字体（好看的前提）
 
@@ -109,9 +140,29 @@ DNS 加一条 `pi.vhkd.top A 47.243.111.1`（或先不加 DNS，用 IP/路径访
 - **双主题**：明暗各一套变量；`<head>` 里的引导脚本按「上次选择 → 系统偏好」在首帧前设好 `data-theme`，
   导航右侧按钮切换并记住（`localStorage: pi-hub-theme`）。新组件必须两套主题下都看过。
 
+## 4.3 产品级检查单（每次改页面前过一遍）
+
+- **没有点不动的按钮**：静态信息（依赖名、平台、层级说明）用 `.meta-chip`（无边框、不悬停），
+  可点的才用边框/底色；不确定能不能点的，就别做成按钮的形状。
+- **首屏动作要有意义**：安装示例固定取底座里最基础的一个（不是数组第一条），并明确标注「安装示例」。
+- **键盘与小屏**：`/` 聚焦搜索、`Esc` 清空；筛选写进 URL（`#core,tool`）可分享可回退；
+  移动端只收起文字链接，**主题开关与搜索必须留**。
+- **站点基础设施**：favicon、`theme-color`（明/暗两版）、OG/Twitter、`robots.txt`、`sitemap.xml`、canonical
+  —— 都由 `render.mjs` 生成（build 落盘、serve 现渲染），别手写。
+- **生成物不进版本库**：`dist/` 已 .gitignore；要发布就跑 `build` + `deploy`。
+- **无障碍最低线**：交互元素有 `aria-label`/`role`，状态用 `aria-pressed`；`focus-visible` 可见；
+  `prefers-reduced-motion` 关动效；**小字（faint/muted）在明暗两主题都要过 AA 对比度**。
+- **收集了就要展示**：`summary`/`useWhen`/`requires`/`config`/`license`/版本 都是页面内容的一部分，
+  少一个就是内容缺口；没有值就明说（「未标版本」「未声明许可」），不要留空。
+- **跳出去就新窗口**：外部链接一律 `target="_blank" rel="noreferrer"`；页脚标更新日期（catalog 的生成时间）。
+- **每个会点的控件都要先问「它到底做什么」**：筛选读的字段必须在检索文本里（否则就是死按钮）。
+- **动态与静态同源**：页面只在 `render.mjs` 里渲染；`build` 落盘与 `serve` 现渲染共用它，不许各写一套。
+
 ## 5. 想加东西往哪加
 
 - **新页面/新字段**：数据来自技能声明，先想清楚它是不是「声明里已经有的事实」——是就渲染，
-  不是就先补声明（别在生成器里造事实）。
+  不是就先补声明（别在生成器里造事实）。页面函数都在 `scripts/render.mjs`。
+- **新路由/接口**：改 `scripts/serve.mjs`（零依赖 Node HTTP）；写完补 `tests/catalog.test.mjs` 的行为断言。
 - **新主题**：改 `assets/style.css`（纯 CSS，无构建）；交互在 `assets/app.js`（搜索/筛选/复制）。
-- **换托管**：改 `deploy_relay`/`deploy_host`/`deploy_path` 三个配置，发布命令不变。
+- **换托管**：改 `deploy_relay`/`deploy_host`/`deploy_path` 三个配置，发布命令不变；
+  systemd 单元与 Caddy 站点块由 `scripts/setup-hosting.sh` 生成。

skills/skill-catalog/SKILL.md

@@ -4,28 +4,37 @@ platforms: [darwin, linux]
 
 # skill-catalog
 
-把「对外发布的技能」生成一个**静态目录站**：每个技能一页，写清能干什么、先装什么、
+把「对外发布的技能」发布成一个**自托管目录站**（https://pi.vhkd.top）：每个技能一页，写清能干什么、
-要配什么、依赖谁、一条安装命令。页面是生成物（`dist/`），永远不手改。
+先装什么、要配什么、依赖谁、一条安装命令。线上是 `serve.mjs` 常驻进程（Node HTTP，从 `catalog.json`
+每次请求现渲染，带 `/api/skills` 与 `/healthz`）；`build` 另落一份同源静态快照（过渡与回退用）。
+页面由声明生成，永不手改。
 
-**收录规则**：只有 `interface.json` 里声明了 `publish.repo` 的技能才上页（见
+**收录规则**：只有 `interface.json` 里声明了 `publish` 的技能才上页（见
 skill-interface 的 REFERENCE §12）。依赖里出现未公开的技能会在页面上标出来且不给安装命令。
 
 ## 首次使用
 
 1. 想公开的技能，在它的 `interface.json` 里声明 `publish`（repo 是 CLI 仓，包仓名默认去 `-cli`）；
-2. `pi-skill skill-catalog check` —— 看收录规则与部署目标有没有配好（缺 `deploy_path` 会告诉你）；
+2. `pi-skill skill-catalog check` —— 看收录规则、部署目标与线上健康（缺 `deploy_path` 会告诉你）；
-3. `pi-skill skill-catalog build` 生成，`pi-skill skill-catalog preview` 本地看效果；
+3. `pi-skill skill-catalog build` 生成，`pi-skill skill-catalog preview` 本地动态预览；
-4. `pi-skill skill-catalog deploy` 发布（走 relay→host 两跳，release 目录 + `current` 软链切换）。
+4. `pi-skill skill-catalog deploy` 发布（relay→host 两跳，release 目录 + `current` 软链切换；
+   内容切换不用重启，代码变了 deploy 会踢一下 systemd 进程）。
+
+**服务器托管（一次性）**：目标机要跑 `serve.mjs` 的 systemd 单元、Caddy 用
+`reverse_proxy 127.0.0.1:8788` 反代；`scripts/setup-hosting.sh` 幂等完成（含没有 Node 时自动装），
+见 REFERENCE「托管」。
 
 ## 页面上的隐私边界
 
 - **只出现声明元数据**：摘要、用法、命令、依赖、要配的键名（不含值）、版本、仓库地址；
 - **不渲染 REFERENCE 全文**，设置值一概不上页；
-- 生成后整站过一遍泄漏扫描（密钥 / 真实家目录 / 工单号），error 级直接拒绝产出。
+- 生成后整站过一遍泄漏扫描（密钥 / 真实家目录 / 工单号），error 级直接拒绝产出；
+- 上服务器的只有公开快照（catalog.json + assets + 服务代码），没有 skills 仓库。
 
 ## 失败 → 动作
 
 - `error=usage` → `pi-skill skill-catalog help`；
 - 生成被拦（`blocked: …`）→ 检查技能声明里是否混进了密钥或真实家目录，页面只该出现声明元数据；
-- 部署失败 → 确认 `deploy_relay`/`deploy_host` 能 ssh、`deploy_path` 可写；Caddy 站点根的
+- 部署失败 → 确认 `deploy_relay`/`deploy_host` 能 ssh、`deploy_path` 可写；
-  一次性配置见 REFERENCE「托管」。
+- 线上 502 或 `/healthz` 不是 JSON → 看目标机 `systemctl status pi-hub` 与 `journalctl -u pi-hub -n 50`；
+  一次性配置见 REFERENCE §4。

skills/skill-catalog/VERSION

@@ -1 +1 @@
-0.1.1
+0.2.1

skills/skill-catalog/assets/app.js

@@ -6,10 +6,76 @@
   const sections = [...document.querySelectorAll('.layer-section')];
   const cards = [...document.querySelectorAll('.card')];
   const reqFilters = [...document.querySelectorAll('.chip[data-requires]')];
+  const platformFilters = [...document.querySelectorAll('.chip[data-platform]')];
   const layerFilters = [...document.querySelectorAll('.seg[data-layer-filter]')];
+  // 主题切换：写进 <html data-theme> 并记住；引导脚本已在首帧前设好初值。
+  const toggle = document.getElementById('theme-toggle');
+  toggle?.addEventListener('click', () => {
+    const root = document.documentElement;
+    const next = root.dataset.theme === 'dark' ? 'light' : 'dark';
+    root.dataset.theme = next;
+    try {
+      localStorage.setItem('pi-hub-theme', next);
+    } catch {
+      /* 隐私模式下存不了就只在本次会话生效 */
+    }
+  });
+
+  // 键盘：/ 聚焦搜索，Esc 清空并退出；筛选状态写进 URL（可分享/可回退）。
+  document.addEventListener('keydown', event => {
+    const typing = /^(INPUT|TEXTAREA|SELECT)$/.test(document.activeElement?.tagName ?? '');
+    if (event.key === '/' && !typing) {
+      event.preventDefault();
+      search?.focus();
+      search?.select();
+    } else if (event.key === 'Escape' && (typing || search?.value)) {
+      if (search) {
+        search.value = '';
+        apply();
+        if (typing) search.blur();
+      }
+    }
+  });
+
+  const syncHash = () => {
+    const hash = activeLayers.size ? `#${[...activeLayers].sort().join(',')}` : '';
+    if (location.hash !== hash) history.replaceState(null, '', `${location.pathname}${location.search}${hash}`);
+  };
+  const readHash = () => {
+    const wanted = location.hash.replace(/^#/, '').split(',').map(s => s.trim()).filter(Boolean);
+    for (const chip of platformFilters) {
+    chip.addEventListener('click', () => {
+      const value = chip.dataset.platform;
+      if (activePlatforms.has(value)) activePlatforms.delete(value);
+      else activePlatforms.add(value);
+      chip.classList.toggle('active', activePlatforms.has(value));
+      chip.setAttribute('aria-pressed', String(activePlatforms.has(value)));
+      apply();
+    });
+  }
+  for (const chip of layerFilters) {
+      const layer = chip.dataset.layerFilter;
+      if (wanted.includes(layer)) {
+        activeLayers.add(layer);
+        chip.classList.add('active');
+        chip.setAttribute('aria-pressed', 'true');
+      }
+    }
+  };
+  for (const chip of layerFilters) {
+    chip.addEventListener('click', () => {
+      chip.setAttribute('aria-pressed', String(activeLayers.has(chip.dataset.layerFilter)));
+      syncHash();
+    });
+  }
+  window.addEventListener('hashchange', () => location.reload());
+  readHash();
+  if (activeLayers.size) apply();
+
   if (!cards.length) return;
   const activeRequires = new Set();
   const activeLayers = new Set();
+  const activePlatforms = new Set();
 
   const apply = () => {
     const query = (search?.value ?? '').trim().toLowerCase();
@@ -19,7 +85,9 @@
       const matchQuery = !query || haystack.includes(query);
       const matchRequires = activeRequires.size === 0 || [...activeRequires].every(name => haystack.includes(name.toLowerCase()));
       const matchLayer = activeLayers.size === 0 || activeLayers.has(card.dataset.layer);
-      const visible = matchQuery && matchRequires && matchLayer;
+      const cardPlatforms = (card.dataset.platforms ?? '').split(' ').filter(Boolean);
+      const matchPlatform = activePlatforms.size === 0 || [...activePlatforms].some(value => cardPlatforms.includes(value));
+      const visible = matchQuery && matchRequires && matchLayer && matchPlatform;
       card.hidden = !visible;
       if (visible) shown += 1;
     }
@@ -28,6 +96,8 @@
     }
     if (count) count.textContent = String(shown);
     if (empty) empty.hidden = shown !== 0;
+    const clear = document.getElementById('clear-filters');
+    if (clear) clear.hidden = activeLayers.size + activeRequires.size + activePlatforms.size === 0;
   };
 
   search?.addEventListener('input', apply);
@@ -64,59 +134,18 @@
     });
   }
 
-  // 主题切换：写进 <html data-theme> 并记住；引导脚本已在首帧前设好初值。
+  document.getElementById('clear-filters')?.addEventListener('click', () => {
-  const toggle = document.getElementById('theme-toggle');
+    activeLayers.clear();
-  toggle?.addEventListener('click', () => {
+    activeRequires.clear();
-    const root = document.documentElement;
+    activePlatforms.clear();
-    const next = root.dataset.theme === 'dark' ? 'light' : 'dark';
+    for (const chip of [...layerFilters, ...reqFilters, ...platformFilters]) {
-    root.dataset.theme = next;
+      chip.classList.remove('active');
-    try {
+      chip.setAttribute('aria-pressed', 'false');
-      localStorage.setItem('pi-hub-theme', next);
-    } catch {
-      /* 隐私模式下存不了就只在本次会话生效 */
     }
+    if (search) search.value = '';
+    history.replaceState(null, '', location.pathname);
+    apply();
   });
 
-  // 键盘：/ 聚焦搜索，Esc 清空并退出；筛选状态写进 URL（可分享/可回退）。
-  document.addEventListener('keydown', event => {
-    const typing = /^(INPUT|TEXTAREA|SELECT)$/.test(document.activeElement?.tagName ?? '');
-    if (event.key === '/' && !typing) {
-      event.preventDefault();
-      search?.focus();
-      search?.select();
-    } else if (event.key === 'Escape' && (typing || search?.value)) {
-      if (search) {
-        search.value = '';
-        apply();
-        if (typing) search.blur();
-      }
-    }
-  });
-
-  const syncHash = () => {
-    const hash = activeLayers.size ? `#${[...activeLayers].sort().join(',')}` : '';
-    if (location.hash !== hash) history.replaceState(null, '', `${location.pathname}${location.search}${hash}`);
-  };
-  const readHash = () => {
-    const wanted = location.hash.replace(/^#/, '').split(',').map(s => s.trim()).filter(Boolean);
-    for (const chip of layerFilters) {
-      const layer = chip.dataset.layerFilter;
-      if (wanted.includes(layer)) {
-        activeLayers.add(layer);
-        chip.classList.add('active');
-        chip.setAttribute('aria-pressed', 'true');
-      }
-    }
-  };
-  for (const chip of layerFilters) {
-    chip.addEventListener('click', () => {
-      chip.setAttribute('aria-pressed', String(activeLayers.has(chip.dataset.layerFilter)));
-      syncHash();
-    });
-  }
-  window.addEventListener('hashchange', () => location.reload());
-  readHash();
-  if (activeLayers.size) apply();
-
   apply();
 })();

skills/skill-catalog/assets/style.css

@@ -12,7 +12,7 @@
   --ink: #1b1e24;
   --ink-2: #454b56;
   --muted: #767c88;
-  --faint: #a3a8b2;
+  --faint: #6f7683;   /* 正文小字也要过 AA 对比度 */
   --line: #e6e6e2;
   --line-2: #d2d2cd;
   --accent: #2f5bd7;
@@ -57,7 +57,7 @@
   --ink: #eceef2;
   --ink-2: #c2c7d0;
   --muted: #8b929e;
-  --faint: #6b7280;
+  --faint: #8a919e;
   --line: #26292e;
   --line-2: #383c43;
   --accent: #93aaff;
@@ -98,13 +98,21 @@ h1 { font-size: clamp(26px, 3.2vw, var(--t-2xl)); line-height: 1.1; letter-spaci
 
 /* 标签 / 导航 / 元信息：等宽小字，字距拉开，全大写。 */
 .label, .nav a, .nav-brand, .ver, .stat, .count, .panel-head, .badge, .rel, .eyebrow,
-.card-foot, .foot h4, .foot-line, .cmd-step {
+.foot h4, .foot-line, .cmd-step {
   font-family: var(--mono);
-  font-size: 11.5px;
+  font-size: var(--t-xs);
   letter-spacing: 0.12em;
   text-transform: uppercase;
 }
 
+/* 卡片脚注：等宽小字，但保持原样大小写（命令名不该被大写化） */
+.card-foot, .used {
+  font-family: var(--mono);
+  font-size: var(--t-xs);
+  letter-spacing: 0.04em;
+  text-transform: none;
+}
+
 a { color: inherit; text-decoration: none; }
 a:hover { color: var(--accent); }
 code { font-family: var(--mono); font-size: 0.86em; letter-spacing: 0; }
@@ -117,7 +125,7 @@ code { font-family: var(--mono); font-size: 0.86em; letter-spacing: 0; }
 .nav {
   position: sticky; top: 0; z-index: 10;
   display: flex; align-items: center; justify-content: space-between; gap: var(--s-5);
-  padding: var(--s-4) 0; margin-bottom: var(--s-8);
+  padding: var(--s-3) 0; margin-bottom: var(--s-6);
   border-bottom: 1px solid var(--line);
   background: color-mix(in srgb, var(--bg) 88%, transparent);
   backdrop-filter: blur(10px);
@@ -145,8 +153,8 @@ code { font-family: var(--mono); font-size: 0.86em; letter-spacing: 0; }
 [data-theme="dark"] .icon-sun { display: none; }
 
 /* ── 主视觉 ───────────────────────────────────────── */
-.masthead { margin-bottom: var(--s-7); }
+.masthead { margin-bottom: var(--s-6); }
-.eyebrow { color: var(--faint); margin: 0 0 20px; }
+.eyebrow { color: var(--faint); margin: 0 0 var(--s-4); }
 .lede { color: var(--ink-2); font-size: var(--t-md); margin: 0 0 var(--s-5); max-width: var(--measure-tight); }
 
 .cta {
@@ -210,33 +218,41 @@ button.chip:hover { color: var(--ink); border-color: var(--line-2); }
 button.chip.active { color: var(--accent); border-color: currentColor; }
 .chip-warn { color: var(--warn); border-color: color-mix(in srgb, var(--warn) 40%, transparent); }
 
-/* ── 分区面板 ─────────────────────────────────────── */
+/* ── 分区与卡片 ───────────────────────────────────── */
-.panel { border: 1px solid var(--line); border-radius: var(--radius); background: var(--surface); margin-bottom: var(--s-5); overflow: hidden; }
+.layer-section { margin: 0 0 var(--s-7); }
-.panel-head {
+.layer-head {
-  display: flex; align-items: center; gap: 10px;
+  display: flex; align-items: baseline; gap: var(--s-2);
-  padding: 11px 16px; border-bottom: 1px solid var(--line);
+  padding-bottom: var(--s-2); margin-bottom: var(--s-4);
-  color: var(--ink-2); background: var(--surface-2);
+  border-bottom: 1px solid var(--line);
 }
-.panel-count { color: var(--faint); }
+.layer-section .label { color: var(--ink-2); }
-.panel-hint { margin-left: auto; color: var(--faint); letter-spacing: .04em; text-transform: none; font-family: var(--kai); font-size: 12.5px; }
+.layer-count { color: var(--faint); }
-.grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(292px, 1fr)); }
+.layer-why {
+  margin-left: auto; color: var(--faint); font-size: var(--t-sm);
+  font-family: var(--kai); letter-spacing: 0; text-transform: none;
+}
+
+.grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(300px, 1fr)); gap: var(--s-4); }
 .card {
   display: flex; flex-direction: column; gap: var(--s-2);
   padding: var(--s-4) var(--s-5) var(--s-4);
-  border-right: 1px solid var(--line); border-bottom: 1px solid var(--line);
+  border: 1px solid var(--line); border-radius: var(--radius);
-  transition: background .15s;
+  background: var(--surface);
+  transition: border-color .15s, background .15s, transform .15s;
 }
-.card:hover { background: var(--surface-2); }
+.card:hover { border-color: var(--line-2); background: var(--surface-2); transform: translateY(-1px); }
-.card-top { display: flex; align-items: baseline; justify-content: space-between; gap: 10px; }
+.card-top { display: flex; align-items: baseline; justify-content: space-between; gap: var(--s-2); }
 .card h3 { margin: 0; font-family: var(--mono); font-size: 15px; letter-spacing: 0; }
 .card .ver { color: var(--faint); }
 .card .summary {
   margin: 0; color: var(--ink-2); font-size: var(--t-sm); line-height: 1.8;
   display: -webkit-box; -webkit-line-clamp: 2; -webkit-box-orient: vertical; overflow: hidden;
 }
-.card-foot { display: flex; align-items: center; gap: 10px; flex-wrap: wrap; color: var(--faint); margin-top: auto; padding-top: 4px; }
+.card-foot {
+  display: flex; align-items: center; gap: var(--s-2); flex-wrap: wrap;
+  color: var(--faint); margin-top: auto; padding-top: var(--s-2);
+}
 .card-layer { display: inline-flex; align-items: center; gap: 6px; color: var(--muted); letter-spacing: .08em; }
-.card-foot .chip { padding: 1px 8px; font-size: 11px; letter-spacing: .04em; text-transform: none; }
 .used { margin-left: auto; }
 
 /* ── 详情页 ───────────────────────────────────────── */
@@ -356,3 +372,24 @@ button.chip.active { color: var(--accent); border-color: currentColor; }
   .nav-links { gap: 0; }
   .nav-links a { display: none; }
 }
+
+/* 筛选行：先说清是什么，再给「清除」出口 */
+.chipbar { align-items: center; }
+.chip-label {
+  font-family: var(--mono); font-size: var(--t-xs); letter-spacing: .12em;
+  text-transform: uppercase; color: var(--faint); margin-right: var(--s-1);
+}
+.chip.clear { color: var(--muted); border-style: dashed; }
+.chip.clear:hover { color: var(--ink); border-style: solid; }
+
+/* 详情页：什么时候用（收集了就必须展示） */
+.use-when { margin: 0 0 var(--s-4); color: var(--muted); font-size: var(--t-sm); max-width: var(--measure); }
+.use-when .label { color: var(--faint); margin-right: var(--s-2); }
+
+/* 平台便签：一眼看出支持哪些系统 */
+.platform-badge {
+  font-family: var(--mono); font-size: 10.5px; letter-spacing: .04em;
+  color: var(--ink-2); border: 1px solid var(--line);
+  border-radius: 3px; padding: 0 6px;
+}
+.chip-sep { width: 1px; height: 16px; background: var(--line); margin: 0 var(--s-2); }

skills/skill-catalog/contract.lock.json

@@ -21,6 +21,9 @@
     },
     "preview": {
       "destructive": false
+    },
+    "serve": {
+      "destructive": false
     }
   },
   "errors": [

skills/skill-catalog/interface.json

@@ -1,5 +1,5 @@
 {
-  "summary": "技能目录站：把对外发布的技能生成一个静态站（能干什么 / 先装什么 / 要配什么 / 依赖谁 / 一条安装命令），生成物不手改页面。",
+  "summary": "技能目录站：把对外发布的技能发布成一个自托管目录站（动态服务从 catalog.json 现渲染，附同源静态快照；能干什么 / 先装什么 / 要配什么 / 依赖谁 / 一条安装命令）。",
   "useWhen": "要更新或发布技能目录页时；想看清哪些技能可公开、依赖闭包是否完整时。",
   "tier": 1,
   "entry": {
@@ -11,15 +11,19 @@
   "commands": [
     {
       "name": "build",
-      "summary": "生成静态站（只收录声明了 publish 的技能）"
+      "summary": "生成 dist：catalog.json + assets + serve.mjs + 静态快照（只收录声明了 publish 的技能）"
+    },
+    {
+      "name": "serve",
+      "summary": "本地跑动态服务：从 catalog.json 现渲染，带 /api/skills 与 /healthz"
     },
     {
       "name": "preview",
-      "summary": "生成并本地预览目录站"
+      "summary": "生成并本地动态预览目录站"
     },
     {
       "name": "deploy",
-      "summary": "把生成的站点发布到部署目标（relay→host，release + current 切换）"
+      "summary": "把 dist 发布到部署目标（relay→host，release + current 切换，systemd 服务自动重启）"
     },
     {
       "name": "list",
@@ -27,7 +31,7 @@
     },
     {
       "name": "check",
-      "summary": "只读自检：收录规则与部署目标配置"
+      "summary": "只读自检：收录规则、部署目标与线上健康"
     }
   ],
   "errors": [
@@ -81,26 +85,26 @@
       "kind": "runtime",
       "name": "node",
       "check": "which node",
-      "note": "生成器；零 npm 依赖"
+      "note": "生成器与动态服务（serve.mjs）；零 npm 依赖"
     },
     {
-      "kind": "runtime",
+      "kind": "binary",
-      "name": "python3",
+      "name": "ssh",
-      "check": "which python3",
+      "note": "部署两跳（relay→host）"
-      "note": "预览用的本地文件服务；部署时的 tar/ssh 走系统命令"
     },
     {
       "kind": "binary",
       "name": "tar",
-      "note": "部署打包（tar）与字体下载/上线自检（curl）"
+      "note": "部署打包（tar -czf）"
     },
     {
       "kind": "binary",
       "name": "curl",
-      "note": "部署打包（tar）与字体下载/上线自检（curl）"
+      "note": "字体下载与上线自检"
     }
   ],
   "publish": {
     "package_repo": "https://gitea.vhkd.top/pi-hub/skill-catalog.git"
-  }
+  },
+  "license": "GPL-3.0-or-later"
 }

skills/skill-catalog/scripts/render.mjs

@@ -0,0 +1,366 @@
+/**
+ * skill-catalog 的页面渲染（唯一定义处）：build 把它落盘成静态页，serve 每次请求现渲染。
+ * 纯函数、零依赖 —— 可以和 catalog.json 一起拷进部署目录，服务器上不需要 skills 仓库。
+ */
+export const BRAND = { name: 'Pi Hub', headline: 'Skill as Software', scope: '技能 · 扩展 · 主题 · 提示模板' };
+const SCOPE_HTML = '<span class="nowrap">技能 · 扩展 · 主题 · 提示模板</span>';
+
+export const LAYER_LABEL = { core: '底座', tool: '工具', app: '组合应用' };
+export const LAYER_HINT = {
+  core: '别的技能建在它上面',
+  tool: '独立可用，装完就用',
+  app: '由多个技能协作完成',
+};
+
+export const escapeHtml = value =>
+  String(value ?? '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+
+const kindLabel = { runtime: '运行环境', binary: '命令', service: '服务', account: '账号' };
+
+export const platformLabelOf = value =>
+  value === 'all' ? '全平台' : value === 'darwin' ? 'macOS' : value === 'win32' ? 'Windows' : value === 'linux' ? 'Linux' : value;
+
+function siteNav(depth = 0) {
+  const prefix = depth === 0 ? '' : '../';
+  return `<nav class="nav">
+  <a class="nav-brand" href="${prefix}index.html"><span class="brand-mark">π</span><span><strong>${BRAND.name}</strong><em>${BRAND.scope}</em></span></a>
+  <div class="nav-links">
+    <a href="${prefix}index.html">目录</a>
+    <a href="https://gitea.vhkd.top/pi-hub" target="_blank" rel="noreferrer">仓库</a>
+    <a href="https://pi.dev/packages" target="_blank" rel="noreferrer">官方画廊</a>
+    <button class="theme-toggle" id="theme-toggle" type="button" aria-label="切换明暗主题" title="切换明暗主题">
+      <svg class="icon-sun" viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="4.2"/><g stroke-linecap="round"><path d="M12 2.6v2.2M12 19.2v2.2M2.6 12h2.2M19.2 12h2.2M5.3 5.3l1.6 1.6M17.1 17.1l1.6 1.6M18.7 5.3l-1.6 1.6M6.9 17.1l-1.6 1.6"/></g></svg>
+      <svg class="icon-moon" viewBox="0 0 24 24" aria-hidden="true"><path d="M20 14.2A8.2 8.2 0 0 1 9.8 4a8.4 8.4 0 1 0 10.2 10.2Z"/></svg>
+    </button>
+  </div>
+</nav>`;
+}
+
+function siteFoot(depth = 0, generatedAt = '') {
+  const prefix = depth === 0 ? '' : '../';
+  const stamp = generatedAt ? `更新于 ${escapeHtml(generatedAt.slice(0, 10))} · ` : '';
+  return `<footer class="foot">
+  <div class="foot-cols">
+    <div><h4>关于</h4><p>这里收录的条目都从技能自己的声明生成，和仓库同步；页面不手改。</p></div>
+    <div><h4>资源</h4><ul>
+      <li><a href="https://pi.dev/packages" target="_blank" rel="noreferrer">官方画廊 pi.dev/packages</a></li>
+      <li><a href="https://gitea.vhkd.top/pi-hub" target="_blank" rel="noreferrer">Gitea 仓库</a></li>
+      <li><a href="${prefix}catalog.json">catalog.json（机器可读）</a></li>
+    </ul></div>
+    <div><h4>字体</h4><ul>
+      <li>中文 霞鹜文楷 Screen（OFL）</li>
+      <li>拉丁 Pragmata Pro（读者本机）</li>
+    </ul></div>
+  </div>
+  <p class="foot-line">${BRAND.name} · ${stamp}由 skill-catalog 从技能声明生成</p>
+</footer>`;
+}
+
+function pageShell({ title, description, body, siteUrl, depth = 0, fontsCss = null, generatedAt = '' }) {
+  const prefix = depth === 0 ? '' : '../';
+  return `<!doctype html>
+<html lang="zh-CN" data-theme="light">
+<head>
+<meta charset="utf-8">
+<script>
+  // 主题：跟随系统，用户切过就记住（在首帧前生效，避免闪一下）。
+  try {
+    var saved = localStorage.getItem('pi-hub-theme');
+    var theme = saved || (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
+    document.documentElement.dataset.theme = theme;
+  } catch (e) {}
+</script>
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)}</title>
+<meta name="description" content="${escapeHtml(description)}">
+${fontsCss ? fontsCss.map(href => `<link rel="stylesheet" href="${prefix}assets/${href}">`).join('\n') : ''}
+<link rel="icon" href="${prefix}assets/favicon.svg" type="image/svg+xml">
+<meta name="theme-color" content="#fbfbf9" media="(prefers-color-scheme: light)">
+<meta name="theme-color" content="#101114" media="(prefers-color-scheme: dark)">
+<meta property="og:type" content="website">
+<meta property="og:title" content="${escapeHtml(title)}">
+<meta property="og:description" content="${escapeHtml(description)}">
+${siteUrl ? `<meta property="og:url" content="${escapeHtml(siteUrl)}">` : ''}
+<meta name="twitter:card" content="summary">
+<link rel="stylesheet" href="${prefix}assets/style.css">
+${siteUrl ? `<link rel="canonical" href="${escapeHtml(siteUrl)}">` : ''}
+</head>
+<body>
+<div class="page">
+${siteNav(depth)}
+${body}
+${siteFoot(depth, generatedAt)}
+</div>
+<script src="${prefix}assets/app.js"></script>
+</body>
+</html>
+`;
+}
+
+function cardOf(entry) {
+  const platformLabel = entry.platforms.includes('all')
+    ? '全平台'
+    : entry.platforms.length
+      ? entry.platforms.map(platformLabelOf).join('/')
+      : '未声明平台';
+  const facts = [
+    `<span class="platform-badge" title="支持平台">${escapeHtml(platformLabel)}</span>`,
+    ...entry.requires.slice(0, 3).map(item => `<span class="meta-chip">${escapeHtml(item.name)}</span>`),
+    ...(entry.installable ? [] : ['<span class="meta-chip meta-chip-warn">依赖未公开</span>']),
+  ].join('');
+  const used = entry.usedByCount ? `<span class="used">被 ${entry.usedByCount} 个技能使用</span>` : '';
+  return `<a class="card" href="skills/${escapeHtml(entry.name)}.html" data-layer="${entry.layer}"
+      data-platforms="${escapeHtml(entry.platforms.join(' '))}"
+      data-search="${escapeHtml(
+        `${entry.name} ${entry.summary} ${entry.useWhen} ${entry.layer} ${entry.commands.map(c => c.name).join(' ')} ${entry.requires.map(r => r.name).join(' ')} ${platformLabel}`,
+      )}">
+  <div class="card-top"><h3>${escapeHtml(entry.name)}</h3><span class="ver">v${escapeHtml(entry.version)}</span></div>
+  <p class="summary">${escapeHtml(entry.summary)}</p>
+  <div class="card-foot">
+    <span class="card-layer"><span class="dot"></span>${LAYER_LABEL[entry.layer]}</span>
+    ${facts}${used}
+  </div>
+</a>`;
+}
+
+export function renderDetailPage({ entry, byName, siteUrl = '', fontsCss = null, generatedAt = '' }) {
+  const steps = entry.installOrder.map(name => byName.get(name)).filter(Boolean);
+  const together =
+    steps.length > 1
+      ? `<div class="well together">
+  <p class="well-title">一次装齐 <span class="muted">按顺序执行 ${steps.length} 条</span></p>
+${steps
+  .map(
+    (item, index) =>
+      `  <div class="cmd"><span class="cmd-step">${index + 1}</span><code>${escapeHtml(item.install.pi)}</code><span class="cmd-tag">${item.name === entry.name ? '本体' : '依赖'}</span></div>`,
+  )
+  .join('\n')}
+  <div class="well-foot"><button class="copy primary" data-copy="${escapeHtml(steps.map(item => item.install.pi).join('\n'))}">复制这 ${steps.length} 条</button></div>
+</div>`
+      : '';
+
+  const installRows = [
+    entry.install.pi
+      ? `<div class="cmd"><span class="cmd-step">Pi</span><code>${escapeHtml(entry.install.pi)}</code><button class="copy" data-copy="${escapeHtml(entry.install.pi)}">复制</button></div>`
+      : '',
+    entry.install.cli
+      ? `<div class="cmd"><span class="cmd-step">CLI</span><code>${escapeHtml(entry.install.cli)}</code><button class="copy" data-copy="${escapeHtml(entry.install.cli)}">复制</button></div>`
+      : '',
+  ].join('\n');
+  const installBlock = entry.installable
+    ? `${together}
+<div class="well">
+${installRows}
+  <p class="well-note">装完跑 <code>pi-skill ${escapeHtml(entry.name)} check</code>${entry.install.cli ? `（Pi）或 <code>${escapeHtml(entry.name)} help</code>（命令行）` : ''}。</p>
+</div>`
+    : `<div class="well blocked"><p><strong>依赖未公开组件</strong>，单独装跑不起来，暂不提供安装命令。</p></div>`;
+
+  const requires = entry.requires.length
+    ? `<div class="facts">${entry.requires
+        .map(
+          item => `<div class="fact">
+  <div class="fact-head"><span class="fact-name">${escapeHtml(item.name)}</span><span class="fact-kind">${escapeHtml(kindLabel[item.kind] ?? item.kind)}</span></div>
+  ${item.note ? `<p class="muted">${escapeHtml(item.note)}</p>` : ''}
+  ${item.install ? `<code class="inline-cmd">${escapeHtml(item.install)}</code>` : ''}
+</div>`,
+        )
+        .join('')}</div>`
+    : '<p class="muted">用系统已有的东西即可，没有额外依赖。</p>';
+
+  const config = entry.config.length
+    ? `<div class="facts">${entry.config
+        .map(
+          item => `<div class="fact">
+  <div class="fact-head"><span class="fact-name mono">${escapeHtml(item.key)}</span>
+    ${item.required ? '<span class="badge badge-req">必配</span>' : '<span class="badge">可选</span>'}
+    ${item.secret ? '<span class="badge">私密</span>' : ''}</div>
+  <p class="muted">${escapeHtml(item.desc)}</p>
+  ${item.ask ? `<p class="ask">${escapeHtml(item.ask)}</p>` : ''}
+</div>`,
+        )
+        .join('')}</div>`
+    : '<p class="muted">装完即用，不需要提前配置。</p>';
+
+  const relations = `<ul class="relations">
+${
+    entry.usesPublic
+      .map(name => `<li><span class="rel rel-depend">依赖</span><a href="${escapeHtml(name)}.html">${escapeHtml(name)}</a></li>`)
+      .join('\n')
+  }
+${
+    entry.usedBy
+      .map(name => `<li><span class="rel rel-used">被用</span><a href="${escapeHtml(name)}.html">${escapeHtml(name)}</a></li>`)
+      .join('\n')
+  }
+${entry.usesPublic.length || entry.usedBy.length ? '' : '<li class="muted">独立可用，不和其它技能往来。</li>'}
+</ul>`;
+
+  const commands = entry.commands.length
+    ? `<table class="commands"><tbody>${entry.commands
+        .map(
+          command =>
+            `<tr><td class="cmd-cell"><code>${escapeHtml(command.name)}</code>${command.destructive ? '<span class="badge">会改状态</span>' : ''}</td><td>${escapeHtml(command.summary)}</td></tr>`,
+        )
+        .join('')}</tbody></table>`
+    : '';
+
+  const body = `<header class="detail-head">
+  <a class="back" href="../index.html">← 全部技能</a>
+  <div class="title-row">
+    <h1>${escapeHtml(entry.name)}</h1>
+    ${entry.version ? `<span class="ver">v${escapeHtml(entry.version)}</span>` : '<span class="ver">未标版本</span>'}
+  </div>
+  <p class="lede">${escapeHtml(entry.summary)}</p>
+  ${entry.useWhen ? `<p class="use-when"><span class="label">什么时候用</span>${escapeHtml(entry.useWhen)}</p>` : ''}
+  <div class="chips">
+    <span class="chip layer-${entry.layer}">${LAYER_LABEL[entry.layer]}</span>
+    <span class="meta-chip">${LAYER_HINT[entry.layer]}</span>
+    ${entry.status !== 'stable' ? `<span class="meta-chip meta-chip-warn">${entry.status === 'experimental' ? '实验性' : '将退役'}</span>` : ''}
+    ${entry.platforms.map(platform => `<span class="meta-chip">${escapeHtml(platformLabelOf(platform))}</span>`).join('')}
+  </div>
+</header>
+<div class="detail-grid">
+  <article>
+    <section class="block"><h2>怎么装</h2>${installBlock}</section>
+    <section class="block"><h2>先准备什么</h2>${requires}</section>
+    <section class="block"><h2>要先配什么</h2>${config}</section>
+    ${commands ? `<section class="block"><h2>常用命令</h2>${commands}</section>` : ''}
+  </article>
+  <aside>
+    <div class="panel side"><div class="panel-head"><span class="label">关系</span></div><div class="panel-body">${relations}</div></div>
+    <div class="panel side"><div class="panel-head"><span class="label">许可</span></div><div class="panel-body">
+      <p class="muted small">${entry.license ? escapeHtml(entry.license) : '未声明许可（以仓库为准）'}</p>
+    </div></div>
+    <div class="panel side"><div class="panel-head"><span class="label">仓库</span></div><div class="panel-body">
+      <ul class="repos">
+        ${entry.repos.package ? `<li><span class="rel">Pi 包</span><a target="_blank" rel="noreferrer" href="${escapeHtml(entry.repos.package)}">${escapeHtml(entry.repos.package.replace(/^https?:\/\//, ''))}</a></li>` : ''}
+        ${entry.repos.cli ? `<li><span class="rel">CLI</span><a target="_blank" rel="noreferrer" href="${escapeHtml(entry.repos.cli)}">${escapeHtml(entry.repos.cli.replace(/^https?:\/\//, ''))}</a></li>` : ''}
+      </ul>
+    </div></div>
+  </aside>
+</div>`;
+
+  return pageShell({
+    title: `${entry.name} — Pi 能力目录`,
+    description: entry.summary,
+    body,
+    fontsCss,
+    generatedAt,
+    siteUrl: siteUrl ? `${siteUrl.replace(/\/$/, '')}/skills/${entry.name}.html` : '',
+    depth: 1,
+  });
+}
+
+export function renderIndexPage({ entries, siteUrl = '', fontsCss = null, generatedAt = '' }) {
+  const requires = [...new Set(entries.flatMap(entry => entry.requires.map(item => item.name)))].sort().slice(0, 10);
+  const platforms = [...new Set(entries.flatMap(entry => entry.platforms))].sort();
+  const layers = ['core', 'tool', 'app'];
+  const sections = layers
+    .map(layer => {
+      const items = entries.filter(entry => entry.layer === layer);
+      if (!items.length) return '';
+      return `<section class="layer-section" data-layer="${layer}">
+  <div class="layer-head">
+    <span class="dot"></span><span class="label">${LAYER_LABEL[layer]}</span>
+    <span class="layer-count">${items.length}</span>
+    <span class="layer-why">${LAYER_HINT[layer]}</span>
+  </div>
+  <div class="grid">${items.map(cardOf).join('\n')}</div>
+</section>`;
+    })
+    .join('\n');
+  // 安装示例取最底层的一个：稳定、有意义，不是随便挑第一条。
+  const sample = entries.find(entry => entry.layer === 'core') ?? entries[0];
+  const body = `<header class="masthead">
+  <p class="eyebrow">${BRAND.name} · 自托管目录</p>
+  <h1>${BRAND.headline}</h1>
+  <p class="lede">把${SCOPE_HTML}当软件来管理：有版本、有依赖、有许可，一条命令装上就能用。</p>
+  ${
+    sample
+      ? `<p class="cta-label">安装示例</p>
+  <div class="cta">
+    <code class="cta-cmd">${escapeHtml(sample.install.pi)}</code>
+    <button class="copy primary" data-copy="${escapeHtml(sample.install.pi)}">复制命令</button>
+    <a class="cta-more" href="skills/${escapeHtml(sample.name)}.html">看它怎么用 →</a>
+  </div>`
+      : ''
+  }
+  <div class="meta">
+    <span class="stat">${entries.length} 个条目</span>
+    <span class="legend">
+      <span class="legend-item core"><span class="dot"></span>底座</span>
+      <span class="legend-item tool"><span class="dot"></span>工具</span>
+      <span class="legend-item app"><span class="dot"></span>组合应用</span>
+    </span>
+    <span class="hint">组合应用会把底座一起带上，不用单独装</span>
+  </div>
+</header>
+<div class="toolbar">
+  <input id="search" type="search" placeholder="搜索技能、命令或关键词…" aria-label="搜索技能" autocomplete="off">
+  <div class="segmented" id="layers" role="group" aria-label="按层筛选">
+    ${layers
+      .filter(layer => entries.some(entry => entry.layer === layer))
+      .map(layer => `<button class="seg" data-layer-filter="${layer}" aria-pressed="false">${LAYER_LABEL[layer]}</button>`)
+      .join('')}
+  </div>
+  <span class="count" id="count">${entries.length}</span>
+</div>
+${
+    requires.length || platforms.length > 1
+      ? `<div class="chipbar" id="requires">
+  ${
+    platforms.length > 1
+      ? `<span class="chip-label">平台</span>${platforms
+          .map(value => `<button class="chip filter" data-platform="${escapeHtml(value)}" aria-pressed="false">${escapeHtml(platformLabelOf(value))}</button>`)
+          .join('')}<span class="chip-sep"></span>`
+      : ''
+  }
+  ${
+    requires.length
+      ? `<span class="chip-label">按依赖筛选</span>${requires.map(name => `<button class="chip filter" data-requires="${escapeHtml(name)}" aria-pressed="false">${escapeHtml(name)}</button>`).join('')}`
+      : ''
+  }
+  <button class="chip clear" id="clear-filters" type="button" hidden>清除筛选</button>
+</div>`
+      : ''
+  }
+<main id="sections">
+${sections}
+</main>
+<p class="empty muted" id="empty" hidden>没有匹配的技能。</p>`;
+  return pageShell({
+    title: `${BRAND.name} — ${BRAND.headline}`,
+    description: 'Pi Hub：把 Pi 的技能、扩展、主题与提示模板当软件管理——版本、依赖、许可与一条命令安装。',
+    body,
+    fontsCss,
+    generatedAt,
+    siteUrl: siteUrl ?? '',
+  });
+}
+
+export function renderNotFoundPage({ siteUrl = '', fontsCss = null, generatedAt = '' } = {}) {
+  const body = `<header class="masthead">
+  <p class="eyebrow">404</p>
+  <h1>没有这个页面</h1>
+  <p class="lede">地址可能拼错了，或者这个条目还没有公开。</p>
+  <div class="cta"><a class="cta-more" href="/">回目录 →</a></div>
+</header>`;
+  return pageShell({ title: `404 — ${BRAND.name}`, description: '没有这个页面', body, fontsCss, generatedAt, siteUrl });
+}
+
+export const renderRobotsTxt = (siteUrl = '') => {
+  const siteRoot = (siteUrl || '').replace(/\/$/, '');
+  return `User-agent: *\nAllow: /\n${siteRoot ? `Sitemap: ${siteRoot}/sitemap.xml\n` : ''}`;
+};
+
+export const renderSitemapXml = (entries, siteUrl = '') => {
+  const siteRoot = (siteUrl || '').replace(/\/$/, '');
+  const urls = [`${siteRoot}/`, ...entries.map(entry => `${siteRoot}/skills/${entry.name}.html`)].filter(url => url.startsWith('http'));
+  return `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls
+    .map(url => `  <url><loc>${url}</loc></url>`)
+    .join('\n')}\n</urlset>\n`;
+};

skills/skill-catalog/scripts/serve.mjs

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+/**
+ * 目录站服务：从 catalog.json 每次请求现渲染（与 build 用同一份 render.mjs），
+ * 零依赖、可单独运行 —— 部署目录里只要有 serve.mjs + render.mjs + catalog.json + assets/。
+ *
+ * 用法:
+ *   node serve.mjs [--root DIR] [--host 127.0.0.1] [--port 8788] [--pidfile FILE]
+ *
+ * 路由:
+ *   GET /                        首页（现渲染）
+ *   GET /skills/<名>[.html]      条目详情（现渲染）
+ *   GET /api/skills              整个 catalog.json（机器可读）
+ *   GET /api/skills/<名>         单个条目
+ *   GET /healthz                 健康检查（catalog 读不出来时 503）
+ *   GET /robots.txt /sitemap.xml 由 catalog 现生成
+ *   GET /assets/*                静态资源（css/js/字体）
+ *   其它                         渲染成站内 404 页
+ *
+ * catalog.json 按 mtime+size 缓存：切 current 软链后不用重启就会读到新内容。
+ * 退出码：0 正常结束；2 用法错误；1 启动失败。
+ */
+import fs from 'node:fs';
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { renderDetailPage, renderIndexPage, renderNotFoundPage, renderRobotsTxt, renderSitemapXml } from './render.mjs';
+
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_PORT = 8788;
+
+const MIME = {
+  css: 'text/css; charset=utf-8',
+  js: 'text/javascript; charset=utf-8',
+  mjs: 'text/javascript; charset=utf-8',
+  svg: 'image/svg+xml',
+  woff2: 'font/woff2',
+  woff: 'font/woff',
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  ico: 'image/x-icon',
+  txt: 'text/plain; charset=utf-8',
+  xml: 'application/xml; charset=utf-8',
+  json: 'application/json; charset=utf-8',
+  html: 'text/html; charset=utf-8',
+};
+
+const contentTypeOf = file => MIME[path.extname(file).slice(1).toLowerCase()] ?? 'application/octet-stream';
+
+/**
+ * 建一个目录站服务对象（不监听）：测试与本地预览直接用它，systemd 跑本文件的 CLI。
+ * root 里应有 catalog.json / assets/ / render.mjs。
+ */
+export function createCatalogServer({ root, logger = console } = {}) {
+  const rootDir = path.resolve(root ?? path.dirname(fileURLToPath(import.meta.url)));
+  const catalogPath = path.join(rootDir, 'catalog.json');
+  const assetsDir = path.join(rootDir, 'assets');
+  const startedAt = Date.now();
+  // 缓存 catalog：key = mtime+size。切 current 软链后下一次请求就会重读。
+  let cache = { key: '', catalog: null, error: null, byName: new Map() };
+
+  const loadCatalog = () => {
+    try {
+      const stat = fs.statSync(catalogPath);
+      const key = `${stat.mtimeMs}:${stat.size}`;
+      if (cache.key !== key || !cache.catalog) {
+        const catalog = JSON.parse(fs.readFileSync(catalogPath, 'utf8'));
+        cache = { key, catalog, error: null, byName: new Map((catalog.skills ?? []).map(entry => [entry.name, entry])) };
+      }
+      return cache;
+    } catch (problem) {
+      cache = { key: '', catalog: null, error: problem.message, byName: new Map() };
+      return cache;
+    }
+  };
+
+  const send = (req, res, status, type, body, { cacheControl = 'no-cache', head } = {}) => {
+    const buffer = Buffer.isBuffer(body) ? body : Buffer.from(String(body ?? ''));
+    res.writeHead(status, {
+      'Content-Type': type,
+      'Content-Length': buffer.length,
+      'Cache-Control': cacheControl,
+      'X-Content-Type-Options': 'nosniff',
+    });
+    if (head ?? req.method === 'HEAD') res.end();
+    else res.end(buffer);
+    return status;
+  };
+
+  const html = (req, res, status, body) => send(req, res, status, MIME.html, body, { cacheControl: 'no-cache' });
+
+  const serveAsset = (req, res, pathname) => {
+    let relative;
+    try {
+      relative = decodeURIComponent(pathname.slice('/assets/'.length));
+    } catch {
+      return html(req, res, 404, renderNotFoundPage());
+    }
+    const file = path.resolve(assetsDir, relative);
+    if (file !== assetsDir && !file.startsWith(assetsDir + path.sep)) return html(req, res, 404, renderNotFoundPage());
+    let stat;
+    try {
+      stat = fs.statSync(file);
+    } catch {
+      return send(req, res, 404, 'text/plain; charset=utf-8', 'not found');
+    }
+    if (!stat.isFile()) return send(req, res, 404, 'text/plain; charset=utf-8', 'not found');
+    // 字体分片是最大的资源且内容稳定；css/js 变动也不频繁。发布新版本会换目录，浏览器按 max-age 过期即可。
+    const cacheControl = /\/fonts\//.test(relative) ? 'public, max-age=86400' : 'public, max-age=600';
+    return send(req, res, 200, contentTypeOf(file), fs.readFileSync(file), { cacheControl });
+  };
+
+  const route = (req, res) => {
+    let pathname;
+    try {
+      pathname = new URL(req.url, 'http://internal').pathname;
+    } catch {
+      return send(req, res, 400, 'text/plain; charset=utf-8', 'bad request');
+    }
+    if (req.method !== 'GET' && req.method !== 'HEAD') return send(req, res, 405, 'text/plain; charset=utf-8', 'method not allowed');
+
+    const loaded = loadCatalog();
+
+    if (pathname === '/' || pathname === '/index.html') {
+      if (loaded.error) return send(req, res, 503, 'text/plain; charset=utf-8', `catalog unavailable: ${loaded.error}`);
+      const { catalog, byName } = loaded;
+      return html(req, res, 200, renderIndexPage({
+        entries: catalog.skills ?? [],
+        siteUrl: catalog.site_url ?? '',
+        fontsCss: catalog.fonts ?? null,
+        generatedAt: catalog.generated_at ?? '',
+      }));
+    }
+
+    if (pathname.startsWith('/skills/')) {
+      if (loaded.error) return send(req, res, 503, 'text/plain; charset=utf-8', `catalog unavailable: ${loaded.error}`);
+      const { catalog, byName } = loaded;
+      let name;
+      try {
+        name = decodeURIComponent(pathname.slice('/skills/'.length)).replace(/\.html$/, '');
+      } catch {
+        return html(req, res, 404, renderNotFoundPage({ siteUrl: catalog.site_url ?? '', fontsCss: catalog.fonts ?? null, generatedAt: catalog.generated_at ?? '' }));
+      }
+      const entry = byName.get(name);
+      if (!entry) {
+        return html(req, res, 404, renderNotFoundPage({ siteUrl: catalog.site_url ?? '', fontsCss: catalog.fonts ?? null, generatedAt: catalog.generated_at ?? '' }));
+      }
+      return html(req, res, 200, renderDetailPage({
+        entry,
+        byName,
+        siteUrl: catalog.site_url ?? '',
+        fontsCss: catalog.fonts ?? null,
+        generatedAt: catalog.generated_at ?? '',
+      }));
+    }
+
+    if (pathname === '/api/skills') {
+      if (loaded.error) return send(req, res, 503, MIME.json, JSON.stringify({ error: 'catalog-unavailable', message: loaded.error }));
+      return send(req, res, 200, MIME.json, JSON.stringify(loaded.catalog, null, 2));
+    }
+
+    if (pathname.startsWith('/api/skills/')) {
+      if (loaded.error) return send(req, res, 503, MIME.json, JSON.stringify({ error: 'catalog-unavailable', message: loaded.error }));
+      let name;
+      try {
+        name = decodeURIComponent(pathname.slice('/api/skills/'.length));
+      } catch {
+        return send(req, res, 404, MIME.json, JSON.stringify({ error: 'notfound' }));
+      }
+      const entry = loaded.byName.get(name);
+      if (!entry) return send(req, res, 404, MIME.json, JSON.stringify({ error: 'notfound', name }));
+      return send(req, res, 200, MIME.json, JSON.stringify(entry, null, 2));
+    }
+
+    if (pathname === '/healthz') {
+      const body = loaded.error
+        ? { status: 'degraded', error: loaded.error, uptime_s: Math.round((Date.now() - startedAt) / 1000) }
+        : {
+            status: 'ok',
+            skills: loaded.catalog.count ?? loaded.catalog.skills?.length ?? 0,
+            generated_at: loaded.catalog.generated_at ?? null,
+            uptime_s: Math.round((Date.now() - startedAt) / 1000),
+          };
+      return send(req, res, loaded.error ? 503 : 200, MIME.json, JSON.stringify(body));
+    }
+
+    if (pathname === '/robots.txt') {
+      return send(req, res, 200, MIME.txt, renderRobotsTxt(loaded.catalog?.site_url ?? ''), { cacheControl: 'public, max-age=600' });
+    }
+
+    if (pathname === '/sitemap.xml') {
+      return send(req, res, 200, MIME.xml, renderSitemapXml(loaded.catalog?.skills ?? [], loaded.catalog?.site_url ?? ''), {
+        cacheControl: 'public, max-age=600',
+      });
+    }
+
+    if (pathname.startsWith('/assets/')) return serveAsset(req, res, pathname);
+
+    return html(req, res, 404, renderNotFoundPage({
+      siteUrl: loaded.catalog?.site_url ?? '',
+      fontsCss: loaded.catalog?.fonts ?? null,
+      generatedAt: loaded.catalog?.generated_at ?? '',
+    }));
+  };
+
+  const server = http.createServer((req, res) => {
+    const started = Date.now();
+    let status = 500;
+    try {
+      status = route(req, res) ?? res.statusCode;
+    } catch (problem) {
+      logger.error(`[serve] ${req.method} ${req.url} 渲染失败：${problem.stack ?? problem.message}`);
+      try {
+        status = send(req, res, 500, 'text/plain; charset=utf-8', 'internal error');
+      } catch {
+        /* 响应头已发出就只能断开 */
+        res.destroy();
+      }
+    }
+    logger.log(`${new Date().toISOString()} ${req.method} ${req.url} ${res.statusCode} ${Date.now() - started}ms`);
+  });
+  server.rootDir = rootDir;
+  return server;
+}
+
+const isMain = (() => {
+  try {
+    return Boolean(process.argv[1]) && fs.realpathSync(process.argv[1]) === fs.realpathSync(fileURLToPath(import.meta.url));
+  } catch {
+    return false;
+  }
+})();
+
+export function serveFromCli(argv = process.argv.slice(2)) {
+  const value = name => {
+    const index = argv.indexOf(name);
+    return index >= 0 ? argv[index + 1] : undefined;
+  };
+  const host = value('--host') ?? DEFAULT_HOST;
+  const port = Number(value('--port') ?? DEFAULT_PORT);
+  const root = value('--root') ?? path.dirname(fileURLToPath(import.meta.url));
+  const pidfile = value('--pidfile');
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    console.error(`error=usage 端口不合法：${value('--port')}`);
+    return 2;
+  }
+  const server = createCatalogServer({ root });
+  server.on('error', problem => {
+    console.error(`error=internal 监听失败：${problem.message}`);
+    process.exit(1);
+  });
+  server.listen(port, host, () => {
+    if (pidfile) fs.writeFileSync(pidfile, `${process.pid}\n`);
+    console.log(`[serve] ${root} → http://${host}:${port}/`);
+  });
+  const stop = () => {
+    try {
+      if (pidfile && fs.readFileSync(pidfile, 'utf8').trim() === String(process.pid)) fs.rmSync(pidfile, { force: true });
+    } catch {
+      /* pidfile 不在了就算了 */
+    }
+    server.close(() => process.exit(0));
+    setTimeout(() => process.exit(0), 1500).unref();
+  };
+  process.on('SIGTERM', stop);
+  process.on('SIGINT', stop);
+  return null; // 常驻
+}
+
+if (isMain) {
+  const code = serveFromCli();
+  if (code !== null && code !== undefined) process.exit(code);
+}

skills/skill-catalog/scripts/setup-hosting.sh

@@ -1,32 +1,126 @@
 #!/usr/bin/env bash
-# 一次性托管步骤：给目录站在 Caddy 里加一个站点块（幂等；需 sudo）。
+# 目录站托管（一次性，幂等；在承载服务的机器上运行，需要 sudo 时会自己提权）：
-# 在承载 Caddy 的机器上运行：scripts/setup-hosting.sh [域名] [站点根]
+#   1. 确保 Node ≥ 18（机器上有就用；没有就装 LTS 到 ~/.local/node，免系统包）
+#   2. 写 systemd 单元 pi-hub.service 并启动（跑 <部署目录>/current/serve.mjs，常驻 8788）
+#   3. 把 Caddy 的站点块改成反代 127.0.0.1:8788（备份 + validate，失败自动回滚）
+# 用法：bash setup-hosting.sh [域名] [部署目录] [端口]
 set -Eeuo pipefail
+
 DOMAIN="${1:-pi.vhkd.top}"
-ROOT="${2:-<部署目录>/current}"
+[ "$(id -u)" -eq 0 ] || exec sudo bash "$0" "$@"
+TARGET_USER="${SUDO_USER:-root}"
+USER_HOME="$(getent passwd "$TARGET_USER" | cut -d: -f6)"
+BASE="${2:-$USER_HOME/websites/skill-catalog}"
+PORT="${3:-8788}"
+UNIT=/etc/systemd/system/pi-hub.service
 CONF=/etc/caddy/Caddyfile
-sudo -v
+
-if grep -qE "^${DOMAIN//./\\.} \{" "$CONF"; then
+[ -d "$BASE" ] || { echo "部署目录不存在：$BASE（先跑一次 skill-catalog deploy）" >&2; exit 3; }
-  echo "已有 ${DOMAIN} 站点块，跳过"
+[ -f "$BASE/current/serve.mjs" ] || { echo "$BASE/current 里没有 serve.mjs：先跑一次 skill-catalog deploy（新版发布里带服务端）" >&2; exit 3; }
-else
+
-  BACKUP="$CONF.bak.skill-catalog.$(date +%Y%m%d-%H%M%S)"
+# 1) Node ≥ 18 —— 系统有就用系统的，否则装 LTS 到用户目录（免 sudo、可删）。
-  sudo cp "$CONF" "$BACKUP"
+NODE_BIN="$(command -v node || true)"
-  printf '\n%s {\n\tencode zstd gzip\n\troot * %s\n\tfile_server\n}\n' "$DOMAIN" "$ROOT" | sudo tee -a "$CONF" >/dev/null
+NODE_MAJOR=0
-  if ! sudo caddy validate --config "$CONF" --adapter caddyfile; then
+[ -n "$NODE_BIN" ] && NODE_MAJOR="$("$NODE_BIN" -p 'process.versions.node.split(".")[0]' 2>/dev/null || echo 0)"
-    sudo cp "$BACKUP" "$CONF"; echo "配置校验失败，已回滚 $BACKUP" >&2; exit 3
+if [ "$NODE_MAJOR" -lt 18 ]; then
+  NODE_DIR="$USER_HOME/.local/node"
+  NODE_BIN="$NODE_DIR/bin/node"
+  if [ ! -x "$NODE_BIN" ]; then
+    NODE_VERSION=v24.21.0
+    case "$(uname -m)" in
+      x86_64|amd64) NODE_ARCH=x64 ;;
+      aarch64|arm64) NODE_ARCH=arm64 ;;
+      *) echo "不认识的架构：$(uname -m)，请先自行安装 Node ≥ 18" >&2; exit 3 ;;
+    esac
+    echo "安装 Node ${NODE_VERSION} → $NODE_DIR"
+    TMP="$(mktemp -d)"
+    curl -fsSL --max-time 300 "https://nodejs.org/dist/${NODE_VERSION}/node-${NODE_VERSION}-linux-${NODE_ARCH}.tar.xz" | tar -xJ -C "$TMP"
+    mkdir -p "$NODE_DIR"
+    cp -a "$TMP/node-${NODE_VERSION}-linux-${NODE_ARCH}/." "$NODE_DIR/"
+    rm -rf "$TMP"
+    chown -R "$TARGET_USER" "$NODE_DIR"
   fi
 fi
-# 让 caddy 用户能「穿过」站点根的祖先目录（只补 o+x，不给读列表权限）。
+echo "Node：$NODE_BIN（$("$NODE_BIN" --version)）"
-# 家目录默认 0700 时 file_server 会 403。
-path="$(dirname "$ROOT")"
-while [ "$path" != "/" ]; do
-  perms="$(stat -c '%a' "$path" 2>/dev/null || echo 755)"
-  if [ $(( (8#$perms) & 1 )) -ne 1 ]; then
-    echo "补充可穿过权限：sudo chmod o+x $path（原 $perms）"
-    sudo chmod o+x "$path"
-  fi
-  path="$(dirname "$path")"
-done
 
-sudo systemctl reload caddy
+# 2) systemd 单元（内容变了才重写，避免无意义的 restart）。
-curl -s -o /dev/null -w "${DOMAIN} 首页: %{http_code}\n" --max-time 15 "https://${DOMAIN}/" || true
+TMP_UNIT="$(mktemp)"
+cat > "$TMP_UNIT" <<EOF
+[Unit]
+Description=Pi Hub skill catalog (dynamic site)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=$TARGET_USER
+WorkingDirectory=$BASE
+ExecStart=$NODE_BIN $BASE/current/serve.mjs --root $BASE/current --port $PORT --pidfile $BASE/server.pid
+Restart=always
+RestartSec=2
+
+[Install]
+WantedBy=multi-user.target
+EOF
+if ! cmp -s "$TMP_UNIT" "$UNIT" 2>/dev/null; then
+  cp "$TMP_UNIT" "$UNIT"
+  systemctl daemon-reload
+  echo "已写入 $UNIT"
+fi
+rm -f "$TMP_UNIT"
+
+# 清掉手工起的旧进程（只在确认那个 pid 还是 serve.mjs 时动手），让 systemd 接管端口。
+PIDFILE="$BASE/server.pid"
+if [ -f "$PIDFILE" ]; then
+  PID="$(cat "$PIDFILE" 2>/dev/null || true)"
+  if [ -n "$PID" ] && [ -d "/proc/$PID" ] && tr '\0' ' ' < "/proc/$PID/cmdline" | grep -q 'serve\.mjs'; then
+    echo "停掉手工进程 pid=$PID"
+    kill "$PID" 2>/dev/null || true
+    sleep 1
+  fi
+fi
+systemctl enable --now pi-hub
+systemctl restart pi-hub
+
+# 3) Caddy：站点块改成反代（幂等；validate 不过就回滚）。
+TMP_CONF="$(mktemp)"
+python3 - "$CONF" "$DOMAIN" "$PORT" > "$TMP_CONF" <<'PY'
+import re, sys
+conf, domain, port = sys.argv[1], sys.argv[2], sys.argv[3]
+text = open(conf, encoding='utf-8').read()
+block = f"{domain} {{\n\tencode zstd gzip\n\treverse_proxy 127.0.0.1:{port}\n}}\n"
+pattern = re.compile(r'(?m)^' + re.escape(domain) + r' \{[^}]*\}\n?')
+if pattern.search(text):
+    sys.stdout.write(pattern.sub(block, text, count=1))
+else:
+    sys.stdout.write(text.rstrip('\n') + '\n\n' + block)
+PY
+if cmp -s "$TMP_CONF" "$CONF"; then
+  echo "Caddy 站点块已是反代，跳过"
+  rm -f "$TMP_CONF"
+else
+  BACKUP="$CONF.bak.skill-catalog.$(date +%Y%m%d-%H%M%S)"
+  cp "$CONF" "$BACKUP"
+  cp "$TMP_CONF" "$CONF"
+  rm -f "$TMP_CONF"
+  if ! caddy validate --config "$CONF" --adapter caddyfile >/dev/null 2>&1; then
+    cp "$BACKUP" "$CONF"
+    echo "Caddy 配置校验失败，已回滚 $BACKUP" >&2
+    exit 3
+  fi
+  systemctl reload caddy
+  echo "已把 $DOMAIN 改成反代 127.0.0.1:$PORT（备份 $BACKUP）"
+fi
+
+# 4) 回读：本地健康检查 + 公网健康检查，一条命令给答案。
+sleep 1
+LOCAL="$(curl -s --max-time 10 "http://127.0.0.1:$PORT/healthz" || true)"
+case "$LOCAL" in
+  *'"status":"ok"'*) echo "本地服务 OK：$LOCAL" ;;
+  *) echo "本地服务未就绪：${LOCAL:-（无响应）}" >&2; systemctl status pi-hub --no-pager | head -15 >&2 || true ;;
+esac
+PUBLIC="$(curl -s --max-time 20 "https://$DOMAIN/healthz" || true)"
+case "$PUBLIC" in
+  *'"status":"ok"'*) echo "公网服务 OK：https://$DOMAIN/healthz → $PUBLIC" ;;
+  *) echo "公网健康检查未见 ok：${PUBLIC:-（无响应）}（证书/DNS/Caddy 站点块？）" >&2 ;;
+esac

skills/skill-catalog/scripts/skill-catalog.mjs

@@ -1,19 +1,27 @@
 #!/usr/bin/env node
 /**
- * skill-catalog — 把「对外发布的技能」生成一个静态目录站（生成物，页面永不手改）。
+ * skill-catalog — 把「对外发布的技能」发布成一个自托管目录站（动态服务 + 同源静态快照）。
  *
  * 数据全部来自技能自己的声明：interface.json（summary/useWhen/commands/requires/
  * config/dependsOn/publish）、VERSION、contract.lock.json。只收录声明了 publish 的技能；
  * 页面不渲染 REFERENCE 全文，配置只列「要配什么」不列值。
  *
+ * 两个出口共用 render.mjs 这一份渲染：
+ *   build → dist/（catalog.json + assets + serve.mjs + render.mjs，同时落盘静态 HTML 快照）
+ *   serve → 从 catalog.json 每次请求现渲染（/api/skills、/healthz；线上由 systemd 常驻）
+ * deploy 把 dist 推到部署目标（relay→host，release 目录 + current 软链切换）。线上是 serve
+ * 常驻进程：切 current 后不用重启就会读到新内容；代码随 release 走，deploy 会踢一下进程
+ * 让 systemd 用新代码重启。
+ *
  * 隐私门禁：生成后对整个 dist 跑一遍 skill-pack 的泄漏扫描（密钥/真实家目录/工单号），
- * error 级直接拒绝产出。
+ * error 级直接拒绝产出。上服务器的只有公开快照，没有 skills 仓库。
  *
  * 用法:
- *   skill-catalog build [--out DIR] [--json]   生成静态站
+ *   skill-catalog build [--out DIR] [--json]     生成 dist（服务端要的全套）
- *   skill-catalog preview [--port N]           生成并在本地起预览（打印 URL）
+ *   skill-catalog serve [--root DIR] [--port N]  本地跑动态服务（默认 dist/）
- *   skill-catalog deploy [--dry-run] [--json]  生成的 dist 推到部署目标（relay→host，release+current）
+ *   skill-catalog preview [--port N]             build + serve 本地预览
- *   skill-catalog list [--json]                收录清单与依赖闭包状态
+ *   skill-catalog deploy [--dry-run] [--json]    dist 推到部署目标（relay→host，release+current）
+ *   skill-catalog list [--json]                  收录清单与依赖闭包状态
  *
  * 配置（interface.json 的 config 声明；值在 local/skills/skill-catalog/config.json）：
  *   site_url / deploy_relay / deploy_host / deploy_path
@@ -28,10 +36,9 @@ import { fileURLToPath } from 'node:url';
 import { loadSkills, repoRoot, agentDir } from '../../skill-interface/scripts/skill-registry.mjs';
 import { resolveConfig, agentDirOf } from '../../skill-interface/scripts/skill-config.mjs';
 import { scanLeaks } from '../../skill-interface/scripts/skill-pack.mjs';
+import { renderIndexPage, renderDetailPage, renderRobotsTxt, renderSitemapXml } from './render.mjs';
 
 const SKILL = 'skill-catalog';
-const BRAND = { name: 'Pi Hub', tagline: '为 Pi 装上你要的能力', scope: '技能 · 扩展 · 主题 · 提示模板' };
-const SCOPE_HTML = '<span class="nowrap">技能 · 扩展 · 主题 · 提示模板</span>';
 // 字体三套（都 OFL，可自托管）：正文楷（读者喜欢的）+ 标题衬线（中文用思源宋）+
 // 拉丁/等宽 PragmataPro（本机 local()，商用字体不随站分发）。
 const FONTS = [
@@ -65,15 +72,16 @@ const EXIT_OK = 0;
 const EXIT_USAGE = 2;
 const EXIT_BLOCKED = 3;
 
-const USAGE = `skill-catalog — 生成并发布「技能目录站」（生成物，不手改页面）
+const USAGE = `skill-catalog — 生成并发布「技能目录站」（动态服务，静态快照同源）
 
-skill-catalog build [--out DIR] [--json]    生成静态站（默认 <技能目录>/dist）
+skill-catalog build [--out DIR] [--json]      生成 dist（catalog.json + assets + serve.mjs + 静态快照）
-skill-catalog preview [--port N]            生成 + 本地预览（默认 8788）
+skill-catalog serve [--root DIR] [--port N]   本地跑动态服务（默认 dist/，现渲染 + /api/skills + /healthz）
-skill-catalog deploy [--dry-run] [--json]   推到部署目标（relay→host 两跳，release + current 切换）
+skill-catalog preview [--port N]              build + serve 本地预览（默认 8788）
-skill-catalog list [--json]                 收录哪些技能、依赖闭包是否完整（只读）
+skill-catalog deploy [--dry-run] [--json]     推到部署目标（relay→host 两跳，release + current 切换）
-skill-catalog check                          只读自检：收录规则与部署目标配置
+skill-catalog list [--json]                   收录哪些技能、依赖闭包是否完整（只读）
+skill-catalog check                           只读自检：收录规则、部署目标与线上健康
 
-收录规则：interface.json 里声明了 publish.repo 的技能才上页；依赖里出现未公开技能会标出来。
+收录规则：interface.json 里声明了 publish 的技能才上页；依赖里出现未公开技能会标出来。
 配置：site_url / deploy_relay / deploy_host / deploy_path（local/skills/skill-catalog/config.json）。
 退出码：0 成功；2 用法；3 被门禁拦下（泄漏扫描 error）。`;
 
@@ -122,12 +130,14 @@ export function collectCatalog(repo = repoRoot()) {
       return {
         name: skill.name,
         status: declared.status ?? 'stable',
+        license: declared.license ?? '',
         declaredLayer: declared.catalog?.layer ?? null,
         summary: declared.summary ?? '',
         useWhen: declared.useWhen ?? '',
         tier: declared.tier,
         version,
-        platforms: declared.platforms ?? ['all'],
+        // 平台声明在 SKILL.md frontmatter（skill.platforms），interface.json 里没有这个字段。
+        platforms: skill.platforms ?? [],
         commands: (declared.commands ?? []).map(command => ({
           name: command.name,
           summary: command.summary ?? '',
@@ -191,305 +201,6 @@ export function collectCatalog(repo = repoRoot()) {
   return { entries, warnings };
 }
 
-const escapeHtml = value =>
-  String(value ?? '')
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
-
-const kindLabel = { runtime: '运行环境', binary: '命令', service: '服务', account: '账号' };
-
-function siteNav(depth = 0) {
-  const prefix = depth === 0 ? '' : '../';
-  return `<nav class="nav">
-  <a class="nav-brand" href="${prefix}index.html"><span class="brand-mark">π</span><span><strong>${BRAND.name}</strong><em>${BRAND.scope}</em></span></a>
-  <div class="nav-links">
-    <a href="${prefix}index.html">目录</a>
-    <a href="https://gitea.vhkd.top/pi-hub" target="_blank" rel="noreferrer">仓库</a>
-    <a href="https://pi.dev/packages" target="_blank" rel="noreferrer">官方画廊</a>
-    <button class="theme-toggle" id="theme-toggle" type="button" aria-label="切换明暗主题" title="切换明暗主题">
-      <svg class="icon-sun" viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="4.2"/><g stroke-linecap="round"><path d="M12 2.6v2.2M12 19.2v2.2M2.6 12h2.2M19.2 12h2.2M5.3 5.3l1.6 1.6M17.1 17.1l1.6 1.6M18.7 5.3l-1.6 1.6M6.9 17.1l-1.6 1.6"/></g></svg>
-      <svg class="icon-moon" viewBox="0 0 24 24" aria-hidden="true"><path d="M20 14.2A8.2 8.2 0 0 1 9.8 4a8.4 8.4 0 1 0 10.2 10.2Z"/></svg>
-    </button>
-  </div>
-</nav>`;
-}
-
-function siteFoot(depth = 0) {
-  const prefix = depth === 0 ? '' : '../';
-  return `<footer class="foot">
-  <div class="foot-cols">
-    <div><h4>关于</h4><p>这里收录的条目都从技能自己的声明生成，和仓库同步；页面不手改。</p></div>
-    <div><h4>资源</h4><ul>
-      <li><a href="https://pi.dev/packages" target="_blank" rel="noreferrer">官方画廊 pi.dev/packages</a></li>
-      <li><a href="https://gitea.vhkd.top/pi-hub" target="_blank" rel="noreferrer">Gitea 仓库</a></li>
-      <li><a href="${prefix}catalog.json">catalog.json（机器可读）</a></li>
-    </ul></div>
-    <div><h4>字体</h4><ul>
-      <li>中文 霞鹜文楷 Screen（OFL）</li>
-      <li>拉丁 Pragmata Pro（读者本机）</li>
-    </ul></div>
-  </div>
-  <p class="foot-line">${BRAND.name} · 由 skill-catalog 生成 · 条目与技能声明一致</p>
-</footer>`;
-}
-
-function pageShell({ title, description, body, siteUrl, depth = 0, fontsCss = null }) {
-  const prefix = depth === 0 ? '' : '../';
-  return `<!doctype html>
-<html lang="zh-CN" data-theme="light">
-<head>
-<meta charset="utf-8">
-<script>
-  // 主题：跟随系统，用户切过就记住（在首帧前生效，避免闪一下）。
-  try {
-    var saved = localStorage.getItem('pi-hub-theme');
-    var theme = saved || (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light');
-    document.documentElement.dataset.theme = theme;
-  } catch (e) {}
-</script>
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>${escapeHtml(title)}</title>
-<meta name="description" content="${escapeHtml(description)}">
-${fontsCss ? fontsCss.map(href => `<link rel="stylesheet" href="${prefix}assets/${href}">`).join('\n') : ''}
-<link rel="icon" href="${prefix}assets/favicon.svg" type="image/svg+xml">
-<meta name="theme-color" content="#fbfbf9" media="(prefers-color-scheme: light)">
-<meta name="theme-color" content="#101114" media="(prefers-color-scheme: dark)">
-<meta property="og:type" content="website">
-<meta property="og:title" content="${escapeHtml(title)}">
-<meta property="og:description" content="${escapeHtml(description)}">
-${siteUrl ? `<meta property="og:url" content="${escapeHtml(siteUrl)}">` : ''}
-<meta name="twitter:card" content="summary">
-<link rel="stylesheet" href="${prefix}assets/style.css">
-${siteUrl ? `<link rel="canonical" href="${escapeHtml(siteUrl)}">` : ''}
-</head>
-<body>
-<div class="page">
-${siteNav(depth)}
-${body}
-${siteFoot(depth)}
-</div>
-<script src="${prefix}assets/app.js"></script>
-</body>
-</html>
-`;
-}
-
-const LAYER_LABEL = { core: '底座', tool: '工具', app: '组合应用' };
-const LAYER_HINT = {
-  core: '别的技能建在它上面',
-  tool: '独立可用，装完就用',
-  app: '由多个技能协作完成',
-};
-
-function cardOf(entry) {
-  const facts = [
-    ...entry.requires.slice(0, 3).map(item => `<span class="meta-chip">${escapeHtml(item.name)}</span>`),
-    ...(entry.installable ? [] : ['<span class="meta-chip meta-chip-warn">依赖未公开</span>']),
-  ].join('');
-  const used = entry.usedByCount ? `<span class="used">被 ${entry.usedByCount} 个技能使用</span>` : '';
-  return `<a class="card" href="skills/${escapeHtml(entry.name)}.html" data-layer="${entry.layer}"
-      data-search="${escapeHtml(`${entry.name} ${entry.summary} ${entry.useWhen} ${entry.layer} ${entry.commands.map(c => c.name).join(' ')}`)}">
-  <div class="card-top"><h3>${escapeHtml(entry.name)}</h3><span class="ver">v${escapeHtml(entry.version)}</span></div>
-  <p class="summary">${escapeHtml(entry.summary)}</p>
-  <div class="card-foot">
-    <span class="card-layer"><span class="dot"></span>${LAYER_LABEL[entry.layer]}</span>
-    ${facts}${used}
-  </div>
-</a>`;
-}
-
-function detailPage(entry, siteUrl, byName, fontsCss) {
-  const steps = entry.installOrder.map(name => byName.get(name)).filter(Boolean);
-  const together =
-    steps.length > 1
-      ? `<div class="well together">
-  <p class="well-title">一次装齐 <span class="muted">按顺序执行 ${steps.length} 条</span></p>
-${steps
-  .map(
-    (item, index) =>
-      `  <div class="cmd"><span class="cmd-step">${index + 1}</span><code>${escapeHtml(item.install.pi)}</code><span class="cmd-tag">${item.name === entry.name ? '本体' : '依赖'}</span></div>`,
-  )
-  .join('\n')}
-  <div class="well-foot"><button class="copy primary" data-copy="${escapeHtml(steps.map(item => item.install.pi).join('\n'))}">复制这 ${steps.length} 条</button></div>
-</div>`
-      : '';
-
-  const installRows = [
-    entry.install.pi
-      ? `<div class="cmd"><span class="cmd-step">Pi</span><code>${escapeHtml(entry.install.pi)}</code><button class="copy" data-copy="${escapeHtml(entry.install.pi)}">复制</button></div>`
-      : '',
-    entry.install.cli
-      ? `<div class="cmd"><span class="cmd-step">CLI</span><code>${escapeHtml(entry.install.cli)}</code><button class="copy" data-copy="${escapeHtml(entry.install.cli)}">复制</button></div>`
-      : '',
-  ].join('\n');
-  const installBlock = entry.installable
-    ? `${together}
-<div class="well">
-${installRows}
-  <p class="well-note">装完跑 <code>pi-skill ${escapeHtml(entry.name)} check</code>${entry.install.cli ? `（Pi）或 <code>${escapeHtml(entry.name)} help</code>（命令行）` : ''}。</p>
-</div>`
-    : `<div class="well blocked"><p><strong>依赖未公开组件</strong>，单独装跑不起来，暂不提供安装命令。</p></div>`;
-
-  const requires = entry.requires.length
-    ? `<div class="facts">${entry.requires
-        .map(
-          item => `<div class="fact">
-  <div class="fact-head"><span class="fact-name">${escapeHtml(item.name)}</span><span class="fact-kind">${escapeHtml(kindLabel[item.kind] ?? item.kind)}</span></div>
-  ${item.note ? `<p class="muted">${escapeHtml(item.note)}</p>` : ''}
-  ${item.install ? `<code class="inline-cmd">${escapeHtml(item.install)}</code>` : ''}
-</div>`,
-        )
-        .join('')}</div>`
-    : '<p class="muted">用系统已有的东西即可，没有额外依赖。</p>';
-
-  const config = entry.config.length
-    ? `<div class="facts">${entry.config
-        .map(
-          item => `<div class="fact">
-  <div class="fact-head"><span class="fact-name mono">${escapeHtml(item.key)}</span>
-    ${item.required ? '<span class="badge badge-req">必配</span>' : '<span class="badge">可选</span>'}
-    ${item.secret ? '<span class="badge">私密</span>' : ''}</div>
-  <p class="muted">${escapeHtml(item.desc)}</p>
-  ${item.ask ? `<p class="ask">${escapeHtml(item.ask)}</p>` : ''}
-</div>`,
-        )
-        .join('')}</div>`
-    : '<p class="muted">装完即用，不需要提前配置。</p>';
-
-  const relations = `<ul class="relations">
-${
-    entry.usesPublic
-      .map(name => `<li><span class="rel rel-depend">依赖</span><a href="${escapeHtml(name)}.html">${escapeHtml(name)}</a></li>`)
-      .join('\n')
-  }
-${
-    entry.usedBy
-      .map(name => `<li><span class="rel rel-used">被用</span><a href="${escapeHtml(name)}.html">${escapeHtml(name)}</a></li>`)
-      .join('\n')
-  }
-${entry.usesPublic.length || entry.usedBy.length ? '' : '<li class="muted">独立可用，不和其它技能往来。</li>'}
-</ul>`;
-
-  const commands = entry.commands.length
-    ? `<table class="commands"><tbody>${entry.commands
-        .map(
-          command =>
-            `<tr><td class="cmd-cell"><code>${escapeHtml(command.name)}</code>${command.destructive ? '<span class="badge">会改状态</span>' : ''}</td><td>${escapeHtml(command.summary)}</td></tr>`,
-        )
-        .join('')}</tbody></table>`
-    : '';
-
-  const body = `<header class="detail-head">
-  <a class="back" href="../index.html">← 全部技能</a>
-  <div class="title-row">
-    <h1>${escapeHtml(entry.name)}</h1>
-    <span class="ver">v${escapeHtml(entry.version)}</span>
-  </div>
-  <p class="lede">${escapeHtml(entry.summary)}</p>
-  <div class="chips">
-    <span class="chip layer-${entry.layer}">${LAYER_LABEL[entry.layer]}</span>
-    <span class="meta-chip">${LAYER_HINT[entry.layer]}</span>
-    ${entry.status !== 'stable' ? `<span class="meta-chip meta-chip-warn">${entry.status === 'experimental' ? '实验性' : '将退役'}</span>` : ''}
-    ${entry.platforms.map(platform => `<span class="meta-chip">${escapeHtml(platform)}</span>`).join('')}
-  </div>
-</header>
-<div class="detail-grid">
-  <article>
-    <section class="block"><h2>怎么装</h2>${installBlock}</section>
-    <section class="block"><h2>先准备什么</h2>${requires}</section>
-    <section class="block"><h2>要先配什么</h2>${config}</section>
-    ${commands ? `<section class="block"><h2>常用命令</h2>${commands}</section>` : ''}
-  </article>
-  <aside>
-    <div class="panel side"><div class="panel-head"><span class="label">关系</span></div><div class="panel-body">${relations}</div></div>
-    <div class="panel side"><div class="panel-head"><span class="label">仓库</span></div><div class="panel-body">
-      <ul class="repos">
-        ${entry.repos.package ? `<li><span class="rel">Pi 包</span><a href="${escapeHtml(entry.repos.package)}">${escapeHtml(entry.repos.package.replace(/^https?:\/\//, ''))}</a></li>` : ''}
-        ${entry.repos.cli ? `<li><span class="rel">CLI</span><a href="${escapeHtml(entry.repos.cli)}">${escapeHtml(entry.repos.cli.replace(/^https?:\/\//, ''))}</a></li>` : ''}
-      </ul>
-    </div></div>
-  </aside>
-</div>`;
-
-  return pageShell({
-    title: `${entry.name} — Pi 能力目录`,
-    description: entry.summary,
-    body,
-    fontsCss,
-    siteUrl: siteUrl ? `${siteUrl.replace(/\/$/, '')}/skills/${entry.name}.html` : '',
-    depth: 1,
-  });
-}
-
-function indexPage(entries, siteUrl, fontsCss) {
-  const requires = [...new Set(entries.flatMap(entry => entry.requires.map(item => item.name)))].sort().slice(0, 10);
-  const layers = ['core', 'tool', 'app'];
-  const sections = layers
-    .map(layer => {
-      const items = entries.filter(entry => entry.layer === layer);
-      if (!items.length) return '';
-      return `<section class="panel layer-section" data-layer="${layer}">
-  <div class="panel-head">
-    <span class="dot"></span><span class="label">${LAYER_LABEL[layer]}</span>
-    <span class="panel-count">${items.length}</span>
-    <span class="panel-hint">${LAYER_HINT[layer]}</span>
-  </div>
-  <div class="grid">${items.map(cardOf).join('\n')}</div>
-</section>`;
-    })
-    .join('\n');
-  // 安装示例取最底层的一个：稳定、有意义，不是随便挑第一条。
-  const sample = entries.find(entry => entry.layer === 'core') ?? entries[0];
-  const body = `<header class="masthead">
-  <p class="eyebrow">${BRAND.name} · 自托管目录</p>
-  <h1>${BRAND.tagline}</h1>
-  <p class="lede">${SCOPE_HTML}的集中目录。每条都写清依赖、前置条件与安装命令，装完就能用。</p>
-  ${
-    sample
-      ? `<p class="cta-label">安装示例</p>
-  <div class="cta">
-    <code class="cta-cmd">${escapeHtml(sample.install.pi)}</code>
-    <button class="copy primary" data-copy="${escapeHtml(sample.install.pi)}">复制命令</button>
-    <a class="cta-more" href="skills/${escapeHtml(sample.name)}.html">看它怎么用 →</a>
-  </div>`
-      : ''
-  }
-  <div class="meta">
-    <span class="stat">${entries.length} 个条目</span>
-    <span class="legend">
-      <span class="legend-item core"><span class="dot"></span>底座</span>
-      <span class="legend-item tool"><span class="dot"></span>工具</span>
-      <span class="legend-item app"><span class="dot"></span>组合应用</span>
-    </span>
-    <span class="hint">组合应用会把底座一起带上，不用单独装</span>
-  </div>
-</header>
-<div class="toolbar">
-  <input id="search" type="search" placeholder="搜索技能、命令或关键词…" aria-label="搜索技能" autocomplete="off">
-  <div class="segmented" id="layers" role="group" aria-label="按层筛选">
-    ${layers
-      .filter(layer => entries.some(entry => entry.layer === layer))
-      .map(layer => `<button class="seg" data-layer-filter="${layer}" aria-pressed="false">${LAYER_LABEL[layer]}</button>`)
-      .join('')}
-  </div>
-  <span class="count" id="count">${entries.length}</span>
-</div>
-${requires.length ? `<div class="chipbar" id="requires">${requires.map(name => `<button class="chip filter" data-requires="${escapeHtml(name)}">${escapeHtml(name)}</button>`).join('')}</div>` : ''}
-<main id="sections">
-${sections}
-</main>
-<p class="empty muted" id="empty" hidden>没有匹配的技能。</p>`;
-  return pageShell({
-    title: BRAND.name,
-    description: 'Pi 能力目录：技能与扩展，写清依赖与前置条件，一条命令装好就能用。',
-    body,
-    fontsCss,
-    siteUrl: siteUrl ?? '',
-  });
-}
-
 
 /** 取（或首次下载）一套网络字体到 local 缓存；失败返回 { dir: null, error }。 */
 export function ensureFont(repo, font) {
@@ -525,18 +236,7 @@ export function ensureFont(repo, font) {
   }
 }
 
-/** 目录页需要的中文字体都准备好；返回 css 相对路径列表。 */
+/** 生成 dist（服务端要的全套 + 静态快照）；返回 { out, entries, warnings, leaks, errors, blocked }。 */
-export function ensureFonts(repo = repoRoot(), warnings = []) {
-  const links = [];
-  for (const font of FONTS) {
-    const ready = ensureFont(repo, font);
-    if (ready.dir) links.push(`fonts/${font.key}/${font.css}`);
-    else warnings.push(`${font.family} 没就位（${ready.error}）：会退回系统字体`);
-  }
-  return links;
-}
-
-/** 生成静态站；返回 { out, files, warnings, leaks }。 */
 export function buildCatalog({ repo = repoRoot(), out, siteUrl = '' } = {}) {
   const { entries, warnings } = collectCatalog(repo);
   const outDir = out ?? path.join(SKILL_DIR, 'dist');
@@ -546,16 +246,12 @@ export function buildCatalog({ repo = repoRoot(), out, siteUrl = '' } = {}) {
   fs.cpSync(path.join(SKILL_DIR, 'assets', 'style.css'), path.join(outDir, 'assets', 'style.css'));
   fs.cpSync(path.join(SKILL_DIR, 'assets', 'app.js'), path.join(outDir, 'assets', 'app.js'));
   fs.cpSync(path.join(SKILL_DIR, 'assets', 'favicon.svg'), path.join(outDir, 'assets', 'favicon.svg'));
-  const siteRoot = (siteUrl || '').replace(/\/$/, '');
+  // 动态服务：serve.mjs 与它引用的 render.mjs 随发布一起走，服务器上不需要 skills 仓库。
-  const urls = [`${siteRoot}/`, ...entries.map(entry => `${siteRoot}/skills/${entry.name}.html`)];
+  fs.cpSync(path.join(SKILL_DIR, 'scripts', 'serve.mjs'), path.join(outDir, 'serve.mjs'));
-  fs.writeFileSync(path.join(outDir, 'robots.txt'), `User-agent: *\nAllow: /\n${siteRoot ? `Sitemap: ${siteRoot}/sitemap.xml\n` : ''}`);
+  fs.cpSync(path.join(SKILL_DIR, 'scripts', 'render.mjs'), path.join(outDir, 'render.mjs'));
-  fs.writeFileSync(
+  const generatedAt = new Date().toISOString();
-    path.join(outDir, 'sitemap.xml'),
+  fs.writeFileSync(path.join(outDir, 'robots.txt'), renderRobotsTxt(siteUrl));
-    `<?xml version="1.0" encoding="UTF-8"?>\n<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">\n${urls
+  fs.writeFileSync(path.join(outDir, 'sitemap.xml'), renderSitemapXml(entries, siteUrl));
-      .filter(url => url.startsWith('http'))
-      .map(url => `  <url><loc>${url}</loc></url>`)
-      .join('\n')}\n</urlset>\n`,
-  );
   // 中文正文字体（霞鹜文楷 Screen）：首次构建下载到 local 缓存，之后直接用；
   // 拿不到就退回系统字体并 warn（页面仍可用）。
   const fontLinks = [];
@@ -579,12 +275,14 @@ export function buildCatalog({ repo = repoRoot(), out, siteUrl = '' } = {}) {
     fontLinks.push(`fonts/${font.key}/${font.css}`);
   }
   const fontsCss = fontLinks.length ? fontLinks : null;
-  fs.writeFileSync(path.join(outDir, 'index.html'), indexPage(entries, siteUrl, fontsCss));
+  // 静态快照与动态服务共用 render.mjs 这一份渲染：静态页是过渡与回退用的落盘快照，
+  // 线上以 serve.mjs 现渲染为准。
+  fs.writeFileSync(path.join(outDir, 'index.html'), renderIndexPage({ entries, siteUrl, fontsCss, generatedAt }));
   const byName = new Map(entries.map(entry => [entry.name, entry]));
   for (const entry of entries) {
-    fs.writeFileSync(path.join(outDir, 'skills', `${entry.name}.html`), detailPage(entry, siteUrl, byName, fontsCss));
+    fs.writeFileSync(path.join(outDir, 'skills', `${entry.name}.html`), renderDetailPage({ entry, byName, siteUrl, fontsCss, generatedAt }));
   }
-  const catalog = { generated_at: new Date().toISOString(), site_url: siteUrl, count: entries.length, skills: entries };
+  const catalog = { generated_at: generatedAt, site_url: siteUrl, count: entries.length, fonts: fontLinks, skills: entries };
   fs.writeFileSync(path.join(outDir, 'catalog.json'), `${JSON.stringify(catalog, null, 2)}\n`);
 
   // 隐私门禁：扫「原始值」而不是渲染结果——HTML/JSON 会把引号转义成 &quot;/\"，
@@ -640,13 +338,18 @@ function deployCatalog({ repo = repoRoot(), dryRun = false, out } = {}) {
     `tar -xzf - -C '${release}'`,
     `ln -sfn 'releases/${stamp}' '${target}/current'`,
     `ls -dt '${target}/releases/'* | tail -n +6 | xargs -r rm -rf`,
+    // 内容切换不用重启（serve 每次请求读 current）；代码随 release 走，所以踢一下进程让
+    // systemd 用新代码重启。只在服务由 systemd 管理时动手，手工起的进程不受影响。
+    `if systemctl is-active --quiet pi-hub && [ -f '${target}/server.pid' ]; then kill "$(cat '${target}/server.pid')" 2>/dev/null || true; fi`,
   ].join(' && ');
   const push = sh('ssh', [relay, `ssh ${host} ${JSON.stringify(remote)}`], { input: fs.readFileSync(tarFile) });
   fs.rmSync(tarFile, { force: true });
   if (push.status !== 0) return { ok: false, blocked: [`推送失败：${(push.stderr || '').trim()}`], ...built };
   // 部署完回读公开地址：内容推上去了但站点块没加/没重载时，这里一眼可见。
   const url = values.site_url ?? '';
-  const probe = url ? (sh('curl', ['-s', '-o', '/dev/null', '-w', '%{http_code}', '--max-time', '12', url]).stdout || '').trim() : '';
+  const probe = url
+    ? (sh('curl', ['-s', '-o', '/dev/null', '-w', '%{http_code}', '--max-time', '12', '--retry', '3', '--retry-delay', '1', '--retry-connrefused', url]).stdout || '').trim()
+    : '';
   return { ok: true, relay, host, release, url, live: probe || 'unreachable', ...built };
 }
 
@@ -687,9 +390,19 @@ if (isMain) {
     console.log(`收录 ${entries.length} 个技能（规则：声明了 publish 的技能）`);
     console.log(`部署目标=${values.deploy_path ? `${values.deploy_relay || 'lightos'}→${values.deploy_host || 'aliyun-hk'}:${values.deploy_path}` : '未配置'}`);
     if (values.site_url) {
-      // 只读回读一次公网地址：站点活没活、证书/站点块在不在，一条命令给答案。
+      // 只读回读一次公网地址：站点活没活、是静态还是动态、新鲜度，一条命令给答案。
-      const code = (sh('curl', ['-s', '-o', '/dev/null', '-w', '%{http_code}', '--max-time', '12', values.site_url]).stdout || '').trim();
+      const root = values.site_url.replace(/\/$/, '');
-      console.log(`站点=${values.site_url} HTTP=${code || '000'}${code === '200' ? '' : '（非 200：站点块/证书/目录权限？见 REFERENCE §4）'}`);
+      const code = (sh('curl', ['-s', '-o', '/dev/null', '-w', '%{http_code}', '--max-time', '12', root]).stdout || '').trim();
+      const healthy = (sh('curl', ['-s', '--max-time', '12', `${root}/healthz`]).stdout || '').trim();
+      let mode = '静态或未就绪';
+      let detail = '';
+      try {
+        const body = JSON.parse(healthy);
+        mode = `动态（${body.status}，${body.skills ?? '?'} 个条目，生成于 ${body.generated_at ?? '?'}）`;
+      } catch {
+        detail = '（/healthz 不是 JSON：站点块可能还是 file_server 静态托管，见 REFERENCE §4）';
+      }
+      console.log(`站点=${values.site_url} HTTP=${code || '000'} 服务=${mode}${detail}${code === '200' ? '' : '（非 200：站点块/证书没就绪？见 REFERENCE §4）'}`);
     } else {
       console.log('站点=未配置 site_url');
     }
@@ -730,7 +443,8 @@ if (isMain) {
     if (json) console.log(JSON.stringify({ ok: true, dryRun, release: result.release, count: result.entries.length, url: result.url }, null, 2));
     else {
       console.log(`${dryRun ? 'dry-run：将发布' : '已发布'} ${result.entries.length} 个技能 → ${result.relay}→${result.host}:${result.release}`);
-      if (result.url) console.log(result.live === '200' ? `公开地址：${result.url}（HTTP 200）` : `公开地址：${result.url}（HTTP ${result.live} —— 站点块/证书没就绪？见 REFERENCE §4 的一次性配置）`);
+      if (result.url && dryRun) console.log(`公开地址：${result.url}（dry-run 不探测）`);
+      else if (result.url) console.log(result.live === '200' ? `公开地址：${result.url}（HTTP 200）` : `公开地址：${result.url}（HTTP ${result.live} —— 站点块/证书没就绪？见 REFERENCE §4 的一次性配置）`);
     }
     process.exit(EXIT_OK);
   }
@@ -742,8 +456,25 @@ if (isMain) {
       process.exit(EXIT_BLOCKED);
     }
     console.log(`预览：http://127.0.0.1:${port}/  （${built.out}；Ctrl-C 结束）`);
-    const server = spawnSync('python3', ['-m', 'http.server', String(port), '--bind', '127.0.0.1', '--directory', built.out], { stdio: 'inherit' });
+    process.exit(runServer(built.out, { port }));
-    process.exit(server.status ?? EXIT_OK);
+  }
+  if (command === 'serve') {
+    const root = value('--root') ?? path.join(SKILL_DIR, 'dist');
+    const port = Number(value('--port') ?? 8788);
+    if (!fs.existsSync(path.join(root, 'catalog.json'))) {
+      fail(`serve 的目录里没有 catalog.json：${root}`, '先 skill-catalog build，或用 --root 指向已生成的 dist');
+    }
+    console.log(`服务：http://127.0.0.1:${port}/  （${root}；Ctrl-C 结束）`);
+    process.exit(runServer(root, { port, host: value('--host'), pidfile: value('--pidfile') }));
   }
   fail(`未知命令「${command}」`, 'skill-catalog help');
 }
+
+/** 起动态服务：preview 与 serve 都走 serve.mjs，本地和线上是同一条渲染路径。 */
+function runServer(root, { port, host, pidfile } = {}) {
+  const args = [path.join(SKILL_DIR, 'scripts', 'serve.mjs'), '--root', root, '--port', String(port)];
+  if (host) args.push('--host', host);
+  if (pidfile) args.push('--pidfile', pidfile);
+  const server = spawnSync(process.execPath, args, { stdio: 'inherit' });
+  return server.status ?? EXIT_OK;
+}