fix(memory): 修 beta.2 压测发现的三个向量/文档缺陷

来源：v1.2.0-beta.2 全方位压测（报告 /var/tmp/stress/REPORT.md）

1. 文档向量迁移结果不落盘（生产已复现）
   - BuildDenseIndex 改完内存不置 dirty；docStore.Stop() 全仓无调用者 → flush 成死代码
   - 后果：每次启动重算同一批文档（线上 496 篇约 17s），磁盘 dense_fp 永不收敛
   - 修：迁移当场落盘（抽出 flushLocked 以免重入锁）+ main.go 关停链 defer docStore.Stop()
   - 生产证据：线上 488 篇文档仅 4 篇含 dense_fp，且这 4 篇均为运行期 Insert 的新文档
2. 块指纹对但维度错时污染文档向量（健壮性缺口）
   - denseFor 只校验 b.Fingerprint，不校验长度；FuseVectors 取最大维度并跳过长度不符者
     → 512 维文本 + 2048 维块 = 2048 维且打上当前指纹
     → 该文档在检索侧被长度守卫永久跳过，且每次启动重算（不收敛）
   - 修：denseFor 要求 len(b.Vector) == 空间维度
   - 可达性：内核两个块产出点均成对取自同一行（it.Vec ↔ it.VecModel），故属防御性修复
3. Insert 与 loadAll 的 ID 约定不对称（低）
   - Insert 落盘任意 <id>.json，loadAll 只加载 doc_ 前缀 → 自定义 ID 文档重启后静默消失
   - 修：loadAll 只要求 .json（空 ID 仍跳过）

回归测试 4 条：迁移跨重启落盘 + 已对齐 0 重算（用向量空间调用计数判定，
不靠日志）、坏块不参与融合且同维度正常块仍参与、自定义 ID 可加载、Stop 落盘。

反向验证（纪律要求）：临时回退本次修复后，前 3 条均变红且报错正是缺陷签名
（dim=999/space-OLD-999 永不收敛、文档向量 2048 维、文件重启后消失）；恢复后全绿。

验证：go build ./cmd/homed ok；go vet ./internal/memory/document ./cmd/homed ok；
go test ./internal/memory/... 7 包全绿。

.gitignore

@@ -48,7 +48,12 @@ codegraph.json
 /adapters/
 /knowledge/
 /memory/
-/scripts/
+# 注：/scripts/ **不**忽略。它是作者维护的工具目录（模型导出、侧车、部署校验），
+# 不是运行期产物：deploy/systemd/embed-sidecar.service 直接引用
+# scripts/embed_sidecar.py，忽略它会让那份 unit 在别人的机器上指向不存在的文件。
+# 只忽略其中的缓存。
+/scripts/__pycache__/
+__pycache__/
 terminal_locked_log.txt
 
 dist/

LICENSE

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

README.md

@@ -12,6 +12,8 @@
 homed（内核零 IO） ← PluginSDK → 插件（所有 IO 能力）
 ```
 
+**v1.1.1 起媒体贯通插件边界**：插件与模型都能读写记忆里的图片/音频（`InsertWithMedia`、`InjectInputMedia`），媒体以 `[<mime> <短digest>] <描述>` 标记存在于纯文本记忆中——描述是可检索的语义记忆，digest 是回到字节的钥匙。
+
 **v1.0.0 起外部插件是独立子进程**：经 stdio JSON-RPC（控制面）+ 共享内存段（数据面）+ 事件环（通知面）与内核通信。插件崩溃不影响内核且自动重启，换 `plugin.bin` 即生效的真热重载。
 
 ## 设计要点
@@ -193,9 +195,36 @@ internal/
 
 ## 项目状态
 
-**v1.0.3** — 内核 stage 协调器双重解锁修复。现网 homed 主进程曾一次 `fatal error: sync: unlock of unlocked mutex` 整体死亡（带走全部 27 个子进程插件）：`Host.endStage` 把「递减 inflight、判定最后离开者」放在 `coordMu` 临界区之外，而摘除协调器在临界区之内，于是后到插件能挂进一个正在收尾的协调器、被误判成最后离开者，对同一把 `stageMu` 解了两次。**`sync.Mutex` 双重解锁是 runtime fatal 而非 panic，两层 `recover` 结构上拦不住**，这才让「插件崩溃不拖垮内核」的隔离设计整体失效。修法是把计数、判定、摘除收进同一临界区，并把首进者写共享段的 `enter()` 也移入锁内（此前后到者可能读到写一半的段）。配套 5 个回归用例，含把旧实现 stash 回来验证测试确实能复现 fatal 的反向验证。
+**v1.2.0** — 统一多模态向量空间 + 媒体升为图记忆一等节点 + 数据面全量迁到共享内存。
 
-**v1.0.1** — 多模态 bugfix。插件 ABI/协议未变，1.0.0 编出的 `plugin.bin` 无需重编。修三类缺陷：（1）**看图假成功**——媒体块挂在 tool message 上不被模型当作可视内容（实测同一张图：tool message 0/3 读到、独立 user message 3/3），改为另起一条紧随其后的 user message 承载，落实插件文案一直在说的「注入后续对话」；（2）**新增多模态能力声明与回退链**——`core.llm.sources.<name>.vision/.audio` 声明源能否真正处理媒体（网关会静默剥离 `image_url` 后仍返回 200，带图与不带图 prompt_tokens 完全相同），不支持时自动走视觉源转写成文字，并落实了 `core.input_processing.image.fallback_provider` 这批早已注册却从未被读取的配置项；（3）**`see_video` 帧数语义反了**——`fps=1/N` 是频率不是数量，20s 视频请求 10 帧只得 2 帧、请求 1 帧反得 20 帧，改为 `ffprobe` 取时长 + `fps=N/时长` + `-frames:v` 硬封顶。
+- **模型中立的统一向量空间**：内核不再适配任何具体模型，只提供公共 provider SPI
+  （`pkg/embedding`：`Modality` / `Input{Data,MIME}` / `Info{Dimension,Fingerprint,Modalities}`
+  + 名字注册表），实现在 `providers/*`。默认 **Chinese-CLIP ViT-B/16** —— text 与 image
+  落在**同一空间**（512 维、指纹 `cd2a495cf990`、Apache-2.0、独立实测常驻约 1.15GB）；
+  `qwen3vl` 保留（2048 维、常驻约 9.4GB，供内存充足或将来要视频的机器切回）。
+  文本检索仍由既有词向量 / TF-IDF 兜底：CLIP 双塔的**纯文本语义弱于 MLLM 型嵌入器**，
+  这是已知并写进文档的代价。
+- **媒体是图数据库的一等节点与边**：**彻底删除**「用文本描述式索引图片」这套将就机制，
+  以及 `media_refs` 与媒体引用计数。记忆块遵循单层不变量——Context → Document → Graph
+  是块的**迁移**，不是复制、也不靠引用保活。
+- **数据面全部走共享内存**（工具调用帧 / Cleaner / 输入输出通道 / 媒体块 / 文档与知识正文），
+  RPC 只传偏移描述符；**RPC 协议升到 2**，fd3 布局改变，**不支持滚动升级**——
+  内核与全部插件必须同批重建、同批安装，存量插件须用新版 `plugindev` 重编。
+- 注入可声明 `InjectOptions{NoMemory, ContextPolicy}`（**默认仍记入记忆、默认不裁剪**）；
+  裁剪必须显式声明，且先经插件注册的 `Cleaner`。SDK 1.2.0 相对 1.1.0 **纯追加**。
+- **发行包默认启用** ONNX 向量空间，并把模型（754MB）与 ONNX Runtime（24MB）随
+  server/full 包发布；`homed` 放弃 Windows 原生支持改走 WSL2；jieba 词库内嵌进二进制。
+- 修掉三个**安装链静默失败**：`initconfig` 因 `CGO_ENABLED=0` 是空操作（打印凭据却一个字节
+  没写）、全新安装被误判「已有配置」而整体跳过默认值播种（装完 0 插件）、deb 的 `postinst`
+  查错 unit 路径导致 `enable` 从未执行。
+- 自本版起以 **AGPL-3.0-only** 发布（含网络条款；插件静态链接 SDK 故须同许可，见「许可」）。
+
+> 以下历史条目保留原文以呈现演进，其中两条机制**已在 v1.2.0 移除**：
+> 「媒体以 `[<mime> <短digest>] <描述>` 标记参与检索」（描述式索引）与「媒体引用计数式 GC」。
+
+**v1.1.1** — 多模态贯通**插件边界**。v1.1.0 让记忆系统支持了二进制多媒体节点，但那条链路只对内核自己开放；本版打通到插件与模型。公开 SDK 新增媒体字段与三个媒体注入接口（配套 [SDK v1.1.0](https://gitcode.com/JianFeeeee/homeagent-sdk/releases/tag/v1.1.0)，整条 1.1.x 线共用），内核实现对应四个 RPC。桥接层此前在**静默裁字段**：插件交进来的 `Confidence`/类型/`SentenceText` 全被丢弃、`Doc` 只留三个字段、`Remove` 不解引用（媒体永久算「被引用」，GC 收不掉）。`processTextInput`/`processMediaInput` 归一成一条 `processInput`，媒体路径由此获得它一直缺的去重、`no_memory`、通道 `Cleaner`、中断语义、`EventRawInput`。修掉三处真实缺陷：**用户发的图从来没出现在 WebUI 聊天记录里**（媒体路径发布 map 而订阅方断言 string）、**`memory_commit` 的 `sentence_text` 从未暴露给模型**（而它是媒体绑定链的必经环节）、**`PluginSDK` 两处并发竞态**（`-race` 实测 11 处，插件重载瞬间偶发 nil 解引用崩溃）。
+
+**v1.1.0** — 记忆系统支持**二进制多媒体节点**。内容寻址媒体存储（CAS + SQLite 元数据 + 磁盘 blob，`Get` always 重校 digest），贯通 L0（上下文事件）/L2（文档）/L3（图谱句子）三层，引用计数式 GC（有引用者绝不删）。视觉模型生成的描述文本是持久语义记忆，blob 只是可被容量 GC 淘汰的缓存。
 
 **v1.0.0** — 外部插件从 C ABI 动态库迁移到**子进程 + 共享内存**。首个不再加载 `.so`/`.dll` 的版本，与 0.9.x 不兼容（存量插件须用新版 `plugindev` 重编为 `plugin.bin`，**业务代码零改动**）。消除 6 类此前在生产造成故障的缺陷：热重载失效（`DF_1_NODELETE` 让 `dlclose` 成 no-op）、崩溃隔离缺失（插件 panic 带崩 homed）、stage lost update（副本模型丢失 35.8~36.8%）、cgo 超时不可中断（线程线性泄漏）、`output_send` 假成功（模型收到「已发送」而消息未送达）、Windows 能力断层（只见 3 个 stage 字段且无法写回）。三面通信：stdio JSON-RPC（控制）+ 共享内存段（数据）+ 事件环（通知）；权限梯度显式化为三道闸。RPC 往返 p50 24.1µs，崩溃到恢复 <1s。
 
@@ -222,7 +251,7 @@ internal/
 | **client** | waiter + 桌面 GUI | 连接远程 HomeAgent |
 
 - Linux：`.deb`（amd64/arm64）、`.rpm`（x86_64）、`.tar.gz`
-- Windows：`HomeAgent_v1.0.3_{Full,Server,Client}_win64.exe`（NSIS 安装向导）
+- Windows：`HomeAgent_v1.2.0_{Full,Server,Client}_win64.exe`（NSIS 安装向导，含 AGPL 许可页）。自 v1.2.0 起因 `homed` 不再支持 Windows 原生（依赖 fd 继承与共享内存段内偏移解引用），安装器改为引导到 **WSL2**，并把 Linux 包送进发行版里按 Linux 方式安装。
 - 免安装：`homeagent-bin-<os>_<arch>.tar.gz`（含 homed/waiter/initconfig）
 - 校验：`SHA256SUMS`
 
@@ -237,3 +266,26 @@ make install            # 安装到系统
 ```
 
 依赖：Go 1.25+, CGo (go-sqlite3), Linux/Windows。
+
+## 许可
+
+本项目以 **GNU Affero 通用公共许可证第 3 版（AGPL-3.0-only）** 发布，全文见 [LICENSE](LICENSE)。
+
+它是 GPL 家族里**传染性最强**的一档：不仅分发时须提供完整对应源码，
+**通过网络提供服务时也要向使用者提供源码**（§13 Remote Network Interaction）。
+即：任何人把改过的 HomeAgent 对外提供网络服务，都必须让该服务的使用者拿到改动后的源码。
+
+插件与本项目通过公开 SDK **静态链接**（SDK 源码会进入插件二进制），因此插件是本项目的
+衍生作品，需以相同许可发布；子进程隔离不改变这一点，因为被链接的是 SDK 代码本身。
+
+### 随包分发的第三方组件
+
+| 组件 | 许可 | 位置 |
+|---|---|---|
+| Chinese-CLIP ViT-B/16（ONNX 产物） | Apache-2.0 | `/usr/lib/homeagent/models/chinese-clip-vit-b16-onnx/` |
+| ONNX Runtime（`libonnxruntime.so`） | MIT | `/usr/lib/homeagent/onnxruntime/` |
+| jieba 词库（内嵌进二进制） | MIT | 源码 `internal/memory/jiebadict/` |
+| Go 依赖（go-sqlite3、gojieba、bubbletea 等） | MIT / BSD-3 / Apache-2.0 | 均为宽松许可，与 AGPL-3.0 兼容 |
+
+这些组件**保持各自原有许可**，不在本项目的 AGPL 授权范围内；发行包把它们的许可全文放在
+`/usr/share/doc/homeagent/licenses/`，并在 dep/rpm 元数据里声明本包许可为 `AGPL-3.0-only`。

README_EN.md

@@ -12,6 +12,11 @@ Combined with a **three-layer memory architecture** (Context → Document → Gr
 homed (kernel, zero IO) ← PluginSDK → plugins (all IO capabilities)
 ```
 
+**Since v1.1.1 media reaches the plugin boundary**: plugins and the model can both read and
+write images/audio in memory (`InsertWithMedia`, `InjectInputMedia`). Media lives in plain-text
+memory as a `[<mime> <short digest>] <description>` marker — the description is the searchable
+semantic memory, the digest is the key back to the bytes.
+
 **Since v1.0.0 external plugins are independent subprocesses**, communicating with the kernel over
 stdio JSON-RPC (control plane) + a shared memory segment (data plane) + an event ring (notification
 plane). A plugin crash cannot take down the kernel and it restarts automatically; swapping
@@ -179,9 +184,61 @@ External plugin development: see [homeagent-sdk](https://gitcode.com/JianFeeeee/
 
 ## Project Status
 
-**v1.0.3** — Kernel stage-coordinator double-unlock fix. The production `homed` main process once died outright with `fatal error: sync: unlock of unlocked mutex`, taking all 27 subprocess plugins with it: `Host.endStage` performed "decrement inflight, decide whether I'm the last leaver" *outside* the `coordMu` critical section while detaching the coordinator *inside* it, so a late-arriving plugin could attach to a coordinator that was already finishing, be misjudged as the last leaver, and unlock the same `stageMu` twice. **A `sync.Mutex` double unlock is a runtime fatal, not a panic, so the two layers of `recover` structurally cannot catch it**—which is exactly why the "a crashing plugin must not take down the kernel" isolation design failed wholesale here. The fix folds counting, decision, and detach into one critical section, and also moves the first arriver's `enter()` (which writes the shared segment) inside the lock—previously a late arriver could read a half-written segment. Ships with 5 regression cases, including a reverse check that stashes the old implementation back to confirm the tests really do reproduce the fatal.
+**v1.2.0** — unified multimodal vector space, media promoted to first-class graph memory, and the whole data plane moved into shared memory.
 
-**v1.0.1** — Multimodal bugfix. The plugin ABI/protocol is unchanged, so `plugin.bin` artifacts built for 1.0.0 need no rebuild. Three defects fixed: (1) **vision silently failing**—media blocks attached to a tool message are not treated as viewable content by the model (measured on one image: 0/3 read from a tool message, 3/3 from a standalone user message); media now rides its own user message placed immediately after, which is what the plugin's own wording ("injected into the following conversation") always claimed; (2) **new multimodal capability declaration + fallback chain**—`core.llm.sources.<name>.vision/.audio` declares whether a source can genuinely process media (a gateway may strip `image_url` and still return 200, with identical prompt_tokens with and without the image); when it cannot, media is transcribed to text via a vision-capable source, finally wiring up the long-registered but never-read `core.input_processing.image.fallback_provider` settings; (3) **`see_video` frame-count semantics were inverted**—`fps=1/N` is a *rate*, not a count, so a 20s video yielded 2 frames when 10 were requested and 20 frames when 1 was requested; now `ffprobe` measures duration and the filter becomes `fps=N/duration` with `-frames:v` as a hard cap.
+- **Model-neutral unified embedding space**: the kernel no longer adapts to any specific model.
+  It exposes only a public provider SPI (`pkg/embedding`: `Modality` / `Input{Data,MIME}` /
+  `Info{Dimension,Fingerprint,Modalities}` + a name registry), with implementations under
+  `providers/*`. Default: **Chinese-CLIP ViT-B/16** — text and image land in the **same space**
+  (512-dim, fingerprint `cd2a495cf990`, Apache-2.0, ~1.15GB RSS measured standalone);
+  `qwen3vl` is kept (2048-dim, ~9.4GB) for machines with headroom or future video. Text search
+  still falls back to the existing word-vector / TF-IDF path — a CLIP dual tower's pure-text
+  semantics are **weaker than an MLLM-style embedder**, a cost documented rather than hidden.
+- **Media are first-class nodes and edges in the graph DB**: the "index images via generated
+  text descriptions" stopgap, `media_refs` and media reference counting are **removed**.
+  Memory blocks follow a single-layer invariant — Context → Document → Graph is a **migration**,
+  not a copy, and not kept alive by references.
+- **The entire data plane goes through shared memory** (tool-call frames, Cleaners, input/output
+  lanes, media blocks, document and knowledge bodies); RPC carries only offset descriptors.
+  **RPC protocol is now 2**: the fd3 layout changed and there is **no rolling upgrade** —
+  kernel and all plugins must be rebuilt and installed together.
+- Injections can declare `InjectOptions{NoMemory, ContextPolicy}` (**defaults: still recorded,
+  not pruned**); pruning must be requested explicitly and goes through the plugin's registered
+  `Cleaner`. SDK 1.2.0 is **purely additive** over 1.1.0.
+- **Release packages enable the ONNX space by default** and bundle the model (754MB) plus
+  ONNX Runtime (24MB) in the server/full packages; `homed` drops native Windows support in
+  favour of WSL2; the jieba dictionary is embedded in the binary.
+- Fixed three **silent install-chain failures**: `initconfig` was a no-op (`CGO_ENABLED=0` stub)
+  that printed credentials without writing any, fresh installs were misdetected as "already
+  configured" so default seeding was skipped entirely (0 plugins installed), and the deb
+  `postinst` looked for the unit in the wrong path so `enable` never ran.
+- Licensed **AGPL-3.0-only** from this version on (network clause included; statically linked
+  plugins must match — see License).
+
+> The historical entries below are kept verbatim to show the evolution; two mechanisms in them
+> were **removed in v1.2.0**: text-description-based media indexing, and reference-counted media GC.
+
+**v1.1.1** — Multimodal reaches the **plugin boundary**. v1.1.0 gave the memory system binary
+multimedia nodes, but that path was open only to the kernel itself; this release opens it to
+plugins and the model. The public SDK gains media fields and three media injection methods
+(paired with [SDK v1.1.0](https://gitcode.com/JianFeeeee/homeagent-sdk/releases/tag/v1.1.0),
+shared by the whole 1.1.x line), and the kernel implements the four matching RPCs. The bridge
+layer had been **silently dropping fields**: `Confidence`/types/`SentenceText` handed in by a
+plugin were discarded, `Doc` kept only three fields, and `Remove` never released references
+(media stayed "referenced" forever, so GC could never reclaim it). `processTextInput` and
+`processMediaInput` were unified into a single `processInput`, which finally gives the media
+path the dedup, `no_memory`, channel `Cleaner`, interrupt semantics and correct `EventRawInput`
+it had always lacked. Three real defects fixed: **user-sent images never appeared in the WebUI
+chat log** (the media path published a map while the subscriber asserted a string),
+**`memory_commit`'s `sentence_text` had never been exposed to the model** (though it is the
+mandatory link in the media binding chain), and **two data races in `PluginSDK`** (11 reported
+by `-race`; in production this showed up as sporadic nil-dereference crashes during plugin reload).
+
+**v1.1.0** — Memory system supports **binary multimedia nodes**. Content-addressed media store
+(CAS + SQLite metadata + on-disk blobs, `Get` always re-verifies the digest) wired through L0
+(context events) / L2 (documents) / L3 (graph sentences), with reference-counted GC (referenced
+items are never deleted). The description text produced by the vision model is the durable
+semantic memory; the blob is only a cache that capacity GC may evict.
 
 **v1.0.0** — External plugins moved from C ABI shared libraries to **subprocess + shared memory**. The first release that no longer loads `.so`/`.dll`, and it is incompatible with 0.9.x (existing plugins must be rebuilt into `plugin.bin` with the new `plugindev`, though **business code needs zero changes**). Eliminates 6 classes of defects that had caused production incidents: hot-reload silently failing (`DF_1_NODELETE` making `dlclose` a no-op), no crash isolation (a plugin panic took down homed), stage lost updates (35.8~36.8% loss under the copy model), uncancellable cgo timeouts (linear OS-thread leaks), `output_send` reporting false success (the model was told "sent" while the message never went out), and Windows capability degradation (only 3 stage fields visible, no write-back). Three communication planes: stdio JSON-RPC (control) + shared memory segment (data) + event ring (notification); the privilege gradient is now enforced by three explicit gates. RPC round-trip p50 24.1µs; crash-to-recovery under 1s.
 
@@ -208,7 +265,7 @@ External plugin development: see [homeagent-sdk](https://gitcode.com/JianFeeeee/
 | **client** | waiter + desktop GUI | Connecting to a remote HomeAgent |
 
 - Linux: `.deb` (amd64/arm64), `.rpm` (x86_64), `.tar.gz`
-- Windows: `HomeAgent_v1.0.3_{Full,Server,Client}_win64.exe` (NSIS installer)
+- Windows: `HomeAgent_v1.2.0_{Full,Server,Client}_win64.exe` (NSIS installer, includes the AGPL license page). Since v1.2.0 `homed` no longer supports native Windows (it relies on fd inheritance and in-segment offset dereferencing), so the installer bootstraps **WSL2** and installs the Linux packages inside the distribution the same way a Linux host would.
 - Portable: `homeagent-bin-<os>_<arch>.tar.gz` (homed/waiter/initconfig)
 - Verification: `SHA256SUMS`
 
@@ -223,3 +280,30 @@ make install            # Install to system
 ```
 
 Dependencies: Go 1.25+, CGo (go-sqlite3), Linux/Windows.
+
+## License
+
+This project is released under the **GNU Affero General Public License, version 3
+(AGPL-3.0-only)** — see [LICENSE](LICENSE).
+
+This is the strongest copyleft in the GPL family: besides shipping the complete corresponding
+source when you distribute the software, **you must also offer the source to users who interact
+with it over a network** (§13, Remote Network Interaction). Anyone running a modified HomeAgent
+as a network service therefore has to make the modified source available to that service's users.
+
+Plugins are **statically linked** against this project through the public SDK (the SDK source
+ends up inside the plugin binary), so plugins are derivative works and must be released under
+the same license. Process isolation does not change this — what is linked is the SDK code itself.
+
+### Third-party components shipped with the packages
+
+| Component | License | Location |
+|---|---|---|
+| Chinese-CLIP ViT-B/16 (ONNX artifacts) | Apache-2.0 | `/usr/lib/homeagent/models/chinese-clip-vit-b16-onnx/` |
+| ONNX Runtime (`libonnxruntime.so`) | MIT | `/usr/lib/homeagent/onnxruntime/` |
+| jieba dictionary (embedded in the binary) | MIT | `internal/memory/jiebadict/` |
+| Go dependencies (go-sqlite3, gojieba, bubbletea, …) | MIT / BSD-3 / Apache-2.0 | permissive, AGPL-3.0-compatible |
+
+These components keep their own licenses and are not relicensed by this project. Full texts are
+shipped in `/usr/share/doc/homeagent/licenses/`, and the package metadata declares this package
+as `AGPL-3.0-only`.

assets/docs/en/ARCHITECTURE.md

@@ -189,6 +189,39 @@ All vectorization unified under `StaticEmbedder` (`internal/memory/static_embedd
 | `doc_query` | Search from Document |
 | `doc_commit` | Write to Document |
 
+Since v1.1.1 `memory_commit` and `doc_commit` accept `media_digests`, and the kernel appends the
+`[<mime> <short digest>] <description>` marker into the sentence/body — **the kernel builds the
+marker, the model only supplies the digest**. Requiring the caller to know the format would mean a
+single typo silently breaks reference binding with no error anywhere in the chain. `memory_commit`
+also gained `sentence_text`: media references hang off a sentence, so with no sentence there is
+nowhere to attach them.
+
+### Media Memory (since v1.1.0)
+
+`internal/memory/media/` — `Store`, content-addressed (CAS)
+
+| Concern | Approach | Why |
+|---|---|---|
+| Addressing | sha256 digest; metadata in SQLite, blobs on disk | Identical bytes stored once; metadata must be queryable, blobs must not live in the database |
+| Integrity | Every `Get` re-verifies the digest | Silently returning corrupt data on disk damage is far worse than an error |
+| Write atomicity | `.tmp` + rename | A half-written file taken as complete content would permanently poison that digest |
+| References | `owner_kind/owner_id/digest` composite primary key, `AddRef` idempotent | Three owner kinds: `context` (context events), `document`, `graph_sentence` |
+| GC | Two-stage with `minAge`, **referenced items are never deleted** | Description text stays in the text layers while blobs may be evicted — semantic memory and byte cache are decoupled |
+
+**How media is represented in plain-text memory** is the marker `[<mime> <short digest>] <description>`:
+
+```
+[image/png a1b2c3d4e5f6] a purple-blue-red three-band chart
+```
+
+Why it must ride on text: `Doc.Content`, `sentences.text` and text memory's `Input` are all strings
+— there is no field to carry structured data. **The description text is the durable semantic
+memory** (retrieval uses it); the digest is the key back to the bytes (reverse lookup uses it).
+After capacity GC evicts a blob, the description remains in the L0/L2/L3 text.
+
+The media store is **optional throughout**: with `core.memory.media.enabled=false` or no
+configuration, the whole chain silently degrades to plain-text behaviour — no errors, no panics.
+
 ### Other Memory Layers
 
 - **Social** (`internal/memory/social/social.go`) — Persona traits and relationship network, wraps GraphDB entity types
@@ -296,7 +329,7 @@ Common ground:
 
 | Plane | Mechanism | Why this choice |
 |---|---|---|
-| Control | stdio JSON-RPC (NDJSON frames), 51 `core.*` methods | The process boundary *is* the ABI boundary—no need to maintain three platform-specific dynamic-library loaders |
+| Control | stdio JSON-RPC (NDJSON frames), 55 `core.*` methods | The process boundary *is* the ABI boundary—no need to maintain three platform-specific dynamic-library loaders |
 | Data | Shared memory segment, **one segment shared by all subprocesses** | One segment per plugin would degrade "kernel ctx → segment → plugin mutates → read back" into the copy model under concurrency, reproducing lost updates exactly |
 | Notification | Event ring + platform notify (Linux eventfd / macOS pipe / Windows Event) | The kernel must never block on a consumer: streaming output publishes per token, so any wait shows up as stutter |
 
@@ -334,8 +367,23 @@ sdk.Memory().Recall/Commit
 sdk.Knowledge().Search/Create
 sdk.Settings().Get/Set/List
 sdk.RegisterOutputChannel("qq", sdk.CapText|sdk.CapAudio|sdk.CapImage, "QQ channel, see output_send__qq_help for details", handler)
+
+// v1.1.1 media APIs (all additive, no signature changes)
+sdk.DocMemory().InsertWithMedia(doc, attachments)   // attachments with Data land in CAS; Digest-only ones reference existing content
+sdk.InjectInputMedia(source, channel, text, blocks) // media reaches the model in *this* turn
+sdk.InjectInputMediaSync(...)                       // same, and waits for the reply
+sdk.InjectInterruptMedia(...)                       // media-bearing interrupt, can preempt current processing
 ```
 
+How media injection differs from `SetToolBlocks`: the latter is only callable inside a tool handler
+and its media reaches the model with the **next** tool message; these three let a plugin
+**initiate a turn that carries media** — it goes out with this turn's message and is automatically
+stored in CAS with a memory reference attached. `Triple` and `Doc` gained `MediaDigests` /
+`Attachments` correspondingly.
+
+`internal/sdk/` is the bridge implementation for this layer and is not subject to the public
+interface freeze (see `docs/git-branching.md` §6).
+
 ### Plugin Interface
 
 ```go

assets/docs/en/OVERVIEW.md

@@ -25,6 +25,19 @@ The significance lies in clear responsibility boundaries: the kernel focuses on
 
 Three progressive layers — context, cold archive, long-term graph memory — form an information decay and consolidation pipeline from short-term to persistent storage.
 
+**Media Memory (since v1.1.0)** — Images and audio are not attachments; they are a kind of node in all three layers:
+- **Content-addressed store (CAS)**: addressed by digest, metadata in SQLite and blobs on disk, identical bytes
+  stored once. Every `Get` re-verifies the digest (silently returning corrupt data is worse than an error).
+- **Reference-counted GC**: `owner_kind/owner_id/digest` is the primary key; context events, documents and graph
+  sentences each hold their own references. **Referenced items are never deleted** — only unowned content past
+  `minAge` is reclaimed.
+- **The description text is the durable semantic memory**: what the vision model produced is written into
+  plain-text memory as a `[<mime> <short digest>] <description>` marker and participates in vector retrieval and
+  distillation; the blob is only a cache that capacity GC may evict. Months later "that purple-blue-red
+  three-band chart" is still findable — via the description, not the bytes.
+- **Reaches the plugin boundary since v1.1.1**: plugins read and write media through `InsertWithMedia` /
+  `InjectInputMedia`; the model attaches media via the `media_digests` argument of `memory_commit` / `doc_commit`.
+
 ## What It Actually Does
 
 Code is in the project root, implemented in Go.

assets/docs/zh/ARCHITECTURE.md

@@ -189,6 +189,36 @@ eventLoop() → processTextInput()
 | `doc_query` | 从 Document 搜索 |
 | `doc_commit` | 写入 Document |
 
+`memory_commit` 与 `doc_commit` 自 v1.1.1 起接受 `media_digests`，并由内核把
+`[<mime> <短digest>] <描述>` 标记补进句子/正文——**标记由内核拼，模型只给 digest**。
+要求调用方知道格式，等于让一个拼写错误静默切断引用绑定而全链路无人报错。
+`memory_commit` 同时新增 `sentence_text`：媒体引用挂在句子上，没有句子就无处可挂。
+
+### 媒体记忆（v1.1.0 起）
+
+`internal/memory/media/` — `Store`，内容寻址（CAS）
+
+| 关注点 | 做法 | 为何 |
+|---|---|---|
+| 寻址 | sha256 digest，元数据在 SQLite、blob 在磁盘 | 相同字节只存一份；元数据要可查询，blob 不该进数据库 |
+| 完整性 | 每次 `Get` 重校 digest | 磁盘损坏时静默返回脏数据比报错危险得多 |
+| 写入原子性 | `.tmp` + rename | 半个文件被当成完整内容会永久污染那个 digest |
+| 引用 | `owner_kind/owner_id/digest` 三元组主键，`AddRef` 幂等 | 三个 owner 类型：`context`（上下文事件）、`document`（文档）、`graph_sentence`（图谱句子） |
+| GC | 两阶段 + `minAge`，**有引用者绝不删** | 描述文本留在文本层，blob 可淘汰——语义记忆与字节缓存分离 |
+
+**媒体在纯文本记忆里的表示**是标记 `[<mime> <短digest>] <描述>`：
+
+```
+[image/png a1b2c3d4e5f6] 一张紫蓝红三色带图
+```
+
+之所以必须借文本承载：`Doc.Content`、`sentences.text`、文本记忆的 `Input` 全是字符串，
+没有字段能挂结构化数据。**描述文本才是持久的语义记忆**（检索靠它），digest 是回到字节的
+钥匙（反查靠它）。blob 被容量 GC 淘汰后，描述仍留在 L0/L2/L3 的文本里。
+
+媒体存储**全程可选**：`core.memory.media.enabled=false` 或未配置时，整条链路静默退化为
+纯文本行为，不报错不 panic。
+
 ### 其他记忆层
 
 - **Social** (`internal/memory/social/social.go`) — 人格特质和关系网，包装 GraphDB 实体类型
@@ -294,10 +324,14 @@ Lua 脚本插件加载：`internal/plugin/` → gopher-lua 解释器执行 `main
 
 | 面 | 机制 | 为何这么选 |
 |---|---|---|
-| 控制面 | stdio JSON-RPC（NDJSON 帧），51 个 `core.*` method | 进程边界即 ABI 边界，无需维护三套平台特定的动态库加载代码 |
+| 控制面 | stdio JSON-RPC（NDJSON 帧），55 个 `core.*` method | 进程边界即 ABI 边界，无需维护三套平台特定的动态库加载代码 |
 | 数据面 | 共享内存段，**全部子进程共用一块** | 每插件一段会让「内核 ctx → 段 → 插件改 → 回读 ctx」在多插件下退化成副本模型，lost update 原样复现 |
 | 通知面 | 事件环 + 平台通知（Linux eventfd / macOS pipe / Windows Event） | 内核发事件绕不等消费者，流式输出逐 token 发布时任何等待都会造成卡顿 |
 
+v1.1.1 新增 4 个 method（51 → 55）：`doc.insertWithMedia`、`io.injectMedia`、
+`io.injectMediaSync`、`io.injectInterruptMedia`。**媒体块走 JSON 而非共享段二进制通道**——
+data URL 本身已是 base64 文本，包进二进制传输省不了空间，还要跟其余 51 个 method 分道。
+
 **子进程生命周期管理**：
 - 每子进程一根专职 `waitLoop`（`cmd.Wait()` 唯一调用点）——不依赖 stdout EOF，
   因为插件 fork 的孙子进程（browser 拉 chromium、editdoc 拉 python）继承同一 stdout，
@@ -330,8 +364,20 @@ sdk.Memory().Recall/Commit
 sdk.Knowledge().Search/Create
 sdk.Settings().Get/Set/List
 sdk.RegisterOutputChannel("qq", sdk.CapText|sdk.CapAudio|sdk.CapImage, "QQ消息通道，详见 output_send__qq_help", handler)
+
+// v1.1.1 媒体接口（全部新增，无签名变更）
+sdk.DocMemory().InsertWithMedia(doc, attachments)   // 带 Data 的落进 CAS，只给 Digest 的引用已有内容
+sdk.InjectInputMedia(source, channel, text, blocks) // 媒体在「本轮」就发给模型
+sdk.InjectInputMediaSync(...)                       // 同上并同步等回复
+sdk.InjectInterruptMedia(...)                       // 带媒体的中断，可抢占当前处理
 ```
 
+媒体注入与 `SetToolBlocks` 的区别：后者只能在工具处理函数内部调用，且媒体要等**下一条**
+tool message 才到模型手上；前三个是插件**主动发起一轮带媒体的对话**，媒体随本轮消息发出，
+并自动落进 CAS、挂上媒体记忆引用。`Triple` 与 `Doc` 相应新增 `MediaDigests`、`Attachments`。
+
+`internal/sdk/` 是这层的桥接实现，不受公开接口冻结约束（见 `docs/git-branching.md` §六）。
+
 ### Plugin 接口
 
 ```go

assets/docs/zh/OVERVIEW.md

@@ -25,6 +25,17 @@ HomeAgent 是一个持续运行的个人智能 Agent 框架。
 
 三层递进：上下文 → 冷归档 → 长期图记忆，构成从短期到持久的信息衰减与整合管道。
 
+**媒体记忆（v1.1.0 起）** — 图片/音频不是附属物，而是三层里的一类节点：
+- **内容寻址存储（CAS）**：digest 寻址，元数据在 SQLite、blob 在磁盘，相同字节只存一份，
+  每次 `Get` 重校 digest（磁盘损坏静默返回脏数据比报错更危险）
+- **引用计数 GC**：`owner_kind/owner_id/digest` 三元组为主键，上下文事件/文档/图谱句子各自持引用；
+  **有引用者绝不删除**，仅回收无主且超过 `minAge` 的内容
+- **描述文本才是持久语义记忆**：视觉模型生成的描述以
+  `[<mime> <短digest>] <描述>` 标记形式写进纯文本记忆，参与向量检索与蒸馏；
+  blob 只是可被容量 GC 淘汰的缓存。几个月后“那张紫蓝红三色带图”仍可检索，靠的是描述而不是字节
+- **v1.1.1 起贯通插件边界**：插件可通过 `InsertWithMedia` / `InjectInputMedia` 读写媒体，
+  模型可用 `memory_commit` / `doc_commit` 的 `media_digests` 参数关联媒体
+
 ## 它实际做了什么
 
 代码位于项目仓库根目录，Go 语言实现。

cmd/homed/main.go

@@ -25,9 +25,11 @@ import (
 	luapkg "gitcode.com/JianFeeeee/HomeAgent/internal/lua"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/memory"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/document"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/media"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/pipeline"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/social"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/text"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/vector"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/meta"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/nlp"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/plugin"
@@ -41,10 +43,21 @@ import (
 	sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/supervisor"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/tracker"
+	"gitcode.com/JianFeeeee/HomeAgent/pkg/embedding"
 	"gitcode.com/JianFeeeee/HomeAgent/pkg/types"
+
+	// 空白导入内置 provider：它们各自在 init 里注册到 pkg/embedding。
+	// 想把核心换成自己的模型，只需替换这一行（或另建一个发行版 main）。
+	_ "gitcode.com/JianFeeeee/HomeAgent/providers/chineseclip"
+	_ "gitcode.com/JianFeeeee/HomeAgent/providers/qwen3vl"
 )
 
 func main() {
+	// 平台门放在最前面：比 flag 解析还早，因为原生 Windows 上根本不应进入任何
+	// 初始化路径（会去建共享段、拉插件进程）。理由与 WSL 指引见
+	// platform_windows.go。
+	requireSupportedPlatform()
+
 	dataDir := flag.String("data", "", "data directory (default: auto-detect next to binary)")
 	httpAddr := flag.String("webui", "", "webui listen address (default: webui.listen_addr from config)")
 	cliSocket := flag.String("socket", "", "cli unix socket path (default: <data>/cli.sock)")
@@ -319,10 +332,67 @@ func main() {
 	// 文档记忆 + 知识库
 	// ========================================================================
 
-	docStore := document.NewStore(filepath.Join(cfg.Daemon.DataDir, "memory", "documents"))
+	docStore := document.NewStore(filepath.Join(cfg.Daemon.DataDir, "memory", "documents"), memory.TokenizeWords)
 	if err := docStore.Start(); err != nil {
 		log.Printf("[homed] warning: document store: %v", err)
 	}
+	// 关停时落盘。文档记忆的内存态变更（迁移结果、访问计数等）只在 flush
+	// 里写盘，而 flush 的唯一入口是 Stop()——此前全仓无人调用它，
+	// 于是迁移结果永不落盘、每次启动白算一遍。
+	defer docStore.Stop()
+
+	// 媒体存储（内容寻址）：记忆块的内容后端。
+	// 开关默认开；关闭后全部媒体接线静默跳过，对话行为与本特性上线前一致。
+	var mediaStore *media.Store
+	if cfgReg.GetBool("core.memory.media.enabled", true) {
+		mediaDir := cfgReg.GetString("core.memory.media.dir",
+			filepath.Join(cfg.Daemon.DataDir, "memory", "media"))
+		ms, err := media.New(mediaDir)
+		if err != nil {
+			// 媒体存储开不起来不该阻止启动——它是记忆增强，不是对话必需品
+			log.Printf("[homed] warning: media store: %v（媒体记忆已禁用）", err)
+		} else {
+			mediaStore = ms
+			defer mediaStore.Close()
+			st := mediaStore.Stats()
+			log.Printf("[homed] media store active: %v 条 / %v 字节",
+				st["count"], st["total_bytes"])
+		}
+	}
+
+	// 统一多模态向量空间。
+	//
+	// 核心**不**知道任何具体模型：它只按配置里的 provider 名从公共注册表
+	// （pkg/embedding）打开一个 provider，并把 options.* 原样交给它。模型文件
+	// 布局、预处理、解码、运行时全部属于 provider 内部实现。
+	// provider 名为空时禁用多模态向量检索，退回纯 fastText 文本路径。
+	var multimodalSpace vector.MultimodalEmbedder
+	if mmProvider := cfgReg.GetString("core.memory.multimodal_space.provider", ""); mmProvider != "" {
+		opts := map[string]string{}
+		const optPrefix = "core.memory.multimodal_space.options."
+		for _, key := range cfgReg.List("core.memory.multimodal_space.options.") {
+			opts[strings.TrimPrefix(key, optPrefix)] = cfgReg.GetString(key, "")
+		}
+		provider, err := embedding.Open(mmProvider, embedding.Config{Options: opts})
+		if err != nil {
+			log.Printf("[homed] warning: 多模态向量 provider %q 打开失败: %v（多模态向量检索已禁用；已注册: %s）",
+				mmProvider, err, strings.Join(embedding.Names(), ", "))
+		} else if adapted, err := vector.AdaptProvider(provider); err != nil {
+			provider.Close()
+			log.Printf("[homed] warning: 多模态向量 provider %q 元数据不合法: %v（多模态向量检索已禁用）", mmProvider, err)
+		} else {
+			multimodalSpace = adapted
+			defer adapted.Close()
+			info := provider.Info()
+			// 指纹可能很长（模型文件哈希），日志里只取前 12 个字符便于对照。
+			shortFP := info.Fingerprint
+			if len(shortFP) > 12 {
+				shortFP = shortFP[:12]
+			}
+			log.Printf("[homed] multimodal space active: provider=%s dim=%d fp=%s modalities=%v",
+				mmProvider, info.Dimension, shortFP, info.Modalities)
+		}
+	}
 
 	ks := knowledge.NewStore(filepath.Join(cfg.Daemon.DataDir, "knowledge"))
 	if err := ks.Start(); err != nil {
@@ -356,6 +426,7 @@ func main() {
 	pluginReg.SetMemory(memDB)
 	pluginReg.SetTextMemory(textMem)
 	pluginReg.SetDocStore(docStore)
+	pluginReg.SetMediaStore(mediaStore) // 插件写入的记忆也走媒体链路；nil 时静默降级
 	pluginReg.SetKnowledge(ks)
 	pluginReg.SetProviderManager(providerMgr)
 	pluginReg.SetConfigRegistry(cfgReg)
@@ -431,6 +502,7 @@ func main() {
 		Knowledge:          ks,
 		SocialStore:        socialStore,
 		TextMemory:         textMem,
+		MediaStore:         mediaStore,
 		Personality:        personality,
 		PluginReg:          pluginReg,
 		PluginDir:          cfg.Plugin.Dir,
@@ -441,6 +513,7 @@ func main() {
 		ContextSavePath:    filepath.Join(cfg.Daemon.DataDir, "memory", "context.json"),
 		EmbeddingModelPath: cfgReg.GetString("core.agent.embedding_model_path", ""),
 		Embedder:           embedder,
+		MultimodalSpace:    multimodalSpace,
 		StageHost:          stageHost,
 		EventBus:           evBus,
 		ThinkingEnabled:    cfg.LLM.ThinkingEnabled,

cmd/homed/platform_other.go

@@ -0,0 +1,9 @@
+//go:build !windows
+
+package main
+
+// requireSupportedPlatform 在受支持的平台上不做任何事。
+//
+// 平台策略见 platform_windows.go：只有 homed 放弃 Windows 原生支持
+// （插件体系依赖 fd 继承与共享内存段内偏移），Windows 用户走 WSL2。
+func requireSupportedPlatform() {}

cmd/homed/platform_windows.go

@@ -0,0 +1,44 @@
+//go:build windows
+
+package main
+
+import (
+	"fmt"
+	"os"
+)
+
+// requireSupportedPlatform 在原生 Windows 上直接拒绝启动 homed。
+//
+// 为什么不做原生支持（不是「还没来得及做」，是设计上不做）：
+//
+// homed 的插件体系建立在两个原语上——**继承的 fd**（Single memfd: 统一共享
+// 内存区 + eventfd 通知）与**同段内相对偏移解引用**（各进程 mmap 到不同虚拟
+// 基址，段内一律用偏移互相读写，这样插件回调才能就地改写内核看到的那份数据）。
+//
+// Windows 的等价物是命名内核对象（CreateFileMappingW / OpenEventW）＋句柄表，
+// 没有 fd 继承语义（os/exec 的 ExtraFiles 在 Windows 上直接不被支持），
+// 生命周期与权限模型也按句柄而非进程继承来组织。要在其上重建这套语义，
+// 等于再维护一套平台专属 ABI 与安全边界——而 C ABI 时代正是「三套 ABI 并存
+// 导致改写型插件在某个平台上静默失效」的教训（§9.2）。
+//
+// 所以选择：**原生 Windows 不提供 homed**。Windows 用户跑 WSL2——
+// WSL2 里就是普通 linux/amd64，走与我们测试矩阵完全相同的那条路径。
+//
+// 注意范围：只有 homed 如此。plugindev 工具链仍可在 Windows 上运行
+// （在 Windows 上开发、为 WSL 构建 linux 插件是合理工作流）。
+func requireSupportedPlatform() {
+	fmt.Fprintln(os.Stderr, "homed 不支持 Windows 原生运行。")
+	fmt.Fprintln(os.Stderr, "")
+	fmt.Fprintln(os.Stderr, "原因：子进程插件依赖 fd 继承 + 统一共享内存区的段内偏移解引用，")
+	fmt.Fprintln(os.Stderr, "而 Windows 的句柄模型无法表达这两者；强行适配等于再维护一套平台专属")
+	fmt.Fprintln(os.Stderr, "ABI——C ABI 时代三套 ABI 并存曾导致改写型插件在某个平台上静默失效。")
+	fmt.Fprintln(os.Stderr, "")
+	fmt.Fprintln(os.Stderr, "请改用 WSL2：")
+	fmt.Fprintln(os.Stderr, "  1. wsl --install -d Ubuntu        # 安装 WSL2")
+	fmt.Fprintln(os.Stderr, "  2. 在 WSL 内下载 linux/amd64 的 homed 与插件（.hmap）")
+	fmt.Fprintln(os.Stderr, "  3. 在 WSL 内运行 homed：与 Linux 主机完全相同，无需额外配置")
+	fmt.Fprintln(os.Stderr, "")
+	fmt.Fprintln(os.Stderr, "数据目录可放在 /mnt/c/... 下以便与 Windows 侧共享，")
+	fmt.Fprintln(os.Stderr, "但不建议（跨文件系统 IO 慢、inotify 语义受限）；推荐放在 WSL 内部路径。")
+	os.Exit(2)
+}

cmd/initconfig/main.go

@@ -17,6 +17,36 @@ func randomSecret(n int) string {
 	return hex.EncodeToString(b)
 }
 
+// must 让失败真正停下来。
+//
+// 这里曾经把所有 db.Exec 的返回值丢掉，配合 CGO_ENABLED=0 构建（go-sqlite3
+// 退化成静态桩），得到的是一个**完全静默的空操作**：打印凭据、退出码 0、
+// config.db 里一个字节都没写。调用方（安装脚本）无法区分成败，用户装完
+// 照着 credentials.txt 登录必然失败。
+func must(err error) {
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "initconfig: %v\n", err)
+		os.Exit(1)
+	}
+}
+
+// verify 回读刚写入的值。
+//
+// 只看 Exec 有没有报错不够：驱动被换掉（如上面的桩）、路径不对、写入被丢弃，
+// 都可能返回 nil 而什么都没落下。这里把真实落盘的值读回来，与预期逐一比对，
+// 不一致就非零退出——"初始化脚本说自己成功了"必须由数据库内容佐证。
+func verify(db *sql.DB, table, key, want string) {
+	var got string
+	if err := db.QueryRow(fmt.Sprintf(`SELECT value FROM %s WHERE key = ?`, table), key).Scan(&got); err != nil {
+		fmt.Fprintf(os.Stderr, "initconfig: 回读 %s.%s 失败: %v\n", table, key, err)
+		os.Exit(1)
+	}
+	if got != want {
+		fmt.Fprintf(os.Stderr, "initconfig: %s.%s 与写入值不一致（读回 %q）\n", table, key, got)
+		os.Exit(1)
+	}
+}
+
 func main() {
 	dataDir := flag.String("data", "", "data directory")
 	webuiUsername := flag.String("username", "admin", "webui username")
@@ -33,16 +63,24 @@ func main() {
 
 	dbPath := *dataDir + "/config.db"
 	db, err := sql.Open("sqlite3", dbPath)
-	if err != nil {
-		fmt.Fprintf(os.Stderr, "open db: %v\n", err)
-		os.Exit(1)
-	}
+	must(err)
 	defer db.Close()
 
-	db.Exec("PRAGMA journal_mode=WAL")
+	// 尽早验证数据库真的可用：sql.Open 是惰性的，不碰一次不会暴露驱动问题。
+	if _, err := db.Exec("PRAGMA journal_mode=WAL"); err != nil {
+		fmt.Fprintf(os.Stderr, "initconfig: 打开数据库 %s 失败: %v\n", dbPath, err)
+		os.Exit(1)
+	}
 
-	db.Exec(`CREATE TABLE IF NOT EXISTS config (key TEXT PRIMARY KEY, value TEXT NOT NULL)`)
-	db.Exec(`INSERT OR IGNORE INTO config (key, value) VALUES (?, ?)`, "webui.listen_addr", ":8080")
+	if _, err := db.Exec(`CREATE TABLE IF NOT EXISTS config (key TEXT PRIMARY KEY, value TEXT NOT NULL)`); err != nil {
+		fmt.Fprintf(os.Stderr, "initconfig: 创建 config 表失败: %v\n", err)
+		os.Exit(1)
+	}
+	const listenAddr = ":8080"
+	if _, err := db.Exec(`INSERT OR IGNORE INTO config (key, value) VALUES (?, ?)`, "webui.listen_addr", listenAddr); err != nil {
+		fmt.Fprintf(os.Stderr, "initconfig: 写入 webui.listen_addr 失败: %v\n", err)
+		os.Exit(1)
+	}
 
 	pw := *webuiPassword
 	if pw == "" {
@@ -53,13 +91,28 @@ func main() {
 		apiKey = randomSecret(16)
 	}
 
-	pt := "config_webui"
-	db.Exec(fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (key TEXT PRIMARY KEY, value TEXT NOT NULL)`, pt))
+	const pt = "config_webui"
+	if _, err := db.Exec(fmt.Sprintf(`CREATE TABLE IF NOT EXISTS %s (key TEXT PRIMARY KEY, value TEXT NOT NULL)`, pt)); err != nil {
+		fmt.Fprintf(os.Stderr, "initconfig: 创建 %s 表失败: %v\n", pt, err)
+		os.Exit(1)
+	}
 	ws := fmt.Sprintf(`INSERT OR REPLACE INTO %s (key, value) VALUES (?, ?)`, pt)
-	db.Exec(ws, "api_key", apiKey)
-	db.Exec(ws, "username", *webuiUsername)
-	db.Exec(ws, "password", pw)
-	db.Exec(ws, "session_ttl_hours", "24")
+	for _, kv := range [][2]string{
+		{"api_key", apiKey},
+		{"username", *webuiUsername},
+		{"password", pw},
+		{"session_ttl_hours", "24"},
+	} {
+		if _, err := db.Exec(ws, kv[0], kv[1]); err != nil {
+			fmt.Fprintf(os.Stderr, "initconfig: 写入 %s.%s 失败: %v\n", pt, kv[0], err)
+			os.Exit(1)
+		}
+	}
+
+	verify(db, pt, "api_key", apiKey)
+	verify(db, pt, "username", *webuiUsername)
+	verify(db, pt, "password", pw)
+	verify(db, "config", "webui.listen_addr", listenAddr)
 
 	fmt.Printf("API_KEY=%s\n", apiKey)
 	fmt.Printf("WEBUI_USERNAME=%s\n", *webuiUsername)

deploy/homeagent.service

@@ -6,9 +6,11 @@ Wants=network-online.target
 
 [Service]
 Type=simple
-ExecStart=/usr/local/bin/homed -data /var/lib/homeagent
+ExecStart=/usr/bin/homed -data /var/lib/homeagent
 Restart=always
 RestartSec=10
+Environment=ONNXRUNTIME_DIR=/usr/lib/homeagent/onnxruntime
+StateDirectory=homeagent
 StartLimitBurst=3
 StartLimitInterval=60s
 
@@ -26,7 +28,9 @@ DeviceAllow=/dev/dsp rw
 # Resource limits
 LimitNOFILE=65536
 LimitNPROC=256
-MemoryMax=2G
+# Chinese-CLIP 本身实测约 1.15GB；加文档稠密索引、词向量、插件与
+# ORT arena 后生产实例约 4.5GB。2GB 会在首次全量建索引时被 cgroup OOM。
+MemoryMax=8G
 CPUQuota=100%
 
 [Install]

deploy/packaging/build.sh

@@ -15,6 +15,13 @@ BUILD_TIME="${BUILD_TIME:-$(date -u '+%Y-%m-%dT%H:%M:%SZ')}"
 GO="${GO:-$(command -v go 2>/dev/null || echo "go")}"
 LDFLAGS="-X gitcode.com/JianFeeeee/HomeAgent/internal/meta.Version=${VERSION} -X gitcode.com/JianFeeeee/HomeAgent/internal/meta.Commit=${COMMIT} -X gitcode.com/JianFeeeee/HomeAgent/internal/meta.BuildTime=${BUILD_TIME}"
 
+# 版本与提交的**权威来源**是上面注入的 meta.Version / meta.Commit，不是 Go 自带的
+# VCS 戳。后者不进 build cache key（Go 文档明确说明 VCS 变化不会触发重建），
+# 命中缓存时会把上一次的 revision 一并带回来——实测发布分支的产物上就出现了
+# 1715b5c（本机任何仓库都不存在的提交），用 `go version -m` 溯源会指向幽灵提交。
+# 统一 -buildvcs=false：宁可没有这个信号，也不要一个错的。
+# 溯源请用：`strings homed | grep -m1 '^<短 hash>$'`（meta.Commit 是字符串常量）。
+
 TARGET="${1:-native}"
 COMPONENT="${2:-all}"
 
@@ -55,7 +62,7 @@ case "$TARGET" in
     ;;
   *)
     echo "Unknown target: $TARGET"
-    echo "Usage: $0 [native|linux/amd64|linux/arm64|darwin/amd64|darwin/arm64|windows/amd64|all]"
+    echo "Usage: $0 [native|linux/amd64|linux/arm64|darwin/amd64|darwin/arm64|windows/amd64|all] [all|homed|waiter|initconfig|gui|payload]"
     echo "       [all|homed|waiter|initconfig|gui]"
     exit 1
 esac
@@ -118,8 +125,21 @@ build_homed() {
   # Go 用 CC 驱动 CGO 编译与链接，用 CC 指定的交叉工具链来决定目标架构。
   # 必须同时 export CC 给 Go 的 CGO 代码生成器，否则 CGO_ENABLED=1 下的
   # 目标文件与 host 的 ld 不兼容（如 arm64 的 .o 给了 x86_64 的 ld）。
+  #
+  # HOMED_TAGS 默认带 onnxruntime：发行版**默认启用**本地向量空间。
+  # 不带这个标签时 providers/chineseclip 与 providers/qwen3vl 仍会注册，
+  # 但打开时报「requires build tag」并优雅降级（不静默假装成功）。
+  # 需要极简构建时可显式 HOMED_TAGS= 关掉。
+  #
+  # 运行期还需要 libonnxruntime.so（provider 按 /opt/onnxruntime、
+  # /usr/local/lib、/usr/lib 顺序查找）；缺失时同样是「日志里的明确错误 +
+  # 降级」，不会假装启用。
   local _cc="${CC:-cc}"
-  CGO_ENABLED=1 CC="$_cc" "$GO" build -trimpath -installsuffix dynlink \
+  local _tags="${HOMED_TAGS-onnxruntime}"
+  local -a _tagargs=()
+  if [ -n "$_tags" ]; then _tagargs=(-tags "$_tags"); fi
+  CGO_ENABLED=1 CC="$_cc" "$GO" build -buildvcs=false -trimpath -installsuffix dynlink \
+    ${_tagargs[@]+"${_tagargs[@]}"} \
     -ldflags "$LDFLAGS" -o "$out" ./cmd/homed/
   echo "  OK ($(file "$out" | sed 's/.*: //') | $(du -h "$out" | cut -f1))"
 }
@@ -131,28 +151,74 @@ build_waiter() {
   if [ "$GOOS" = "windows" ]; then out="${out}.exe"; fi
 
   echo "[BUILD] waiter ${plat} → $out"
-  CGO_ENABLED=0 "$GO" build -trimpath -installsuffix dynlink \
+  CGO_ENABLED=0 "$GO" build -buildvcs=false -trimpath -installsuffix dynlink \
     -ldflags "$LDFLAGS" -o "$out" ./cmd/waiter/
   echo "  OK ($(du -h "$out" | cut -f1))"
 }
 
-# ---- initconfig (CGO-free 配置初始化器) ----
+# ---- initconfig（必须 cgo：写 config.db 用的是 go-sqlite3）----
 #
-# NSIS 安装包（installer.nsi:220 File "..\build\initconfig.exe"）与
-# package-linux.sh 的 stage_variant 都引用它，但此前 build.sh 从不构建它——
-# Windows 安装包构建会直接失败在缺文件上。
+# 这里**必须** CGO_ENABLED=1。此前写的是 CGO_ENABLED=0，而 cmd/initconfig 通过
+# database/sql 使用 mattn/go-sqlite3：CGO_ENABLED=0 时该库退化成 static_mock.go
+# 里的桩，sql.Open 是懒的所以不报错、第一次 Exec 才失败；而 main.go 当时忽略
+# 了所有错误——于是 initconfig 打印凭据、退出码 0、一个字节都没写进 config.db。
+# 安装脚本把这份凭据写进 credentials.txt，用户照它登录必然失败，全程无报错。
+#
+# NSIS 安装包（installer.nsi）与 package-linux.sh 的 stage_variant 都引用它，
+# 但此前 build.sh 从不构建它——Windows 安装包构建会直接失败在缺文件上。
 build_initconfig() {
   local plat="${GOOS:-linux}/${GOARCH:-amd64}"
   local out="$BUILD_DIR/initconfig${SUFFIX:+_$SUFFIX}"
   if [ "$GOOS" = "windows" ]; then out="${out}.exe"; fi
 
   echo "[BUILD] initconfig ${plat} → $out"
-  CGO_ENABLED=0 "$GO" build -trimpath -installsuffix dynlink \
+  CGO_ENABLED=1 "$GO" build -buildvcs=false -trimpath -installsuffix dynlink \
     -ldflags "$LDFLAGS" -o "$out" ./cmd/initconfig/
   echo "  OK ($(du -h "$out" | cut -f1))"
 }
 
+# ---- linux-payload（给 Windows 安装器用的 Linux 包）----
+#
+# Windows 不再安装 homed.exe：homed 依赖 fd 继承 + 统一共享内存区的段内偏移
+# 解引用，Windows 句柄模型无法表达（见 cmd/homed/platform_windows.go）。
+# Windows 安装器改为引导到 WSL2，并把 **Linux 包**送进发行版里安装。
+# 因此 Windows 安装包必须带上 Linux 产物——这一段就是把它暂存到
+# build/linux-payload/（installer.nsi 从这里 File /r 打进安装包）。
+#
+# 复用 package-linux.sh 的产物，而不是在这里另行编译：WSL 里跑的就是普通
+# linux/amd64，安装内容必须与 Linux 原生安装**完全一致**，否则又变成两个平台。
+stage_linux_payload() {
+  local src="$PROJECT_ROOT/dist/linux"
+  local out="$BUILD_DIR/linux-payload"
+
+  rm -rf "$out"
+  mkdir -p "$out"
+
+  local found=0
+  for f in "$src"/*.deb "$src"/*.tar.gz; do
+    [ -f "$f" ] || continue
+    cp "$f" "$out/"
+    found=$((found + 1))
+  done
+
+  if [ "$found" -eq 0 ]; then
+    echo "[FAIL] build/linux-payload 为空：先运行 package-linux.sh 产出 dist/linux/*.deb|*.tar.gz" >&2
+    echo "       （Windows 安装器会把这里的包送进 WSL 安装；空包等于装不上）" >&2
+    return 1
+  fi
+  echo "[BUILD] linux-payload ← $found 个包"
+  ls -1 "$out" | sed 's/^/  /'
+}
+
 # ---- gui (Electron) ----
+#
+# 输出目录必须用 --config.directories.output，**不能用 -o**：
+# electron-builder 的 `-o` 是 `--mac`/`--macos` 的短别名（见 --help 的 Building 段），
+# 不是 output。此前 `-o "$BUILD_DIR"` 被当成 macOS 的 target 列表，报
+#   ⨯ Unknown target: /home/program/trueagent/build
+# （路径被 lowercase 后去匹配 target 名表，所以错误信息里的路径是全小写的，
+#  这也是它看起来像「路径错」而实际是「参数位置错」的原因）。
+# v1.0.1 与 v1.0.3 两次发布都因此手工组装过 GUI。
 build_gui() {
   if [ -n "${GOOS:-}" ] && [ "$GOOS" != "$("$GO" env GOOS)" ]; then
     echo "[SKIP] gui ${GOOS}/${GOARCH} — electron-builder handles cross-platform natively; run 'all' on CI host"
@@ -170,22 +236,52 @@ build_gui() {
   # 不传 --config：electron-builder 默认从 package.json 的 "build" 键读配置。
   # 传 --config package.json 会让它把**整个** package.json 当配置校验，
   # 于是 devDependencies / build / scripts 全被判为 "unknown property" 而失败。
-  (cd "$gui_dir" && npx electron-builder \
-    --linux --win --mac \
-    --x64 --arm64 \
-    -p never \
-    -o "$BUILD_DIR")
-  echo "  OK"
+  #
+  # GUI 失败不中断整体构建：homed/waiter/initconfig 是发布的主体，
+  # 而 GUI 依赖 electron 运行时下载（离线机器、arm64 缺缓存都会失败）。
+  # set -e 下若不接住，一个可选组件会让整轮跨平台构建全废。
+  if (cd "$gui_dir" && npx electron-builder \
+      --linux --win --mac \
+      --x64 --arm64 \
+      -p never \
+      --config.directories.output="$BUILD_DIR"); then
+    echo "  OK"
+  else
+    echo "  WARN: gui 构建失败（可选组件，不影响 homed/waiter/initconfig）"
+    echo "        Linux 包可用 deploy/packaging/package-linux.sh 内置的手工组装路径"
+    return 0
+  fi
 }
 
 # ---- dispatch ----
-case "$COMPONENT" in
-  all)   build_homed; build_waiter; build_initconfig; build_gui ;;
-  homed) build_homed ;;
-  waiter) build_waiter ;;
-  initconfig) build_initconfig ;;
-  gui)   build_gui ;;
-  *)
-    echo "Unknown component: $COMPONENT"
-    exit 1
-esac
+if [ "${GOOS:-}" = "windows" ]; then
+  # Windows 目标：构建的**不是** homed——它已放弃 Windows 原生支持。
+  # 需要的是：Linux 包（送进 WSL 安装）+ Windows 侧客户端（waiter CLI / GUI）。
+  case "$COMPONENT" in
+    all)   build_waiter; stage_linux_payload; build_gui ;;
+    waiter) build_waiter ;;
+    payload) stage_linux_payload ;;
+    gui)   build_gui ;;
+    homed|initconfig)
+      echo "homed/initconfig 不再提供 Windows 原生构建：请用 WSL2（或用 linux/amd64 目标）。" >&2
+      echo "原因见 cmd/homed/platform_windows.go。" >&2
+      exit 1
+      ;;
+    *)
+      echo "Unknown component: $COMPONENT"
+      exit 1
+      ;;
+  esac
+else
+  case "$COMPONENT" in
+    all)   build_homed; build_waiter; build_initconfig; build_gui ;;
+    homed) build_homed ;;
+    waiter) build_waiter ;;
+    initconfig) build_initconfig ;;
+    gui)   build_gui ;;
+    *)
+      echo "Unknown component: $COMPONENT"
+      exit 1
+      ;;
+  esac
+fi

deploy/packaging/installer.nsi

@@ -14,7 +14,7 @@
 # 此前硬编码 0.8.0 而 release 已到 1.0.0，装出来的包在「添加/删除程序」里
 # 会显示错误版本（DisplayVersion 也取自这个宏）。
 !ifndef PRODUCT_VERSION
-  !define PRODUCT_VERSION "1.0.3"
+  !define PRODUCT_VERSION "1.0.0"
 !endif
 
 !if "${VARIANT}" == "full"
@@ -76,6 +76,10 @@ Function GenKey
 FunctionEnd
 
 !insertmacro MUI_PAGE_WELCOME
+; 许可页：AGPL-3.0-only（全文在仓库根 LICENSE）。
+; NSIS 的 File/!insertmacro 相对路径以**本 .nsi 所在目录**为基准解析，
+; 而本文件在 deploy/packaging/，故仓库根是 ..\..\ 。
+!insertmacro MUI_PAGE_LICENSE "..\..\LICENSE"
 !insertmacro MUI_PAGE_DIRECTORY
 
 !if "${HAS_CREDENTIALS}" == "1"
@@ -216,17 +220,26 @@ FunctionEnd
 
 Section "Install" SEC_INSTALL
   SetOutPath "$INSTDIR"
+  ; WSL 引导脚本随安装包分发（它负责检测/引导 WSL 并把 Linux 包装进发行版）
+  File "..\..\deploy\packaging\windows\install-via-wsl.ps1"
   CreateDirectory "$INSTDIR\data"
   CreateDirectory "$INSTDIR\data\log"
   CreateDirectory "$INSTDIR\data\plugins"
   CreateDirectory "$INSTDIR\data\adapters"
 
+; homed **不再装到 Windows**：插件体系依赖 fd 继承与统一共享内存区的段内偏移
+; 解引用，Windows 的句柄模型无法表达（见 cmd/homed/platform_windows.go）。
+; Windows 侧改为引导到 WSL2，把 **Linux 包**送进发行版里按 Linux 的方式安装。
+; 所以这里带的是 linux/amd64 的 payload，不是 homed.exe。
 !if "${HAS_CORE}" == "1"
-  File "..\..\build\initconfig.exe"
-  File "..\..\build\homed.exe"
+  SetOutPath "$PLUGINSDIR\linux-payload"
+  File /r "..\..\build\linux-payload\*.*"
+  SetOutPath "$INSTDIR"
 !endif
 
 !if "${HAS_WAITER}" == "1"
+  ; waiter 是 CLI 客户端：WSL 侧会装上 Linux 版；Windows 侧仍可保留原生版
+  ; （它只是个客户端，不走插件体系）。
   File "..\..\build\waiter.exe"
 !endif
 
@@ -237,11 +250,24 @@ Section "Install" SEC_INSTALL
 !endif
 
 !if "${HAS_CORE}" == "1"
-  DetailPrint "初始化配置数据库..."
-  nsExec::Exec '"$INSTDIR\initconfig.exe" -data "$INSTDIR\data" -username "$webuiUsername" -password "$webuiPassword" -apikey "$apiKey"'
+  ; 在 WSL2 里安装 homed。凭据（页面上收的那三个）透传进去，避免
+  ; 「界面显示一份、config.db 里另一份」导致登录不上。
+  DetailPrint "检测 WSL 并在其中安装 HomeAgent..."
+  nsExec::ExecToStack 'powershell -NoProfile -ExecutionPolicy Bypass -File "$INSTDIR\install-via-wsl.ps1" -PayloadDir "$PLUGINSDIR\linux-payload" -ApiKey "$apiKey" -WebUIUser "$webuiUsername" -WebUIPass "$webuiPassword"'
   Pop $0
+  Pop $1
   ${If} $0 != 0
-    DetailPrint "警告: 数据库初始化可能未成功完成"
+    ; 退出码含义见 install-via-wsl.ps1：20/21 是「WSL 或发行版缺失，需要先装」，
+    ; 属于可指引的用户动作，不当成安装失败来恐吓人。
+    ${If} $0 == 20
+      MessageBox MB_ICONINFORMATION|MB_OK "未检测到 WSL。$\r$\n$\r$\n请在管理员 PowerShell 中执行：$\r$\n    wsl --install$\r$\n$\r$\n然后重启 Windows，再重新运行本安装程序。"
+    ${ElseIf} $0 == 21
+      MessageBox MB_ICONINFORMATION|MB_OK "WSL 已安装，但还没有发行版。$\r$\n$\r$\n请先执行：$\r$\n    wsl --install -d Ubuntu$\r$\n$\r$\n完成首次初始化后再重新运行本安装程序。"
+    ${Else}
+      MessageBox MB_ICONEXCLAMATION|MB_OK "WSL 内安装失败（退出码 $0）。$\r$\n$\r$\n可进入 WSL 手动排查：wsl -d Ubuntu$\r$\n安装脚本输出见上方日志。"
+    ${EndIf}
+  ${Else}
+    DetailPrint "HomeAgent 已在 WSL2 内安装完成"
   ${EndIf}
 !endif
 

deploy/packaging/linux/deb/control-full

@@ -3,7 +3,7 @@ Version: VERSION_PLACEHOLDER
 Architecture: ARCH_PLACEHOLDER
 Maintainer: HomeAgent Team <team@homeagent.ai>
 Installed-Size: INSTALLED_SIZE_PLACEHOLDER
-Depends: libc6 (>= 2.28)
+Depends: libc6 (>= 2.28), libstdc++6, libgcc-s1
 Section: utils
 Priority: optional
 Homepage: https://github.com/trueagent/HomeAgent

deploy/packaging/linux/deb/control-server

@@ -3,7 +3,7 @@ Version: VERSION_PLACEHOLDER
 Architecture: ARCH_PLACEHOLDER
 Maintainer: HomeAgent Team <team@homeagent.ai>
 Installed-Size: INSTALLED_SIZE_PLACEHOLDER
-Depends: libc6 (>= 2.28)
+Depends: libc6 (>= 2.28), libstdc++6, libgcc-s1
 Section: utils
 Priority: optional
 Homepage: https://github.com/trueagent/HomeAgent

deploy/packaging/linux/deb/postinst

@@ -2,24 +2,63 @@
 set -e
 
 SERVICE_NAME="homeagent"
-SERVICE_FILE="/lib/systemd/system/${SERVICE_NAME}.service"
 HOMED_BIN="/usr/bin/homed"
 DATA_DIR="/var/lib/homeagent"
+SETUP_SH="/usr/lib/homeagent/setup.sh"
+
+# unit 由本包装到 /etc/systemd/system/，而旧 postinst 只查
+# /lib/systemd/system/（merged-usr 下等于 /usr/lib/systemd/system，那里没有
+# 这个文件）——于是 daemon-reload 与 enable **从未执行过**：装完不会开机自启，
+# 而 postinst 全程无报错。这里三个候选位置都看一下。
+find_unit() {
+  for p in "/etc/systemd/system/${SERVICE_NAME}.service" \
+           "/usr/lib/systemd/system/${SERVICE_NAME}.service" \
+           "/lib/systemd/system/${SERVICE_NAME}.service"; do
+    if [ -f "$p" ]; then
+      printf '%s' "$p"
+      return 0
+    fi
+  done
+  return 1
+}
 
 case "$1" in
   configure)
     if [ -f "$HOMED_BIN" ]; then
       mkdir -p "$DATA_DIR"
 
-      # 初始化凭据和数据库
-      if [ -x /usr/lib/homeagent/setup.sh ]; then
-        HOMEAGENT_DATA="$DATA_DIR" /usr/lib/homeagent/setup.sh || true
+      # 初始化凭据和数据库。
+      #
+      # 这里不能再用 `|| true` 吞失败：setup.sh 靠 initconfig 写 config.db，
+      # 而 initconfig 曾因 CGO_ENABLED=0 静默空操作（凭据只进了
+      # credentials.txt、没进数据库），用户拿它登录必然失败，安装却一声不响。
+      # 失败必须看得见，并给出可直接执行的补救命令。
+      if [ -x "$SETUP_SH" ]; then
+        if ! HOMEAGENT_DATA="$DATA_DIR" "$SETUP_SH"; then
+          echo "E: homeagent 初始化失败——凭据可能未写入 config.db。" >&2
+          echo "E: 请手动重试：HOMEAGENT_DATA=$DATA_DIR $SETUP_SH" >&2
+        fi
+      else
+        echo "W: 未找到 $SETUP_SH，跳过凭据初始化。" >&2
       fi
 
       # 注册 systemd 服务
-      if [ -f "$SERVICE_FILE" ]; then
-        systemctl daemon-reload 2>/dev/null || true
-        systemctl enable "$SERVICE_NAME" 2>/dev/null || true
+      if command -v systemctl >/dev/null 2>&1; then
+        if find_unit >/dev/null; then
+          systemctl daemon-reload 2>/dev/null || true
+          systemctl enable "$SERVICE_NAME" 2>/dev/null || true
+          # 首次安装就拉起来，装完即可用；升级时重启以真正加载新二进制
+          # （仅 enable 不会让已在运行的进程换用新文件）。
+          if [ -z "${2:-}" ]; then
+            systemctl start "$SERVICE_NAME" 2>/dev/null || \
+              echo "W: homeagent 服务未能启动，请检查：systemctl status $SERVICE_NAME" >&2
+          else
+            systemctl restart "$SERVICE_NAME" 2>/dev/null || \
+              echo "W: homeagent 服务未能重启，请检查：systemctl status $SERVICE_NAME" >&2
+          fi
+        else
+          echo "W: 未找到 ${SERVICE_NAME}.service，未启用服务。" >&2
+        fi
       fi
     fi
     ;;

deploy/packaging/linux/setup.sh

@@ -8,16 +8,32 @@ CRED_FILE="${DATA_DIR}/credentials.txt"
 CONFIG_DB="${DATA_DIR}/config.db"
 WAITER_CONF="${DATA_DIR}/waiter.yaml"
 INITCONFIG_BIN="/usr/bin/initconfig"
+BUNDLED_MODEL_DIR="/usr/lib/homeagent/models/chinese-clip-vit-b16-onnx"
+MODEL_LINK="${DATA_DIR}/models/chinese-clip-vit-b16-onnx"
 
-# 如果已经初始化过，跳过
+# 模型随 server/full 包安装到只读的 /usr/lib；配置默认仍指向 dataDir/models。
+# 用符号链接把两者接起来，既不复制 754MB，也保持 dataDir 可迁移语义。
+# 用户已有自定义目录时绝不覆盖；升级时既有链接自然指向新版包内容。
+if [ -d "$BUNDLED_MODEL_DIR" ]; then
+  mkdir -p "${DATA_DIR}/models"
+  if [ ! -e "$MODEL_LINK" ] && [ ! -L "$MODEL_LINK" ]; then
+    ln -s "$BUNDLED_MODEL_DIR" "$MODEL_LINK"
+  fi
+fi
+
+# 如果已经初始化过，只跳过凭据/数据库生成；上面的模型链接仍须在升级时补齐。
 if [ -f "$CONFIG_DB" ] && [ -f "$CRED_FILE" ]; then
   exit 0
 fi
 
 mkdir -p "$DATA_DIR"
 
-# 生成随机凭据
-API_KEY=$(cat /proc/sys/kernel/random/uuid 2>/dev/null | tr -d '-' || echo "homeagent$(date +%s)")
+# 生成随机凭据。
+#
+# 允许环境变量覆盖：安装器（包括 Windows 上的 WSL 引导安装）已经在界面上
+# 向用户收过这些值，若不接受传入就只能两个地方各生成一份，用户看到的那份
+# 与实际写入 config.db 的那份不一致——那种错会直接表现为「登录不上」。
+API_KEY="${HOMEAGENT_API_KEY:-$(cat /proc/sys/kernel/random/uuid 2>/dev/null | tr -d '-' || echo "homeagent$(date +%s)")}"
 WEBUI_USER="${WEBUI_USER:-admin}"
 WEBUI_PASS="${WEBUI_PASS:-$(openssl rand -hex 12 2>/dev/null || echo "homeagent")}"
 

deploy/packaging/package-linux.sh

@@ -5,23 +5,56 @@ PROJECT_ROOT="$(cd "$(dirname "$0")/../.." && pwd)"
 BUILD_DIR="${PROJECT_ROOT}/build"
 DIST_DIR="${PROJECT_ROOT}/dist/linux"
 VERSION="${VERSION:-$(git -C "$PROJECT_ROOT" describe --tags --dirty 2>/dev/null || echo "0.8.0")}"
+
+# git describe 给出的是 v1.0.0-68-gba0b5a1-dirty 这类描述串，它不是合法的包版本：
+# deb 的 Version 必须以数字开头，rpm 的 Version 不允许 '-'（那是版本/发布的分隔符）。
+# 以前只有显式传 VERSION=1.0.3 才打得出来，默认路径一跑就死在 dpkg-deb 上——
+# 而且死在 stage 之后，前面每条日志都是真的，只有最后一个产物没生成。
+PKG_VERSION="${VERSION#v}"
+case "$PKG_VERSION" in
+  [0-9]*) ;;
+  *) echo "ERROR: 包版本必须以数字开头（得到 '$VERSION'）。请显式设置 VERSION=x.y.z 后重试。" >&2; exit 1 ;;
+esac
+PKG_VERSION="$(printf '%s' "$PKG_VERSION" | sed -e 's/-/+/g')"
 PACKAGE_ROOT="${PROJECT_ROOT}/deploy/packaging/linux"
 GO="${GO:-$(command -v go 2>/dev/null || echo "go")}"
 
 ARCH="${1:-amd64}"   # amd64 or arm64
+
+# server/full 发行包默认带 Chinese-CLIP ONNX 产物与 ONNX Runtime。
+# 二进制大资产不进 git：发布环境通过这两个目录提供已验证的产物；若缺失，
+# server/full 打包必须明确失败，不能生成一个「默认启用但装完不能用」的假包。
+CHINESECLIP_BUNDLE_DIR="${CHINESECLIP_BUNDLE_DIR:-$BUILD_DIR/model-assets/chinese-clip-vit-b16-onnx}"
+ONNXRUNTIME_ASSET_DIR="${ONNXRUNTIME_ASSET_DIR:-$BUILD_DIR/runtime-assets/$ARCH}"
+ONNXRUNTIME_LIB="${ONNXRUNTIME_LIB:-$ONNXRUNTIME_ASSET_DIR/libonnxruntime.so}"
+ONNXRUNTIME_LICENSE="${ONNXRUNTIME_LICENSE:-$ONNXRUNTIME_ASSET_DIR/LICENSE}"
+ONNXRUNTIME_NOTICES="${ONNXRUNTIME_NOTICES:-$ONNXRUNTIME_ASSET_DIR/ThirdPartyNotices.txt}"
+
+# 打包 staging 会把 719MB 模型真的复制一份，临时目录必须落在构建目录所在的磁盘，
+# 不能落在系统临时目录：本机 /tmp 是 9.8GB tmpfs，一次 full 包 staging 就能写满，
+# 而且失败发生在 cp 进行到一半，报出来是 "No space left on device"——看上去像
+# 资产／版本有问题，实际只是临时目录选错了文件系统。
+STAGE_TMP="${BUILD_DIR}/.stage-tmp"
+
+# electron 官方发布物用 x64/arm64 命名，而 Debian 用 amd64/arm64。
+# 两者在 arm64 上恰好同名，amd64 上不同——此前缓存查找统一用 TAR_ARCH
+# （amd64），于是 electron-v*-linux-x64.zip 永远命中不到，amd64 GUI 只能
+# 靠"回退到 host node_modules"这条路组装。干净 worktree 里没有完整
+# node_modules，GUI 就被静默跳过。故单独映射。
 ACTION="${2:-all}"    # all, build, deb, tar, rpm
 
 DEB_ARCH="$ARCH"
 RPM_ARCH="$ARCH"
 TAR_ARCH="$ARCH"
 case "$ARCH" in
-  amd64) DEB_ARCH="amd64"; RPM_ARCH="x86_64"; TAR_ARCH="amd64" ;;
-  arm64) DEB_ARCH="arm64"; RPM_ARCH="aarch64"; TAR_ARCH="arm64" ;;
+  amd64) DEB_ARCH="amd64"; RPM_ARCH="x86_64"; TAR_ARCH="amd64"; ELECTRON_ARCH="x64" ;;
+  arm64) DEB_ARCH="arm64"; RPM_ARCH="aarch64"; TAR_ARCH="arm64"; ELECTRON_ARCH="arm64" ;;
   *) echo "Unknown arch: $ARCH (use amd64 or arm64)"; exit 1 ;;
 esac
 
 echo "=== HomeAgent Linux Packager ==="
 echo "Version: $VERSION"
+[ "$PKG_VERSION" = "$VERSION" ] || echo "Package: $PKG_VERSION (normalized for deb/rpm)"
 echo "Arch:    $ARCH"
 echo ""
 
@@ -83,7 +116,7 @@ restore_syso() {
 }
 
 # ensure both are always restored on exit
-restore_all() { restore_gomod; restore_syso; }
+restore_all() { restore_gomod; restore_syso; rmdir "$STAGE_TMP" 2>/dev/null || true; }
 trap restore_all EXIT
 
 # ---- build Go binaries via existing build.sh ----
@@ -93,35 +126,42 @@ build_go() {
   prepare_gomod || true
   hide_syso
 
-  bash "$PROJECT_ROOT/deploy/packaging/build.sh" "linux/$ARCH" "homed" 2>&1 || {
-    echo "WARNING: homed build failed (CGO/sqlite3 issue). Server/full packages may be incomplete."
-  }
-  bash "$PROJECT_ROOT/deploy/packaging/build.sh" "linux/$ARCH" "waiter" 2>&1 || {
-    echo "WARNING: waiter build failed."
-  }
-  bash "$PROJECT_ROOT/deploy/packaging/build.sh" "linux/$ARCH" "initconfig" 2>&1 || {
-    echo "WARNING: initconfig build failed（包内将缺少首次配置初始化器）。"
-  }
-
   local suffix="linux_${ARCH}"
   local homed_bin="$BUILD_DIR/homed_$suffix"
   local waiter_bin="$BUILD_DIR/waiter_$suffix"
+  local initconfig_bin="$BUILD_DIR/initconfig_$suffix"
 
-  if [ ! -f "$homed_bin" ]; then
-    echo "ERROR: homed binary not found at $homed_bin"
-    exit 1
-  fi
-  if [ ! -f "$waiter_bin" ]; then
-    echo "ERROR: waiter binary not found at $waiter_bin"
-    exit 1
+  # 先删旧产物：否则本次构建失败后，残留文件会让「产物存在」判据假绿。
+  rm -f "$homed_bin" "$waiter_bin" "$initconfig_bin"
+
+  bash "$PROJECT_ROOT/deploy/packaging/build.sh" "linux/$ARCH" "homed"
+  test -x "$homed_bin"
+  if ! go version -m "$homed_bin" | grep -Eq 'build[[:space:]]+-tags=.*onnxruntime'; then
+    echo "ERROR: homed 不是 onnxruntime 构建，拒绝打 server/full 包：$homed_bin" >&2
+    return 1
   fi
 
-  echo "  homed:  $homed_bin ($(du -h "$homed_bin" | cut -f1))"
-  echo "  waiter: $waiter_bin ($(du -h "$waiter_bin" | cut -f1))"
+  bash "$PROJECT_ROOT/deploy/packaging/build.sh" "linux/$ARCH" "waiter"
+  test -x "$waiter_bin"
+  bash "$PROJECT_ROOT/deploy/packaging/build.sh" "linux/$ARCH" "initconfig"
+  test -x "$initconfig_bin"
+
+  echo "  homed:      $homed_bin ($(du -h "$homed_bin" | cut -f1), onnxruntime)"
+  echo "  waiter:     $waiter_bin ($(du -h "$waiter_bin" | cut -f1))"
+  echo "  initconfig: $initconfig_bin ($(du -h "$initconfig_bin" | cut -f1))"
   echo ""
 }
 
 # ---- build GUI (manual directory assembly, avoids electron-packager network issues) ----
+#
+# electron 运行时必须按**目标架构**取，不能用 host 的
+# node_modules/electron/dist——那里永远是 host 架构（本机 x64）。
+# v1.0.0 / v1.0.1 的 arm64 full/client 包都踩了这个坑：目录名带
+# -arm64、homed/waiter 确实是 aarch64，但里面的 electron 是 x86-64，
+# 在 arm64 机器上一启动就是 Exec format error（从未被交叉验证过）。
+#
+# 现在改为优先从 electron 缓存里取对应架构的 zip，并在最后做
+# 一道强制校验：架构不符就删掉目录并跳过 GUI，宁可不发也不发坏包。
 build_gui() {
   local gui_dir="$PROJECT_ROOT/cmd/gui"
   local gui_out="$BUILD_DIR/homeagent-gui-linux-${TAR_ARCH}"
@@ -133,22 +173,81 @@ build_gui() {
 
   echo ">>> Building GUI directory for linux/$ARCH..."
 
-  if [ ! -d "$gui_dir/node_modules" ]; then
+  # 判据是 electron 包本身在不在，而不是 node_modules 目录在不在。
+  #
+  # npm install 失败（离线、网络受限）会留下一个只有一两个条目的空壳
+  # node_modules，目录存在但 electron 缺失。只看目录会以为"已安装"，
+  # 于是 ever 读不到版本、缓存匹配退化、最后走到"host dist 也没有"而
+  # 静默跳过 GUI——包名和目录名全都正确，只是没有 GUI，没有任何一步报错。
+  if [ ! -f "$gui_dir/node_modules/electron/package.json" ]; then
+    if [ -d "$gui_dir/node_modules" ]; then
+      echo "  node_modules 存在但 electron 缺失（疑似上次 npm install 未完成）"
+    fi
     echo "  npm install..."
-    (cd "$gui_dir" && npm install --production)
+    if ! (cd "$gui_dir" && npm install --production); then
+      echo "  WARNING: npm install 失败——离线环境下这是预期的。"
+      echo "           GUI 需要 cmd/gui/node_modules/electron 或 ~/.cache/electron 缓存。"
+    fi
   fi
 
-  local electron_dir="$gui_dir/node_modules/electron/dist"
-  if [ ! -f "$electron_dir/electron" ]; then
-    echo "  WARNING: electron binary not found at $electron_dir. GUI will be skipped."
-    return
+  # electron 版本优先从已安装的包里读，保证运行时与 app 依赖一致。
+  # 读不到时退而从 package.json 的依赖声明里取数字部分（它可能写成
+  # "^33.0.0" 这类范围，只用于给缓存匹配一个提示，匹配不上仍会走通配）。
+  local ever
+  ever=$(python3 -c "import json;print(json.load(open('$gui_dir/node_modules/electron/package.json'))['version'])" 2>/dev/null || true)
+  if [ -z "$ever" ]; then
+    ever=$(python3 -c "
+import json, re
+d = json.load(open('$gui_dir/package.json'))
+spec = (d.get('devDependencies', {}) or {}).get('electron') or (d.get('dependencies', {}) or {}).get('electron') or ''
+m = re.search(r'(\\d+(?:\\.\\d+)*)', spec)
+print(m.group(1) if m else '')
+" 2>/dev/null || true)
+    [ -n "$ever" ] && echo "  electron 版本取自 package.json 依赖声明: $ever（非精确）"
+  fi
+
+  mkdir -p "$gui_out"
+
+  # 优先：缓存里的目标架构 zip（~/.cache/electron/<hash>/electron-v<ver>-linux-<arch>.zip）
+  local zip=""
+  if [ -n "$ever" ]; then
+    zip=$(find "$HOME/.cache/electron" -name "electron-v${ever}-linux-${ELECTRON_ARCH}.zip" 2>/dev/null | head -1)
+  fi
+  if [ -z "$zip" ]; then
+    zip=$(find "$HOME/.cache/electron" -name "electron-v*-linux-${ELECTRON_ARCH}.zip" 2>/dev/null | head -1)
+  fi
+
+  if [ -n "$zip" ]; then
+    echo "  electron runtime: $(basename "$zip")"
+    unzip -q -o "$zip" -d "$gui_out"
+  else
+    # 回退：仅当目标架构 == host 架构时才能用 host 的 dist
+    local host_arch
+    case "$(uname -m)" in
+      x86_64) host_arch=amd64 ;;
+      aarch64|arm64) host_arch=arm64 ;;
+      *) host_arch=unknown ;;
+    esac
+    if [ "$TAR_ARCH" != "$host_arch" ]; then
+      echo "  WARNING: 缺 electron-v*-linux-${ELECTRON_ARCH}.zip 缓存，且目标架构与 host"
+      echo "           ($host_arch) 不同——不能用 host 的 electron 冒充。跳过 GUI。"
+      echo "           解法：下载 electron-v${ever:-<ver>}-linux-${ELECTRON_ARCH}.zip 到"
+      echo "           ~/.cache/electron/<任意子目录>/ 后重跑。"
+      rm -rf "$gui_out"
+      return
+    fi
+    local electron_dir="$gui_dir/node_modules/electron/dist"
+    if [ ! -f "$electron_dir/electron" ]; then
+      echo "  WARNING: electron binary not found at $electron_dir. GUI will be skipped."
+      rm -rf "$gui_out"
+      return
+    fi
+    echo "  electron runtime: host node_modules (同架构 $host_arch)"
+    cp -r "$electron_dir"/* "$gui_out/" 2>/dev/null
   fi
 
   mkdir -p "$gui_out/resources/app/node_modules"
   mkdir -p "$gui_out/resources/app/renderer"
-
-  # copy electron runtime (binary + shared libs)
-  cp -r "$electron_dir"/* "$gui_out/" 2>/dev/null
   rm -f "$gui_out/resources/default_app.asar" 2>/dev/null
 
   # copy app source
@@ -190,7 +289,28 @@ LAUNCHER
   chmod +x "$gui_out/homeagent-gui"
   chmod +x "$gui_out/electron"
 
-  echo "  GUI built: $gui_out ($(du -sh "$gui_out" | cut -f1))"
+  # 最后一道强制校验：electron 二进制的实际架构必须匹配目标架构。
+  # 不做这步就会重现 v1.0.0/v1.0.1 的隐形坏包：包名、目录名、
+  # homed/waiter 全对，只有 electron 是错架构，直到用户在 arm64 机器上
+  # 双击才发现 Exec format error。
+  local want_pat
+  case "$TAR_ARCH" in
+    amd64) want_pat="x86-64" ;;
+    arm64) want_pat="aarch64" ;;
+    *)     want_pat="" ;;
+  esac
+  if [ -n "$want_pat" ]; then
+    local got
+    got=$(file -b "$gui_out/electron" 2>/dev/null || echo "")
+    if ! printf '%s' "$got" | grep -q "$want_pat"; then
+      echo "  ERROR: electron 架构不符——期望 $want_pat，实际: ${got%%,*}"
+      echo "         删除 GUI 目录并跳过（宁可不发，也不发装了跑不起来的包）。"
+      rm -rf "$gui_out"
+      return
+    fi
+  fi
+
+  echo "  GUI built: $gui_out ($(du -sh "$gui_out" | cut -f1), $(file -b "$gui_out/electron" | cut -d, -f2 | tr -d ' '))"
   echo ""
 }
 
@@ -215,6 +335,8 @@ stage_variant() {
       cp "$PROJECT_ROOT/deploy/homeagent.service" "$staging/etc/systemd/system/homeagent.service"
       [ -f "$initconfig_bin" ] && cp "$initconfig_bin" "$staging/usr/bin/initconfig"
       stage_setup "$staging"
+      stage_license "$staging"
+      stage_multimodal_assets "$staging"
       stage_gui "$staging"
       ;;
     server)
@@ -223,9 +345,12 @@ stage_variant() {
       cp "$PROJECT_ROOT/deploy/homeagent.service" "$staging/etc/systemd/system/homeagent.service"
       [ -f "$initconfig_bin" ] && cp "$initconfig_bin" "$staging/usr/bin/initconfig"
       stage_setup "$staging"
+      stage_license "$staging"
+      stage_multimodal_assets "$staging"
       ;;
     client)
       cp "$BUILD_DIR/waiter_$suffix" "$staging/usr/bin/waiter"
+      stage_license "$staging"
       stage_gui "$staging"
       ;;
   esac
@@ -260,6 +385,127 @@ stage_setup() {
   fi
 }
 
+# 项目自身的许可：**所有变体**都要带（client 也分发 waiter 与 GUI）。
+#
+# deb 按 Debian 惯例给 /usr/share/doc/homeagent/copyright（DEP-5 机器可读格式），
+# 同时把 LICENSE 全文放进去；rpm 的许可走 fpm 的 --license 元数据。
+# 与 stage_multimodal_assets 的 licenses/ 分工：那里放**第三方**（模型/运行库）的
+# 许可全文，这里放本项目自己的。
+stage_license() {
+  local staging="$1"
+  local docdir="$staging/usr/share/doc/homeagent"
+  mkdir -p "$docdir"
+  cp "$PROJECT_ROOT/LICENSE" "$docdir/LICENSE"
+  cat > "$docdir/copyright" <<'EOF'
+Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
+Upstream-Name: HomeAgent
+Source: https://gitcode.com/JianFeeeee/HomeAgent
+
+Files: *
+Copyright: HomeAgent contributors
+License: AGPL-3.0-only
+ This program is free software: you can redistribute it and/or modify it under
+ the terms of the GNU Affero General Public License as published by the Free
+ Software Foundation, version 3 of the License.
+ .
+ This program is distributed in the hope that it will be useful, but WITHOUT
+ ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ FOR A PARTICULAR PURPOSE.  See the GNU Affero General Public License for more
+ details.
+ .
+ You should have received a copy of the GNU Affero General Public License along
+ with this program.  If not, see <https://www.gnu.org/licenses/>.
+ .
+ The license is AGPL-3.0-only: no later version may be chosen. Note the network
+ clause (§13 Remote Network Interaction) — offering modified versions of this
+ software to users over a network also requires offering them the source.
+ .
+ Full text: /usr/share/doc/homeagent/LICENSE
+
+Files: usr/lib/homeagent/models/chinese-clip-vit-b16-onnx/*
+Copyright: OFA-Sys / Chinese-CLIP authors
+License: Apache-2.0
+ Full text: /usr/share/doc/homeagent/licenses/Chinese-CLIP-Apache-2.0.txt
+ Comment: pre-trained model artifacts; NOT covered by this package's AGPL grant
+
+Files: usr/lib/homeagent/onnxruntime/*
+Copyright: Microsoft Corporation
+License: MIT
+ Full text: /usr/share/doc/homeagent/licenses/ONNX-Runtime-MIT.txt
+ Comment: license texts and third-party notices under licenses/ONNX-Runtime-*
+EOF
+  chmod 644 "$docdir/LICENSE" "$docdir/copyright"
+}
+
+# server/full 的 ONNX 资产。模型与运行库是发行版能力的一部分，不是可选下载：
+# 只要打 server/full 包，两者缺一就失败。client 包不运行 homed，故不携带。
+stage_multimodal_assets() {
+  local staging="$1"
+  local model_dst="$staging/usr/lib/homeagent/models/chinese-clip-vit-b16-onnx"
+  local ort_dst="$staging/usr/lib/homeagent/onnxruntime"
+  local licenses="$staging/usr/share/doc/homeagent/licenses"
+
+  if [ ! -d "$CHINESECLIP_BUNDLE_DIR" ]; then
+    echo "ERROR: Chinese-CLIP 产物目录不存在：$CHINESECLIP_BUNDLE_DIR" >&2
+    echo "先运行 scripts/export_chineseclip_onnx.py，再通过 CHINESECLIP_BUNDLE_DIR 指向产物。" >&2
+    return 1
+  fi
+  for f in TextEncoder.onnx VisionEncoder.onnx embed_config.json vocab.txt reference.json SHA256SUMS; do
+    if [ ! -s "$CHINESECLIP_BUNDLE_DIR/$f" ]; then
+      echo "ERROR: Chinese-CLIP 产物缺少或为空：$CHINESECLIP_BUNDLE_DIR/$f" >&2
+      return 1
+    fi
+  done
+  if ! (cd "$CHINESECLIP_BUNDLE_DIR" && sha256sum -c SHA256SUMS); then
+    echo "ERROR: Chinese-CLIP SHA256SUMS 校验失败，拒绝打包。" >&2
+    return 1
+  fi
+
+  if [ ! -s "$ONNXRUNTIME_LIB" ]; then
+    echo "ERROR: ONNX Runtime 不存在：$ONNXRUNTIME_LIB" >&2
+    echo "通过 ONNXRUNTIME_ASSET_DIR 或 ONNXRUNTIME_LIB 指向与目标架构匹配的资产。" >&2
+    return 1
+  fi
+  for notice in "$ONNXRUNTIME_LICENSE" "$ONNXRUNTIME_NOTICES"; do
+    if [ ! -s "$notice" ]; then
+      echo "ERROR: ONNX Runtime 许可证资产缺失：$notice" >&2
+      return 1
+    fi
+  done
+  local runtime_desc
+  runtime_desc=$(file -b "$ONNXRUNTIME_LIB")
+  case "$ARCH" in
+    amd64) printf '%s' "$runtime_desc" | grep -qE 'x86-64|x86_64' || {
+      echo "ERROR: ONNX Runtime 架构不是 amd64：$runtime_desc" >&2; return 1; } ;;
+    arm64) printf '%s' "$runtime_desc" | grep -qE 'aarch64|ARM aarch64' || {
+      echo "ERROR: ONNX Runtime 架构不是 arm64：$runtime_desc" >&2; return 1; } ;;
+  esac
+
+  mkdir -p "$model_dst" "$ort_dst" "$licenses"
+  cp -a "$CHINESECLIP_BUNDLE_DIR/." "$model_dst/"
+  install -m 0755 "$ONNXRUNTIME_LIB" "$ort_dst/libonnxruntime.so"
+
+  # 许可证随二进制分发：Chinese-CLIP = Apache-2.0；ONNX Runtime = MIT，
+  # 同时携带其 ThirdPartyNotices（含 MKL/protobuf/zlib 等第三方条款）。
+  cp /usr/share/common-licenses/Apache-2.0 "$licenses/Chinese-CLIP-Apache-2.0.txt"
+  cp "$ONNXRUNTIME_LICENSE" "$licenses/ONNX-Runtime-MIT.txt"
+  cp "$ONNXRUNTIME_NOTICES" "$licenses/ONNX-Runtime-ThirdPartyNotices.txt"
+  cat > "$licenses/MODEL-SOURCES.txt" <<EOF
+Chinese-CLIP ViT-B/16
+  upstream: https://huggingface.co/OFA-Sys/chinese-clip-vit-base-patch16
+  license: Apache-2.0
+  exported-by: scripts/export_chineseclip_onnx.py
+  dimensions: 512
+  modalities: text,image
+
+ONNX Runtime
+  upstream: https://github.com/microsoft/onnxruntime
+  license: MIT (see ONNX-Runtime-MIT.txt and ONNX-Runtime-ThirdPartyNotices.txt)
+EOF
+
+  echo "  ONNX assets: model=$(du -sh "$model_dst" | cut -f1) runtime=$(du -h "$ort_dst/libonnxruntime.so" | cut -f1)"
+}
+
 # ---- create .deb ----
 build_deb() {
   local variant="$1"
@@ -267,9 +513,9 @@ build_deb() {
   local deb_dir="${DIST_DIR}/deb"
   mkdir -p "$deb_dir"
 
-  local pkg_name="homeagent-${variant}_${VERSION}_${DEB_ARCH}.deb"
+  local pkg_name="homeagent-${variant}_${PKG_VERSION}_${DEB_ARCH}.deb"
   local deb_root
-  deb_root="$(mktemp -d)"
+  deb_root="$(mktemp -d "$STAGE_TMP/deb.XXXXXX")"
 
   mkdir -p "$deb_root/DEBIAN"
 
@@ -277,7 +523,7 @@ build_deb() {
   local installed_size_kb
   installed_size_kb=$(du -sk "$staging" | cut -f1)
 
-  sed -e "s/VERSION_PLACEHOLDER/$VERSION/g" \
+  sed -e "s/VERSION_PLACEHOLDER/$PKG_VERSION/g" \
       -e "s/ARCH_PLACEHOLDER/$DEB_ARCH/g" \
       -e "s/INSTALLED_SIZE_PLACEHOLDER/$installed_size_kb/g" \
       "$control_file" > "$deb_root/DEBIAN/control"
@@ -306,13 +552,13 @@ build_tar() {
   local tar_dir="${DIST_DIR}/tar"
   mkdir -p "$tar_dir"
 
-  local archive_name="homeagent_${VERSION}_linux_${TAR_ARCH}.tar.gz"
-  local archive_dir="homeagent-${VERSION}-linux-${TAR_ARCH}"
+  local archive_name="homeagent_${PKG_VERSION}_linux_${TAR_ARCH}.tar.gz"
+  local archive_dir="homeagent-${PKG_VERSION}-linux-${TAR_ARCH}"
 
   # build combined staging
   local staging
-  staging="$(mktemp -d)"
-  mkdir -p "$staging/usr/bin" "$staging/usr/lib/homeagent"
+  staging="$(mktemp -d "$STAGE_TMP/tar.XXXXXX")"
+  mkdir -p "$staging/usr/bin" "$staging/usr/lib/homeagent" "$staging/etc/systemd/system"
 
   # copy all available binaries
   for bin in homed waiter initconfig; do
@@ -323,6 +569,9 @@ build_tar() {
   # setup script
   local setup_src="$PROJECT_ROOT/deploy/packaging/linux/setup.sh"
   [ -f "$setup_src" ] && cp "$setup_src" "$staging/usr/lib/homeagent/setup.sh"
+  cp "$PROJECT_ROOT/deploy/homeagent.service" "$staging/etc/systemd/system/homeagent.service"
+  stage_license "$staging"
+  stage_multimodal_assets "$staging"
 
   # GUI if available
   local gui_src="$BUILD_DIR/homeagent-gui-linux-${TAR_ARCH}"
@@ -351,7 +600,7 @@ build_rpm() {
   local rpm_dir="${DIST_DIR}/rpm"
   mkdir -p "$rpm_dir"
 
-  local pkg_name="homeagent-${variant}-${VERSION}-1.${RPM_ARCH}.rpm"
+  local pkg_name="homeagent-${variant}-${PKG_VERSION}-1.${RPM_ARCH}.rpm"
 
   # find fpm
   local fpm_bin="$(command -v fpm 2>/dev/null || true)"
@@ -400,7 +649,7 @@ build_rpm() {
     -a "$RPM_ARCH" \
     --description "HomeAgent ${variant^} package" \
     --url "https://github.com/trueagent/HomeAgent" \
-    --license "Proprietary" \
+    --license "AGPL-3.0-only" \
     -C "$staging" \
     -p "$rpm_dir/$pkg_name" \
     . 2>&1
@@ -411,7 +660,7 @@ build_rpm() {
 main() {
   local target_arch="$ARCH"
 
-  mkdir -p "$BUILD_DIR"
+  mkdir -p "$BUILD_DIR" "$STAGE_TMP"
 
   case "$ACTION" in
     all|build)
@@ -428,6 +677,10 @@ main() {
 
   mkdir -p "$DIST_DIR"
 
+  # 上次成功构建留下的校验和必须在本次开工前删掉：本次若中途失败，脚本直接退出、
+  # 不重算 SHA256SUMS，旧的它会一直躺在 dist 里，看上去像在为这一批残缺产物背书。
+  rm -f "$DIST_DIR/SHA256SUMS"
+
   for variant in full server client; do
     echo ""
     echo "=============================================="
@@ -435,7 +688,7 @@ main() {
     echo "=============================================="
 
     local staging
-    staging=$(mktemp -d)
+    staging=$(mktemp -d "$STAGE_TMP/stage.XXXXXX")
     stage_variant "$variant" "$staging"
 
     case "$ACTION" in
@@ -457,9 +710,19 @@ main() {
   echo "=== Done! Packages in: $DIST_DIR ==="
   echo ""
   echo "Summary:"
-  find "$DIST_DIR" -type f \( -name "*.deb" -o -name "homeagent_*.tar.gz" -o -name "*.rpm" \) 2>/dev/null | sort | while read -r f; do
+  mapfile -t release_files < <(find "$DIST_DIR" -type f \( -name "*.deb" -o -name "homeagent_*.tar.gz" -o -name "*.rpm" \) 2>/dev/null | sort)
+  for f in "${release_files[@]}"; do
     echo "  $(du -h "$f" | cut -f1)  $f"
   done
+  # 全部包生成之后一次计算，避免边打边算漏掉后生成的产物。
+  if [ ${#release_files[@]} -gt 0 ]; then
+    (
+      cd "$DIST_DIR"
+      find . -type f \( -name "*.deb" -o -name "homeagent_*.tar.gz" -o -name "*.rpm" \) \
+        -print0 | sort -z | xargs -0 sha256sum > SHA256SUMS
+    )
+    echo "  SHA256SUMS: $DIST_DIR/SHA256SUMS"
+  fi
 }
 
 main

deploy/packaging/windows/install-via-wsl.ps1

@@ -0,0 +1,259 @@
+<#
+.SYNOPSIS
+  在 WSL2 中安装 HomeAgent（homed + 插件 + WebUI）。
+
+.DESCRIPTION
+  Windows 不再提供 homed 的原生安装。原因见 cmd/homed/platform_windows.go：
+  homed 的插件体系依赖「继承的 fd」与「统一共享内存区的段内偏移解引用」，
+  Windows 的句柄模型无法表达这两者；强行适配等于再维护一套平台专属 ABI，
+  而 C ABI 时代三套 ABI 并存正是「改写型插件在某个平台上静默失效」的根因。
+
+  本脚本因此把 Windows 安装流程变成一条引导链：
+    检测 WSL → 必要时引导安装 → 配置（默认版本 2 / systemd）
+    → 把 **Linux 包** 送进发行版 → 在 WSL 内按 Linux 的方式安装。
+
+  它复用 Linux 侧的安装包与初始化脚本，不另写一套安装逻辑——
+  「WSL 里就是普通 linux/amd64」这一点必须保持成立，否则等于又开了第三个平台。
+
+.PARAMETER PayloadDir
+  内含 Linux 安装包的目录（安装器把它解到临时目录后传进来）。
+  优先取 *.deb；没有 deb 时回退 *.tar.gz。
+
+.PARAMETER Distro
+  目标发行版名。省略则用默认发行版；没有发行版时引导安装 Ubuntu。
+
+.PARAMETER DataDir
+  WSL 内的数据目录。默认 /var/lib/homeagent（与 Linux 原生安装一致）。
+  不建议放 /mnt/c/...：跨文件系统 IO 慢，且 inotify 语义受限。
+
+.NOTES
+  ⚠️ 本脚本在开发环境（Linux）中只能做语法/逻辑审查，**未在真实 Windows + WSL
+  上执行过**。首次使用请逐段核对输出；下面每个阶段都打印了实际执行的命令，
+  便于定位到具体哪一步与预期不符。
+#>
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)][string]$PayloadDir,
+    [string]$Distro = "",
+    [string]$DataDir = "/var/lib/homeagent",
+    [string]$ApiKey = "",
+    [string]$WebUIUser = "",
+    [string]$WebUIPass = "",
+    [switch]$Uninstall
+)
+
+$ErrorActionPreference = "Stop"
+$script:StageNo = 0
+$script:DistroName = $Distro
+
+function Write-Stage([string]$Text) {
+    $script:StageNo++
+    Write-Host ""
+    Write-Host ("=" * 64) -ForegroundColor DarkGray
+    Write-Host ("[$script:StageNo] $Text") -ForegroundColor Cyan
+    Write-Host ("=" * 64) -ForegroundColor DarkGray
+}
+
+function Write-Ok([string]$Text) { Write-Host "  ✓ $Text" -ForegroundColor Green }
+function Write-Warn2([string]$Text) { Write-Host "  ! $Text" -ForegroundColor Yellow }
+function Fail([string]$Text, [string]$Hint = "") {
+    Write-Host ""
+    Write-Host "  安装中止：$Text" -ForegroundColor Red
+    if ($Hint) { Write-Host "  $Hint" -ForegroundColor Yellow }
+    exit 1
+}
+
+# ── 0. 前置检查 ────────────────────────────────────────────────────────────
+Write-Stage "前置检查"
+
+$identity = [Security.Principal.WindowsPrincipal][Security.Principal.WindowsIdentity]::GetCurrent()
+if (-not $identity.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) {
+    # 装 WSL 与写 \\wsl$ 都需要管理员。不静默提权：用户应当看到发生了什么。
+    Fail "需要管理员权限" "请以管理员身份重新运行安装程序。"
+}
+Write-Ok "管理员权限"
+
+if (-not (Get-Command wsl.exe -ErrorAction SilentlyContinue)) {
+    Write-Warn2 "未找到 wsl.exe"
+    Write-Host "  homed 不再提供 Windows 原生版本，必须通过 WSL2 运行。"
+    Write-Host ""
+    Write-Host "  在管理员 PowerShell 中执行：" -ForegroundColor Yellow
+    Write-Host "      wsl --install" -ForegroundColor White
+    Write-Host "  然后重启 Windows，再重新运行本安装程序。"
+    Write-Host ""
+    Write-Host "  （Windows 10 需 2004+ 且启用虚拟机平台；Windows 11 开箱可用）"
+    exit 20
+}
+Write-Ok "wsl.exe 可用"
+
+# ── 1. 检测 WSL 状态与发行版 ───────────────────────────────────────────────
+Write-Stage "检测 WSL 与发行版"
+
+# wsl -l -v 在「没有发行版」时返回非零，且输出是 UTF-16LE——直接解析会踩编码坑。
+# 用 --status 取默认发行版，再单独枚举列表。
+$distros = @()
+try {
+    $raw = (& wsl.exe -l -q 2>$null | Out-String)
+    $distros = $raw -split "`r?`n" | ForEach-Object { $_.Trim() } | Where-Object { $_ -ne "" }
+} catch {
+    $distros = @()
+}
+
+if ($distros.Count -eq 0) {
+    Write-Warn2 "WSL 已安装，但没有任何发行版"
+    Write-Host ""
+    Write-Host "  请先安装发行版（推荐 Ubuntu）：" -ForegroundColor Yellow
+    Write-Host "      wsl --install -d Ubuntu" -ForegroundColor White
+    Write-Host ""
+    Write-Host "  首次启动 Ubuntu 会要求创建 Linux 用户名与密码，完成后重新运行本安装程序。"
+    exit 21
+}
+
+if ($script:DistroName -eq "") {
+    try {
+        $script:DistroName = (& wsl.exe --status 2>$null | Select-String -Pattern "Default Distribution" |
+            ForEach-Object { ($_ -split ":")[1].Trim() })
+    } catch { }
+    if (-not $script:DistroName) { $script:DistroName = $distros[0] }
+}
+Write-Ok "发行版：$($script:DistroName)（共 $($distros.Count) 个：$($distros -join ', ')）"
+
+# ── 2. 确保是 WSL2 ─────────────────────────────────────────────────────────
+Write-Stage "确保使用 WSL2"
+
+# WSL1 没有真正的 Linux 内核、没有 systemd，且在共享内存/事件语义上与 WSL2 不同。
+# homed 依赖 eventfd + mmap 语义，WSL1 会以难以诊断的方式失败，因此显式要求 WSL2。
+try {
+    $verLine = (& wsl.exe -l -v 2>$null | Out-String) -split "`r?`n" |
+        Where-Object { $_ -match [regex]::Escape($script:DistroName) } | Select-Object -First 1
+    if ($verLine -match "\b1\b") {
+        Write-Warn2 "该发行版当前是 WSL1，正在升级为 WSL2 ..."
+        & wsl.exe --set-version $script:DistroName 2
+        if ($LASTEXITCODE -ne 0) { Fail "WSL2 升级失败" "可手动执行：wsl --set-version $($script:DistroName) 2" }
+    }
+} catch { }
+& wsl.exe --set-default-version 2 | Out-Null
+Write-Ok "已使用 WSL2"
+
+# ── 3. 准备 Linux 包 ───────────────────────────────────────────────────────
+Write-Stage "准备 Linux 安装包"
+
+$deb = Get-ChildItem -Path $PayloadDir -Filter "*.deb" -ErrorAction SilentlyContinue | Select-Object -First 1
+$tar = Get-ChildItem -Path $PayloadDir -Filter "*.tar.gz" -ErrorAction SilentlyContinue | Select-Object -First 1
+if ($deb) {
+    $pkg = $deb.FullName
+    $pkgKind = "deb"
+} elseif ($tar) {
+    $pkg = $tar.FullName
+    $pkgKind = "tar"
+} else {
+    Fail "在 $PayloadDir 下既没找到 .deb 也没找到 .tar.gz" "安装器应把 Linux 包解到该目录。"
+}
+Write-Ok "使用 $(Split-Path $pkg -Leaf)（$pkgKind）"
+
+# ── 4. 把包送进 WSL ────────────────────────────────────────────────────────
+Write-Stage "把安装包送入 WSL"
+
+# 走 /mnt/c 而不是 \\wsl$：前者是 WSL 稳定的对外通道，且不需要额外的 UNC 权限；
+# 后者在某些 Windows 版本上对 Program Files 路径有重定向限制。
+$winPath = (Resolve-Path $pkg).Path
+$mntPath = "/mnt/" + $winPath.Substring(0, 1).ToLower() + ($winPath.Substring(2) -replace '\\', '/')
+Write-Host "  源：$mntPath"
+
+& wsl.exe -d $script:DistroName -u root -- bash -lc "mkdir -p /tmp/homeagent-install"
+if ($LASTEXITCODE -ne 0) { Fail "无法在 WSL 内创建临时目录" "确认发行版可正常启动：wsl -d $($script:DistroName)" }
+& wsl.exe -d $script:DistroName -u root -- bash -lc "cp '$mntPath' /tmp/homeagent-install/"
+if ($LASTEXITCODE -ne 0) { Fail "复制安装包失败" }
+Write-Ok "已送到 /tmp/homeagent-install/"
+
+# ── 5. 在 WSL 内安装 ───────────────────────────────────────────────────────
+Write-Stage "在 WSL 内安装 homed"
+
+# 凭据经环境变量传给 setup.sh（它已支持 HOMEAGENT_API_KEY / WEBUI_USER / WEBUI_PASS）。
+# 不传的话就会「界面显示一份、config.db 里另一份」，用户直接登录不上。
+$credEnv = ""
+if ($ApiKey)    { $credEnv += "export HOMEAGENT_API_KEY='$ApiKey'; " }
+if ($WebUIUser) { $credEnv += "export WEBUI_USER='$WebUIUser'; " }
+if ($WebUIPass) { $credEnv += "export WEBUI_PASS='$WebUIPass'; " }
+
+# 安装逻辑复用 Linux 侧：deb 走 apt（postinst 会调用 setup.sh 生成凭据与 config.db），
+# tar 则解包到你同一套布局再执行同一份 setup.sh。刻意不在这里重写安装步骤——
+# 「WSL 里就是普通 linux/amd64」必须保持成立，否则等于又开了第三个平台。
+if ($pkgKind -eq "deb") {
+    $inWslPkg = "/tmp/homeagent-install/" + (Split-Path $pkg -Leaf)
+    & wsl.exe -d $script:DistroName -u root -- bash -lc @"
+set -e
+$credEnv
+export HOMEAGENT_DATA='$DataDir'
+apt-get update -qq
+DEBIAN_FRONTEND=noninteractive apt-get install -y -qq '$inWslPkg'
+"@
+} else {
+    $inWslPkg = "/tmp/homeagent-install/" + (Split-Path $pkg -Leaf)
+    & wsl.exe -d $script:DistroName -u root -- bash -lc @"
+set -e
+$credEnv
+mkdir -p /opt/homeagent /tmp/homeagent-extract
+tar -xzf '$inWslPkg' -C /tmp/homeagent-extract
+cd /tmp/homeagent-extract
+# 与 deb 完全相同的布局：/usr/bin/homed + /usr/lib/homeagent/setup.sh。
+# 两套安装若落到不同路径，之后的升级/排障就会出现「按文档找不到文件」。
+install -m 0755 homed      /usr/bin/homed
+install -m 0755 waiter     /usr/bin/waiter
+[ -f initconfig ] && install -m 0755 initconfig /usr/bin/initconfig
+if [ -f homeagent.service ]; then
+  install -m 0644 homeagent.service /etc/systemd/system/homeagent.service
+fi
+mkdir -p /usr/lib/homeagent
+if [ -f setup.sh ]; then install -m 0755 setup.sh /usr/lib/homeagent/setup.sh; fi
+export HOMEAGENT_DATA='$DataDir'
+if [ -x /usr/lib/homeagent/setup.sh ]; then bash /usr/lib/homeagent/setup.sh; fi
+"@
+}
+if ($LASTEXITCODE -ne 0) {
+    Fail "WSL 内安装失败（退出码 $LASTEXITCODE）" "可进入 WSL 手动排查：wsl -d $($script:DistroName)"
+}
+Write-Ok "安装完成"
+
+# ── 6. 启动与自启 ──────────────────────────────────────────────────────────
+Write-Stage "启动 homed 与自启配置"
+
+& wsl.exe -d $script:DistroName -u root -- bash -lc @"
+if command -v systemctl >/dev/null 2>&1 && systemctl list-unit-files 2>/dev/null | grep -q homeagent; then
+    systemctl enable homeagent 2>/dev/null || true
+    systemctl restart homeagent
+    echo '  ✓ systemd 服务 homeagent 已启动并设为自启'
+else
+    # 没有 systemd（WSL2 默认可能没开）：用 nohup 起，并把自启交给 Windows 侧的计划任务。
+    pkill -f '/usr/bin/homed' 2>/dev/null || true
+    nohup /usr/bin/homed -data '$DataDir' > /var/log/homeagent-boot.log 2>&1 &
+    echo '  ✓ 已用 nohup 启动（未检测到 systemd）'
+fi
+"@
+
+$creds = & wsl.exe -d $script:DistroName -u root -- bash -lc "cat '$DataDir/credentials.txt' 2>/dev/null || true"
+
+Write-Host ""
+Write-Host "============================================================" -ForegroundColor Green
+Write-Host " HomeAgent 已在 WSL2（$($script:DistroName)）内安装完成" -ForegroundColor Green
+Write-Host "============================================================" -ForegroundColor Green
+Write-Host ""
+Write-Host "  WebUI：http://localhost:8080" -ForegroundColor White
+Write-Host "  （WSL2 会把 WSL 内的端口映射到 Windows 的 localhost，无需额外配置）"
+Write-Host ""
+if ($creds) {
+    Write-Host "  初始凭据（也保存在 WSL 内 $DataDir/credentials.txt）：" -ForegroundColor Yellow
+    Write-Host $creds
+} else {
+    Write-Host "  未读到凭据文件，请进入 WSL 检查：cat $DataDir/credentials.txt" -ForegroundColor Yellow
+}
+Write-Host ""
+Write-Host "  常用操作（在 PowerShell 中）："
+Write-Host "      进入 WSL        : wsl -d $($script:DistroName)"
+Write-Host "      查看日志        : wsl -d $($script:DistroName) -u root -- journalctl -u homeagent -f"
+Write-Host "      重启服务        : wsl -d $($script:DistroName) -u root -- systemctl restart homeagent"
+Write-Host ""
+Write-Host "  注意：WSL 实例不会随 Windows 启动而自动拉起。若需要开机自启，"
+Write-Host "        可创建一个登录时触发的计划任务执行："
+Write-Host "            wsl -d $($script:DistroName) -u root -- systemctl start homeagent"
+exit 0

deploy/systemd/embed-sidecar.service

@@ -0,0 +1,20 @@
+[Unit]
+Description=Jina v5-omni-nano Embedding Sidecar for HomeAgent
+After=network.target
+
+[Service]
+Type=simple
+User=root
+WorkingDirectory=/home/newqqagent
+ExecStart=/usr/local/bin/python3 /home/program/TrueAgent/scripts/embed_sidecar.py
+Restart=on-failure
+RestartSec=5
+Environment=JINA_MODEL_DIR=/home/newqqagent/models/jina-v5-omni-nano
+Environment=JINA_PORT=18999
+Environment=JINA_DIMENSION=768
+Environment=OMP_NUM_THREADS=8
+Environment=MKL_NUM_THREADS=8
+Environment=TOKENIZERS_PARALLELISM=false
+
+[Install]
+WantedBy=multi-user.target

docs/embedding-comparison.md

@@ -0,0 +1,124 @@
+# 检索方案对比报告（2026-09-09）
+## 测试数据
+- 文档库：492 篇生产文档（过滤 108 条健康检查测试文档）
+- 媒体库：3 张生产图片（验证码、新闻截图、深色模式备忘录）
+- 文本查询：10 组（精确匹配、语义、跨语言、模糊表达）
+- 媒体查询：6 组（中文/英文查图片，3 张图片各 2 条）
+
+---
+
+## 一、文本检索对比（文档库）
+
+| 方案 | Hit@1 | Hit@5 | MRR | 平均延迟 |
+|------|-------|-------|-----|----------|
+| TF-IDF | 3/10 | 7/10 | 0.457 | 0.3ms |
+| fastText（200k 中文+378k 英文） | 5/10 | 5/10 | 0.530 | 8.3ms |
+| TF-IDF + fastText RRF | 4/10 | 7/10 | 0.552 | 12.3ms |
+| **Jina v5-omni-nano** | **8/10** | **10/10** | **0.900** | **39.9ms** |
+
+### 关键发现
+
+1. **Jina 的优势来自"短语语义"能力**：
+   - "邮件代理是否已经成功接入" → TF-IDF rank 5，Jina rank 1
+   - "升级安装 QQ 插件包" → fastText rank 169，Jina rank 1（margin +0.30）
+   - "我所在城市的天气预报" → fastText rank 44，Jina rank 1
+   - "聊天输入区域文字多了会不会自动增高" → TF-IDF rank 1，Jina rank 1（margin +0.33）
+
+2. **TF-IDF 在精确匹配上不可替代**：
+   - "长期文档记忆功能是否健康" → TF-IDF rank 3，Jina rank 1
+   - "重新加载全部扩展组件" → TF-IDF rank 0（完全未命中），Jina rank 2
+   - TF-IDF 的 Hit@5 70% 证明精确关键词召回仍有价值
+
+3. **RRF 融合反而变差**：
+   - TF-IDF+fastText RRF MRR=0.552，低于 Jina 单路 0.900
+   - 原因：两种稀疏向量的排序在语义查询上高度重叠，RRF 无法弥补各自短板
+
+---
+
+## 二、图片检索对比（同 3 张图片，6 条查询）
+
+| 方案 | Hit@1 | MRR | 平均 margin |
+|------|-------|-----|-------------|
+| CLIP ViT-B/32 | 4/6 | 0.806 | -0.008（负值！） |
+| Jina v5-omni-nano | 4/6 | 0.833 | +0.024 |
+
+### 逐条对比
+
+| 查询 | CLIP rank | CLIP margin | Jina rank | Jina margin |
+|------|-----------|-------------|-----------|-------------|
+| 验证码图片（中） | 1 | +0.027 | 1 | +0.036 |
+| 验证码图片（英） | 1 | +0.063 | 1 | +0.077 |
+| 新闻截图（中） | 6 | -0.091 | 2 | -0.064 |
+| 新闻截图（英） | 1 | +0.008 | 2 | -0.028 |
+| 备忘录截图（中） | 3 | -0.045 | 1 | +0.045 |
+| 备忘录截图（英） | 1 | +0.051 | 1 | +0.079 |
+
+### 关键发现
+
+1. **中文文本→图片**：Jina 明显优于 CLIP（MRR 0.833 vs 0.611）
+   - CLIP 中文查询余弦可低至 -0.076（完全反直觉）
+   - Jina 最差也是 +0.045，正样本始终高于负样本
+
+2. **新闻截图是共同弱点**：
+   - CLIP 和 Jina 都被"深色模式备忘录"抢走新闻截图的排序
+   - 原因：新闻截图的文字描述含"深色"、"备忘录"等词，与备忘录图片的视觉特征重叠
+   - 这是描述质量 vs 视觉特征的竞争，不是模型问题
+
+3. **margin 的实际意义**：
+   - CLIP 的平均 margin = -0.008（负值意味着正样本平均不如负样本）
+   - Jina 的平均 margin = +0.024（正样本始终略高于负样本）
+   - 但两者的 margin 都很小（< 0.1），生产环境仍需阈值校准
+
+---
+
+## 三、延迟与资源
+
+| 方案 | 单次查询延迟 | 索引构建 | 内存 |
+|------|-------------|----------|------|
+| TF-IDF | 0.3ms | <1s | ~50MB |
+| fastText | 8.3ms | <1s | ~200MB |
+| CLIP ONNX | 26ms | N/A | ~600MB |
+| Jina v5-omni CPU | 39.9ms | 78s（492篇） | ~4GB |
+
+---
+
+## 四、结论与建议
+
+### 核心判断
+
+| 维度 | TF-IDF/fastText | CLIP | Jina v5-omni |
+|------|-----------------|------|--------------|
+| 文本精确匹配 | ★★★★★ | N/A | ★★★★ |
+| 文本语义检索 | ★★ | N/A | ★★★★★ |
+| 中文文本→图片 | 无能力 | ★ | ★★★★ |
+| 英文文本→图片 | 无能力 | ★★★ | ★★★★ |
+| 图片→图片 | 无能力 | ★★★ | ★★★★ |
+| 多语言统一空间 | 无能力 | 有限 | ★★★★★ |
+| 延迟 | ★★★★★ | ★★★ | ★★ |
+
+### 架构建议
+
+1. **保留 TF-IDF 作为精确召回的一级通道**：
+   - 0.3ms 延迟不可替代
+   - Hit@5 70% 证明在关键词匹配场景仍有价值
+   - 特别是"插件安装"、"设备查询"这类精确操作指令
+
+2. **用 Jina 替换 fastText + CLIP 的稠密通道**：
+   - Jina 单路 MRR=0.90，超过 fastText+CLIP 融合
+   - 统一空间消除三条通道的维护成本
+   - 中文文本→图片从"无法检索"提升到"可检索"
+
+3. **两路融合：TF-IDF + Jina RRF**（而非 TF-IDF + fastText RRF）：
+   - TF-IDF 精确匹配 + Jina 语义覆盖
+   - RRF 避免跨空间分数归一化问题
+   - 预期 MRR > 0.90（精确匹配补 Jina 的语义盲区）
+
+4. **图片检索仍需阈值校准**：
+   - Jina 的 margin 平均 +0.024，生产环境需设置合理阈值
+   - 建议：用真实正负样本对重新标定，而非沿用 CLIP 的 0.20 阈值
+
+### 下一步
+
+- 实现 TF-IDF + Jina RRF 融合，验证 MRR 是否能突破 0.90
+- 用更多生产图片标定 Jina 的图片检索阈值
+- 测试 fastText 词嵌入是否可以完全被 Jina 文本编码替代（L0 相关性计算）

docs/git-branching.md

@@ -1,7 +1,8 @@
 # Git 分支管理规范
 
-> 生效：2026-08-31。适用：**本仓（TrueAgent/HomeAgent）与 third_party/homeagent-sdk（SDK 仓）**——两仓协作时分支策略必须一致，本规范两仓同用。
-> 核心原则一句话：**main 唯一长命、永远可部署；一切新工作在特性分支；版本发布走 release 分支 + tag；hotfix 只进 released 分支并 cherry-pick 回 main。**
+> 生效：2026-08-31，2026-09-04 修订（三级发布通道 + 单条发布分支），2026-09-06 修订（SDK 仓版本语义与发版联动，见 §七）。
+> 适用：**本仓（TrueAgent/HomeAgent）与 third_party/homeagent-sdk（SDK 仓）**——两仓协作时分支策略必须一致，本规范两仓同用。
+> 核心原则一句话：**main 唯一长命、永远可部署；一切新工作在特性分支；一个中版本一条发布分支，alpha/beta/正式由 tag 区分；hotfix 只进发布分支并 cherry-pick 回 main。**
 
 ---
 
@@ -11,18 +12,24 @@
 |---|---|---|---|---|
 | `main` | **唯一长命分支** | — | — | ✅ **永远可部署** |
 | `feature/xxx` | 短命（本次特性完成即删） | main | 合回 main | ❌ 不部署 |
-| `release/vX.Y.Z` | 中命（从切出到下个版本发布） | main | 打 tag → 构建发布 | ✅ **发布产物来源** |
-| hotfix（直接提交 release 分支） | 随 release 分支 | release 分支 | **cherry-pick 回 main** | ✅ |
+| `release/vX.Y.x` | 中命（**整个中版本生命周期**） | main | 打 tag → 构建发布 | ✅ **发布产物来源** |
+| hotfix（直接提交发布分支） | 随发布分支 | 发布分支 | **cherry-pick 回 main** | ✅ |
 
 ```
 main ──────────────── E ──────────────── G ────────────────（永远可部署）
       │                                    ▲
-      │ feature/xxx                         │ cherry-pick（hotfix 逐个 pick 回）
+      │ feature/xxx                         │ cherry-pick（修复逐个 pick 回）
       ├── A ── B ──(合回)───────────────────┤
       │                                    │
-      └── release/v1.2.0                release/v1.2.0
-          ├─(tag v1.2.0)→ 构建发布         ├─(hotfix) F ← 版本特定严重 bug
-          └─ 退役（可删可留）                └─ F 被 separately cherry-pick 到 main
+      └── release/v1.0.x ────────────────────────────────────────────────
+          │                                │              │
+          ├─(tag v1.0.0-alpha.1) 内部验证   │              │
+          ├─(tag v1.0.0-beta.1)  小范围试用 │              │
+          ├─(tag v1.0.0)         正式发布   │              │
+          ├─(hotfix) F ─────────────────────┤              │
+          ├─(tag v1.0.1)         patch 发布 │              │
+          ├─(hotfix) H ────────────────────────────────────┤
+          └─(tag v1.0.3)         patch 发布
 ```
 
 ---
@@ -32,8 +39,9 @@ main ──────────────── E ────────
 ### 1. `main`（唯一长命分支）
 
 - **唯一长期存在且永远可部署**。任何时刻 `git checkout main` 出来都是可构建、可上线的状态。
-- 积攒**下一个版本**的功能：feature 分支完成即合回，main 持续向前。
+- 积攒**下一个中版本**的功能：feature 分支完成即合回，main 持续向前。
 - **main 上不直接开发**。所有改动经 feature 分支合入；hotfix 经 cherry-pick 注入。
+- **main 的 `internal/meta.Version` 始终是下一个未发布版本**，不随 patch 发布变动。
 - 合入门禁（**单人直推也遵守**，不强制 PR 但强制验证）：
   - `make test` 全绿
   - 涉及插件/工具链时：接口冻结检查 `git diff third_party/homeagent-sdk/sdk/` 为空
@@ -41,80 +49,160 @@ main ──────────────── E ────────
 
 ### 2. `feature/xxx`（新特性/修复）
 
-- 命名：`feature/<短横线描述>`，如 `feature/plugin-proc-migration`、`feature/webui-narrow-fix`。
+- 命名：`feature/<短横线描述>`，如 `feature/plugin-proc-migration`、`feature/memory-media`。
 - **从 main 开出**：`git checkout -b feature/xxx main`。
 - 完成后合回 main：
   - 单人：直推（`git merge --no-ff` 保留特性边界，或 squash 成一个 commit，二选一在团队内固定）。
   - 多人：走 PR（review 后合入）。
 - 合回后删除 feature 分支（避免累积）。
 
-### 3. `release/vX.Y.Z`（发布）
+### 3. `release/vX.Y.x`（发布分支：一个中版本一条）
 
-- **从 main 的某个可部署点切出**：`git checkout -b release/v1.2.0 main`。
-- 切出后**冻结功能**——release 分支上只做：版本号 bump、发布准备、bug 修复、文档。
-- 打 tag → 构建发布安装包 → 上传（附件命名规范见历史记录）。
-- **现网部署永远用 release tag 的构建产物**，不是 main 头部、更不是 feature。
+- **命名用 `x` 占位 patch 位**：`release/v1.0.x` 承载 1.0.0 → 1.0.1 → … → 1.0.N 全部发布，
+  直到 `release/v1.1.x` 切出为止。**不要按 patch 号建分支**（`release/v1.0.1`、`release/v1.0.3` 各一条会把
+  同一发布线切成互不相连的碎片，追溯时无法用一条分支看完整条线的演进）。
+- **从 main 的某个可部署点切出**：`git checkout -b release/v1.0.x main`。
+- 切出后**冻结功能**——发布分支上只做：版本号 bump、发布准备、bug 修复、文档。
+- **现网部署永远用发布分支上 tag 的构建产物**，不是 main 头部、更不是 feature。
 
-### 4. hotfix（只属于此版本的严重 bug）
+### 4. 三级发布通道（alpha / beta / 正式）
+
+通道**由 tag 区分，不由分支区分**——三者共用同一条 `release/vX.Y.x`。
+
+| 通道 | tag 形式 | 含义 | 受众 |
+|---|---|---|---|
+| alpha | `vX.Y.Z-alpha.N` | 功能齐了但未充分验证，可能有已知缺陷 | 仅内部/开发者自测 |
+| beta | `vX.Y.Z-beta.N` | alpha 问题已修，等待真实环境暴露长尾问题 | 小范围试用、愿意承担风险的用户 |
+| 正式 | `vX.Y.Z` | 通过验证，可上现网 | 所有用户 |
+
+- **推进顺序**：alpha → beta → 正式，逐级向前，**每级都是同一条分支上的新 tag**。
+  这也是 semver 的标准预发布语义（`1.1.0-alpha.1 < 1.1.0-beta.1 < 1.1.0`），
+  包管理器与版本比较逻辑天然认得，无需额外约定。
+- **允许跳级**：若改动小、验证充分（如仅一处已定位并有回归测试覆盖的内核修复），
+  可直接打正式 tag。跳级要在发布说明里写明理由。
+- alpha/beta 的构建产物**可以上传 release 附件**，但必须在 gitcode release 上勾选
+  "预发布"标记，且发布说明首行标注通道与已知风险。
+- **beta 未清零的严重问题不得进正式**：正式 tag 意味着"我们认为它能上 24/7 现网"。
+- **发版动作只在发布分支上做**：版本号 bump、打 tag、构建产物、上传 release 附件，
+  全部发生在 `release/vX.Y.x` 上。**main 永远不是发版分支**——即使某个改动刚刚合进 main、
+  即使 main 此刻可部署，也不从 main 打 tag、不拿 main 的构建产物发布。
+  main 的版本号是「下一个未发布中版本」的路牌，不是任何一次发布的版本号。
+
+### 5. hotfix（发布后发现的严重 bug）
 
 - **场景**：版本已发布后，发现只存在于该版本（或该发布线）的严重 bug。
-- **动作**：直接把修复提交到 **release 分支**（不收进 main 的开发流）→ 该 release 分支重新构建、打 patch tag（如 `v1.2.1`）发布。
+- **动作**：直接把修复提交到**发布分支** → 该分支重新构建、打下一个 patch tag（如 `v1.0.4`）发布。
 - **关键：hotfix 必须 cherry-pick 回 main**：
 
   ```bash
-  # 在 release 分支上提交修复（代码部分与版本号 bump 分开提交）
+  # 在发布分支上提交修复（代码部分与版本号 bump 分开提交）
+  git checkout release/v1.0.x
   git commit -m "fix(x): ..."                    # ① 修复本身
-  git commit -m "chore: bump v1.2.1"             # ② 版本号（此 commit 不 pick 回 main）
+  git commit -m "chore(release): bump v1.0.4"    # ② 版本号（此 commit 不 pick 回 main）
+  git tag -a v1.0.4 -m "..."
 
   # 回到 main，只挑修复本身
   git checkout main
-  git cherry-pick <修复commit的sha>              # 只 pick ①，不 pick ②
+  git cherry-pick <修复①的sha>                   # 只 pick ①，不 pick ②
   ```
 
-  > **为什么 cherry-pick 而不是 merge**：release 分支只承载该版本特有的补丁，merge 会把 release 分支的版本号/发布相关改动一并带进 main 造成冲突。逐个 cherry-pick 修复 commit 让 main 精确地只获得修复本身。**版本号 bump 不要 pick 回 main**（main 的版本号应始终是下一个未发布版本）。
+  > **为什么 cherry-pick 而不是 merge**：发布分支只承载该版本特有的补丁，merge 会把
+  > 版本号/发布相关改动一并带进 main 造成冲突，并让 main 的 `meta.Version` 变成
+  > 已发布的旧版本号。逐个 cherry-pick 让 main 精确地只获得修复本身。
+  > **版本号 bump 不要 pick 回 main。**
 
-- **hotfix 已逐个 pick 回 main ⇒ main 已含全部修复 ⇒ 无需再合并 release 回 main**。这是本规范刻意为之——除非 release 分支上有 main 想要的**功能级**改动（罕见），否则 release 永不 merge 回 main。
+- **同时存在多个活跃 feature 分支时**：修复也要 pick 到那些分支，否则它们合回 main 时
+  可能带回旧代码。实践做法是修复落地当天就 pick 到全部活跃分支
+  （如 2026-09-04 的 stage 双重解锁修复同时 pick 到 `main` 与 `feature/memory-media`）。
 
-### 5. release 分支退役
+- **hotfix 已逐个 pick 回 main ⇒ main 已含全部修复 ⇒ 无需再合并发布分支回 main**。
+  这是本规范刻意为之——除非发布分支上有 main 想要的**功能级**改动（罕见），
+  否则发布分支永不 merge 回 main。
 
-- **下个版本发布 = 此 release 分支生命周期结束**（不再维护）。
+### 6. 发布分支退役
+
+- **下个中版本发布 = 上一条发布分支生命周期结束**（`release/v1.1.x` 出现即 `release/v1.0.x` 退役）。
 - 退役后可删可留：
   - 删除：保持仓库干净（tag 已保留全部历史，删分支不丢东西）。
-  - 保留：便于追溯该发布线的历史构建（对 24/7 现网友好，推荐与本仓库一样保留已打 tag 的历史分支做对照）。
-- 本仓对现网多代版本并行维护时，保留近期 release 分支是合理的。
+  - 保留：便于追溯该发布线的历史构建（对 24/7 现网友好）。
+- **按 patch 号命名的历史发布分支应当合并/删除**：它们是本规范修订前的遗留形态，
+  内容已被对应的 `release/vX.Y.x` 完全包含，保留只会让"哪条才是这条线"变得含糊。
 
 ---
 
-## 三、当前分支对齐（2026-08-31 执行）
+## 三、当前分支对齐（2026-09-12 更新）
 
 ### 主仓（TrueAgent）
 
-| 现存分支 | 状态 | 处理 |
+| 分支 | 状态 | 处理 |
 |---|---|---|
-| `main` | `48b5c24` [origin/main] | ✅ 保持不变（规范基线） |
-| `feature/plugin-proc-migration` | 原 `update`，`69a138c`（领先 main 5：文档基线 + Part 0.1/0.2 + 本规范） | ✅ **已对齐重命名**（2026-08-31） |
-| `backup-local`（SDK 仓） | `7092d15`（ahead 3, behind 14，含 `ignore example/recoverydiag` 敏感提交） | ⚠️ 遗留本地分支，功能已合入 main，**保留不删**（无远端，删除即永久丢失） |
+| `main` | 含全部回流修复；`meta.Version` = 下一个未发布中版本（现为 `1.3.0`） | ✅ 保持 |
+| `release/v1.2.x` | **本条发布线**，`meta.Version` = `1.2.0`，vendored SDK 定版 `1.2.0`；已载入两个发布前修复（GUI 输出目录、知识库同名覆盖） | 🆕 2026-09-12 从 main 切出；**尚无 tag** |
+| `release/v1.1.x` | 承载 `v1.1.0-beta.1` / `v1.1.0` / `v1.1.1` | 📦 已退役（§2.6：下个中版本发布即退役），保留供追溯 |
+| `release/v1.0.x` | 承载 1.0.x 全部 tag | 📦 保留 |
+| `feature/multimodal-embedding` | 已合入 main（`eb4762a`，43 提交，`--no-ff`） | ⏳ 待删（删远端分支需用户确认，§执行守则 3） |
+
+> `feature/memory-media`、`feature/plugin-proc-migration` 均已从远端删除（旧表里的待删项已处理）。
 
 ### SDK 仓（homeagent-sdk）
 
-| 现存分支 | 状态 | 处理 |
+| 分支 | 状态 | 处理 |
 |---|---|---|
-| `main` | `61f307b` v1.2.0 | ✅ 保持不变 |
-| `update` | `5648519`（领先 main 1：Part 0.2 模板修复） | ⚠️ 与主仓 `update` 对齐重命名 |
-| `backup-local` | `7092d15`（ahead 3, behind 14，遗留调试分支） | ⚠️ 可选清理 |
+| `main` | `meta.Version` = 下一个未发布中版本（现为 **`1.2.0`**）——SDK **不跟 beta 发版**（§七.2），1.2.0 要等核心的**正式** tag 才定版（§七.3），在那之前路牌不得越过它。此阶段与核心 main（`1.3.0`）**故意不对称**，详见 §七.4 | ✅ 保持 |
+| `release/v1.1.x` | `meta.Version` = `1.1.0`，承载 tag `v1.1.0` | ✅ 与核心对应 |
+| `release/v1.2.x` | **尚未创建** | ⏳ 随核心**正式** tag 一起建（§七.3：分支上把版本定为 `1.2.0` 再打 `v1.2.0`；beta 阶段不发 SDK） |
+| `release/v1.0.0` | 旧 patch 号命名形态，内容已被 main 完全包含 | 📦 保留（供追溯 1.0 线构建） |
 
-> `update` 整改工作分支按规范应为 `feature/plugin-proc-migration`（多进程插件化整改，8-9 周大特性）。
-> 是否重命名由执行人确认；不重命名则视为偏离规范的既有分支，须在文档记录其存在。
+### 1.0.x 发布线 tag 历史
+
+| tag | 提交 | 通道 | 说明 |
+|---|---|---|---|
+| `v1.0.0` | `9b92a04` | 正式 | 外部插件从 C ABI 迁移到子进程 + 共享内存 |
+| `v1.0.1` | `e671a8c` | 正式 | 多模态 bugfix（假成功、能力声明与回退链、see_video 帧数语义） |
+| `v1.0.3` | `26dc76f` | 正式 | 内核 stage 协调器双重解锁（直接跳正式：单点修复 + 反向验证 + 全类审计） |
+
+> `v1.0.2` 未使用：该号从未发布也无 tag，留空以免与任何本地构建混淆。
+
+### 1.1.x 发布线 tag 历史
+
+| tag | 提交 | 通道 | SDK | 说明 |
+|---|---|---|---|---|
+| `v1.1.0` | `579d7db` | 正式 | 1.0.0 | 记忆系统支持二进制多媒体节点（CAS 媒体存储 + L0/L2/L3 贯通） |
+| `v1.1.0-beta.1` | `7a57a14` | beta | 不发 | 打包链路验证（GUI 架构污染 + 空壳 node_modules）。按 §七.2，beta 不伴随 SDK 发版 |
+| `v1.1.1` | 见发布说明 | 正式 | **1.1.0** | 多模态贯通插件边界；SDK 首次随核心正式版发布 |
+
+> `v1.1.0-beta.1` 的提交序在 `v1.1.0` **之后**（它多含一个打包修复），
+> 而 semver 预发布语义里 `1.1.0-beta.1 < 1.1.0`。这是「一条发布分支 + tag 区分通道」的
+> 已知代价：beta 是为验证**打包链路**而补打的，不代表源码更旧。发布说明里已注明。
+
+### 1.2.x 发布线 tag 历史
+
+| tag | 提交 | 通道 | SDK | 说明 |
+|---|---|---|---|---|
+| `v1.2.0-beta.1` | `215804c` | beta | 不发 | 统一多模态向量空间 + 媒体升为图记忆一等节点 + 数据面全量迁到共享内存（RPC 协议 **2**，与 1.x 不兼容）。按 §七.2，beta 不伴随 SDK 发版 |
+| （正式 tag 待打） | — | — | — | 试运行 beta 无回退问题后打 `v1.2.0`，并同步 SDK 仓 `release/v1.2.x` + `v1.2.0` |
+
+> 1.2.x 与存量插件**不兼容**：RPC 协议升到 2（fd3 布局改变），存量外部插件必须用
+> 新版 plugindev 重编为 `plugin.bin`——**不支持滚动升级**，内核与插件须同批重建、同批安装。
+> 按 §2.4，跳级直发正式版需在发布说明里列明「单点修复 / 反向验证 / 全类审计」三项；
+> 本次改动面大（统一多模态向量空间 + 协议 2 + 数据面全量迁移），不满足跳级条件。
 
 ---
 
 ## 四、现网部署与版本对应（运维纪律）
 
-- **现网 homed 永远部署 `release/vX.Y.Z` 分支打出的 tag 构建**，路径见 `Makefile`（`make build` → `build/homed`）。
-- systemd 服务（`/usr/local/bin/homed`）替换前：备份旧二进制 → 停服 → 替换 → 起服 → 健康检查（`scripts/verify_deploy.sh`）。
-- **改造期间（update 整改）现网不得部署 main 或 feature 的中间态**——只有发版才用 release。
+- **现网 homed 永远部署 `release/vX.Y.x` 分支上 tag 的构建产物**，路径见 `Makefile`（`make build` → `build/homed`）。
+- systemd 服务（`/usr/local/bin/homed`）替换流程：
+  1. 备份旧二进制（`homed.bak.pre<版本>.<时间戳>`）
+  2. 备份配置库（**用 `sqlite3 .backup`，不用 `cp`**——WAL 模式下 cp 可能拿到不一致快照）
+  3. 记录当前插件建链清单，供重启后逐项比对
+  4. `install -m 0755` 替换（原子 rename，不会写坏正在运行的进程镜像）
+  5. `systemctl restart homeagent`
+  6. 健康检查：版本号、插件清单无缺失、`/api/v1/status`、一次真实对话、`fatal error` 计数为 0
+- **改造期间现网不得部署 main 或 feature 的中间态**——只有发版才用发布分支的 tag。
+- alpha/beta tag 的产物**不上现网**（现网是 24/7 服务，预发布通道的存在就是为了不拿它冒险）。
 - 涉及 SDK 仓时：主仓 `go.mod` 的 `replace => ./third_party/homeagent-sdk` 指向本地 vendored 副本，
-  发版前确认 vendored SDK 与 SDK 仓 release tag 一致（两仓版本对齐是第一优先级）。
+  发版前确认 vendored SDK 与 SDK 仓 release tag 一致（**两仓中版本对齐是第一优先级**，见 §七）。
 
 ---
 
@@ -128,28 +216,112 @@ git checkout -b feature/xxx
 git checkout main && git merge --no-ff feature/xxx   # 或 squash
 git branch -d feature/xxx
 
-# 发布
-git checkout -b release/v1.2.0 main
-git commit -am "chore: bump v1.2.0"                  # 版本号
-git tag v1.2.0
-# ... 构建发布 ...
+# 开一条新中版本的发布线
+git checkout -b release/v1.1.x main
+git commit -am "chore(release): bump v1.1.0-alpha.1"
+git tag -a v1.1.0-alpha.1 -m "..."                   # alpha：内部验证
+# ... 修问题 ...
+git commit -am "chore(release): bump v1.1.0-beta.1"
+git tag -a v1.1.0-beta.1 -m "..."                    # beta：小范围试用
+# ... 真实环境验证 ...
+git commit -am "chore(release): bump v1.1.0"
+git tag -a v1.1.0 -m "..."                           # 正式
 
-# hotfix（发布后）
-git checkout release/v1.2.0
+# hotfix（发布后）——注意是同一条 release/v1.0.x，不新建分支
+git checkout release/v1.0.x
 git commit -am "fix(x): 严重 bug"                    # ① 修复
-git commit -am "chore: bump v1.2.1"                  # ② 版本号
-git tag v1.2.1
+git commit -am "chore(release): bump v1.0.4"         # ② 版本号
+git tag -a v1.0.4 -m "..."
 git checkout main
 git cherry-pick <修复①的sha>                          # ③ 只挑修复
+# 若有活跃 feature 分支，也 pick 过去
+git checkout feature/xxx && git cherry-pick <main 上那个 pick 的 sha>
 
-# release 退役（可选）
-git branch -d release/v1.2.0                          # tag 已保存历史，删分支不丢东西
+# 公开 SDK 接口改动（feature，不是 hotfix）：先进 main，再 pick 到发布分支
+git checkout -b feature/sdk-xxx main
+# ... 改 third_party/homeagent-sdk/sdk/ 与内核桥接层 ...
+git checkout main && git merge --no-ff feature/sdk-xxx
+git checkout release/v1.1.x
+git cherry-pick <feature 的各 sha>                    # 只挑改动，不挑 main 的版本号
+git commit -am "chore(release): bump v1.1.1"          # 发布分支自己的版本号
+git tag -a v1.1.1 -m "..."
+# SDK 仓同步（仅在核心打正式 tag 时，见 §七.2/§七.3）
+cd third_party/homeagent-sdk
+git checkout -b release/v1.1.x main
+git commit -am "chore(release): SDK 1.1.0（1.1.x 线全程共用）"
+git tag -a v1.1.0 -m "..."
+
+# 发布分支退役（下个中版本发布后，可选）
+git branch -d release/v1.0.x                          # tag 已保存历史，删分支不丢东西
 ```
 
 ---
 
 ## 六、本规范与「接口冻结」约束的关系
 
-- feature 分支合回 main 的门禁（`git diff sdk/` 为空）是本仓特有的硬约束，独立于 Git 流程本身。
-- 插件多进程化整改（`feature/plugin-proc-migration` 或现 `update`）**不满足接口冻结不等于不能合并**——
-  接口冻结约束的是「公开 SDK 不变」，整改若突破需走变更评审（见 `docs/zh/plugin-interface-matrix.md` §七）。
+- feature 分支合回 main 的门禁（`git diff third_party/homeagent-sdk/sdk/` 为空）是本仓特有的硬约束，独立于 Git 流程本身。
+- `internal/sdk` **不受冻结约束**，可自由扩展；冻结只针对公开 SDK 接口（`third_party/homeagent-sdk/sdk/`）。
+- 若整改确需突破公开接口，走变更评审（见 `docs/zh/plugin-interface-matrix.md` §七），
+  并同步 `SDKCompatibleVersion` 与 SDK 仓的 release tag。
+- **公开接口的改动本身是 feature，不是发布准备**：它必须走 `feature/xxx` → 合回 main 的路径，
+  再 cherry-pick 到发布分支。不允许把接口新增当成"发布分支上的 bug 修复"直接提交进 release
+  ——发布分支冻结功能（§2.3），接口是最典型的功能面。
+
+---
+
+## 七、SDK 仓的版本语义与发版联动
+
+### 1. SDK 版本号跟随核心的中版本，patch 位恒为 `.0`
+
+| 核心版本 | 对应 SDK 版本 |
+|---|---|
+| 1.1.0 / 1.1.1 / 1.1.2 / … / 1.1.N | **1.1.0**（全线共用，不随核心 patch 变动） |
+| 1.2.0 起 | **1.2.0** |
+
+- 核心的 patch 位（`x`）专用于 **bugfix 与漏洞修复**，这类改动不触碰公开 SDK 接口，
+  因此 SDK 版本号没有理由跟着动。
+- **为什么不逐位对齐**：SDK 版本号是插件开发者的依赖声明。若核心每发一个 bugfix 就把 SDK
+  也推一个新号，开发者要么被迫跟版、要么怀疑自己版本过时，而接口其实一个字都没变。
+  让 SDK 号只在**接口可能变化的中版本边界**上跳，开发者只需关心「我在为哪个中版本写插件」。
+- 因此「两仓版本对齐」在本规范里指**中版本对齐**（核心 1.1.x ↔ SDK 1.1.0），
+  不是三位全等。核心 1.1.1 配 SDK 1.1.0 就是对齐状态。
+
+### 2. beta 阶段不发 SDK
+
+- **核心的 alpha/beta tag 不伴随 SDK 仓发版**：SDK 仓在这一阶段**不打 tag、不建 release**。
+- **为什么**：beta 是核心自己的测试阶段，此时 SDK 接口尚未固定。若此刻给 SDK 发版，
+  插件开发者会照着一个还会变的接口写代码——**那是无效开发**。接口没定就没有可依赖的契约，
+  发出去的版本号是一个假承诺。
+- 这条约束的对象是 **SDK 仓的发版动作**，不是核心二进制里有没有 SDK 代码。
+  主仓 `go.mod` 用 `replace => ./third_party/homeagent-sdk`，任何核心构建都必然含 vendored
+  SDK 源码，这是构建机制决定的，不在本条约束范围内。
+
+### 3. 正式发布时 SDK 随核心一起发
+
+核心打**正式 tag**（`vX.Y.Z`，无预发布后缀）时，SDK 仓同步执行：
+
+1. SDK 仓也有自己的 `release/vX.Y.x`（与核心同名，一个中版本一条）；
+2. 在该分支上把 `meta.Version` 定为 `X.Y.0`；
+3. 打 tag `vX.Y.0`（首次进入该中版本时），并建 gitcode release；
+4. 上传 5 平台 plugindev 产物 + `SHA256SUMS`。
+
+同一中版本内的后续核心 patch（1.1.1 → 1.1.2 …）**不重复发 SDK**——SDK 已经是 1.1.0，
+没有新东西要发。只有接口再次变化并进入下一个中版本时，SDK 才发 1.2.0。
+
+### 4. 版本号在两仓 main 上的含义
+
+两仓的 `main` 都遵守 §2.1：`meta.Version` 是**下一个未发布中版本**。
+所以在 1.1.x 线发布期间，两仓 main 上的值都是 `1.2.0`——它标记「main 正在积攒 1.2 的东西」，
+而不是「1.2.0 已经存在」。已发布的版本号一律看对应 `release/vX.Y.x` 分支与 tag。
+
+**但两仓「同步推进」是有条件的**（这一点曾导致误判，现补写清楚）：
+推进的前提是**该中版本已经正式发布过**。具体到当前：
+
+- 核心：切出 `release/v1.2.x` 后，1.2.0 就归发布线所有，main 立即推进到 `1.3.0`；
+  **即使 1.2.0 目前只有 beta tag**（beta 不上现网，但发布线已占住这个号）。
+- SDK：因为 §七.2 **beta 不发 SDK**，SDK 1.2.0 要等核心的**正式** tag 才定版、
+  建 `release/v1.2.x`、打 `v1.2.0`（§七.3）。在那之前，SDK 的「下一个未发布中版本」
+  仍然是 `1.2.0`，其 main 不得越过它。
+
+→ 因此在这一阶段，**核心 main = `1.3.0` 而 SDK main = `1.2.0` 是正确的**，
+不是遗漏同步。（曾按本节的例子把 SDK main 也推到 1.3.0，等于宣称 SDK 1.2.0 已发布。）

docs/zh/multimodal-space.md

@@ -0,0 +1,455 @@
+# 统一多模态向量空间
+
+核心不绑定任何具体模型：它按 provider 名从公共注册表（`pkg/embedding`）打开一个
+向量空间。仓库内自带两个：
+
+| provider | 模态 | 维度 | 实测常驻 | 许可 | 适用 |
+|---|---|---|---|---|---|
+| `chineseclip` | text + image | 512 | **1.15 GB** | Apache-2.0 | 默认（内存受限 / 中文图文） |
+| `qwen3vl` | text + image（视频已实现未纳入契约） | 2048 | 9.4 GB | Apache-2.0 | 内存充足 / 需要更强文本语义或视频 |
+| `http` | 由外部服务决定 | 由外部服务决定 | 由外部服务决定 | — | 侧车部署（如 jina-v5-omni-nano，注意其 CC BY-NC 许可） |
+
+下面第一节是 Qwen3-VL（2048 维，最强但最重），第二节是 Chinese-CLIP（512 维，
+默认推荐）。两者互斥启用，改配置后重启生效。
+
+文本、图像、**视频帧** 在同一模型、同一维度、同一 fingerprint 空间里被编码。
+记忆系统用它做三件事：多模态图记忆的跨模态召回、multimodal doc 的向量融合、
+multimodal context 的相关性裁剪/淘汰。
+
+统一空间取代了此前「把图片交给视觉模型生成文字描述、再按描述检索」的做法。
+那条链路有三个致命缺陷：描述是异步生成的（未生成前媒体等于不存在）、语义检索
+实际上只搜描述文字、图库里的「媒体节点」只是描述文本的投影而不是媒体本身。
+**不要再引入任何描述式索引。**
+
+## 一、产物与获取
+
+产物约 8 GB（含外部权重），**不进仓库**；用导出脚本自动拉取模型并导出：
+
+```bash
+# 默认导出 图像 + 视频 G=2,3,4（即 4/6/8 帧）
+python3 scripts/export_qwen3vl_embedding_onnx.py \
+    --out /home/newqqagent/models/qwen3-vl-embed-multimodal-onnx
+
+# 只要 4 帧的视频档（省磁盘、省内存）
+python3 scripts/export_qwen3vl_embedding_onnx.py --video-groups 2 --out ...
+
+# 已下载过模型：跳过拉取
+python3 scripts/export_qwen3vl_embedding_onnx.py \
+    --model-dir /path/to/Qwen3-VL-Embedding-2B \
+    --out /home/newqqagent/models/qwen3-vl-embed-multimodal-onnx
+
+# 参考向量默认直接写进产物目录（<out>/qwen_reference.json），无需额外参数
+python3 scripts/export_qwen3vl_embedding_onnx.py --model-dir ... --out ...
+```
+
+国内镜像：导出脚本沿用 `huggingface_hub` 的约定，直接 `export HF_ENDPOINT=https://hf-mirror.com` 即可。
+依赖：`torch`（CPU 版即可）、`transformers>=4.57`、`onnx`、`onnxruntime`、`pillow`、`numpy`，
+以及可选的 `huggingface_hub` / `modelscope`。显存不需要，内存建议 ≥ 16 GB（FP32 加载约 8 GB）。
+
+导出脚本**会清空 --out 目录**后重写，避免旧图/旧外部权重污染 fingerprint
+（fingerprint 变化会触发一次无意义的全量向量重算）。因此不要直接覆盖线上正在使用的目录，
+先导出到新目录再切换。
+
+### 产物契约（Go 侧按此读取）
+
+| 文件 | 输入 | 输出 |
+|---|---|---|
+| `TokenEmbedding.onnx` | `input_ids` int64 `[1,seq]` | `hidden` float `[1,seq,2048]` |
+| `Transformer.onnx` | `hidden`、`deepstack_0/1/2` `[1,seq,2048]`、`rotary_cos/sin` `[1,seq,128]`、`causal_mask` `[1,1,seq,seq]` | `embedding` `[1,2048]` |
+| `Vision.onnx(+.data)` | `pixel_values` `[2304,1536]` | `deepstack_feature_0/1/2`、`vision_hidden_states` `[576,2048]` |
+| `Vision_g{N}.onnx` | `pixel_values` `[N×2304,1536]` | 同上，`[N×576,2048]` |
+
+外加 `tokenizer.json`、`tokenizer_config.json`、`chat_template.jinja`、`embed_config.json`、
+`qwen_reference.json`。
+
+`Vision.onnx` 是图像（单时间组）；`Vision_g{N}.onnx` 是视频（N 个时间组 = 2N 帧）。
+**没有 `Vision_g1.onnx`**——单组就是图像那张。
+
+三段只是部署形式，不是三个向量空间：图文共用同一 token embedding、同一 28 层
+Transformer、同一 last-token 池化。RoPE 与视觉特征散射故意留在 Go 计算，
+因为旧式 tracer 会把 `seq=598 / visual=576` 烘焙进图里——签名上写着 dynamic
+axis，实际却只能用导出的那个长度运行。
+
+### ⚠️ max_length 必须按最大视频档推导
+
+`embed_config.json` 的 `max_length` 是**整条序列**的上限，包含视觉占位符：
+图像只需 598 token（1×576 + 模板），而视频是 G×576——G=2 就要 1190，G=4 要 2342。
+沿用图像的 1024 会让处理器静默截断，然后在 transformers 内部报
+`Mismatch in video token count between text and input_ids`。
+导出脚本因此用 `max_length_for(video_groups) = max(1024, max(G)×576 + 256)` 自动推导，
+并在构造视觉输入后显式断言视觉 token 数，把错误提前到导出阶段。
+
+### 导出脚本自检（不可省）
+
+脚本内部跑两道校验，任一道 cos < 0.999999 就以非零码退出：
+
+1. 分段 PyTorch（三段组合）对比完整模型前向；
+2. 用 onnxruntime 跑**导出后**的三段图，再对比完整模型前向。
+
+「能加载」不等于「算得对」：形状错、输入名错、池化位置错的图都能正常 load。
+
+## 一·补、text+image 默认空间：Chinese-CLIP ViT-B/16
+
+**为什么它是默认**：text+image 只需要一个向量空间时，同时满足「小、可商用、中文原生」
+的选项只有一个。
+
+| | Chinese-CLIP | jina-v5-omni-nano | Qwen3-VL-Emb-2B |
+|---|---|---|---|
+| 参数量 | 188M | 1.04B | 2B |
+| 产物 / 实测常驻 | **721MB / 1.15GB** | ~2GB / 2.23GB | 8GB / 9.4GB |
+| 维度 | 512 | 768 | 2048 |
+| 许可 | **Apache-2.0** | CC BY-NC（不可商用） | Apache-2.0 |
+| 中文 | 原生（~2 亿中文图文对） | 多语言 | 多语言 |
+| 文本语义 | 弱（双塔对比） | 好 | 最好 |
+| 视频 | 无 | 有 | 有 |
+
+**要诚实记录的代价**：CLIP 是双塔对比学习，text↔image 是强项，但**纯文本语义
+（text↔text）明显弱于 MLLM 型嵌入器**。文本检索仍由既有词向量/TF-IDF 路径兜底，
+本空间主要用于跨模态召回与相关性裁剪。需要更强文本语义或视频时切回 `qwen3vl`。
+
+### 产物与获取
+
+产物约 754MB，**不进仓库**；用导出脚本从官方权重导出（脚本入库，保证可复现）：
+
+```bash
+python3 scripts/export_chineseclip_onnx.py \
+    --model-dir /path/to/chinese-clip-vit-base-patch16 \
+    --out /home/newqqagent/models/chinese-clip-vit-b16-onnx
+```
+
+国内下载：本机 `huggingface.co` 走代理会被 reset，用 `hf-mirror.com` 且**不设代理**：
+
+```bash
+curl -4 -L --retry 3 -o vocab.txt \
+  https://hf-mirror.com/OFA-Sys/chinese-clip-vit-base-patch16/resolve/main/vocab.txt
+```
+
+### 产物契约（Go 侧按此读取）
+
+| 文件 | 输入 | 输出 |
+|---|---|---|
+| `TextEncoder.onnx` | `input_ids` int64 `[B,52]`、`attention_mask` int64 `[B,52]` | `text_features` float `[B,512]` |
+| `VisionEncoder.onnx` | `pixel_values` float `[B,3,224,224]` | `image_features` float `[B,512]` |
+
+外加 `embed_config.json`（维度/预处理/分词超参/文件名——provider 的唯一权威）、
+`vocab.txt`、`reference.json`（冻结参考：逐文本 token id + 逐样本向量）、`SHA256SUMS`。
+
+图像预处理：缩放到 224×224（双三次，复刻 PIL 系数）→ `(x/255 - mean) / std`，
+不裁剪。文本：BERT WordPiece，`max_length=52`，补 `[PAD]`，超长截断尾部。
+两个塔的输出**都没有在图中归一化**，归一化由 provider 负责（检索按余弦）。
+
+### 启用
+
+```bash
+core.memory.multimodal_space.provider = chineseclip
+core.memory.multimodal_space.options.model_dir = /home/newqqagent/models/chinese-clip-vit-b16-onnx
+```
+
+**新装默认就是这个**（`SeedDefaults` 写入 `chineseclip` + `<dataDir>/models/chinese-clip-vit-b16-onnx`），
+发行版构建也默认带 `onnxruntime` 标签（`deploy/packaging/build.sh` 的 `HOMED_TAGS`，
+需要极简构建时显式 `HOMED_TAGS=` 关闭）。
+
+**老安装不会自动拿到**：播种判据是显式标记 `core.internal.seed_version`。
+老安装（已播种过）下次启动只会被补上标记，**不会**被注入新默认值——
+升级就静默加载 1.8GB 模型不是无副作用的事。要启用请显式写上面两个键。
+
+> 这个判据曾经是「`config` 表为空才播种」。而发行包的 postinst 会先跑
+> `initconfig`，它写一行 `webui.listen_addr` ——于是**全新安装**被误判为
+> "已有配置"，整个播种被跳过：没有 `core.plugin.dir`（装完 0 个插件）、
+> 也没有多模态 provider（随包的模型与运行库成了死重量）。回归测试
+> `TestSeedDefaultsAfterInitconfigPrepopulate` 与
+> `TestSeedDefaultsDoesNotInjectIntoLegacyInstall` 钉住了这两种情形。
+
+同样要求 `homed` 带 `onnxruntime` build tag。
+
+### 随包分发（server / full 包自带模型与运行库）
+
+模型与运行库是发行版能力的一部分，不做成「可选下载」：
+
+| 内容 | 包内路径 |
+|---|---|
+| Chinese-CLIP 产物（754MB） | `/usr/lib/homeagent/models/chinese-clip-vit-b16-onnx/` |
+| ONNX Runtime（24MB） | `/usr/lib/homeagent/onnxruntime/libonnxruntime.so` |
+| 许可证 | `/usr/share/doc/homeagent/licenses/`（Apache-2.0、MIT、ThirdPartyNotices、模型来源） |
+
+- `deploy/packaging/package-linux.sh` 的 `stage_multimodal_assets()` 在打 server/full 前
+  会校验产物 `SHA256SUMS`、逐文件非空、运行库架构与目标一致；**缺一即失败**，
+  不生成「默认启用但装完不能用」的假包。`client` 包不含（它不跑 homed）。
+- 安装时 `setup.sh` 把包内模型目录软链到 `<dataDir>/models/chinese-clip-vit-b16-onnx`
+  （既不复制 754MB，也保持 dataDir 可迁移；已存在的自定义目录绝不覆盖）。
+- 服务单元设 `Environment=ONNXRUNTIME_DIR=/usr/lib/homeagent/onnxruntime`；
+  provider 的查找顺序是 `ONNXRUNTIME_DIR` → `ONNX_ML_DIR` → 包内路径 →
+  `/opt/onnxruntime` → `/usr/local/lib` → `/usr/lib`。
+- 构建机需自备产物：`build/model-assets/chinese-clip-vit-b16-onnx/` 与
+  `build/runtime-assets/<arch>/{libonnxruntime.so,LICENSE,ThirdPartyNotices.txt}`
+  （可用 `CHINESECLIP_BUNDLE_DIR` / `ONNXRUNTIME_ASSET_DIR` 覆盖）。
+
+实测（从真实 deb 解包、按 postinst 顺序跑 `setup.sh`、再冷启动包内 homed）：
+`multimodal space active: provider=chineseclip dim=512 fp=cd2a495cf990 modalities=[text image]`，
+并完成一次真实对话；`homeagent-server` 包 722MB（旧版 17MB），差额即模型与运行库。
+
+#### ORT 环境是进程级单例（单主不析构）
+
+进程内可能有多个 ORT 消费者（本 provider、`qwen3vl`、`internal/nlp` 的依存解析器）。
+`onnxruntime_go` 的行为是：第二次 `InitializeEnvironment` 报错，而
+`DestroyEnvironment` 会把别人正在用的环境一起拆掉。约定：
+
+- 初始化前先 `IsInitialized()`，只有未初始化时才初始化；
+- **任何消费者都不销毁环境**（环境随进程存活），只销毁自己的会话。
+
+这个缺陷是「发行版默认带 onnxruntime 标签」后才暴露的：不带标签时多个消费者不会
+同时存在（此前 `internal/nlp` 会重复初始化并降级，失败路径还会误销毁环境）。
+
+### 模态范围
+
+只声明 `text` 与 `image`。`audio`/`video` **明确返回 `ErrUnsupportedModality`**——
+本空间没有它们的原生编码器，用别的模型向量冒充会污染整个向量空间
+（这正是「音频明确 unsupported」那条纪律的落地）。
+
+### 验证
+
+Go 侧回归对着官方 PyTorch 参考（`reference.json`），模型目录由
+`CHINESECLIP_MODEL_DIR` 指定，缺失时 skip：
+
+```bash
+CHINESECLIP_MODEL_DIR=/home/newqqagent/models/chinese-clip-vit-b16-onnx \
+  go test -tags onnxruntime ./providers/chineseclip/ -v
+```
+
+实测结果：文本 5 个用例 `cos = 1.000000000000`（与官方逐位一致）；
+图像 4 个纯色用例 `cos = 1.000000`（自写 bicubic 与 PIL 在 6 位小数内一致）；
+另有跨模态判别、模态拒绝、指纹稳定性、产物缺失报错等用例。
+
+### 两个已踩过的坑（都在测试里钉住了）
+
+1. **分词器不能自己拼**。第一版探针用 `BertTokenizer(vocab_file=..., do_lower_case=True)`
+   手工分词，中文被整体切成 `[UNK]`，三个不同句子产出几乎相同的向量（余弦 0.98），
+   差点把「模型坏了」当成结论。官方配置是 `do_lower_case=true` + **删音标生效** +
+   **中文逐字切分**；Go 侧实现必须与官方**逐 token** 对齐（`TestTokenizerMatchesOfficialReference`）。
+2. **参考向量是未归一化的原始输出**（模长 10~36）。用「点积当余弦 + 单侧下界」判定
+   会得到 13.6 而「通过」——测试里因此改成真余弦 + 双侧容差。
+
+## 二、启用
+
+核心不识别任何具体模型：它只按配置里的 **provider 名**从公共注册表
+（`pkg/embedding`）打开一个 provider，并把 `options.*` 原样交给它。
+模型文件布局、预处理、媒体解码、运行时都在 provider 内部。
+
+```bash
+# 配置库（config.db）或 WebUI 设置页
+core.memory.multimodal_space.provider = qwen3vl
+core.memory.multimodal_space.options.model_dir = /home/newqqagent/models/qwen3-vl-embed-multimodal-onnx
+
+# 或换成一个外部向量服务（任何语言写的都行）
+core.memory.multimodal_space.provider = http
+core.memory.multimodal_space.options.endpoint = http://127.0.0.1:18999/embed
+core.memory.multimodal_space.options.dimension = 2048
+```
+
+`options.*` 是 provider 自己的命名空间，核心不做任何解释（对 `qwen3vl` 是
+`model_dir`，对 `http` 是 `endpoint`/`dimension`/`api_key`/…）。第三方 provider
+可以定义自己的选项，无需改核心。
+
+注意事项：
+
+- 内置 provider `qwen3vl` 要求 `homed` 带 `onnxruntime` build tag 构建，且
+  `libonnxruntime.so` 可被找到（`/opt/onnxruntime/libonnxruntime.so` 等）。
+  未带 tag 时该 provider 会注册但打开时报「requires build tag」，而不是静默降级。
+- `provider` 为空时禁用多模态向量检索，退回纯 fastText 文本路径。
+- 改配置后需重启进程生效。
+- 未配置时优雅降级：文档层退到 TF-IDF 稀疏检索，媒体块仍按结构边关联，只是没有跨模态召回。
+
+## 二·补、给核心接自己的模型
+
+核心只依赖一个很小的公共接口（`pkg/embedding`）：
+
+```go
+// 输入对核心是不透明字节：modality 决定语义，Data+MIME 由 provider 解释。
+type Input struct {
+    Modality Modality   // text / image / audio / video / …
+    Purpose  Purpose    // query / document
+    Text     string
+    Data     []byte
+    MIME     string
+    Metadata map[string]string
+}
+
+type Provider interface {
+    Embed(ctx context.Context, in Input) ([]float64, error)
+    Info() Info                     // Dimension, Fingerprint, Modalities
+    Close()
+}
+```
+
+接入步骤：新建一个包，在 `init()` 里 `embedding.Register("your-model", factory)`，
+再把这个包空白导入你的发行版 `main`（或替换内置 provider 的导入行）。
+分词、预处理、解码、显存/内存管理、模型文件命名全部由你的 provider 决定。
+
+两条原则值得强调：
+
+- **能力是数据，不是接口方法**：支持哪些模态写在 `Info().Modalities` 里。
+  这样新增模态不需要改核心接口，核心也不需要为每个新模态做类型断言。
+- **不支持的模态返回 `embedding.ErrUnsupportedModality`**，而不要拿别的模型顶替，
+  也不要降级成一个普通错误——调用方靠它区分「永远不会有向量」与「本次失败可重试」。
+
+## 三、模态覆盖范围
+
+### Qwen3-VL-Embedding-2B（本空间，2048 维）
+
+模型卡明载支持 **Text / images / screenshots / videos**；`config.json` 有
+`image_token_id` 与 `video_token_id`，**没有 `audio_token_id`/`audio_config`**。
+
+| 模态 | 状态 | 说明 |
+|---|---|---|
+| 文本 | ✅ 原生 | `VectorizeDense` |
+| 图像 | ✅ 原生 | `EmbedImageDense`，`Vision.onnx`，固定 768×768 |
+| 视频 | ⚠️ 视觉侧已导出并校验，**Go 模板未完成** | `EmbedVideoDense` + `Vision_g{N}.onnx`；见下节 |
+| 音频 | ❌ 本轮明确不做 | 决策结果；该模型也不具备（无 `audio_token_id`） |
+
+### 视频：帧 → 时间组 → M-RoPE（均已实测对齐）
+
+| 项 | 值 | 验证方式 |
+|---|---|---|
+| 占位符 | `<|video_pad|>` = **151656**（图像是 `<|image_pad|>` = 151655） | 处理器实测 |
+| 模板 | 与图像同构，只换占位符 | `apply_chat_template` repr 逐字符比对 |
+| 帧→槽位 | 组 g 的 tp0←帧2g、tp1←帧2g+1 | PyTorch `torch.equal == True`，maxdiff=0；反向对照 False |
+| patch 布局 | `[G,24,24,2,2,3,2,16,16]`，即图像排列以 grid_t 为最外层堆叠 | 纯色视频于图像张量 `torch.equal == True` |
+| 视觉 token | `G×576` | 处理器实测（G=2 → 1152） |
+| M-RoPE | 每组独立：`base=start+24g`；`t=base`、`h=base+j/24`、`w=base+j%24` | 对应 `get_rope_index` 把 video grid 展开成 G 个 `t=1` 项 |
+| 用错档 | onnxruntime 报 `InvalidArgument`（维度不符） | 实验实测，**不会静默算错** |
+
+同步注意事项：
+
+- **帧数必须恰好是 `2×G`**（G 取已导出的档）。奇数帧时只用得上前 `2×floor(n/2)` 帧，
+  多出的丢弃——不补重复帧，那会改变跳帧注意力看到的运动。
+- **`video/*`（视频文件）不能直接喂给图像入口**：Go 侧没有视频解码器，
+  `EmbedImageDense(raw, "video/mp4")` 返回 `ErrModalityUnsupported`。调用方必须先抽帧。
+- 视觉图按需懒加载（每张约 1.6GB），未用到的档位不占内存。
+
+### 导出视频时踩过的两个坑（都已加断言）
+
+两个坑都会让产物「看起来正常、实际是错的」，且都不会在导出时报错：
+
+1. **处理器会静默重采样帧**。不给 `video_metadata` 时它回落到 `fps=24`，
+   把**任何**帧数都改成 `grid_t=2`：实测 4/6/8 帧全部得到 1152 个视觉 token。
+   修法：`processor(..., videos=[frames], do_sample_frames=False)`。
+2. **`max_length` 只按图像算是不够的**。它是整条序列（含视觉占位符）的上限：
+   图像只需 598 token，而视频是 `G×576`——G=2 要 1190、G=4 要 2342。
+   沿用 1024 会截断并报
+   `Mismatch in video token count between text and input_ids`。
+   修法：`max_length_for(G) = max(1024, max(G)×576 + 256)`。
+
+两个坑都会在导出脚本里显式断言（视觉 token 数、`video_grid_thw` 的组数），
+把错误提前到导出阶段而不是留给运行时。
+
+### 音频（本轮决策：不加）
+
+**Qwen3-VL 不支持音频**，由模型卡与 `config.json` 双重确认：
+
+```
+模型卡：Supported Input Modalities: Text, images, screenshots, videos, and …
+config：image_token_id ✓ / video_token_id ✓ / audio_token_id ✗ / audio_config ✗
+```
+
+本机有音频能力的是另一个模型（**jina-v5-omni-nano**，768 维，含
+`modeling_llava_eurobert_audio.py` 与 `audio_token_id=128256`），与 Qwen 空间
+**不同维度、不同坐标系，绝不可互相比较**。决定：**本轮不接入**；
+其侧车（`scripts/embed_sidecar.py`）也仍只实现 `text`/`image`，`audio` 返回 400。
+
+无论何时接入，都**不允许**：拿视觉塔去编码音频字节、或用另一个模型的向量
+冒充某空间的音频向量——那会把两套坐标系混进同一空间，且错误是静默的。
+音频在原空间返回 `vector.ErrModalityUnsupported`，使调用方区分
+「永远不会有向量」与「本次失败可重试」。
+
+Qwen3-VL 视觉塔把 `grid_thw` 当 Python 值消费（源码里是 `grid_thw.tolist()`），
+legacy tracer（`dynamo=False`）会把它固化成常量：实测把 `grid_thw` 声明为图输入后，
+导出的 ONNX 图里**根本没有该输入**，换帧数调用直接报 `Invalid input name: grid_thw`；
+导出时的 TracerWarning 明确提示
+`Converting a tensor to a Python list might cause the trace to be incorrect`。
+
+因此视频的可行做法是：**在导出时固定时间组数 G，每个 G 一张 Vision 图**
+（grid = `[G, 48, 48]`），Go 侧按实际帧数选用匹配的图；用 G=2 的图去喂 G=3 的
+数据属于未定义行为。视频文件本身不能直接喂进本空间（`video/*` 返回
+`ErrModalityUnsupported`），必须由上层先抽帧。
+
+## 四、验证
+
+```bash
+# Go 侧：ONNX 路径（模型目录缺失时自动 skip）
+QWEN_ONNX_MODEL_DIR=/home/newqqagent/models/qwen3-vl-embed-multimodal-onnx \
+  go test -tags onnxruntime ./internal/memory/qwen/ -v
+
+# 排除二进制交付问题的替代：先单独验证模型与 CSV 无关的 ONNX 图
+go vet -tags onnxruntime ./...
+```
+
+Go 测试覆盖：冻结参考向量（文本/图像各 12 维）、同输入确定性、不同输入敏感性、
+图像与文本向量必须不同、以及音频/视频必须返回 `ErrModalityUnsupported`。
+
+冻结参考向量由导出脚本写入**产物目录本身**（`<out>/qwen_reference.json`），
+来源可追溯：同一脚本既产出模型，也产出「这个模型对固定输入应有的输出」。
+重新导出后若参考值变化，说明权重或图结构变了，必须显式更新参考而不是放宽阈值。
+
+> **参考向量是 L2 归一化后的值。** ONNX 图返回的是 final norm 之后的原始
+> last hidden（量级约 100），而 Go 侧 `VectorizeDense` / `EmbedImageDense`
+> 返回归一化向量。写参考时忘归一化，Go 测试会全线不匹配，而现象看起来
+> 像“模型不对”，实际只是两边对“向量”的定义不同。
+
+验证既有产物（不重新导出）：
+
+```bash
+python3 scripts/export_qwen3vl_embedding_onnx.py --verify-only --model-dir <model> \
+    --out /home/newqqagent/models/qwen3-vl-embed-multimodal-onnx
+```
+
+脚本会顺便把归一化后的参考向量写入该目录。
+
+### 与现有部署产物的等价性
+
+本仓库脚本对同一源模型导出时，`TokenEmbedding.onnx` 与 `Transformer.onnx` 与
+线上在用的产物**逐字节相同**（sha256 一致）；`Vision.onnx` 差异仅在打包形式：
+旧产物把权重量到外部 `Vision.onnx.data`，新脚本内联在图里。两者数值等价。
+
+注意这会带来一个**操作性**差异：Go 的结构指纹（`computeFingerprint`）把
+`*.onnx.data` 的文件名与大小算在内，因此「外部权重版 ↔ 内联版」互换会让
+fingerprint 变化，从而触发一次全量向量重算。重算不会**算错**（数值等价），
+只是白花一次 CPU；若不想触发，就保持产物打包形式不变。
+
+## 五、资源成本
+
+- 产物磁盘约 8 GB；导出过程峰值内存约 10–12 GB（FP32 加载）。
+- 单次 CPU 推理：文本约几十毫秒量级，图像（2304 patch 过 24 层视觉塔 + 28 层语言模型）
+  明显更重，因此入库时不阻塞对话，靠 `reembedStaleMedia` 在启动时并发迁移
+  （ONNX 路径 4 worker）。
+- fingerprint 由三段图 + `embed_config.json` + 外部权重文件名/大小共同决定；
+  换模型或重新导出都会让它变化，从而触发历史向量重算——这是预期行为。
+
+## 视频：当前状态（未完成，不得当作已验证）
+
+**视觉侧**：`Vision_g2/g3/g4.onnx` 已导出，且每一档都与完整 PyTorch 模型逐档对过
+（`cos` 分别为 1.000000119 / 1.000000119 / 1.000000000，覆盖度断言通过）。
+
+**Go 侧模板**：与 HuggingFace processor 产出**不相等**，因此冻结回归
+（`TestEmbedderVideoMatchesONNXReference`）当前**显式跳过**并注明原因，不算通过。
+
+已定位的差异：processor 会按时间组插入字面时间戳文本。逐 token 实测：
+
+```
+<|vision_start|> <0.0 seconds> <|vision_start|> {576×<|video_pad|>} <|vision_end|>
+<1.0 seconds>   <|vision_start|> {576×<|video_pad|>} <|vision_end|>
+```
+
+而 Go 侧只生成 `<|vision_start|>{G×576 pads}<|vision_end|>`。同一输入下
+Python `seq=1190`（1152 视觉 + **38** 文本），Go 侧只有 **22** 个文本 token。
+
+注意两点：
+
+- 时间戳文本**也占用 M-RoPE 位置**，所以 `TestVideoModelInputMRope` 的自洽断言
+  通过**不能**证明与官方实现一致（它是拿自己算的序列验自己算的位置）。
+- 修复位置在 provider 内部（模型专属模板本就属于 provider），不是核心。
+
+另外，公共 provider 契约把 `Data+MIME` 交给 provider 自行解码；本 provider
+没有视频解码器（Go 标准库不含 H.264/MP4），因此 `Info().Modalities` **不声明 video**，
+`Embed(video)` 返回 `ErrUnsupportedModality`。视频走 provider 自己的
+`EmbedVideoDense`（接收已解码帧）。待核心有了对 provider 不透明的多帧容器后，
+再把视频纳入公共契约。

docs/zh/plugin-interface-matrix.md

@@ -1,12 +1,16 @@
 # 外部插件接口不变矩阵（多进程化整改基线）
 
-> 状态：**完成 v2**（2026-09-03）——迁移已落地并上生产，内核 v1.0.0。
+> 状态：**完成 v3**（2026-09-06）——v2 的迁移已上生产（内核 v1.0.0）；v3 记录 v1.1.1 的公开接口**扩展**。
 > 目的：钉死「暴露给外部插件的接口不变」这一约束的**合同面**——迁移前、迁移后外部插件看到/调用的 SDK 接口完全一致；
 > 所有改造落在**核心（homed 侧）+ 工具链（plugindev）**，外部插件业务代码零改动，只需用新 plugindev 重编。
 >
 > **结果（已验证）**：`git diff third_party/homeagent-sdk/sdk/` 全程为空；17 个 `example/*/plugin.go` 逐字节未改
 > （`git status example/` 无输出）；生产 17 插件全部经子进程通道运行。
 >
+> ⚠️ **v1.1.x 起冻结约束被有意解除**，因为「接口不变」这条约束本身是为**迁移期**设的：
+> 它要保的是「换运行模型不动业务代码」。迁移完成后，SDK 需要能随功能演进而扩展，
+> 否则多模态这类能力永远到不了插件手上。解除的边界见 §九：**只增不减，签名不改**。
+>
 > 维护规则：每次改动公开 SDK 接口面 `third_party/homeagent-sdk/sdk/` 或模板 `tools/plugindev/templates/` 后，
 > 必须同步更新本矩阵。
 >
@@ -67,7 +71,7 @@ type Plugin interface {
 |---|---|---|
 | `Settings()` | `SettingsAPI` | **17 插件全部使用**（Get/Set/List/GetCore/SetCore/ListCore/DataDir/GetPlugin/SetPlugin/ListPlugin/RegisterDef/Defs/Dump/Plugins） |
 | `Memory()` | `MemoryAPI`（Recall/Commit/Introspect/MergeEntities/Purge） | 低（controllable） |
-| `DocMemory()` | `DocMemoryAPI`（Query/Insert/Remove/Stats） | 低 |
+| `DocMemory()` | `DocMemoryAPI`（Query/Insert/**InsertWithMedia**/Remove/Stats） | 低（`InsertWithMedia` v1.1.0 新增） |
 | `TextMemory()` | `TextMemoryAPI`（Append） | 0 当前 |
 | `Knowledge()` | `KnowledgeAPI`（Search/Add/List） | 2 |
 | `LLM()` | `LLMAPI`（ListSources/SetSource/CurrentSource） | 0 当前 |
@@ -85,7 +89,14 @@ type Plugin interface {
 | `InjectInterruptText` | `(source, channel, text string)` | example 使用 6 次 → case 6 |
 | `InjectTextNoMemory` | `(source, channel, text string)` | → case 7 |
 | `InjectInputSync` | `(source, channel, text string) string` | → case 47（例：qq 闭环） |
-| `SetToolBlocks` | `(blocks []ContentBlock)` | **当前空实现**（C ABI 无对应），迁移后经 arena 二进制注入可实现 |
+| `SetToolBlocks` | `(blocks []ContentBlock)` | ✅ **v1.1.1 已落地**（`io.setToolBlocks`）；同版补上 `PluginSDK` 侧一直缺失的便捷包装——接口里有、便捷方法里没有，插件此前只能自己去拿 injector |
+| `InjectInputMedia` | `(source, channel, text string, blocks []ContentBlock)` | **v1.1.0 新增** → `io.injectMedia`。与 `SetToolBlocks` 的区别见下方说明 |
+| `InjectInputMediaSync` | `(source, channel, text string, blocks []ContentBlock) string` | **v1.1.0 新增** → `io.injectMediaSync` |
+| `InjectInterruptMedia` | `(source, channel, text string, blocks []ContentBlock)` | **v1.1.0 新增** → `io.injectInterruptMedia` |
+
+**为何媒体注入不能搭 `SetToolBlocks` 的车**：后者只在**工具处理函数内部**可用，且媒体要等
+**下一条 tool message** 才到模型手上。插件主动发起一轮带媒体的对话、以及中断注入，
+需要各自的签名，且媒体在**本轮**就随消息发出，并自动落进 CAS、挂上媒体记忆引用。
 | `RegisterStopHandler` / `RunStopHandlers` | `(func())` / `()` | 已有（qq 等 1 次） |
 | `RegisterOnRemoveHandler` / `RunOnRemoveHandlers` | `(func())` / `()` | example 使用 3 次 |
 | `Set*`（SetIOInjector/SetMemoryAPI/.../SetPluginMgrAPI） | — | 供 bridge/核心启动时接线，插件不直接调 |
@@ -99,8 +110,12 @@ type Plugin interface {
 | `ChannelDef` | NoMemory/Cleaner(func) | 同上 |
 | `ToolCall` / `ToolResult` / `MemItem` | ID/Name/Plugin/Arguments；CallID/Name/Plugin/Success/Result；Role/Content/Score | 全部纯 JSON 可序列化 |
 | `ContentBlock` / `ImageURL` / `AudioURL` | Type/Text/ImageURL/AudioURL；URL/Detail；URL | 全部可偏移化（迁移评估 3.3 已核实） |
+| `MediaAttachment`（**v1.1.0 新增**） | Digest/MIME/Data/Name/Description | 一个类型服务两个方向：给 `Data`+`MIME` 是新内容（CAS 按字节去重），只给 `Digest` 是引用已有内容。**读路径不回 `Data`**——一次检索可能命中几十份媒体，全塞回去会撑爆跨进程消息 |
 | `Event` / `EventHandler` / `EventSubscriber` | Type/Source/Payload/Timestamp | 迁移后才对外部插件真正可用 |
 | `Triple` / `Entity` / `Relation` / `Doc` / `TextEvent` / `PersonProfile` / `SocialRelation` / `Knowledge` / `ConfigDef` | — | 全部 JSON 可序列化 |
+| `Triple`（**v1.1.0 扩展**） | += `SentenceText` / `MediaDigests` | 媒体引用挂在**句子**上（`SentenceText` → `sentences` → `sentence_id` → `media_refs`），所以 `MediaDigests` 非空而 `SentenceText` 为空时内核会用媒体标记本身充当句子 |
+| `Doc`（**v1.1.0 扩展**） | += `MediaDigests` / `Attachments` | `Query` 返回时由内核填充（仅元数据，不带字节） |
+| `TextEvent`（**v1.1.0 扩展**） | += `Attachments` | 写入时内核把标记并进正文；`RecentEvents` 读回时从标记反解 |
 
 **函数类型字段盘点（唯一无法跨进程序列化的东西）**：
 - `ToolDef.Cleaner func(string) string`
@@ -252,7 +267,9 @@ Part 0.2 先做了过渡补丁（只回传真正变更的字段）；Part 4 的
 | 能力 | 迁移前 | 迁移后 | 实际结果 |
 |---|---|---|---|
 | 事件订阅 `Events().Subscribe`（case 23/24） | ❌ 空实现 | ✅ 事件环（EvtRing + eventfd + 独立游标） | ✅ 已接线（当前零用户） |
-| `SetToolBlocks` 多模态注入 | ❌ 空实现 | ✅ 二进制落 arena，Slice 描述符回传 | ⚠️ method 已定义，内核侧仍未实现 |
+| `SetToolBlocks` 多模态注入 | ❌ 空实现 | ✅ `io.setToolBlocks` | ✅ **v1.1.1 已落地**（走 JSON 而非共享段二进制通道，理由见 §九） |
+| 媒体入记忆（`InsertWithMedia`、`Triple.MediaDigests`） | ❌ 不存在 | ✅ CAS + 引用计数 GC | ✅ **v1.1.0 类型 / v1.1.1 内核实现** |
+| 插件主动发起带媒体的一轮对话（`InjectInputMedia*`） | ❌ 不存在 | ✅ 媒体在本轮就到模型手上 | ✅ **v1.1.1** |
 | `ContextMsgs`/`ReasoningContent`/`TokenUsage`/`Memory`/`Extra`/`Errors` | ❌ 看不到 | ✅ 共享内存全字段 | ✅ 18 字段全可见可写 |
 | 插件崩溃隔离 | ❌ panic 带崩 homed | ✅ 子进程独立崩溃 | ✅ 测试 + 生产验证 |
 | 热重载 `.so` | ❌ `DF_1_NODELETE` no-op | ✅ 同路径替换 `.bin` 即生效 | ✅ 生产实测 |
@@ -291,6 +308,8 @@ C 结构体不好传函数指针（那是运气，任何人给 dispatch 加个 c
 3. ✅ **阶段 5**：17 个外部插件全部 `.bin` 化、cabi 删除（-3198 行）；
    `go build ./...` 与全仓 `go test ./...` 均通过。
 4. ✅ **全程**：`git diff third_party/homeagent-sdk/sdk/` 为零——接口冻结的硬证据。
+5. ⚠️ **v1.1.x 起该检查项不再适用**：冻结是迁移期的约束，迁移完成即到期（见 §九）。
+   取代它的门禁是「存量插件零改动零重编」——见 §九的验证方式。
 
 生产端到端（2026-09-03，真实 QQ 消息）：
 
@@ -304,6 +323,100 @@ tool output_send__qq result: 已通过 [qq] 通道发送: map[status:sent]
 
 ---
 
+## 九、v1.1.x 的接口扩展规则（冻结解除后的替代约束）
+
+冻结约束是为**迁移期**设的：它要保的是「换运行模型不动业务代码」。迁移完成后继续冻结，
+等于让 SDK 永远停在迁移那天的能力面——多模态这类功能永远到不了插件手上。
+
+取代它的是三条更弱但仍然硬的约束：
+
+### 1. 只增不减，签名不改
+
+新增字段、新增方法可以；**改已有方法的签名、删字段、改字段语义不行**。
+
+实例：v1.1.0 想让插件能给三元组关联媒体，两条路——改 `Commit` 的签名加一个参数，
+或新增 `CommitWithMedia`。选了后者。改签名会让每个调 `Commit` 的插件编译失败，
+而那些插件根本不关心媒体。
+
+### 2. 新增方法必须是「插件调用、内核实现」方向
+
+这是**存量插件不需要重编**的技术原因：`IOInjector` 新增三个方法后，插件只是
+*多了可以调的东西*，没有新的实现义务。反过来若在 `Plugin` 接口上加方法，
+每个存量插件都会因未实现而编译失败。
+
+因此 `SDKCompatibleVersion` 与 SDK 的 `CoreVersion` 都不必随之跃迁：
+1.1.0 的 SDK 配 1.0.0 编的插件仍然成立。
+
+### 3. 生成模板必须同步接线，否则是**全体外部插件编译失败**
+
+公开接口加方法时，`tools/plugindev/templates/proc_main.go.tmpl` 里的 `procIO` /
+`procDocMemory` 若不实现新方法，就不满足接口——**每个外部插件都编不过**，是硬失败
+不是软降级。v1.1.1 这一层是被 `go test` 抓出来的（`internal/plugin/proc` 的两个
+E2E 用例编译失败），不是靠人工检查发现的。
+
+完整接线链共六处：`protocol.go` 的 method 常量 → `capability.go` 的能力归属 →
+`corehandler.go` 的分派分支 → `proc_core.go` 的委托 → `proc_main.go.tmpl` 的模板实现 →
+测试替身（`fakeCoreSDK`、`injectCapture`、`capability_test.go` 的手工方法清单）。
+还要同步 `yaegi/mocksdk`——它没有任何代码对着编译，所以漂移不会被编译器抓到
+（v1.1.1 修的时候发现它的 `Triple` 用的是 `Predicate`，而公开 SDK 一直叫 `Relation`）。
+
+### 验证方式（取代「diff 为零」）
+
+| 检查 | 命令 | v1.1.1 结果 |
+|---|---|---|
+| 存量插件源码零改动 | `cd example/<n> && go vet ./...`（17 个） | ✅ 17/17 通过 |
+| 旧产物仍能建链 | 用 SDK 0.9.2 编的 `plugin.bin` 跑 `TestRealPlugin_*` | ✅ 4/4 通过（握手校验 `ProtocolVersion=1`，不是 SDK 版本） |
+| 模板已接线 | `cd tools/plugindev && go test ./...` | ✅ `TestProcTemplate_CoversAllCoreMethods` 含新 method |
+| 并发安全 | `go test ./sdk/ -race -count=5` | ✅ 零 DATA RACE（13 例压测） |
+
+### v1.2.x 的接口扩展（2026-09-12）
+
+1.2.0 把「记不记入记忆 / 要不要据此裁剪上下文」从**只有工具与通道能声明**，扩到**注入侧也能声明**：
+
+| 新增 | 方向 | 说明 |
+|---|---|---|
+| `InjectOptions{NoMemory, ContextPolicy, CleanerName}` | 新增类型 | 单次注入的行为声明 |
+| `ContextPolicyNone` / `ContextPolicyPrune` + `ValidContextPolicy` | 新增常量/函数 | 取值只有 `""` / `none` / `prune`；`prune` 必须显式声明 |
+| 六个 `*Opts` 变体（Text / InterruptText / InputSync / InputMedia / InputMediaSync / InterruptMedia） | 插件调用、内核实现 | 旧的三参数方法保留为**零值糖**，与 `InjectOptions{}` 逐键等价 |
+| `ChannelDef.ContextPolicy` + `ChannelDef` 的 JSON tag | 结构体字段 | 通道也可声明裁剪；补 tag 是因为通道定义要跨进程传给内核，而 `Cleaner` 是函数必须忽略——无 tag 时新增字段会被**静默丢掉** |
+
+签名层面零变更（六个方法全是新增），满足第 1、2 条。
+
+**但「接口纯追加」不等于「无需重编」**：1.2.0 同时把插件运行协议升到 2
+（fd3 布局改变，不支持滚动升级），`ProtocolVersion` 不匹配会在握手时被明确拒绝
+并提示用配套 plugindev 重编。两件事必须分开说，否则会被误读成「既然纯追加就还能用旧产物」。
+
+#### 这次扩展自己抓出来的两处漂移（都是本节第 3 条要防的那类）
+
+1. **模板接线守卫红了**：`TestProcTemplate_CoversAllCoreMethods` 要求模板出现内核提供的
+   每一个 method id，而注入标志位落地后模板不再发 `io.injectTextNoMem`（旧模板发它，
+   现在走 `io.injectText` + `NoMemory` 标志位）。内核保留该 id 是**刻意的向后兼容面**
+   （用那时模板编出的二进制仍在外面），不是漏接线——所以改的是判据：把它移入显式的
+   `deprecated` 表，并加**反向保护**（条目一旦重新出现在模板里就报错，避免这张表
+   退化成「永久豁免」的垃圾抽屉）。
+2. **mocksdk 缺一个方法**：拿公共 SDK `IOInjector` 的 14 个方法名与 mock 的方法集
+   **机械求差**，差集恰好是旧的三参数 `InjectInputSync`——通道类插件（qq / a2a）完成
+   「入站 → agent 处理 → 回复取回」闭环要调的那个。`git log -S` 证实它**从来就缺**，
+   不是本次引入；补齐后差集为空。（上次漂的是 `Triple.Predicate` vs `Relation`，同一类问题。）
+
+#### 验证（1.2.0，本机实测）
+
+| 检查 | 命令 | 结果 |
+|---|---|---|
+| 存量插件源码零改动 | 逐个 `cd example/<n> && go vet ./...` | ✅ 17/17 通过（`luademo` 是 Lua、无 `go.mod`，跳过） |
+| 模板已接线 | `cd tools/plugindev && go test ./...` | ✅ 全绿（修复前为红；反向保护另用「把 id 塞回模板」验证过会报错） |
+| 并发安全 | `go test -race -count=5 ./sdk/` | ✅ ok |
+| mocksdk 未漂移 | 方法集求差（14 个方法） | ✅ 差集为空 |
+
+### 为何媒体块走 JSON 而不是共享段二进制通道
+
+`SetToolBlocks` 的原设计是「二进制落 arena，Slice 描述符回传」。实际落地时改走 JSON：
+data URL 本身已是 base64 文本，包进二进制传输省不了空间，还要让这四个 method 跟其余
+51 个分道扬镳。共享段的价值在于**并发改写同一份状态**（StageContext 的 lost update），
+而媒体块是单向传递的不可变数据，没有这个问题。
+
+---
+
 ## 八、关联文档
 
 - `docs/zh/架构迁移评估.md` — 完整论证（§3.2 method id 平移、§3.3 数据面、§3.4 SDK 封装、§3.5 回调型资源、§3.8 能力对齐）

go.mod

@@ -18,6 +18,7 @@ require (
 	github.com/charmbracelet/bubbletea v1.3.10
 	github.com/charmbracelet/lipgloss v1.1.0
 	golang.org/x/sys v0.38.0
+	golang.org/x/text v0.3.8
 )
 
 require (
@@ -40,8 +41,6 @@ require (
 	github.com/muesli/termenv v0.16.0 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/xo/terminfo v0.0.0-20220910002029-abceb7e1c41e // indirect
-	golang.org/x/text v0.3.8 // indirect
 )
 
-
 replace gitcode.com/JianFeeeee/homeagent-sdk => ./third_party/homeagent-sdk

internal/agent/core/agent.go

@@ -14,8 +14,10 @@ import (
 	"gitcode.com/JianFeeeee/HomeAgent/internal/knowledge"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/memory"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/document"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/media"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/social"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/text"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/vector"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/plugin"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/tracker"
 	"gitcode.com/JianFeeeee/HomeAgent/pkg/types"
@@ -50,6 +52,11 @@ type Agent struct {
 	// 文本记忆（原始对话日志）
 	textMem *text.Memory
 
+	// 媒体存储（内容寻址）：对话里出现的图片/音频按 sha256 落盘去重。
+	// 它是记忆块的内容存储，不单独做生命周期管理：块的创建/迁移/删除
+	// 由记忆系统本身决定。为 nil 时全部媒体接线静默跳过。
+	mediaStore *media.Store
+
 	// 人格设定
 	personality *agentPkg.Personality
 
@@ -83,10 +90,17 @@ type Agent struct {
 	selfInputCh chan selfInputMsg
 
 	// 子任务异步执行
-	childMu      sync.Mutex
-	childNextID  int64
-	childResults map[string]string
-	childRunning map[string]bool // 运行中的子任务（child_result 查询时区分'运行中'与'不存在'）
+	childMu     sync.Mutex
+	childNextID int64
+	// childTasks 记录子任务状态：运行中 / 结果 / 是否已交付。
+	//
+	// 为什么保留结果而不是“读到即删”：完成通知会写进持久上下文
+	// （formatMergedTimeline 每轮都重新注入），模型之后还会再查。若读到即删，
+	// 第二次查询就得到“不存在或已过期”这个**永久失败信号**——模型据此认为
+	// 任务未完成，会无限重试/汇报（实测单轮 35 次工具调用、持续 514 秒）。
+	childTasks map[string]*childTaskState
+	// childSeq 给完成的任务排个序，用于有界淘汰。
+	childSeq int64
 
 	// 高优先级打断通道：interceptLoop 注入，process() 在工具循环轮次间非阻塞读取
 	interceptCh chan *agentIO.InputEvent
@@ -106,6 +120,13 @@ type Agent struct {
 	// 当前轮次的非文本媒体数据（图片/音频），供 describe_image 等工具访问
 	pendingMedia map[string]interface{}
 
+	// pendingMediaDigests 累积本轮已落进 CAS 的媒体 digest。
+	//
+	// 需要缓存而不是当场挂到事件上：媒体在 process() 执行期间被捕获，
+	// 而承载它的 ContextEvent 要等 process() 返回后才 Append——此刻还没有 owner_id。
+	// 与 pendingMedia 同受 a.mu 保护。
+	pendingMediaDigests []string
+
 	// 当前输入是否为工具提醒/中断（以 system 角色注入，避免被当成用户消息）
 	interruptInput bool
 
@@ -119,12 +140,19 @@ type Agent struct {
 
 	// 输入去重：防 webui/GUI 断线重连导致的消息重放
 	// key=source+"|"+content, value=上次接收时间；短窗口内同内容丢弃
-	lastInput  map[string]time.Time
+	lastInput   map[string]time.Time
 	lastInputMu sync.Mutex
 
 	// 词嵌入模型，用于实体语义相似度计算
 	embedder *memory.StaticEmbedder
 
+	// multimodalSpace 是统一多模态向量空间（可选）。实现可以是内嵌 ONNX，
+	// 也可以是外部 API 客户端；两者共享同一套 L0/L2/L3 向量缓存与检索基础设施。
+	multimodalSpace vector.MultimodalEmbedder
+
+	// fusionCfg 控制文本路与视觉路的跨模态融合权重，可按模型实测结果配置。
+	fusionCfg CrossModalFusionConfig
+
 	// 技能索引提供者：由 skillmgr 插件实现，向 system prompt 注入轻量技能索引
 	skillIndex SkillIndexProvider
 }
@@ -151,16 +179,19 @@ type AgentConfig struct {
 	Knowledge          *knowledge.Store
 	SocialStore        *social.SocialStore
 	TextMemory         *text.Memory
+	MediaStore         *media.Store
+	MultimodalSpace    vector.MultimodalEmbedder
+	FusionCfg          CrossModalFusionConfig // 跨模态融合权重；零值用默认
 	Personality        *agentPkg.Personality
 	PluginReg          *plugin.Registry
 	PluginDir          string
 	DistillInterval    time.Duration
-	ArchiveInterval    time.Duration // 冷文档归档间隔（L2→L3），0 则使用 DistillInterval
-	ReviewInterval     time.Duration // 关系复审间隔，0 则使用 DistillInterval
-	MergeInterval      time.Duration // 实体合并检测间隔，0 则使用 DistillInterval
-	MaxContextSize     int           // 活跃上下文最大条数，超出按相关性裁剪
-	ContextSavePath    string        // 上下文持久化路径，空则不持久化
-	EmbeddingModelPath string        // 预训练词嵌入模型路径（word2vec 文本格式），空则不使用
+	ArchiveInterval    time.Duration          // 冷文档归档间隔（L2→L3），0 则使用 DistillInterval
+	ReviewInterval     time.Duration          // 关系复审间隔，0 则使用 DistillInterval
+	MergeInterval      time.Duration          // 实体合并检测间隔，0 则使用 DistillInterval
+	MaxContextSize     int                    // 活跃上下文最大条数，超出按相关性裁剪
+	ContextSavePath    string                 // 上下文持久化路径，空则不持久化
+	EmbeddingModelPath string                 // 预训练词嵌入模型路径（word2vec 文本格式），空则不使用
 	Embedder           *memory.StaticEmbedder // 共享词嵌入实例；nil 时按 EmbeddingModelPath 自建
 	StageHost          *StageHost
 	EventBus           *events.Bus
@@ -194,8 +225,7 @@ func New(cfg AgentConfig) *Agent {
 		embedder = memory.NewStaticEmbedder(strings.Split(cfg.EmbeddingModelPath, ",")...)
 	}
 	if cfg.DocStore != nil {
-		cfg.DocStore.SetVectorizer(embedder)
-		cfg.DocStore.ReindexWithVectorizer(embedder)
+		// TF-IDF 内置为 fallback，无需外部注入
 	}
 	if cfg.Knowledge != nil {
 		cfg.Knowledge.SetVectorizer(embedder)
@@ -209,6 +239,16 @@ func New(cfg AgentConfig) *Agent {
 	if cfg.IO != nil {
 		rc.SetChannelDefLookup(cfg.IO.GetInputChannelDef)
 	}
+	// 注入稠密多模态向量空间（可选）：配置后文档检索、L0 相关性裁剪、
+	// 跨模态检索全部共享同一向量空间，取代稀疏 fastText 语义路。
+	// 未配置时退化到 TF-IDF/fastText 稀疏检索，保持既有行为。
+	if cfg.MultimodalSpace != nil && cfg.MultimodalSpace.Loaded() {
+		rc.SetDenseSpace(cfg.MultimodalSpace)
+		if cfg.DocStore != nil {
+			cfg.DocStore.SetDenseSpace(cfg.MultimodalSpace)
+			cfg.DocStore.BuildDenseIndex(cfg.MultimodalSpace)
+		}
+	}
 
 	return &Agent{
 		id:              cfg.ID,
@@ -227,6 +267,7 @@ func New(cfg AgentConfig) *Agent {
 		knowledge:       cfg.Knowledge,
 		social:          cfg.SocialStore,
 		textMem:         cfg.TextMemory,
+		mediaStore:      cfg.MediaStore,
 		personality:     cfg.Personality,
 		pluginReg:       cfg.PluginReg,
 		pluginDir:       cfg.PluginDir,
@@ -239,13 +280,14 @@ func New(cfg AgentConfig) *Agent {
 		skillIndex:      cfg.SkillIndexProvider,
 		eventBus:        cfg.EventBus,
 		selfInputCh:     make(chan selfInputMsg, 64),
-		childResults:    make(map[string]string),
-		childRunning:    make(map[string]bool),
+		childTasks:      make(map[string]*childTaskState),
 		interceptCh:     make(chan *agentIO.InputEvent, 64),
 		pluginHealth:    newPluginHealthTracker(),
 		thinkingEnabled: cfg.ThinkingEnabled,
 		inputCfg:        cfg.InputProcessing,
 		embedder:        embedder,
+		multimodalSpace: cfg.MultimodalSpace,
+		fusionCfg:       cfg.FusionCfg,
 		noMergeMarkers:  make(map[string]int),
 		lastInput:       make(map[string]time.Time),
 	}
@@ -261,6 +303,8 @@ func (a *Agent) Start() {
 	go a.archiveLoop()
 	go a.mergeLoop()
 	go a.reviewLoop()
+	a.reembedStaleMedia()
+	a.migrateLegacyGraphMedia()
 	log.Printf("[agent] %s started, waiting for IO interrupts", a.id)
 }
 

internal/agent/core/agent_tools_test.go

@@ -15,14 +15,14 @@ type mockOutputDevice struct {
 	toolFn func(string, map[string]interface{}) (interface{}, error)
 }
 
-func (d *mockOutputDevice) Name() string                          { return d.name }
-func (d *mockOutputDevice) Type() agentIO.DeviceType              { return agentIO.DeviceOutput }
-func (d *mockOutputDevice) Description() string                   { return "mock " + d.name }
-func (d *mockOutputDevice) Tools() []agentIO.ToolDef              { return d.tools }
-func (d *mockOutputDevice) Start() error                          { return nil }
-func (d *mockOutputDevice) Stop() error                           { return nil }
+func (d *mockOutputDevice) Name() string                                 { return d.name }
+func (d *mockOutputDevice) Type() agentIO.DeviceType                     { return agentIO.DeviceOutput }
+func (d *mockOutputDevice) Description() string                          { return "mock " + d.name }
+func (d *mockOutputDevice) Tools() []agentIO.ToolDef                     { return d.tools }
+func (d *mockOutputDevice) Start() error                                 { return nil }
+func (d *mockOutputDevice) Stop() error                                  { return nil }
 func (d *mockOutputDevice) OutputCapabilities() agentIO.OutputCapability { return d.caps }
-func (d *mockOutputDevice) ChannelDef() agentIO.ChannelDef { return agentIO.ChannelDef{} }
+func (d *mockOutputDevice) ChannelDef() agentIO.ChannelDef               { return agentIO.ChannelDef{} }
 func (d *mockOutputDevice) Execute(tool string, args map[string]interface{}) (interface{}, error) {
 	if d.toolFn != nil {
 		return d.toolFn(tool, args)
@@ -67,8 +67,8 @@ func TestExecuteOutputSendTool(t *testing.T) {
 		"type":    "text",
 	}}
 	result := a.executeOutputSendTool(tc)
-	if !strings.Contains(result, "screen") {
-		t.Errorf("unexpected result: %s", result)
+	if result != "ok" {
+		t.Errorf("expected ok, got: %s", result)
 	}
 }
 

internal/agent/core/context.go

@@ -22,13 +22,23 @@ type ToolResultItem struct {
 }
 
 type ContextEvent struct {
-	Timestamp   time.Time         `json:"timestamp"`
-	Source      string            `json:"source"`
-	Input       string            `json:"input"`
-	Response    string            `json:"response,omitempty"`
-	ToolsUsed   []string          `json:"tools_used,omitempty"`
-	ToolResults []ToolResultItem  `json:"tool_results,omitempty"`
-	Vector      vector.Vector     `json:"-"`
+	// ID 是事件的稳定标识。惰性生成：只有真的要挂媒体块时才赋值。
+	//
+	// 全量生成会让每条事件都多一个字段进 context.json，而绝大多数对话没有媒体。
+	// omitempty 保证存量 context.json 读回来时该字段为空，不影响任何既有行为。
+	ID          string           `json:"id,omitempty"`
+	Timestamp   time.Time        `json:"timestamp"`
+	Source      string           `json:"source"`
+	Input       string           `json:"input"`
+	Response    string           `json:"response,omitempty"`
+	ToolsUsed   []string         `json:"tools_used,omitempty"`
+	ToolResults []ToolResultItem `json:"tool_results,omitempty"`
+	// --- 原生多模态记忆 ---
+	// 一等记忆块：块本身随事件在层间迁移，身份不变，不建引用计数。
+	Blocks   []memory.MemoryBlock `json:"blocks,omitempty"` // 一等记忆块（text/image/video/audio）
+	Vector   vector.Vector        `json:"-"`                // 稀疏词向量（TF-IDF/fastText 空间）
+	DenseVec []float64            `json:"-"`                // 稠密多模态向量（与媒体/文档共享空间）
+	DenseFP  string               `json:"-"`                // DenseVec 所属统一空间指纹（缓存字段，不持久化）
 }
 
 const contextFlushInterval = 5 * time.Second
@@ -37,6 +47,7 @@ type RelevanceContext struct {
 	mu               sync.Mutex
 	events           []*ContextEvent
 	embedder         *memory.StaticEmbedder
+	denseSpace       vector.MultimodalEmbedder
 	savePath         string
 	saveTimer        *time.Timer
 	dirty            bool
@@ -55,6 +66,14 @@ func NewRelevanceContext(savePath string, embedder *memory.StaticEmbedder) *Rele
 	return rc
 }
 
+// SetDenseSpace 注入稠密多模态向量空间。配置后 L0 相关性裁剪可用稠密向量
+// 余弦（与媒体检索、文档检索共享同一空间），未配置时退化到稀疏词向量。
+func (c *RelevanceContext) SetDenseSpace(ds vector.MultimodalEmbedder) {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	c.denseSpace = ds
+}
+
 func (c *RelevanceContext) SetToolDefLookup(fn func(name string) *sdk.ToolDef) {
 	c.mu.Lock()
 	defer c.mu.Unlock()
@@ -77,7 +96,7 @@ func (c *RelevanceContext) load() {
 		return
 	}
 	for _, evt := range events {
-		evt.Vector = c.computeVector(evt)
+		c.computeVector(evt)
 	}
 	c.events = events
 }
@@ -176,12 +195,32 @@ func (c *RelevanceContext) channelCleanerForDoc() document.ChannelCleaner {
 	}
 }
 
-func (c *RelevanceContext) computeVector(evt *ContextEvent) vector.Vector {
+func (c *RelevanceContext) computeVector(evt *ContextEvent) {
 	text := textForVector(evt, c.toolDefLookup, c.channelDefLookup)
-	if text == "" {
-		return nil
+	// 稀疏向量始终计算（TF-IDF/fastText，退化时仍可用）
+	if text != "" {
+		evt.Vector = c.embedder.Vectorize(text)
+	}
+	// 稠密向量：文本向量 ⊕ 本事件持有的一等记忆块媒体向量（同一统一空间）。
+	// 只有媒体的输入（无文本）也要有可比较的坐标，因此不再按 text=="" 提前返回。
+	if c.denseSpace != nil && c.denseSpace.Loaded() {
+		fp := c.denseSpace.Fingerprint()
+		var parts [][]float64
+		if text != "" {
+			if dv, err := c.denseSpace.VectorizeDense(text); err == nil && len(dv) > 0 {
+				parts = append(parts, dv)
+			}
+		}
+		for _, b := range evt.Blocks {
+			// 只融合同指纹的块向量：另一套坐标系的向量混进来会算出
+			// 两边都不像的方向。
+			if len(b.Vector) > 0 && b.Fingerprint == fp {
+				parts = append(parts, b.Vector)
+			}
+		}
+		evt.DenseVec = vector.FuseVectors(parts...)
+		evt.DenseFP = fp
 	}
-	return c.embedder.Vectorize(text)
 }
 
 func (c *RelevanceContext) Save() error {
@@ -202,7 +241,7 @@ func (c *RelevanceContext) Append(evt ContextEvent) {
 	c.mu.Lock()
 	defer c.mu.Unlock()
 
-	evt.Vector = c.computeVector(&evt)
+	c.computeVector(&evt)
 	c.events = append(c.events, &evt)
 
 	c.save()
@@ -212,7 +251,7 @@ func (c *RelevanceContext) InsertByTimestamp(evt ContextEvent) {
 	c.mu.Lock()
 	defer c.mu.Unlock()
 
-	evt.Vector = c.computeVector(&evt)
+	c.computeVector(&evt)
 
 	idx := sort.Search(len(c.events), func(i int) bool {
 		return c.events[i].Timestamp.After(evt.Timestamp)
@@ -256,6 +295,15 @@ func (c *RelevanceContext) flush() {
 	c.dirty = false
 }
 
+// scoredEvent 是 Prune 里按相关度排序的事件。
+//
+// 提为包级类型：Prune 需要把待归档列表传给后续处理。
+type scoredEvent struct {
+	event *ContextEvent
+	score float64
+	idx   int
+}
+
 func (c *RelevanceContext) Prune(currentInput string, topK int, docStore *document.Store) int {
 	c.mu.Lock()
 	defer c.mu.Unlock()
@@ -275,17 +323,30 @@ func (c *RelevanceContext) Prune(currentInput string, topK int, docStore *docume
 		return 0
 	}
 
+	// 优先使用稠密向量余弦（与媒体/文档共享空间）；退化到稀疏词向量。
+	var queryDense []float64
+	useDense := false
+	queryFP := ""
+	if c.denseSpace != nil && c.denseSpace.Loaded() {
+		if dv, err := c.denseSpace.VectorizeDense(currentInput); err == nil {
+			queryDense = dv
+			queryFP = c.denseSpace.Fingerprint()
+			useDense = true
+		}
+	}
 	queryVec := c.embedder.VectorizeClean(currentInput)
 
-	type scored struct {
-		event *ContextEvent
-		score float64
-		idx   int
-	}
-	scoredEvents := make([]scored, len(candidates))
+	scoredEvents := make([]scoredEvent, len(candidates))
 	for i, evt := range candidates {
-		score := vector.CosineSimilarity(queryVec, evt.Vector)
-		scoredEvents[i] = scored{event: evt, score: score, idx: i}
+		var score float64
+		// 只在同一统一空间内比稠密余弦：换了模型/维度后旧事件的向量
+		// 属于另一个坐标系，拿来比会得到无意义的分数。
+		if useDense && evt.DenseFP == queryFP && len(evt.DenseVec) == len(queryDense) {
+			score = vector.DenseCosine(queryDense, evt.DenseVec)
+		} else {
+			score = vector.CosineSimilarity(queryVec, evt.Vector)
+		}
+		scoredEvents[i] = scoredEvent{event: evt, score: score, idx: i}
 	}
 
 	sort.Slice(scoredEvents, func(i, j int) bool {
@@ -322,11 +383,20 @@ func (c *RelevanceContext) Prune(currentInput string, topK int, docStore *docume
 				Content:     s.event.Input,
 				Response:    s.event.Response,
 				ToolResults: convertToolResults(s.event.ToolResults),
+				Blocks:      append([]memory.MemoryBlock(nil), s.event.Blocks...),
 			}
 		}
 		doc, err := docStore.ContextToDoc("context_archived", entries, c.embedder, nil, c.toolOutputClean, c.channelCleanerForDoc())
 		if err == nil && doc != nil {
 			archived = len(entries)
+			// 一等记忆块的迁移：块随归档事件离开 L0、进入 L2。
+			// 迁移的是块本身（ID 不变、只换持有层），不是复制也不是保活引用；
+			// 因此归档后清空源事件的块，确保同一块不同时留在两层。
+			for _, s := range archive {
+				if s.event != nil {
+					s.event.Blocks = nil
+				}
+			}
 		}
 	}
 
@@ -369,6 +439,18 @@ func (c *RelevanceContext) Recent(n int) []ContextEvent {
 	return result
 }
 
+// Blocks 返回当前上下文持有的一等记忆块（供跨层存活判定）。
+// 迁移后源事件已被清空，因此这里只会拿到真正属于 L0 的块。
+func (c *RelevanceContext) Blocks() []memory.MemoryBlock {
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	var out []memory.MemoryBlock
+	for _, e := range c.events {
+		out = append(out, e.Blocks...)
+	}
+	return out
+}
+
 func (c *RelevanceContext) Len() int {
 	c.mu.Lock()
 	defer c.mu.Unlock()
@@ -385,5 +467,3 @@ func convertToolResults(items []ToolResultItem) []document.ToolResultItem {
 	}
 	return result
 }
-
-

internal/agent/core/crossmodal.go

@@ -0,0 +1,268 @@
+package core
+
+import (
+	"fmt"
+	"log"
+	"sort"
+	"strings"
+
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/document"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/media"
+)
+
+// CrossModalHit 是跨模态检索融合后的一条候选。
+//
+// 统一的检索单元是记忆块而非 CAS 全库：媒体在 L0/L2/L3 都由层容器持有，
+// 只有仍被某层记忆块持有的媒体才可召回。Doc 是 L2 文档；Media 是该块携带的
+// 原生媒体坐标。两路分数尺度不同，融合前各自归一化，见 fuseCrossModal。
+type CrossModalHit struct {
+	Doc        *document.Doc // 文本路命中的文档；视觉路命中时为 nil
+	Media      *media.Item   // 视觉路命中的媒体；文本路命中时也可能带关联媒体
+	MediaScore float64       // 视觉路原始 cosine（无则 0）
+	DocScore   float64       // 文本路原始 cosine（无则 0）
+	Fused      float64       // 归一化加权融合分，供最终排序
+	// 该媒体同时被两路命中（文本路经文档关联、视觉路直接命中）时，
+	// DoubleHit=true —— 双信号确认，应排在只被一路命中的候选之前。
+	DoubleHit bool
+}
+
+// CrossModalFusionConfig 控制文本路与视觉路的融合行为。
+// 默认各路权重 0.5，双命中加权 0.15；不同模型/场景可按实测调整。
+type CrossModalFusionConfig struct {
+	WeightText     float64 // 文本路融合权重（默认 0.5）
+	WeightVisual   float64 // 视觉路融合权重（默认 0.5）
+	DoubleHitBonus float64 // 双命中额外加分（默认 0.15）
+	MinMaxEps      float64 // min-max 归一化除零保护（默认 1e-12）
+}
+
+var defaultFusionConfig = CrossModalFusionConfig{
+	WeightText:     0.5,
+	WeightVisual:   0.5,
+	DoubleHitBonus: 0.15,
+	MinMaxEps:      1e-12,
+}
+
+func (c CrossModalFusionConfig) textWeight() float64 {
+	if c.WeightText <= 0 {
+		return defaultFusionConfig.WeightText
+	}
+	return c.WeightText
+}
+func (c CrossModalFusionConfig) visualWeight() float64 {
+	if c.WeightVisual <= 0 {
+		return defaultFusionConfig.WeightVisual
+	}
+	return c.WeightVisual
+}
+func (c CrossModalFusionConfig) doubleHitBonus() float64 {
+	return c.DoubleHitBonus
+}
+func (c CrossModalFusionConfig) minMaxEps() float64 {
+	if c.MinMaxEps <= 0 {
+		return defaultFusionConfig.MinMaxEps
+	}
+	return c.MinMaxEps
+}
+
+// retrieveCrossModal 是跨模态并行检索的统一入口。
+//
+// 策略（两路并行，召回真正最相似的）：
+//  1. 文本路：query 整段文本编码后查文档层（Doc.DenseVec 已融合其块的媒体向量），
+//     命中文档若持有媒体块，直接带上该块。
+//  2. 视觉路：query 经多模态模型文本编码 → 与媒体块向量比余弦
+//     （QueryMediaScored），覆盖文本向量没写到的视觉内容。
+//  3. 融合：两条路候选各自 min-max 归一化到 [0,1]，加权求和后降序，取 topK。
+//     同一媒体被两路同时命中视为双信号确认，额外加权。
+//
+// 多模态空间未配置时视觉路为空，退化为纯文本路（等价旧 docStore.Query）。
+func (a *Agent) retrieveCrossModal(query string, topK int, cfg CrossModalFusionConfig) []CrossModalHit {
+	if topK <= 0 {
+		topK = 5
+	}
+	// 融合前各取 2× 余量，保证融合排序后 topK 仍有足够候选。
+	per := topK * 2
+	if per < 8 {
+		per = 8
+	}
+
+	// ---- 文本路 ----
+	var textHits []CrossModalHit
+	if a.docStore != nil {
+		for _, dh := range a.docStore.QueryScored(query, per) {
+			hit := CrossModalHit{Doc: dh.Doc, DocScore: dh.Score}
+			// 命中文档若持有一等记忆块，把首个媒体块一并带上。
+			if a.mediaStore != nil && len(dh.Doc.Blocks) > 0 {
+				if it, err := a.mediaStore.Stat(dh.Doc.Blocks[0].PayloadDigest); err == nil {
+					hit.Media = it
+				}
+			}
+			textHits = append(textHits, hit)
+		}
+	}
+
+	// ---- 视觉路（多模态文本编码 → 当前记忆层持有的媒体块）----
+	var visualHits []CrossModalHit
+	if a.multimodalSpace != nil && a.multimodalSpace.Loaded() && a.mediaStore != nil {
+		qv, err := a.multimodalSpace.VectorizeDense(query)
+		if err != nil {
+			log.Printf("[crossmodal] 多模态文本编码失败: %v", err)
+		} else if mh, err := a.mediaStore.QueryMediaScored(qv, a.multimodalSpace.Fingerprint(), per); err != nil {
+			log.Printf("[crossmodal] 媒体记忆检索失败: %v", err)
+		} else {
+			// 只有仍被某层记忆块持有的媒体才可召回：CAS 是全库字节存储，
+			// 直接拿它的检索结果会把已无处可归的内容也从记忆里翻出来。
+			held := a.heldMediaDigests()
+			for _, h := range mh {
+				if h.Item == nil || !held[h.Item.Digest] {
+					continue
+				}
+				visualHits = append(visualHits, CrossModalHit{
+					Media: h.Item, MediaScore: h.Score,
+				})
+			}
+		}
+	}
+
+	return fuseCrossModal(textHits, visualHits, topK, cfg)
+}
+
+// fuseCrossModal 把文本路与视觉路候选按各自归一化分融合排序。
+//
+// 归一化模板：两路分数尺度不可直接相加，先各自在路内 min-max 到 [0,1]：
+//
+//	norm(x) = (x - min) / (max - min)，max==min 时置 1
+//
+// 再加权求和：fused = wText·normText + wVisual·normVisual。同一媒体两路都命中
+// （经文档关联 + 视觉直接）时 DoubleHit，在加权分上再加双信号确认分。
+// 权重通过 CrossModalFusionConfig 按场景配置，不同模型/版本可按实测调整。
+func fuseCrossModal(textHits, visualHits []CrossModalHit, topK int, cfg CrossModalFusionConfig) []CrossModalHit {
+	norm := func(hits []CrossModalHit, pick func(CrossModalHit) float64) []float64 {
+		out := make([]float64, len(hits))
+		if len(hits) == 0 {
+			return out
+		}
+		maxV, minV := pick(hits[0]), pick(hits[0])
+		for _, h := range hits[1:] {
+			v := pick(h)
+			if v > maxV {
+				maxV = v
+			}
+			if v < minV {
+				minV = v
+			}
+		}
+		for i, h := range hits {
+			v := pick(h)
+			if maxV-minV < cfg.minMaxEps() {
+				out[i] = 1
+				continue
+			}
+			out[i] = (v - minV) / (maxV - minV)
+		}
+		return out
+	}
+	textN := norm(textHits, func(h CrossModalHit) float64 { return h.DocScore })
+	visualN := norm(visualHits, func(h CrossModalHit) float64 { return h.MediaScore })
+
+	byKey := make(map[string]*CrossModalHit)
+	var keys []string
+	key := func(h CrossModalHit) string {
+		if h.Doc != nil {
+			return "doc:" + h.Doc.ID
+		}
+		if h.Media != nil {
+			return "media:" + h.Media.Digest
+		}
+		return ""
+	}
+
+	// 先并入视觉路（视觉媒体是独立实体）
+	for i, h := range visualHits {
+		k := key(h)
+		if k == "" {
+			continue
+		}
+		clone := h
+		clone.Fused = cfg.visualWeight() * visualN[i]
+		byKey[k] = &clone
+		keys = append(keys, k)
+	}
+	// 再并入文本路：命中的文档是独立实体；带媒体的文档若其媒体 digest
+	// 已在视觉路（双命中），合并到同一候选并标记 DoubleHit。
+	for i, h := range textHits {
+		if h.Doc == nil {
+			continue
+		}
+		if h.Media != nil {
+			if ex, ok := byKey["media:"+h.Media.Digest]; ok {
+				ex.DoubleHit = true
+				ex.Doc = h.Doc
+				ex.Fused += cfg.textWeight()*textN[i] + cfg.doubleHitBonus()
+				continue
+			}
+		}
+		k := "doc:" + h.Doc.ID
+		if ex, ok := byKey[k]; ok {
+			ex.Doc = h.Doc
+			ex.DoubleHit = false
+			ex.Fused += cfg.textWeight() * textN[i]
+			continue
+		}
+		clone := h
+		clone.Fused = cfg.textWeight() * textN[i]
+		byKey[k] = &clone
+		keys = append(keys, k)
+	}
+
+	var merged []CrossModalHit
+	for _, k := range keys {
+		if c := byKey[k]; c != nil {
+			merged = append(merged, *c)
+		}
+	}
+	sort.SliceStable(merged, func(i, j int) bool {
+		if merged[i].DoubleHit != merged[j].DoubleHit {
+			return merged[i].DoubleHit
+		}
+		return merged[i].Fused > merged[j].Fused
+	})
+	if len(merged) > topK {
+		merged = merged[:topK]
+	}
+	return merged
+}
+
+// crossModalMarkdown 把融合候选渲染成注入上下文的文本。
+// 文档行给出摘要；媒体行只给 MIME + 短 digest（不再有生成的描述）。
+func (a *Agent) crossModalMarkdown(hits []CrossModalHit) string {
+	if len(hits) == 0 {
+		return ""
+	}
+	var lines []string
+	for i, h := range hits {
+		marker := ""
+		switch {
+		case h.DoubleHit:
+			marker = "（图文双命中）"
+		case h.Doc != nil:
+			marker = "（文本命中）"
+		case h.Media != nil:
+			marker = "（视觉命中）"
+		}
+		parts := []string{fmt.Sprintf("[%d]", i+1)}
+		if h.Doc != nil {
+			parts = append(parts, h.Doc.Summary)
+			if h.Doc.Source != "" {
+				parts = append(parts, fmt.Sprintf("(来源:%s)", h.Doc.Source))
+			}
+		}
+		if h.Media != nil {
+			if line := mediaLabel(h.Media); line != "" {
+				parts = append(parts, line)
+			}
+		}
+		parts = append(parts, fmt.Sprintf("相关度:%.2f%s", h.Fused, marker))
+		lines = append(lines, strings.Join(parts, " "))
+	}
+	return "【跨模态相关记忆】\n" + strings.Join(lines, "\n")
+}

internal/agent/core/distill.go

@@ -180,15 +180,40 @@ func (a *Agent) archiveColdDocs() {
 		coldDocs := a.docStore.FindColdDocs(72*time.Hour, 2)
 		for _, doc := range coldDocs {
 			triples := docToTriples(doc, a.embedder)
-			if len(triples) > 0 {
-				ec, rc, err := a.memory.Commit(triples, string(a.id)+"_doc_archival", 0)
-				if err != nil {
-					log.Printf("[agent] doc→graph archival error: %v", err)
+			if len(triples) == 0 {
+				continue
+			}
+			ec, rc, blocks, err := a.commitTriplesWithMedia(triples, string(a.id)+"_doc_archival", 0, doc.Blocks)
+			if err != nil {
+				log.Printf("[agent] doc→graph archival error: %v", err)
+				continue
+			}
+
+			// 归档的实质是「信息从 L2 搬到 L3」。一条实体、一条关系都没写进
+			// 图库时，信息并没有搬过去，此时删文档等于直接丢数据。
+			//
+			// 这不是理论情形：Commit 会静默跳过实体名不合法的三元组
+			//（validEntityName 要求 2–50 字符），而 LLM 生成的长描述几乎
+			// 提不出合规实体名——实测 456 字图片描述得到 0 entities 0
+			// relations，随后文档被删、媒体引用被释放、blob 被 GC 清掉，
+			// 图片与描述彻底消失。保留文档，下一轮再试。
+			if ec == 0 && rc == 0 {
+				log.Printf("[agent] doc→graph: %s 未写入任何实体/关系，保留文档待下轮重试"+
+					"（三元组 %d 条全被实体名校验拒绝）", doc.ID, len(triples))
+				continue
+			}
+			log.Printf("[agent] doc→graph: %s → %d entities, %d relations, %d blocks", doc.ID, ec, rc, blocks)
+
+			// 文档持有的一等块写入 L3，并以 document --contains--> block 边关联；
+			// 块 ID 原样保留（迁移而非重建）。块迁走后删除文档即完成迁移。
+			if len(doc.Blocks) > 0 {
+				if bound := a.linkBlocksToDocument(doc.ID, doc.Blocks); bound != len(doc.Blocks) {
+					log.Printf("[agent] doc→graph: %s 块迁移不完整 (%d/%d)，保留文档待下轮重试",
+						doc.ID, bound, len(doc.Blocks))
 					continue
 				}
-				log.Printf("[agent] doc→graph: %s → %d entities, %d relations", doc.ID, ec, rc)
-				a.docStore.Remove(doc.ID)
 			}
+			a.docStore.Remove(doc.ID)
 		}
 	}
 }
@@ -412,6 +437,10 @@ func docToTriples(doc *document.Doc, embedder nlp.Vectorizer) []memory.Triple {
 		})
 	}
 
+	// 媒体不再参与三元组：它作为一等块由 linkBlocksToDocument
+	// 写入 L3 并以 document --contains--> block 边关联，
+	// 不经过文本描述与 NLP 提取器。
+
 	// NLP 通用提取
 	e := nlp.NewExtractor(nil)
 	if embedder != nil {

internal/agent/core/eventloop.go

@@ -10,6 +10,7 @@ import (
 	agentIO "gitcode.com/JianFeeeee/HomeAgent/internal/agent/io"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/events"
 	sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk"
+	pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
 )
 
 func (a *Agent) eventLoop() {
@@ -125,30 +126,18 @@ func (a *Agent) handleSelfInput(msg selfInputMsg) {
 	if msg.channel == "" {
 		msg.channel = channelConsolidation // 兼容空值：默认走整理路径
 	}
-	a.processTextInput(&agentIO.InputEvent{
+	a.processInput(&agentIO.InputEvent{
 		Source:        "system",
 		Type:          "text",
 		Payload:       map[string]interface{}{"content": msg.text},
 		OutputChannel: msg.channel,
-	}, msg.text)
+	})
 }
 
 func (a *Agent) handleInput(evt *agentIO.InputEvent) {
 	switch evt.Type {
-	case "text":
-		input, _ := evt.Payload["content"].(string)
-		if input == "" {
-			return
-		}
-		// 去重：webui/GUI 断线重连会重放未确认消息，短窗口内同来源同内容丢弃，避免轰炸
-		if a.isDuplicateInput(evt.Source, input) {
-			log.Printf("[agent] dropped duplicate input from %s: %s", evt.Source, truncateStr(input, 60))
-			return
-		}
-		a.processTextInput(evt, input)
-
-	case "image", "audio":
-		a.processMediaInput(evt)
+	case "text", "image", "audio":
+		a.processInput(evt)
 
 	case "event":
 		log.Printf("[agent] event from %s: %v", evt.Source, evt.Payload)
@@ -162,74 +151,97 @@ func (a *Agent) handleInput(evt *agentIO.InputEvent) {
 	}
 }
 
-func (a *Agent) processMediaInput(evt *agentIO.InputEvent) {
-	start := time.Now()
-	a.pendingMedia = evt.Payload
-	defer func() { a.pendingMedia = nil }()
+// inputPayload 是一次输入在「模态」这个维度上的全部内容。
+//
+// 拆出这个结构，是为了让 processInput 只有一条主干：模态不再决定走哪个函数，
+// 只决定这里的字段填不填。此前 text 与 image/audio 各有一个 process 函数，
+// 媒体那条缺了去重、no_memory、通道 Cleaner、中断语义、EventRawInput 五项——
+// 不是因为媒体不需要，而是复制粘贴之后文本那条继续演进、媒体那条没跟上。
+type inputPayload struct {
+	// text 是进 LLM 与记忆的文本。纯媒体输入时它是 mediaToBlocks 给的 alt 文案。
+	text string
+	// blocks 非空表示本轮带多模态内容，随当前轮的 message 一起发给模型。
+	blocks []agentAPI.ContentBlock
+	// mediaType 供插件在 stage 里判断本轮媒体的模态。
+	mediaType string
+	// captureTool 是媒体落进 CAS 时记录的来源标签。
+	captureTool string
+}
 
-	a.currentOutputChannel = evt.OutputChannel
-	if a.currentOutputChannel == "" {
-		a.currentOutputChannel = evt.Source
+// resolveInput 把 InputEvent 归一成 inputPayload。
+//
+// 三种来源在这里合流：
+//  1. evt.Type 是 image/audio —— 用户直接发的媒体，payload 里是 data/url；
+//  2. evt.Type 是 text 且 payload 带 media_blocks —— 插件经 IOInjector 的
+//     InjectInputMedia / InjectInputMediaSync / InjectInterruptMedia 注入的
+//     媒体，块已经是成品；
+//  3. 纯文本。
+//
+// 第 2 种此前无处可去：注入方把块放进 payload，而文本路径不看这个键，
+// 于是插件注入的媒体到 payload 就断了，且不报错。
+func (a *Agent) resolveInput(evt *agentIO.InputEvent) (inputPayload, bool) {
+	switch evt.Type {
+	case "image", "audio":
+		blocks, alt := a.mediaToBlocks(evt.Payload, evt.Type, evt.Source)
+		return inputPayload{
+			text:        alt,
+			blocks:      blocks,
+			mediaType:   evt.Type,
+			captureTool: "input_" + evt.Type,
+		}, true
 	}
 
-	blocks, fallback := a.mediaToBlocks(evt.Payload, evt.Type, evt.Source)
-
-	stageCtx := a.stageCtxFromInput(fallback, evt.Source, "")
-	stageCtx.Extra = map[string]interface{}{
-		"media_blocks":   blocks,
-		"media_type":     evt.Type,
-		"input_source":   evt.Source,
-		"output_channel": evt.OutputChannel,
+	text, _ := evt.Payload["content"].(string)
+	blocks, mediaType := injectedBlocks(evt.Payload)
+	// 文本与媒体都空才算无效输入：只带图不带字是合法的（插件注入常这样）。
+	if text == "" && len(blocks) == 0 {
+		return inputPayload{}, false
 	}
-	a.injectSourceContext(stageCtx, evt)
+	return inputPayload{
+		text:        text,
+		blocks:      blocks,
+		mediaType:   mediaType,
+		captureTool: "inject_" + evt.Source,
+	}, true
+}
 
-	if a.runStage(sdk.StageOnInput, stageCtx) {
-		a.emitResponse(evt, *stageCtx.Response)
-		return
+// injectedBlocks 取出 payload 里插件注入的多模态块。
+//
+// 两种静态类型都要认：内核内部注入直接给 []agentAPI.ContentBlock，
+// 而经公共 SDK 的 IOInjector 过来的是 []pubsdk.ContentBlock。两者字段完全一致，
+// 但 Go 不会自动转换，只认一种的后果是另一种被静默丢弃。
+func injectedBlocks(payload map[string]interface{}) ([]agentAPI.ContentBlock, string) {
+	var blocks []agentAPI.ContentBlock
+	switch v := payload["media_blocks"].(type) {
+	case []agentAPI.ContentBlock:
+		blocks = v
+	case []pubsdk.ContentBlock:
+		blocks = make([]agentAPI.ContentBlock, 0, len(v))
+		for _, b := range v {
+			nb := agentAPI.ContentBlock{Type: b.Type, Text: b.Text}
+			if b.ImageURL != nil {
+				nb.ImageURL = &agentAPI.ImageURL{URL: b.ImageURL.URL, Detail: b.ImageURL.Detail}
+			}
+			if b.AudioURL != nil {
+				nb.AudioURL = &agentAPI.AudioURL{URL: b.AudioURL.URL}
+			}
+			blocks = append(blocks, nb)
+		}
 	}
-
-	a.publishEvent(events.EventRawInput, map[string]interface{}{
-		"content": evt.Payload,
-		"source":  evt.Source,
-	})
-
-	archived := a.context.Prune(fallback, a.maxContextSize-1, a.docStore)
-	if archived > 0 {
-		log.Printf("[agent] pruned %d low-relevance events to document memory", archived)
+	if len(blocks) == 0 {
+		return nil, ""
 	}
-
-	a.context.Append(ContextEvent{
-		Timestamp: start,
-		Source:    evt.Source,
-		Input:     fallback,
-	})
-
-	response, toolsUsed, toolResults, err := a.process(fallback, stageCtx)
-	if err != nil {
-		log.Printf("[agent] process media error: %v", err)
-		resp := fmt.Sprintf("处理错误: %v", err)
-		a.emitResponse(evt, resp)
-		a.context.Append(ContextEvent{Timestamp: time.Now(), Source: "agent", Input: fallback, Response: resp})
-		return
-	}
-
-	elapsed := time.Since(start)
-	log.Printf("[agent] %s from %s → response (%dms, tools=%v)", evt.Type, evt.Source, elapsed.Milliseconds(), toolsUsed)
-
-	a.context.Append(ContextEvent{
-		Timestamp:   time.Now(),
-		Source:      "agent",
-		Input:       fallback,
-		Response:    response,
-		ToolsUsed:   toolsUsed,
-		ToolResults: toolResults,
-	})
-
-	a.emitResponse(evt, response)
-
-	if !stageCtx.NoMemory {
-		a.emitMemoryCandidate(evt.Source, fallback, response, toolResults, toolsUsed)
+	// 模态由块自身判定，注入方不必额外声明。图优先：一次注入里图片是主体。
+	mediaType := ""
+	for _, b := range blocks {
+		if b.ImageURL != nil {
+			return blocks, "image"
+		}
+		if b.AudioURL != nil {
+			mediaType = "audio"
+		}
 	}
+	return blocks, mediaType
 }
 
 func (a *Agent) mediaToBlocks(payload map[string]interface{}, mediaType string, source string) ([]agentAPI.ContentBlock, string) {
@@ -271,12 +283,12 @@ func (a *Agent) mediaToBlocks(payload map[string]interface{}, mediaType string,
 		}
 		if mediaType == "image" {
 			blocks = append(blocks, agentAPI.ContentBlock{
-				Type: "image_url",
+				Type:     "image_url",
 				ImageURL: &agentAPI.ImageURL{URL: imgURL, Detail: "auto"},
 			})
 		} else if mediaType == "audio" {
 			blocks = append(blocks, agentAPI.ContentBlock{
-				Type: "audio_url",
+				Type:     "audio_url",
 				AudioURL: &agentAPI.AudioURL{URL: imgURL},
 			})
 		}
@@ -285,19 +297,51 @@ func (a *Agent) mediaToBlocks(payload map[string]interface{}, mediaType string,
 	return blocks, alt
 }
 
-func (a *Agent) processTextInput(evt *agentIO.InputEvent, input string) {
+// processInput 是全部模态输入的唯一主干。
+//
+// 文本、用户上传的图/音频、插件注入的多模态块走同一条路径，因此去重、
+// no_memory、通道 Cleaner、中断语义、EventRawInput、媒体入 CAS、媒体记忆绑定
+// 对所有模态一致——不会再出现「文本路径加了功能、媒体路径没跟上」。
+func (a *Agent) processInput(evt *agentIO.InputEvent) {
 	start := time.Now()
 
+	in, ok := a.resolveInput(evt)
+	if !ok {
+		return
+	}
+
+	// 去重按文本做：webui/GUI 断线重连会重放未确认消息。
+	// 带媒体时跳过——媒体输入的 alt 文案（"[从 qq 收到了 image]"）对不同图片
+	// 是同一句，拿它去重会把连发的两张图误判成重复。
+	if len(in.blocks) == 0 && a.isDuplicateInput(evt.Source, in.text) {
+		log.Printf("[agent] dropped duplicate input from %s: %s", evt.Source, truncateStr(in.text, 60))
+		return
+	}
+
 	a.currentOutputChannel = evt.OutputChannel
 	if a.currentOutputChannel == "" {
 		a.currentOutputChannel = evt.Source
 	}
 
 	if evt.OutputChannel == "_consolidation_" {
-		a.processConsolidation(evt, input)
+		a.processConsolidation(evt, in.text)
 		return
 	}
 
+	// pendingMedia 让 describe_image / transcribe_audio / ocr_image 拿到本轮媒体的
+	// 原始 data/url，也是这三个工具是否出现在工具表里的开关。仅对用户直接上传成立
+	//（payload 里才有 data/url）；插件注入的是成品 block，取不到原始数据。
+	if evt.Type == "image" || evt.Type == "audio" {
+		a.pendingMedia = evt.Payload
+		defer func() { a.pendingMedia = nil }()
+	}
+
+	// 媒体先落进 CAS。不存的后果是 ContextEvent.Input 只剩一句 alt 文本，
+	// base64 随 message 数组发给模型后就丢了。
+	if len(in.blocks) > 0 {
+		a.stageMediaDigests(a.captureBlockMedia(in.blocks, in.captureTool)...)
+	}
+
 	noMemory := false
 	if v, ok := evt.Payload["no_memory"].(bool); ok {
 		noMemory = v
@@ -318,9 +362,13 @@ func (a *Agent) processTextInput(evt *agentIO.InputEvent, input string) {
 		noMemory = true
 	}
 
-	stageCtx := a.stageCtxFromInput(input, evt.Source, "")
+	stageCtx := a.stageCtxFromInput(in.text, evt.Source, "")
 	stageCtx.Extra["input_source"] = evt.Source
 	stageCtx.Extra["output_channel"] = evt.OutputChannel
+	if len(in.blocks) > 0 {
+		stageCtx.Extra["media_blocks"] = in.blocks
+		stageCtx.Extra["media_type"] = in.mediaType
+	}
 	if noMemory {
 		stageCtx.NoMemory = true
 	}
@@ -331,7 +379,7 @@ func (a *Agent) processTextInput(evt *agentIO.InputEvent, input string) {
 		return
 	}
 
-	input = stageCtx.RawMessage
+	input := stageCtx.RawMessage
 
 	// 计算层用的清洗文本（不改原文）：通道 Cleaner 提取语义内容后用于向量化/提关键词
 	cleanInput := input
@@ -341,12 +389,18 @@ func (a *Agent) processTextInput(evt *agentIO.InputEvent, input string) {
 		}
 	}
 
-	a.publishEvent(events.EventRawInput, map[string]interface{}{
-		"content": input,
-		"source":  evt.Source,
-	})
+	// upload_* 字段一并转发：webui 的 EventRawInput 订阅方靠它们还原附件卡片。
+	// 媒体路径此前把整个 payload 塞进 content（一个 map），订阅方按 string 断言
+	// 直接失败 → 用户发的图从不出现在聊天记录里。
+	rawPayload := map[string]interface{}{"content": input, "source": evt.Source}
+	for _, k := range []string{"upload_url", "upload_type", "upload_size", "upload_name"} {
+		if v, ok := evt.Payload[k]; ok {
+			rawPayload[k] = v
+		}
+	}
+	a.publishEvent(events.EventRawInput, rawPayload)
 
-	archived := a.context.Prune(cleanInput, a.maxContextSize-1, a.docStore)
+	archived := a.pruneOnInput(evt, cleanInput)
 	if archived > 0 {
 		log.Printf("[agent] pruned %d low-relevance events to document memory", archived)
 	}
@@ -361,7 +415,7 @@ func (a *Agent) processTextInput(evt *agentIO.InputEvent, input string) {
 
 	response, toolsUsed, toolResults, err := a.process(input, stageCtx)
 	if err != nil {
-		log.Printf("[agent] process error: %v", err)
+		log.Printf("[agent] process %s error: %v", evt.Type, err)
 		resp := fmt.Sprintf("处理错误: %v", err)
 		a.emitResponse(evt, resp)
 		a.context.Append(ContextEvent{Timestamp: time.Now(), Source: "agent", Input: input, Response: resp})
@@ -369,16 +423,21 @@ func (a *Agent) processTextInput(evt *agentIO.InputEvent, input string) {
 	}
 
 	elapsed := time.Since(start)
-	log.Printf("[agent] input from %s → response (%dms, tools=%v)", evt.Source, elapsed.Milliseconds(), toolsUsed)
+	log.Printf("[agent] %s from %s → response (%dms, tools=%v)", evt.Type, evt.Source, elapsed.Milliseconds(), toolsUsed)
 
-	a.context.Append(ContextEvent{
+	// 本轮捕获的媒体一起挂到这条事件上：用户上传的、插件注入的，以及模型调
+	// multimodal_see_picture / see_video 时经 SetToolBlocks 注入的（后者在
+	// process() 里被捕获，纯文本输入也会有）。
+	turnEvt := ContextEvent{
 		Timestamp:   time.Now(),
 		Source:      "agent",
 		Input:       cleanInput,
 		Response:    response,
 		ToolsUsed:   toolsUsed,
 		ToolResults: toolResults,
-	})
+	}
+	a.bindEventMedia(&turnEvt, a.drainMediaDigests())
+	a.context.Append(turnEvt)
 
 	a.emitResponse(evt, response)
 
@@ -463,3 +522,66 @@ func (a *Agent) drainInterrupts() []string {
 		}
 	}
 }
+
+// pruneOnInput 按声明的上下文策略裁剪上下文，返回归档的事件数。
+//
+// 默认**不裁剪**：ContextPolicy 必须在注入点（payload 的 context_policy）
+// 或通道定义（ChannelDef.ContextPolicy）上显式声明为 prune 才会裁剪。
+//
+// 为什么把无条件裁剪改成需声明：裁剪会把低相关事件归档到文档记忆并从上下文里
+// 移走，是破坏性的。此前每条输入都裁一次，于是「谁把上下文裁了」在排查时无从
+// 得知；而插件注入的内容也会被不相关的内容挤掉。按来源/注入点声明后，触发条件
+// 是可枚举、可审计的。
+//
+// 查询向量取**清洗后**的输入（通道 Cleaner 的输出），与工具侧同一套语义：
+// 原始输入里的 ANSI/base64/JSON 包装会把相关性打分带偏，裁掉本该保留的事件。
+func (a *Agent) pruneOnInput(evt *agentIO.InputEvent, cleanInput string) int {
+	if a.context == nil || !a.pruneDeclared(evt) {
+		return 0
+	}
+	topK := a.maxContextSize - 1
+	if topK < 1 {
+		topK = 1
+	}
+	return a.context.Prune(cleanInput, topK, a.docStore)
+}
+
+// pruneDeclared 判定这次输入是否显式声明了裁剪。
+//
+// 优先级：注入点声明的（payload）> 通道声明的（ChannelDef）> 默认不裁剪。
+// 注入点是更窄的声明面，同一通道下的不同注入可以有不同意图。
+func (a *Agent) pruneDeclared(evt *agentIO.InputEvent) bool {
+	if p, ok := evt.Payload["context_policy"].(string); ok && p != "" {
+		return p == pubsdk.ContextPolicyPrune
+	}
+	if a.io != nil {
+		if chDef, ok := a.io.GetInputChannelDef(evt.Source); ok {
+			return chDef.ContextPolicy == pubsdk.ContextPolicyPrune
+		}
+	}
+	return false
+}
+
+// cleanInputFor 解析这条输入在计算层应当使用的清洗文本。
+//
+// 优先级：注入点声明的 cleaner（payload.cleaner_name，引用某个已注册的通道
+// cleaner）> 按 source 查到的通道 cleaner > 原文。
+//
+// 声明的 cleaner 名字查不到时**记日志并回退**，而不是静默当没声明：
+// 注入是 fire-and-forget 的，插件那边看不到错误；至少要在内核日志里留下
+// 「你声明的清洗没生效」的痕迹，否则排查时只能看到「记忆里的内容很脏」。
+func (a *Agent) cleanInputFor(evt *agentIO.InputEvent, input string) string {
+	if a.io == nil {
+		return input
+	}
+	if name, ok := evt.Payload["cleaner_name"].(string); ok && name != "" {
+		if chDef, ok := a.io.GetInputChannelDef(name); ok && chDef.Cleaner != nil {
+			return chDef.Cleaner(input)
+		}
+		log.Printf("[agent] 注入声明了 cleaner_name=%q 但没有注册过该通道的 Cleaner，已回退", name)
+	}
+	if chDef, ok := a.io.GetInputChannelDef(evt.Source); ok && chDef.Cleaner != nil {
+		return chDef.Cleaner(input)
+	}
+	return input
+}

internal/agent/core/graphmedia.go

@@ -0,0 +1,266 @@
+package core
+
+import (
+	"fmt"
+	"log"
+	"strconv"
+	"strings"
+
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/document"
+)
+
+// L3 图库的媒体绑定。
+//
+// 媒体在 L3 是一等记忆块（memory_blocks），以结构边与承载它的节点相连：
+//   sentence --contains--> block（对话/三元组产生的记忆）
+//   document --contains--> block（L2 文档归档进 L3）
+//
+// 这里不再有任何 marker 文本、正则反解或"描述文本当索引"的路径：
+// 媒体只按自己的统一空间向量被检索，图库/文档只记录它的结构归属。
+
+// migrateLegacyGraphMedia 把 marker 反解出来的旧媒体实体迁移成原生一等块。
+//
+// 旧数据里媒体是 type=Media 的普通实体（「图片 a1b2c3d4e5f6」），
+// 靠生成的描述文本当索引。迁移后它变成真正的记忆块，以
+// sentence --contains--> block 结构边挂回原句子，旧实体与描述关系删除。
+// 迁移幂等（实体处理完即删除），因此在每个 Agent 启动时跑一次是安全的。
+func (a *Agent) migrateLegacyGraphMedia() {
+	if a.memory == nil || a.mediaStore == nil {
+		return
+	}
+	blocks, entities, err := a.memory.MigrateLegacyMediaEntities(func(short string) (memory.MemoryBlock, bool) {
+		full, err := a.mediaStore.ResolvePrefix(short)
+		if err != nil {
+			return memory.MemoryBlock{}, false
+		}
+		return a.blockFromDigest(full)
+	})
+	if err != nil {
+		log.Printf("[media] 旧媒体实体迁移失败（下轮重试）: %v", err)
+		return
+	}
+	if blocks > 0 || entities > 0 {
+		log.Printf("[media] 旧媒体实体迁移完成: 新建 %d 个原生块，删除 %d 个描述式实体", blocks, entities)
+	}
+}
+
+// attachBlocksToSentence 把一组 digest 变成 L3 一等块并挂到句子上。
+// seed 允许复用已持有块的 ID（L2→L3 迁移保持块身份不变）。
+func (a *Agent) attachBlocksToSentence(sentenceID int64, digests []string, seed map[string]memory.MemoryBlock) int {
+	if a.mediaStore == nil || a.memory == nil || sentenceID == 0 {
+		return 0
+	}
+	bound := 0
+	for _, d := range digests {
+		full, err := a.mediaStore.ResolvePrefix(d)
+		if err != nil {
+			log.Printf("[media] digest %s 无法解析: %v", d, err)
+			continue
+		}
+		b, ok := seed[full]
+		if !ok {
+			if b, ok = a.blockFromDigest(full); !ok {
+				continue
+			}
+		}
+		if err := a.memory.PutMemoryBlocks([]memory.MemoryBlock{b}); err != nil {
+			log.Printf("[media] L3 块写入失败 (%s): %v", shortDigest(full), err)
+			continue
+		}
+		if err := a.memory.AddMemoryBlockEdge("sentence", strconv.FormatInt(sentenceID, 10), "block", b.ID, "contains"); err != nil {
+			log.Printf("[media] 句子→块边建立失败 (%s): %v", shortDigest(full), err)
+			continue
+		}
+		bound++
+	}
+	return bound
+}
+
+// linkBlocksToDocument 把文档持有的块写入 L3，并建立
+// document --contains--> block 边。块的 ID 原样保留（迁移而非重建）。
+func (a *Agent) linkBlocksToDocument(docID string, blocks []memory.MemoryBlock) int {
+	if a.memory == nil || docID == "" || len(blocks) == 0 {
+		return 0
+	}
+	if err := a.memory.PutDocumentNode(docID, ""); err != nil {
+		log.Printf("[media] 写入 L3 文档节点失败 (%s): %v", docID, err)
+		return 0
+	}
+	if err := a.memory.PutMemoryBlocks(blocks); err != nil {
+		log.Printf("[media] 写入 L3 记忆块失败 (doc %s): %v", docID, err)
+		return 0
+	}
+	bound := 0
+	for _, b := range blocks {
+		if err := a.memory.AddMemoryBlockEdge("document", docID, "block", b.ID, "contains"); err != nil {
+			log.Printf("[media] 文档→块边建立失败 (%s): %v", shortDigest(b.PayloadDigest), err)
+			continue
+		}
+		bound++
+	}
+	return bound
+}
+
+// commitTriplesWithMedia 提交三元组并把三元组显式携带的媒体变成 L3 一等块。
+//
+// seed 是调用方已持有的一等块（如 L2 文档的 Blocks），用于保持块身份；
+// 普通对话路径传 nil。blocks 是本次写入 L3 的块数。
+func (a *Agent) commitTriplesWithMedia(triples []memory.Triple, sessionID string, turnID int, seed []memory.MemoryBlock) (entities, relations, blocks int, err error) {
+	if a.memory == nil {
+		return 0, 0, 0, fmt.Errorf("graph memory 未启用")
+	}
+	if a.mediaStore == nil {
+		ec, rc, cErr := a.memory.Commit(triples, sessionID, turnID)
+		return ec, rc, 0, cErr
+	}
+	sentenceIDs, ec, rc, err := a.memory.CommitWithMedia(triples, sessionID, turnID)
+	if err != nil {
+		return ec, rc, 0, err
+	}
+	byDigest := make(map[string]memory.MemoryBlock, len(seed))
+	for _, b := range seed {
+		if b.PayloadDigest != "" {
+			byDigest[b.PayloadDigest] = b
+		}
+	}
+	for _, t := range triples {
+		if len(t.MediaDigests) == 0 {
+			continue
+		}
+		sid := sentenceIDs[t.SentenceText]
+		if sid == 0 {
+			continue
+		}
+		blocks += a.attachBlocksToSentence(sid, t.MediaDigests, byDigest)
+	}
+	return ec, rc, blocks, nil
+}
+
+// RecallBlocksForSentence 反查某条图库句子持有的一等记忆块。
+func (a *Agent) RecallBlocksForSentence(sentenceID int64) ([]memory.MemoryBlock, error) {
+	if a.memory == nil {
+		return nil, nil
+	}
+	return a.memory.BlocksForNode("sentence", strconv.FormatInt(sentenceID, 10))
+}
+
+// resolveMediaDigests 把模型给的（多为短）digest 补全成完整 digest。
+//
+// 补不上就丢弃那一条并记日志：模型可能凭印象编了个 digest，也可能内容已被删除。
+func (a *Agent) resolveMediaDigests(digests []string) []string {
+	if a.mediaStore == nil || len(digests) == 0 {
+		return nil
+	}
+	seen := make(map[string]bool, len(digests))
+	var out []string
+	for _, d := range digests {
+		full, err := a.mediaStore.ResolvePrefix(d)
+		if err != nil {
+			log.Printf("[media] 模型给的 digest %s 无法解析: %v", d, err)
+			continue
+		}
+		if seen[full] {
+			continue
+		}
+		seen[full] = true
+		out = append(out, full)
+	}
+	return out
+}
+
+// sentenceIDsFromRelations 收集一批关系引用的句子 id（去重、去零）。
+//
+// 关系行本身不持有媒体，媒体作为一等块以 sentence --contains--> block
+// 结构边与句子相连；因此"这次召回涉及哪些媒体"必须经由关系 → 句子这一跳。
+func sentenceIDsFromRelations(relations []memory.Relation) []int64 {
+	if len(relations) == 0 {
+		return nil
+	}
+	seen := make(map[int64]bool, len(relations))
+	var out []int64
+	for _, r := range relations {
+		if r.SentenceID == 0 || seen[r.SentenceID] {
+			continue
+		}
+		seen[r.SentenceID] = true
+		out = append(out, r.SentenceID)
+	}
+	return out
+}
+
+// mediaContextForRelations 是 mediaContextForSentences 的关系入口。
+func (a *Agent) mediaContextForRelations(relations []memory.Relation) string {
+	return a.mediaContextForSentences(sentenceIDsFromRelations(relations))
+}
+
+// mediaContextForInjectedEntities 为自动注入路径产出媒体说明。
+//
+// Indexer.BuildContext 刻意不返回关系（只给实体索引以省 token），
+// 因此这里用命中的实体名再查一次关系，只为拿到 sentence_id。
+func (a *Agent) mediaContextForInjectedEntities(injected *memory.InjectedContext) string {
+	if a.mediaStore == nil || a.memory == nil || injected == nil || len(injected.Entities) == 0 {
+		return ""
+	}
+	names := make([]string, 0, len(injected.Entities))
+	for _, e := range injected.Entities {
+		names = append(names, e.Name)
+	}
+	res, err := a.memory.Recall(nil, names, 1, "")
+	if err != nil || res == nil {
+		return ""
+	}
+	return a.mediaContextForRelations(res.Relations)
+}
+
+// blockLabelsForDoc 渲染文档持有块的标签（MIME + 短 digest），供 doc_query 展示。
+func (a *Agent) blockLabelsForDoc(d *document.Doc) string {
+	if a.mediaStore == nil || d == nil || len(d.Blocks) == 0 {
+		return ""
+	}
+	var parts []string
+	for _, b := range d.Blocks {
+		it, err := a.mediaStore.Stat(b.PayloadDigest)
+		if err != nil || it == nil {
+			continue
+		}
+		if line := mediaLabel(it); line != "" {
+			parts = append(parts, line)
+		}
+	}
+	return strings.Join(parts, "；")
+}
+
+// mediaContextForSentences 给一组句子附上其持有的一等块标签。
+//
+// 标签只含 MIME 与短 digest：图片按向量检索，标签的作用是告诉模型
+// "这条记忆当时带着哪份媒体、可用该 digest 取回字节"。
+func (a *Agent) mediaContextForSentences(sentenceIDs []int64) string {
+	if a.mediaStore == nil || a.memory == nil || len(sentenceIDs) == 0 {
+		return ""
+	}
+	var lines []string
+	for _, sid := range sentenceIDs {
+		blocks, err := a.memory.BlocksForNode("sentence", strconv.FormatInt(sid, 10))
+		if err != nil || len(blocks) == 0 {
+			continue
+		}
+		var parts []string
+		for _, b := range blocks {
+			it, err := a.mediaStore.Stat(b.PayloadDigest)
+			if err != nil || it == nil {
+				continue
+			}
+			if line := mediaLabel(it); line != "" {
+				parts = append(parts, line)
+			}
+		}
+		if len(parts) > 0 {
+			lines = append(lines, fmt.Sprintf("句子 #%d 关联媒体：%s", sid, strings.Join(parts, "；")))
+		}
+	}
+	if len(lines) == 0 {
+		return ""
+	}
+	return strings.Join(lines, "\n")
+}

internal/agent/core/graphmedia_test.go

@@ -0,0 +1,761 @@
+package core
+
+import (
+	"fmt"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/document"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/media"
+)
+
+// L3 图库媒体绑定测试。
+//
+// 这一层的目的只有一个：几个月后从图谱走到一条句子，要能取回当时那份媒体。
+// 媒体作为一等块进入 L3，以结构边与承载节点相连：
+//
+//	sentence --contains--> block（对话/三元组产生的记忆）
+//	document --contains--> block（L2 文档归档进 L3）
+//
+// 描述文本、marker 反解、由 marker 反推出的「媒体实体」全部已废弃，
+// 因此这些测试也不存在任何按描述检索的断言。
+
+// attachBlockToSentence 提交一条句子并把媒体变成 L3 一等块。
+// 必须走真实提交：边要求两端都是真实图节点。
+func attachBlockToSentence(t *testing.T, g *memory.GraphDB, ms *media.Store, sentenceText, digest string) (int64, memory.MemoryBlock) {
+	t.Helper()
+	ids, _, _, err := g.CommitWithMedia([]memory.Triple{{
+		Subject: "媒体载体", Relation: "包含", Object: "内容", SentenceText: sentenceText,
+	}}, "test", 0)
+	if err != nil {
+		t.Fatalf("CommitWithMedia: %v", err)
+	}
+	sid := ids[sentenceText]
+	if sid == 0 {
+		t.Fatalf("拿不到句子 id: %q", sentenceText)
+	}
+	it, err := ms.Stat(digest)
+	if err != nil || it == nil {
+		t.Fatalf("Stat(%s): %v", shortDigest(digest), err)
+	}
+	b := memory.MemoryBlock{
+		ID:            fmt.Sprintf("blk_test_%d_%s", sid, shortDigest(digest)),
+		Modality:      memory.BlockImage,
+		PayloadDigest: it.Digest,
+		MIME:          it.MIME,
+		Size:          it.Size,
+		Width:         it.Width,
+		Height:        it.Height,
+		Vector:        it.Vec,
+		Fingerprint:   it.VecModel,
+	}
+	if err := g.PutMemoryBlocks([]memory.MemoryBlock{b}); err != nil {
+		t.Fatalf("PutMemoryBlocks: %v", err)
+	}
+	if err := g.AddMemoryBlockEdge("sentence", strconv.FormatInt(sid, 10), "block", b.ID, "contains"); err != nil {
+		t.Fatalf("AddMemoryBlockEdge: %v", err)
+	}
+	return sid, b
+}
+
+func newGraphMediaAgent(t *testing.T) (*Agent, *memory.GraphDB, *media.Store) {
+	t.Helper()
+	dir := t.TempDir()
+
+	g, err := memory.NewGraphDB(filepath.Join(dir, "graph.db"))
+	if err != nil {
+		t.Fatalf("NewGraphDB: %v", err)
+	}
+	t.Cleanup(func() { g.Close() })
+
+	ms, err := media.New(filepath.Join(dir, "media"))
+	if err != nil {
+		t.Fatalf("media.New: %v", err)
+	}
+	t.Cleanup(func() { ms.Close() })
+
+	return &Agent{memory: g, mediaStore: ms}, g, ms
+}
+
+func TestCommitWithMedia_ReturnsSentenceIDs(t *testing.T) {
+	_, g, _ := newGraphMediaAgent(t)
+
+	sentence := "这张图是紫蓝红三色带。"
+	triples := []memory.Triple{{
+		Subject: "图片", Relation: "内容", Object: "三色带",
+		SentenceText: sentence,
+	}}
+
+	ids, ec, rc, err := g.CommitWithMedia(triples, "s1", 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if ec == 0 || rc == 0 {
+		t.Fatalf("应写入实体与关系，实际 ec=%d rc=%d", ec, rc)
+	}
+	if ids[sentence] == 0 {
+		t.Fatalf("应返回句子 id，实际 %v", ids)
+	}
+}
+
+func TestCommit_StillWorksAfterRefactor(t *testing.T) {
+	// Commit 有三十多个调用点，内部转调后行为必须完全不变
+	_, g, _ := newGraphMediaAgent(t)
+
+	triples := []memory.Triple{
+		{Subject: "张三", Relation: "喜欢", Object: "咖啡", SentenceText: "张三喜欢咖啡"},
+		{Subject: "李四", Relation: "住在", Object: "北京"},
+	}
+	ec, rc, err := g.Commit(triples, "s1", 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if ec != 4 || rc != 2 {
+		t.Fatalf("期望 4 实体 2 关系，实际 ec=%d rc=%d", ec, rc)
+	}
+
+	// 重复提交同一批：关系被唯一约束去重。
+	//
+	// 实体计数**不**归零——这是 upsertEntity 的既有行为：SQLite 的
+	// ON CONFLICT DO UPDATE 也算一行 affected，于是 RowsAffected() > 0
+	// 被当成"新建了"。用 main 分支的 graph.go 单独验证过基线同样是
+	// 首次 ec=2 / 重复 ec=2，与 CommitWithMedia 重构无关。
+	// entitiesCreated 只用于日志，故此处记录现状而不改行为。
+	ec2, rc2, err := g.Commit(triples, "s1", 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if rc2 != 0 {
+		t.Fatalf("重复提交不该新建关系，实际 rc=%d", rc2)
+	}
+	if ec2 != 4 {
+		t.Fatalf("实体计数应与首次一致（既有 upsert 计数行为），实际 ec=%d", ec2)
+	}
+}
+
+func TestCommitTriplesWithMedia_RoundTrip(t *testing.T) {
+	// 整层的核心断言：写入 → 提交 → 反查取回原始字节
+	a, _, ms := newGraphMediaAgent(t)
+
+	content := []byte("\x89PNG\r\n\x1a\n fake image bytes")
+	digest, err := ms.Put(content, media.Item{MIME: "image/png", Kind: media.KindImage})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	sentence := "用户发来一张紫蓝红三色带图。"
+	triples := []memory.Triple{{
+		Subject: "图片", Relation: "内容", Object: "三色带",
+		SentenceText: sentence,
+		MediaDigests: []string{digest[:12]}, // 模型手里通常只有短 digest
+	}}
+
+	if _, _, bound, err := a.commitTriplesWithMedia(triples, "s1", 0, nil); err != nil {
+		t.Fatal(err)
+	} else if bound != 1 {
+		t.Fatalf("应绑定 1 个块，实际 %d", bound)
+	}
+
+	ids, _, _, err := a.memory.CommitWithMedia(triples, "s1", 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	sid := ids[sentence]
+	if sid == 0 {
+		t.Fatal("拿不到句子 id")
+	}
+
+	// 反查：从句子取回一等块，再取回字节
+	blocks, err := a.RecallBlocksForSentence(sid)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(blocks) != 1 || blocks[0].PayloadDigest != digest {
+		t.Fatalf("反查应得完整 digest %s，实际 %+v", shortDigest(digest), blocks)
+	}
+	got, err := ms.Get(blocks[0].PayloadDigest)
+	if err != nil {
+		t.Fatalf("取回内容失败: %v", err)
+	}
+	if string(got) != string(content) {
+		t.Fatal("取回的内容与写入不一致")
+	}
+
+	// 块仍被 L3 持有 → 内容应仍可读
+	if _, err := ms.Get(digest); err != nil {
+		t.Fatalf("被 L3 记忆块持有的内容不该被清除: %v", err)
+	}
+}
+
+func TestAttachBlocksToSentence_SkipsUnresolvable(t *testing.T) {
+	// digest 在库里不存在时必须跳过，不能建一条指向虚无的块边。
+	a, g, _ := newGraphMediaAgent(t)
+	if n := a.attachBlocksToSentence(42, []string{"deadbeefdead"}, nil); n != 0 {
+		t.Fatalf("无法补全的 digest 不该建块，实际绑定 %d", n)
+	}
+	blocks, err := g.BlocksForNode("sentence", "42")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(blocks) != 0 {
+		t.Fatalf("不该有块，实际 %+v", blocks)
+	}
+}
+
+func TestAttachBlocksToSentence_NilStoreNoop(t *testing.T) {
+	a := &Agent{}
+	if n := a.attachBlocksToSentence(1, []string{"aaaaaaaaaaaa"}, nil); n != 0 {
+		t.Fatalf("媒体关闭时应静默无操作，实际 %d", n)
+	}
+	if got, err := a.RecallBlocksForSentence(1); err != nil || got != nil {
+		t.Fatalf("媒体关闭时应静默无操作，实际 %v / %v", got, err)
+	}
+}
+
+func TestAttachBlocksToSentence_ReusesSeedIdentity(t *testing.T) {
+	// L2→L3 迁移必须保持块身份：同一个块换层，而不是另建一个同内容的新块。
+	a, g, ms := newGraphMediaAgent(t)
+	digest, _ := ms.Put([]byte("seed-img"), media.Item{MIME: "image/png"})
+	seedBlock, ok := a.blockFromDigest(digest)
+	if !ok {
+		t.Fatal("blockFromDigest 失败")
+	}
+
+	ids, _, _, err := g.CommitWithMedia([]memory.Triple{{
+		Subject: "迁移", Relation: "包含", Object: "媒体", SentenceText: "迁移测试句。",
+	}}, "seed", 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	sid := ids["迁移测试句。"]
+
+	byDigest := map[string]memory.MemoryBlock{digest: seedBlock}
+	if n := a.attachBlocksToSentence(sid, []string{digest}, byDigest); n != 1 {
+		t.Fatalf("应绑定 1 个块，实际 %d", n)
+	}
+	blocks, err := g.BlocksForNode("sentence", strconv.FormatInt(sid, 10))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(blocks) != 1 || blocks[0].ID != seedBlock.ID {
+		t.Fatalf("块身份应保持为 %s，实际 %+v", seedBlock.ID, blocks)
+	}
+}
+
+func TestLinkBlocksToDocument_CreatesDocumentNodeEdge(t *testing.T) {
+	// 文档归档进 L3：块原样迁入，document --contains--> block 边建立。
+	a, g, ms := newGraphMediaAgent(t)
+
+	digest, _ := ms.Put([]byte("doc-img"), media.Item{MIME: "image/png"})
+	b, ok := a.blockFromDigest(digest)
+	if !ok {
+		t.Fatal("blockFromDigest 失败")
+	}
+
+	if n := a.linkBlocksToDocument("doc_42", []memory.MemoryBlock{b}); n != 1 {
+		t.Fatalf("应建立 1 条文档→块边，实际 %d", n)
+	}
+	blocks, err := g.BlocksForNode("document", "doc_42")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(blocks) != 1 || blocks[0].ID != b.ID {
+		t.Fatalf("文档应持有块 %s，实际 %+v", b.ID, blocks)
+	}
+}
+
+func TestCommitTriplesWithMedia_FallsBackWithoutStore(t *testing.T) {
+	// 媒体关闭时退回普通 Commit，行为与直接调 Commit 完全一致
+	dir := t.TempDir()
+	g, err := memory.NewGraphDB(filepath.Join(dir, "g.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer g.Close()
+
+	a := &Agent{memory: g}
+	ec, rc, _, err := a.commitTriplesWithMedia([]memory.Triple{
+		{Subject: "张三", Relation: "喜欢", Object: "咖啡"},
+	}, "s1", 0, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if ec != 2 || rc != 1 {
+		t.Fatalf("期望 2 实体 1 关系，实际 ec=%d rc=%d", ec, rc)
+	}
+}
+
+func TestMediaContextForSentences(t *testing.T) {
+	a, g, ms := newGraphMediaAgent(t)
+
+	digest, _ := ms.Put([]byte("img"), media.Item{MIME: "image/png"})
+	sid, _ := attachBlockToSentence(t, g, ms, "一张紫蓝红三色带图。", digest)
+
+	out := a.mediaContextForSentences([]int64{sid, sid + 100})
+	if out == "" {
+		t.Fatal("应产出媒体说明")
+	}
+	if !contains(out, fmt.Sprintf("句子 #%d", sid)) || !contains(out, shortDigest(digest)) {
+		t.Fatalf("说明内容不对: %q", out)
+	}
+	// 说明只含 MIME 与短 digest，不含任何生成的描述
+	if contains(out, "紫蓝红") {
+		t.Fatalf("说明里不该有描述文本（描述式索引已废弃）: %q", out)
+	}
+	// 无引用的句子不该出现
+	if contains(out, fmt.Sprintf("句子 #%d", sid+100)) {
+		t.Fatalf("无引用的句子不该出现: %q", out)
+	}
+}
+
+func TestMediaContextForRelations_SurfacesMediaToAgent(t *testing.T) {
+	// L3 检索接线回归：媒体作为一等块进了图库，agent 必须拿得出来。
+	a, g, ms := newGraphMediaAgent(t)
+
+	digest, err := ms.Put([]byte("img bytes"), media.Item{MIME: "image/png"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	sid, _ := attachBlockToSentence(t, g, ms, "一张紫蓝红三色带图。", digest)
+
+	// 命中的关系挂着该句子 → 应产出媒体说明
+	out := a.mediaContextForRelations([]memory.Relation{{ID: 1, SentenceID: sid}})
+	if out == "" {
+		t.Fatal("关系挂着有媒体的句子，却没产出媒体说明——L3 检索接线断了")
+	}
+	if !contains(out, shortDigest(digest)) {
+		t.Errorf("媒体说明里应含短 digest 供反查: %q", out)
+	}
+
+	// 没挂媒体的关系不该产出噪声
+	if out := a.mediaContextForRelations([]memory.Relation{{ID: 2, SentenceID: 99}}); out != "" {
+		t.Errorf("无媒体的句子不该产出说明: %q", out)
+	}
+	if out := a.mediaContextForRelations(nil); out != "" {
+		t.Errorf("空关系不该产出说明: %q", out)
+	}
+}
+
+func TestBuildMemoryContext_IncludesMediaSection(t *testing.T) {
+	// buildMemoryContext 是自动注入路径（每次 LLM 调用都走）。
+	// 媒体说明必须出现在这里，否则 agent 只有显式调 memory_recall 才知道有图。
+	a, graph, ms := newGraphMediaAgent(t)
+
+	digest, err := ms.Put([]byte("auto inject"), media.Item{MIME: "image/png"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	sentence := "用户发来的图片。"
+	sids, _, _, err := graph.CommitWithMedia([]memory.Triple{{
+		Subject: "测试图片", Relation: "包含", Object: "三色带", SentenceText: sentence,
+	}}, "auto", 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	sid := sids[sentence]
+	if sid == 0 {
+		t.Fatal("拿不到句子 id")
+	}
+	if err := graph.PutMemoryBlocks([]memory.MemoryBlock{{
+		ID: "blk_auto_1", Modality: memory.BlockImage,
+		PayloadDigest: digest, MIME: "image/png",
+	}}); err != nil {
+		t.Fatal(err)
+	}
+	if err := graph.AddMemoryBlockEdge("sentence", strconv.FormatInt(sid, 10), "block", "blk_auto_1", "contains"); err != nil {
+		t.Fatal(err)
+	}
+
+	a.indexer = memory.NewIndexer(graph)
+	if err := a.indexer.Sync(); err != nil {
+		t.Fatalf("indexer sync: %v", err)
+	}
+
+	out := a.buildMemoryContext("测试图片", 0)
+	if out == "" {
+		t.Skip("图库召回未命中（indexer 检索策略所致），无法验证媒体段注入")
+	}
+	if !contains(out, "【关联媒体】") {
+		t.Errorf("自动注入的记忆上下文缺少媒体段: %q", out)
+	}
+	if !contains(out, shortDigest(digest)) {
+		t.Errorf("媒体段里应含短 digest: %q", out)
+	}
+}
+
+func TestResolvePrefix(t *testing.T) {
+	dir := t.TempDir()
+	ms, err := media.New(filepath.Join(dir, "m"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer ms.Close()
+
+	digest, _ := ms.Put([]byte("content"), media.Item{MIME: "image/png"})
+
+	// 短前缀补全
+	full, err := ms.ResolvePrefix(digest[:12])
+	if err != nil || full != digest {
+		t.Fatalf("短前缀补全失败: %v / %v", full, err)
+	}
+	// 完整 digest 原样返回
+	full, err = ms.ResolvePrefix(digest)
+	if err != nil || full != digest {
+		t.Fatalf("完整 digest 应原样返回: %v / %v", full, err)
+	}
+	// 过短拒绝
+	if _, err := ms.ResolvePrefix("abc"); err == nil {
+		t.Fatal("过短前缀应报错")
+	}
+	// 不存在
+	if _, err := ms.ResolvePrefix("deadbeefdead"); err == nil {
+		t.Fatal("不存在的前缀应报错")
+	}
+	// 完整但不存在的 digest 也要报错，否则调用方会挂一条孤儿块
+	fake := strings.Repeat("0", 64)
+	if _, err := ms.ResolvePrefix(fake); err == nil {
+		t.Fatal("不存在的完整 digest 应报错")
+	}
+}
+
+func TestResolvePrefix_AmbiguityIsError(t *testing.T) {
+	// 前缀歧义视为错误而非"取第一个"：挂错块会让内容被误删。
+	// 构造歧义需要两个同前缀 digest——sha256 无法人为构造，
+	// 因此这里退而验证「12 位前缀在大量样本下的行为是确定的」：
+	// 要么唯一命中，要么明确报歧义，绝不静默取第一个。
+	dir := t.TempDir()
+	ms, err := media.New(filepath.Join(dir, "m"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer ms.Close()
+
+	digests := make([]string, 0, 200)
+	for i := 0; i < 200; i++ {
+		d, err := ms.Put([]byte("content-"+strconv.Itoa(i)), media.Item{MIME: "image/png"})
+		if err != nil {
+			t.Fatal(err)
+		}
+		digests = append(digests, d)
+	}
+
+	for _, d := range digests {
+		got, err := ms.ResolvePrefix(d[:12])
+		if err != nil {
+			if !contains(err.Error(), "歧义") {
+				t.Fatalf("非歧义错误: %v", err)
+			}
+			continue
+		}
+		if got != d {
+			t.Fatalf("补全结果错误: 前缀 %s 得到 %s", d[:12], got)
+		}
+	}
+}
+
+func TestArchiveColdDocs_KeepsDocWhenGraphWriteEmpty(t *testing.T) {
+	// 数据丢失回归：三元组全被实体名校验拒绝时（Commit 无错但 0 entities
+	// 0 relations），文档不能删、其持有的块不能丢。
+	a, _, ms := newGraphMediaAgent(t)
+
+	dir := t.TempDir()
+	ds := document.NewStore(filepath.Join(dir, "docs"), memory.TokenizeWords)
+	if err := ds.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer ds.Stop()
+	a.docStore = ds
+	a.embedder = memory.NewStaticEmbedder()
+
+	content := []byte("image bytes")
+	digest, err := ms.Put(content, media.Item{MIME: "image/png"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// 精确构造「三元组非空 + Commit 全部拒绝」这个状态：
+	// Source/Summary 都超过 validEntityName 的 50 字符上限，
+	// 于是 docToTriples 产出的两条元数据三元组都被跳过。
+	longSource := strings.Repeat("超长来源名", 20)   // 100 字
+	longSummary := strings.Repeat("超长摘要文本", 20) // >80 字触发长度门槛被跳过
+	it, _ := ms.Stat(digest)
+	doc := &document.Doc{
+		ID:          "doc_keep",
+		Summary:     longSummary,
+		Content:     "一段没有媒体标记的正文",
+		Source:      longSource,
+		CreatedAt:   time.Now().Add(-200 * time.Hour),
+		LastAccess:  time.Now().Add(-200 * time.Hour),
+		AccessCount: 0,
+		Blocks: []memory.MemoryBlock{{ID: "blk_keep_1", Modality: memory.BlockImage,
+			PayloadDigest: it.Digest, MIME: it.MIME, Size: it.Size}},
+	}
+	if err := ds.Insert(doc); err != nil {
+		t.Fatal(err)
+	}
+	// Insert 会把 LastAccess 覆写成 now、AccessCount 置 1，
+	// 于是 FindColdDocs(72h, 2) 一篇都找不到。插入后再改回来，
+	// 让文档真正满足"冷"的条件——这是触发归档路径的前提。
+	for _, d := range ds.RecentDocs(10) {
+		if d.ID == doc.ID {
+			d.LastAccess = time.Now().Add(-200 * time.Hour)
+			d.AccessCount = 0
+		}
+	}
+	a.archiveColdDocs()
+
+	// 关键断言：内容在、块在、文档在
+	if _, err := ms.Get(digest); err != nil {
+		t.Fatalf("图库未写入任何实体/关系，内容却丢了: %v", err)
+	}
+	held := false
+	for _, d := range ds.RecentDocs(10) {
+		if d.ID == doc.ID && len(d.Blocks) > 0 {
+			held = true
+		}
+	}
+	if !held {
+		t.Error("文档或块被释放了——图库没有句子承载它，内容会被删除")
+	}
+}
+
+func TestArchiveColdDocs_MigratesBlocksToGraph(t *testing.T) {
+	// 归档成功时块必须迁进 L3 并以 document --contains--> block 关联，
+	// 然后文档才被删除（迁移而非复制/引用保活）。
+	a, g, ms := newGraphMediaAgent(t)
+
+	dir := t.TempDir()
+	ds := document.NewStore(filepath.Join(dir, "docs"), memory.TokenizeWords)
+	if err := ds.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer ds.Stop()
+	a.docStore = ds
+	a.embedder = memory.NewStaticEmbedder()
+
+	digest, _ := ms.Put([]byte("archived-image"), media.Item{MIME: "image/png"})
+	it, _ := ms.Stat(digest)
+	doc := &document.Doc{
+		ID:      "doc_arch",
+		Summary: "带图的冷文档",
+		Content: "张三把三色带图交给了李四。",
+		Source:  "manual",
+		Blocks: []memory.MemoryBlock{{ID: "blk_arch_1", Modality: memory.BlockImage,
+			PayloadDigest: it.Digest, MIME: it.MIME, Size: it.Size}},
+	}
+	if err := ds.Insert(doc); err != nil {
+		t.Fatal(err)
+	}
+	for _, d := range ds.RecentDocs(10) {
+		if d.ID == doc.ID {
+			d.LastAccess = time.Now().Add(-200 * time.Hour)
+			d.AccessCount = 0
+		}
+	}
+	a.archiveColdDocs()
+
+	if d := ds.Get("doc_arch"); d != nil {
+		t.Fatal("块已迁入 L3，文档应被删除")
+	}
+	blocks, err := g.BlocksForNode("document", "doc_arch")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(blocks) != 1 || blocks[0].ID != "blk_arch_1" {
+		t.Fatalf("L3 文档节点应持有原块（身份不变），实际 %+v", blocks)
+	}
+	if _, err := ms.Get(digest); err != nil {
+		t.Fatalf("块被 L3 持有，内容应仍可读: %v", err)
+	}
+}
+
+func TestMigrateLegacyMediaEntities(t *testing.T) {
+	// 旧数据：媒体被伪装成 type=Media 的实体，靠描述文本当索引。
+	// 迁移必须把它还原成原生块（挂回原句子）并删掉旧实体与描述关系。
+	_, g, ms := newGraphMediaAgent(t)
+
+	digest, _ := ms.Put([]byte("legacy-img"), media.Item{MIME: "image/png"})
+	sentence := "老数据里的三色带图 [image/png " + digest[:12] + "]"
+	// 直接构造旧的实体/关系形态（不走已删除的 marker 代码）。
+	ids, _, _, err := g.CommitWithMedia([]memory.Triple{{
+		Subject:      "图片 " + digest[:12],
+		SubjectType:  "Media",
+		Relation:     "内容",
+		Object:       "三色带的描述文本",
+		ObjectType:   "Description",
+		SentenceText: sentence,
+	}}, "legacy", 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	sid := ids[sentence]
+	if sid == 0 {
+		t.Fatal("拿不到句子 id")
+	}
+
+	blocks, entities, err := g.MigrateLegacyMediaEntities(func(short string) (memory.MemoryBlock, bool) {
+		full, err := ms.ResolvePrefix(short)
+		if err != nil {
+			return memory.MemoryBlock{}, false
+		}
+		it, err := ms.Stat(full)
+		if err != nil {
+			return memory.MemoryBlock{}, false
+		}
+		return memory.MemoryBlock{
+			ID: "blk_legacy_" + short, Modality: memory.BlockImage,
+			PayloadDigest: it.Digest, MIME: it.MIME, Size: it.Size,
+		}, true
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if blocks != 1 || entities != 1 {
+		t.Fatalf("应迁移 1 块 / 删 1 实体，实际 %d / %d", blocks, entities)
+	}
+
+	// 旧媒体实体与描述关系必须消失
+	res, err := g.Recall([]string{"图片 " + digest[:12]}, nil, 2, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, e := range res.Entities {
+		if e.Type == "Media" {
+			t.Fatalf("旧媒体实体仍存在: %+v", e)
+		}
+	}
+	// 块必须挂回原句子
+	got, err := g.BlocksForNode("sentence", strconv.FormatInt(sid, 10))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != 1 || got[0].PayloadDigest != digest {
+		t.Fatalf("句子应持有原生块，实际 %+v", got)
+	}
+
+	// 幂等：再跑一遍不应重复建块
+	blocks2, entities2, err := g.MigrateLegacyMediaEntities(nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if blocks2 != 0 || entities2 != 0 {
+		t.Fatalf("无 resolver 时应空操作，实际 %d / %d", blocks2, entities2)
+	}
+}
+
+func TestCleanupOrphanedSentences_KeepsBlockBackedSentences(t *testing.T) {
+	// 旧媒体实体被删除后，承载它的句子可能再无关系引用，
+	// 但它还挂着媒体块——清理孤儿句子时不能把它删掉。
+	a, g, ms := newGraphMediaAgent(t)
+
+	digest, _ := ms.Put([]byte("orphan-img"), media.Item{MIME: "image/png"})
+	sentence := "只靠媒体块存活的句子。"
+	ids, _, _, err := g.CommitWithMedia([]memory.Triple{{
+		Subject: "媒体载体", Relation: "包含", Object: "内容", SentenceText: sentence,
+	}}, "orphan", 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	sid := ids[sentence]
+
+	b, ok := a.blockFromDigest(digest)
+	if !ok {
+		t.Fatal("blockFromDigest 失败")
+	}
+	if err := g.PutMemoryBlocks([]memory.MemoryBlock{b}); err != nil {
+		t.Fatal(err)
+	}
+	if err := g.AddMemoryBlockEdge("sentence", strconv.FormatInt(sid, 10), "block", b.ID, "contains"); err != nil {
+		t.Fatal(err)
+	}
+
+	// 解除关系引用，句子只剩块边
+	res, err := g.Recall([]string{"媒体载体"}, nil, 2, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, r := range res.Relations {
+		if err := g.ClearSentenceID(r.ID); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if _, err := g.CleanupOrphanedSentences(); err != nil {
+		t.Fatal(err)
+	}
+	blocks, err := g.BlocksForNode("sentence", strconv.FormatInt(sid, 10))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(blocks) != 1 {
+		t.Fatalf("承载媒体块的句子被误删，块反查失败: %+v", blocks)
+	}
+}
+
+func TestSentenceIDsFromRelations(t *testing.T) {
+	// 关系行不持有媒体，媒体挂在句子上。这个函数负责"关系→句子"这一跳，
+	// 去重与去零都不能少：sentence_id=0 表示该关系没有关联句子。
+	rels := []memory.Relation{
+		{ID: 1, SentenceID: 5},
+		{ID: 2, SentenceID: 0}, // 无句子
+		{ID: 3, SentenceID: 5}, // 重复
+		{ID: 4, SentenceID: 7},
+	}
+	got := sentenceIDsFromRelations(rels)
+	if len(got) != 2 {
+		t.Fatalf("应得 2 个去重后的句子 id，实际 %v", got)
+	}
+	if got[0] != 5 || got[1] != 7 {
+		t.Fatalf("句子 id 或顺序不对: %v", got)
+	}
+	if n := sentenceIDsFromRelations(nil); n != nil {
+		t.Fatalf("空输入应返回 nil，实际 %v", n)
+	}
+}
+
+func TestMediaBlocksHeldByDocumentSurviveDeletion(t *testing.T) {
+	// 文档持有的一等块把内容钉住；文档被删后块随之消失，内容才可回收。
+	_, _, ms := newGraphMediaAgent(t)
+
+	digest, err := ms.Put([]byte("doc image"), media.Item{MIME: "image/png"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	dir := t.TempDir()
+	ds := document.NewStore(filepath.Join(dir, "docs"), memory.TokenizeWords)
+	if err := ds.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer ds.Stop()
+
+	it, _ := ms.Stat(digest)
+	doc := &document.Doc{
+		ID: "doc_1", Summary: "带图的文档", Content: "正文",
+		Blocks: []memory.MemoryBlock{{ID: "blk_doc_1", Modality: memory.BlockImage,
+			PayloadDigest: it.Digest, MIME: it.MIME, Size: it.Size}},
+	}
+	if err := ds.Insert(doc); err != nil {
+		t.Fatal(err)
+	}
+
+	// 文档仍持有块 → 内容在
+	if _, err := ms.Stat(digest); err != nil {
+		t.Fatal("有文档块持有内容时不该被清")
+	}
+
+	// 删除文档 → 一并删除其内容（与文本块一致：删块即删内容）
+	ds.Remove(doc.ID)
+	if blocks := ds.Blocks(); len(blocks) != 0 {
+		t.Fatalf("删除文档后不该还有块，实际 %+v", blocks)
+	}
+	if err := ms.Delete(digest); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := ms.Stat(digest); err == nil {
+		t.Fatal("删除后内容应已移除")
+	}
+}

internal/agent/core/inputunify_test.go

@@ -0,0 +1,615 @@
+package core
+
+import (
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+
+	agentAPI "gitcode.com/JianFeeeee/HomeAgent/internal/agent/api"
+	agentIO "gitcode.com/JianFeeeee/HomeAgent/internal/agent/io"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/document"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/media"
+	pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
+)
+
+// 统一输入主干（processInput / resolveInput / injectedBlocks）与
+// 模型可调用工具的媒体接线测试。
+//
+// 这一层此前的结构性缺陷：text 与 image/audio 各有一个 process 函数，
+// 媒体那条缺了去重、no_memory、通道 Cleaner、中断语义、EventRawInput 五项。
+// 归一成一条主干后，这些行为对所有模态一致——下面的断言就是这个不变量。
+
+func newInputTestAgent(t *testing.T) (*Agent, *media.Store) {
+	t.Helper()
+	dir := t.TempDir()
+
+	ms, err := media.New(filepath.Join(dir, "media"))
+	if err != nil {
+		t.Fatalf("media.New: %v", err)
+	}
+	t.Cleanup(func() { ms.Close() })
+
+	return &Agent{mediaStore: ms}, ms
+}
+
+// ---------- injectedBlocks ----------
+
+// 内核内部注入直接给 []agentAPI.ContentBlock；经公共 SDK 的 IOInjector 过来的是
+// []pubsdk.ContentBlock。两者字段一致但 Go 不会自动转换，只认一种的后果是
+// 另一种被静默丢弃——插件注入的图到 payload 就断了，且不报错。
+func TestInjectedBlocks_AcceptsBothStaticTypes(t *testing.T) {
+	t.Run("内核类型", func(t *testing.T) {
+		blocks, kind := injectedBlocks(map[string]interface{}{
+			"media_blocks": []agentAPI.ContentBlock{
+				{Type: "text", Text: "看图"},
+				{Type: "image_url", ImageURL: &agentAPI.ImageURL{URL: "data:image/png;base64,AAA"}},
+			},
+		})
+		if len(blocks) != 2 {
+			t.Fatalf("blocks = %d，期望 2", len(blocks))
+		}
+		if kind != "image" {
+			t.Errorf("mediaType = %q，期望 image", kind)
+		}
+	})
+
+	t.Run("公共SDK类型", func(t *testing.T) {
+		blocks, kind := injectedBlocks(map[string]interface{}{
+			"media_blocks": []pubsdk.ContentBlock{
+				{Type: "text", Text: "听音频"},
+				{Type: "audio_url", AudioURL: &pubsdk.AudioURL{URL: "data:audio/wav;base64,BBB"}},
+			},
+		})
+		if len(blocks) != 2 {
+			t.Fatalf("blocks = %d，期望 2（公共 SDK 类型被静默丢弃）", len(blocks))
+		}
+		if kind != "audio" {
+			t.Errorf("mediaType = %q，期望 audio", kind)
+		}
+		// 转换必须保留 URL，否则块到了模型手上是空的
+		if blocks[1].AudioURL == nil || blocks[1].AudioURL.URL != "data:audio/wav;base64,BBB" {
+			t.Errorf("AudioURL 转换丢失: %+v", blocks[1].AudioURL)
+		}
+	})
+
+	t.Run("图优先于音频", func(t *testing.T) {
+		_, kind := injectedBlocks(map[string]interface{}{
+			"media_blocks": []agentAPI.ContentBlock{
+				{Type: "audio_url", AudioURL: &agentAPI.AudioURL{URL: "a"}},
+				{Type: "image_url", ImageURL: &agentAPI.ImageURL{URL: "b"}},
+			},
+		})
+		if kind != "image" {
+			t.Errorf("mediaType = %q，期望 image", kind)
+		}
+	})
+
+	t.Run("无媒体块", func(t *testing.T) {
+		blocks, kind := injectedBlocks(map[string]interface{}{"content": "纯文本"})
+		if blocks != nil || kind != "" {
+			t.Errorf("无 media_blocks 时应返回 (nil,\"\")，实际 (%v,%q)", blocks, kind)
+		}
+	})
+
+	t.Run("ImageURL 的 Detail 透传", func(t *testing.T) {
+		blocks, _ := injectedBlocks(map[string]interface{}{
+			"media_blocks": []pubsdk.ContentBlock{
+				{Type: "image_url", ImageURL: &pubsdk.ImageURL{URL: "u", Detail: "high"}},
+			},
+		})
+		if len(blocks) != 1 || blocks[0].ImageURL.Detail != "high" {
+			t.Errorf("Detail 未透传: %+v", blocks)
+		}
+	})
+}
+
+// ---------- resolveInput ----------
+
+func TestResolveInput_UnifiesAllModalities(t *testing.T) {
+	a, _ := newInputTestAgent(t)
+
+	t.Run("用户上传图片", func(t *testing.T) {
+		in, ok := a.resolveInput(&agentIO.InputEvent{
+			Source:  "qq",
+			Type:    "image",
+			Payload: map[string]interface{}{"data": "AAAA", "mime": "image/png"},
+		})
+		if !ok {
+			t.Fatal("图片输入被判为无效")
+		}
+		if in.mediaType != "image" || in.captureTool != "input_image" {
+			t.Errorf("mediaType=%q captureTool=%q", in.mediaType, in.captureTool)
+		}
+		if in.text == "" {
+			t.Error("纯媒体输入应有 alt 文案作为文本落点")
+		}
+		if len(in.blocks) == 0 {
+			t.Error("图片应转成内容块")
+		}
+	})
+
+	t.Run("插件注入的媒体", func(t *testing.T) {
+		in, ok := a.resolveInput(&agentIO.InputEvent{
+			Source: "myplugin",
+			Type:   "text",
+			Payload: map[string]interface{}{
+				"content": "帮我看看这张图",
+				"media_blocks": []pubsdk.ContentBlock{
+					{Type: "image_url", ImageURL: &pubsdk.ImageURL{URL: "data:image/png;base64,AAA"}},
+				},
+			},
+		})
+		if !ok {
+			t.Fatal("带媒体的文本输入被判为无效")
+		}
+		if in.text != "帮我看看这张图" {
+			t.Errorf("text = %q", in.text)
+		}
+		if len(in.blocks) != 1 || in.mediaType != "image" {
+			t.Errorf("blocks=%d mediaType=%q —— 插件注入的媒体到 payload 就断了", len(in.blocks), in.mediaType)
+		}
+		if in.captureTool != "inject_myplugin" {
+			t.Errorf("captureTool = %q，期望带来源便于溯源", in.captureTool)
+		}
+	})
+
+	t.Run("只带图不带字也合法", func(t *testing.T) {
+		_, ok := a.resolveInput(&agentIO.InputEvent{
+			Source: "myplugin",
+			Type:   "text",
+			Payload: map[string]interface{}{
+				"media_blocks": []agentAPI.ContentBlock{
+					{Type: "image_url", ImageURL: &agentAPI.ImageURL{URL: "u"}},
+				},
+			},
+		})
+		if !ok {
+			t.Error("只带媒体不带文本应视为有效输入（插件注入常这样）")
+		}
+	})
+
+	t.Run("文本与媒体都空才无效", func(t *testing.T) {
+		if _, ok := a.resolveInput(&agentIO.InputEvent{
+			Source:  "cli",
+			Type:    "text",
+			Payload: map[string]interface{}{"content": ""},
+		}); ok {
+			t.Error("空输入应被拒")
+		}
+	})
+
+	t.Run("纯文本", func(t *testing.T) {
+		in, ok := a.resolveInput(&agentIO.InputEvent{
+			Source:  "cli",
+			Type:    "text",
+			Payload: map[string]interface{}{"content": "你好"},
+		})
+		if !ok || in.text != "你好" || len(in.blocks) != 0 || in.mediaType != "" {
+			t.Errorf("纯文本路径异常: ok=%v in=%+v", ok, in)
+		}
+	})
+}
+
+// ---------- 模型工具侧：memory_digests 结构化传递 ----------
+
+// 模型只知道 digest（从对话或 memory_recall 的「关联媒体」读到）。
+// 它不再需要自己拼任何标记：digest 作为结构化字段随三元组提交。
+func TestResolveMediaDigestsAndNoMarkerText(t *testing.T) {
+	a, ms := newInputTestAgent(t)
+	digest, err := ms.Put([]byte("marker-bytes"), media.Item{MIME: "image/png"})
+	if err != nil {
+		t.Fatalf("Put: %v", err)
+	}
+
+	t.Run("短digest补全", func(t *testing.T) {
+		got := a.resolveMediaDigests([]string{digest[:12]})
+		if len(got) != 1 || got[0] != digest {
+			t.Fatalf("短 digest 应补全为完整 digest，得到 %v", got)
+		}
+	})
+
+	t.Run("无法解析的digest被丢弃", func(t *testing.T) {
+		if got := a.resolveMediaDigests([]string{"ffffffffffff"}); len(got) != 0 {
+			t.Errorf("不存在的 digest 不该保留: %v", got)
+		}
+	})
+
+	t.Run("无媒体存储时返回nil", func(t *testing.T) {
+		bare := &Agent{}
+		if got := bare.resolveMediaDigests([]string{digest}); got != nil {
+			t.Errorf("无媒体存储时应返回 nil: %v", got)
+		}
+	})
+}
+
+// 句子文本必须保持原样：媒体归属走结构化块边，不往文本里贴 marker。
+func TestMemoryCommit_DoesNotPolluteSentenceText(t *testing.T) {
+	dir := t.TempDir()
+	g, err := memory.NewGraphDB(filepath.Join(dir, "graph.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer g.Close()
+	ms, err := media.New(filepath.Join(dir, "media"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer ms.Close()
+	a := &Agent{memory: g, mediaStore: ms}
+
+	digest, _ := ms.Put([]byte("clean-sentence"), media.Item{MIME: "image/png"})
+
+	sentence := "用户发来一张图。"
+	triples := []memory.Triple{{
+		Subject: "用户", Relation: "发来", Object: "图片",
+		SentenceText: sentence,
+		MediaDigests: a.resolveMediaDigests([]string{digest[:12]}),
+	}}
+	if _, _, _, err := a.commitTriplesWithMedia(triples, "s1", 0, nil); err != nil {
+		t.Fatal(err)
+	}
+
+	res, err := a.memory.Recall([]string{"用户"}, nil, 2, "")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(res.Relations) == 0 {
+		t.Fatal("召回为空")
+	}
+	if res.Relations[0].SentenceText != sentence {
+		t.Errorf("句子文本被污染: %q", res.Relations[0].SentenceText)
+	}
+	blocks, err := a.memory.BlocksForNode("sentence", strconv.FormatInt(res.Relations[0].SentenceID, 10))
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(blocks) != 1 || blocks[0].PayloadDigest != digest {
+		t.Errorf("块应挂到句子，实际 %+v", blocks)
+	}
+}
+
+// ---------- resolveMediaDigests ----------
+
+func TestResolveMediaDigests(t *testing.T) {
+	a, ms := newInputTestAgent(t)
+	d1, _ := ms.Put([]byte("one"), media.Item{MIME: "image/png"})
+	d2, _ := ms.Put([]byte("two"), media.Item{MIME: "image/png"})
+
+	got := a.resolveMediaDigests([]string{d1[:10], d2, d1, "ffffffffffff"})
+	if len(got) != 2 {
+		t.Fatalf("got = %v，期望 2 条（去重 + 丢弃无法解析的）", got)
+	}
+	for _, d := range got {
+		if len(d) != 64 {
+			t.Errorf("应返回完整 digest，实际 %q", d)
+		}
+	}
+
+	if a.resolveMediaDigests(nil) != nil {
+		t.Error("空输入应返回 nil")
+	}
+	bare := &Agent{}
+	if bare.resolveMediaDigests([]string{d1}) != nil {
+		t.Error("无媒体存储时应返回 nil")
+	}
+}
+
+// ---------- 文档持有的一等记忆块 ----------
+
+func TestDocCommit_StoresBlocks(t *testing.T) {
+	// doc_commit 带 media_digests 时，媒体应作为一等块直接存在文档上，
+	// 并随 doc 一起持久化（不再靠 media_refs 保活）。
+	dir := t.TempDir()
+	ds := document.NewStore(filepath.Join(dir, "docs"), memory.TokenizeWords)
+	if err := ds.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer ds.Stop()
+
+	ms, err := media.New(filepath.Join(dir, "media"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer ms.Close()
+
+	d1, _ := ms.Put([]byte("doc-one"), media.Item{MIME: "image/png"})
+	d2, _ := ms.Put([]byte("doc-two"), media.Item{MIME: "image/png"})
+
+	doc := &document.Doc{ID: "doc_x", Summary: "s", Content: "c"}
+	for _, d := range []string{d1, d2} {
+		if b, ok := (&Agent{mediaStore: ms}).blockFromDigest(d); ok {
+			doc.Blocks = append(doc.Blocks, b)
+		}
+	}
+	if err := ds.Insert(doc); err != nil {
+		t.Fatal(err)
+	}
+
+	blocks := ds.Blocks()
+	if len(blocks) != 2 {
+		t.Fatalf("文档应持有 2 个块，实际 %d", len(blocks))
+	}
+	seen := map[string]bool{}
+	for _, b := range blocks {
+		seen[b.PayloadDigest] = true
+	}
+	if !seen[d1] || !seen[d2] {
+		t.Errorf("块 digest 不对: %+v", blocks)
+	}
+}
+
+// ---------- 文档持有块标签（doc_query 展示用） ----------
+
+func TestBlockLabelsForDoc(t *testing.T) {
+	a, ms := newInputTestAgent(t)
+	digest, _ := ms.Put([]byte("ctx-bytes"), media.Item{MIME: "image/png"})
+	b, ok := a.blockFromDigest(digest)
+	if !ok {
+		t.Fatal("blockFromDigest 失败")
+	}
+
+	t.Run("从文档持有的一等块渲染", func(t *testing.T) {
+		got := a.blockLabelsForDoc(&document.Doc{ID: "doc_1", Blocks: []memory.MemoryBlock{b}})
+		if !strings.Contains(got, shortDigest(digest)) {
+			t.Errorf("标签应含短 digest: %q", got)
+		}
+		if !strings.Contains(got, "image/png") {
+			t.Errorf("标签应含 MIME: %q", got)
+		}
+	})
+
+	t.Run("无块时为空", func(t *testing.T) {
+		if got := a.blockLabelsForDoc(&document.Doc{ID: "doc_x", Content: "普通正文"}); got != "" {
+			t.Errorf("应返回空串，实际 %q", got)
+		}
+	})
+
+	t.Run("无媒体存储", func(t *testing.T) {
+		bare := &Agent{}
+		if got := bare.blockLabelsForDoc(&document.Doc{ID: "doc_x"}); got != "" {
+			t.Errorf("无媒体存储时应返回空串，实际 %q", got)
+		}
+	})
+}
+
+// ---------- mediaLabel ----------
+
+// 媒体标签的唯一生成处：只含 MIME 与短 digest，不含任何生成的描述。
+func TestMediaLabel(t *testing.T) {
+	a, ms := newInputTestAgent(t)
+	_ = a
+
+	digest, _ := ms.Put([]byte("labelled"), media.Item{MIME: "image/png"})
+	it, err := ms.Stat(digest)
+	if err != nil {
+		t.Fatal(err)
+	}
+	got := mediaLabel(it)
+	if !strings.Contains(got, "image/png") {
+		t.Errorf("标签应含 MIME: %q", got)
+	}
+	if !strings.Contains(got, shortDigest(digest)) {
+		t.Errorf("必须带短 digest 供反查: %q", got)
+	}
+	if got := mediaLabel(nil); got != "" {
+		t.Errorf("nil 应返回空串，实际 %q", got)
+	}
+}
+
+// ---------- 模型工具端到端：memory_commit / doc_commit / doc_query ----------
+
+func newToolTestAgent(t *testing.T) (*Agent, *media.Store) {
+	t.Helper()
+	dir := t.TempDir()
+
+	g, err := memory.NewGraphDB(filepath.Join(dir, "graph.db"))
+	if err != nil {
+		t.Fatalf("NewGraphDB: %v", err)
+	}
+	t.Cleanup(func() { g.Close() })
+
+	ds := document.NewStore(filepath.Join(dir, "documents"), memory.TokenizeWords)
+	if err := ds.Start(); err != nil {
+		t.Fatalf("doc store: %v", err)
+	}
+	t.Cleanup(func() { ds.Stop() })
+
+	ms, err := media.New(filepath.Join(dir, "media"))
+	if err != nil {
+		t.Fatalf("media.New: %v", err)
+	}
+	t.Cleanup(func() { ms.Close() })
+
+	emb := memory.NewStaticEmbedder("")
+	a := &Agent{
+		id:         "tester",
+		memory:     g,
+		docStore:   ds,
+		mediaStore: ms,
+		context:    NewRelevanceContext("", emb),
+	}
+	return a, ms
+}
+
+// memory_commit 带 media_digests：三元组入库后必须能从句子反查回那份字节。
+func TestToolMemoryCommit_BindsMedia(t *testing.T) {
+	a, ms := newToolTestAgent(t)
+	digest, _ := ms.Put([]byte("commit-bytes"), media.Item{MIME: "image/png"})
+
+	out := a.executeMemoryTool(agentAPI.ToolCall{
+		Name: "memory_commit",
+		Arguments: map[string]interface{}{
+			"triples": []interface{}{
+				map[string]interface{}{
+					"subject":       "配色方案",
+					"relation":      "参考",
+					"object":        "三色带图",
+					"media_digests": []interface{}{digest[:12]},
+				},
+			},
+		},
+	})
+	if !strings.Contains(out, "关联") {
+		t.Errorf("返回值应告知模型媒体已关联: %q", out)
+	}
+
+	res, err := a.memory.Recall([]string{"配色方案"}, nil, 2, "")
+	if err != nil {
+		t.Fatalf("Recall: %v", err)
+	}
+	if len(res.Relations) == 0 || res.Relations[0].SentenceID == 0 {
+		t.Fatal("没有句子落点 —— 媒体引用无从挂起")
+	}
+	blocks, err := a.memory.BlocksForNode("sentence", strconv.FormatInt(res.Relations[0].SentenceID, 10))
+	if err != nil {
+		t.Fatalf("BlocksForNode: %v", err)
+	}
+	if len(blocks) != 1 || blocks[0].PayloadDigest != digest {
+		t.Errorf("句子块 = %+v，期望 [%s]", blocks, digest)
+	}
+}
+
+// 不带 media_digests 时行为与本特性上线前一致（不多写句子、不报错）。
+func TestToolMemoryCommit_WithoutMedia(t *testing.T) {
+	a, _ := newToolTestAgent(t)
+	out := a.executeMemoryTool(agentAPI.ToolCall{
+		Name: "memory_commit",
+		Arguments: map[string]interface{}{
+			"triples": []interface{}{
+				map[string]interface{}{"subject": "甲方", "relation": "签署", "object": "合同"},
+			},
+		},
+	})
+	if strings.Contains(out, "失败") {
+		t.Errorf("普通提交不该失败: %q", out)
+	}
+	if strings.Contains(out, "关联") {
+		t.Errorf("无媒体时不该提媒体: %q", out)
+	}
+}
+
+// sentence_text 必须透传：丢了它，图谱就回不到原文。
+func TestToolMemoryCommit_CarriesSentenceText(t *testing.T) {
+	a, _ := newToolTestAgent(t)
+	a.executeMemoryTool(agentAPI.ToolCall{
+		Name: "memory_commit",
+		Arguments: map[string]interface{}{
+			"triples": []interface{}{
+				map[string]interface{}{
+					"subject":       "李四",
+					"relation":      "住在",
+					"object":        "杭州",
+					"sentence_text": "李四搬到杭州已经三年了。",
+				},
+			},
+		},
+	})
+	res, _ := a.memory.Recall([]string{"李四"}, nil, 2, "")
+	if len(res.Relations) == 0 {
+		t.Fatal("召回为空")
+	}
+	if res.Relations[0].SentenceText != "李四搬到杭州已经三年了。" {
+		t.Errorf("SentenceText = %q", res.Relations[0].SentenceText)
+	}
+}
+
+// doc_commit 带 media_digests：媒体成为文档直接持有的一等块；正文保持原样。
+func TestToolDocCommit_BindsMedia(t *testing.T) {
+	a, ms := newToolTestAgent(t)
+	digest, _ := ms.Put([]byte("doc-commit-bytes"), media.Item{MIME: "image/png"})
+
+	out := a.executeDocTool(agentAPI.ToolCall{
+		Name: "doc_commit",
+		Arguments: map[string]interface{}{
+			"content":       "这是一篇带图的笔记正文。",
+			"summary":       "带图笔记",
+			"media_digests": []interface{}{digest[:12]},
+		},
+	})
+	if !strings.Contains(out, "关联") {
+		t.Errorf("返回值应告知模型媒体已关联: %q", out)
+	}
+
+	docs := a.docStore.RecentDocs(5)
+	if len(docs) == 0 {
+		t.Fatal("文档未写入")
+	}
+	d := docs[0]
+	if strings.Contains(d.Content, "image/png") {
+		t.Errorf("正文不该被媒体标记污染: %q", d.Content)
+	}
+	var held bool
+	for _, b := range d.Blocks {
+		if b.PayloadDigest == digest {
+			held = true
+		}
+	}
+	if !held {
+		t.Errorf("文档应持有一等记忆块 [%s]，实际 %+v", digest, d.Blocks)
+	}
+}
+
+// doc_query 必须把媒体说明附在返回值里，否则模型检索到带图文档也不知道有图。
+func TestToolDocQuery_ShowsMedia(t *testing.T) {
+	a, ms := newToolTestAgent(t)
+	digest, _ := ms.Put([]byte("query-bytes"), media.Item{MIME: "image/png"})
+
+	a.executeDocTool(agentAPI.ToolCall{
+		Name: "doc_commit",
+		Arguments: map[string]interface{}{
+			"content":       "紫蓝红三色带配色说明正文",
+			"summary":       "紫蓝红三色带",
+			"media_digests": []interface{}{digest},
+		},
+	})
+
+	a.executeDocTool(agentAPI.ToolCall{
+		Name:      "doc_query",
+		Arguments: map[string]interface{}{"query": "紫蓝红三色带 配色说明", "top_k": float64(3)},
+	})
+
+	// 正文进的是 cold_storage 事件（工具返回值只给引用编号），媒体说明也在那里。
+	var found bool
+	for _, e := range a.context.Recent(10) {
+		if strings.Contains(e.Response, shortDigest(digest)) {
+			found = true
+		}
+	}
+	if !found {
+		t.Error("doc_query 未把媒体说明带进上下文 —— 模型不知道这篇文档带过图")
+	}
+}
+
+// 无媒体存储时三个工具的行为与本特性上线前完全一致。
+func TestTools_NilMediaStoreDegrades(t *testing.T) {
+	a, _ := newToolTestAgent(t)
+	a.mediaStore = nil
+
+	out := a.executeMemoryTool(agentAPI.ToolCall{
+		Name: "memory_commit",
+		Arguments: map[string]interface{}{
+			"triples": []interface{}{
+				map[string]interface{}{
+					"subject": "无存储", "relation": "仍可", "object": "提交",
+					"media_digests": []interface{}{"aabbccddeeff"},
+				},
+			},
+		},
+	})
+	if strings.Contains(out, "失败") {
+		t.Errorf("无媒体存储时提交不该失败: %q", out)
+	}
+
+	out = a.executeDocTool(agentAPI.ToolCall{
+		Name: "doc_commit",
+		Arguments: map[string]interface{}{
+			"content":       "无媒体存储的文档",
+			"media_digests": []interface{}{"aabbccddeeff"},
+		},
+	})
+	if strings.Contains(out, "失败") {
+		t.Errorf("无媒体存储时文档写入不该失败: %q", out)
+	}
+}

internal/agent/core/medialive_test.go

@@ -0,0 +1,545 @@
+//go:build medialive
+
+// 媒体记忆自动触发链的集成测试。
+//
+// 与其他媒体测试的区别：**不手工调用任何一步**。这里只做两件事——
+// 往 IOManager 注入一个 image 事件，然后等。之后全部由生产代码自己走：
+//
+//	processMediaInput → captureBlockMedia（入 CAS）
+//	  → Prune（L0→L2 块迁移）
+//	  → describePendingMedia（真实视觉模型生成描述）
+//	  → archiveColdDocs → commitTriplesWithMedia → bindSentenceBlocks（L2→L3）
+//	  → 第二轮提问，验证 agent 真能召回
+//
+// 为什么必须这样测：单测能证明每个函数正确，却证明不了它**被接上了**——
+// 手工注入 store 的单测全绿而生产链路断开，是本文件要拦的典型缺陷。
+//
+// 需要真实 LLM，因此加 medialive build tag，默认 go test 不跑：
+//
+//	MEDIALIVE_BASE_URL=http://127.0.0.1:8081/v1 \
+//	MEDIALIVE_API_KEY=sk-xxx \
+//	MEDIALIVE_MODEL=claude-opus-5 \
+//	MEDIALIVE_ADAPTER=openai \
+//	go test -tags medialive ./internal/agent/core/ -run TestMediaLive -v -timeout 20m
+//
+// 源、模型、密钥全部由调用方显式指定，测试自己不猜任何默认值——
+// 猜一个默认端点会让测试在别人机器上打到意料之外的服务。
+package core
+
+import (
+	"bytes"
+	"compress/zlib"
+	"encoding/binary"
+	"fmt"
+	"hash/crc32"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+	"time"
+
+	agentAPI "gitcode.com/JianFeeeee/HomeAgent/internal/agent/api"
+	agentIO "gitcode.com/JianFeeeee/HomeAgent/internal/agent/io"
+	luaVM "gitcode.com/JianFeeeee/HomeAgent/internal/lua"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/document"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/media"
+	"gitcode.com/JianFeeeee/HomeAgent/pkg/types"
+)
+
+// liveCfg 是调用方通过环境变量显式提供的 LLM 源配置。
+type liveCfg struct {
+	baseURL string
+	apiKey  string
+	model   string
+	adapter string
+}
+
+// requireLiveCfg 读取环境变量；缺任何一项就 Skip 而非猜默认值。
+//
+// 刻意不提供 fallback：一个猜出来的 base_url 可能打到调用者机器上
+// 完全不相干的服务，而测试会把那次调用的失败报成"媒体记忆有问题"。
+func requireLiveCfg(t *testing.T) liveCfg {
+	t.Helper()
+	c := liveCfg{
+		baseURL: os.Getenv("MEDIALIVE_BASE_URL"),
+		apiKey:  os.Getenv("MEDIALIVE_API_KEY"),
+		model:   os.Getenv("MEDIALIVE_MODEL"),
+		adapter: os.Getenv("MEDIALIVE_ADAPTER"),
+	}
+	var missing []string
+	if c.baseURL == "" {
+		missing = append(missing, "MEDIALIVE_BASE_URL")
+	}
+	if c.apiKey == "" {
+		missing = append(missing, "MEDIALIVE_API_KEY")
+	}
+	if c.model == "" {
+		missing = append(missing, "MEDIALIVE_MODEL")
+	}
+	if c.adapter == "" {
+		missing = append(missing, "MEDIALIVE_ADAPTER")
+	}
+	if len(missing) > 0 {
+		t.Skipf("缺少环境变量 %s——本测试要求调用方显式指定源/模型/密钥，不使用任何默认值",
+			strings.Join(missing, ", "))
+	}
+	return c
+}
+
+// livePNG 造一张横向三色带真 PNG（手工拼 IHDR/IDAT/IEND）。
+//
+// 用可辨认的纯色而非随机字节：断言要能检查"模型是否真的看到了内容"，
+// 随机噪声无法产生可验证的描述。
+func livePNG(t *testing.T, w, h int, colors [][3]byte) []byte {
+	t.Helper()
+	chunk := func(typ string, data []byte) []byte {
+		var b bytes.Buffer
+		if err := binary.Write(&b, binary.BigEndian, uint32(len(data))); err != nil {
+			t.Fatal(err)
+		}
+		body := append([]byte(typ), data...)
+		b.Write(body)
+		if err := binary.Write(&b, binary.BigEndian, crc32.ChecksumIEEE(body)); err != nil {
+			t.Fatal(err)
+		}
+		return b.Bytes()
+	}
+	var raw bytes.Buffer
+	for y := 0; y < h; y++ {
+		raw.WriteByte(0) // filter type: none
+		c := colors[y*len(colors)/h]
+		for x := 0; x < w; x++ {
+			raw.Write(c[:])
+		}
+	}
+	var comp bytes.Buffer
+	zw := zlib.NewWriter(&comp)
+	if _, err := zw.Write(raw.Bytes()); err != nil {
+		t.Fatal(err)
+	}
+	zw.Close()
+
+	var ihdr bytes.Buffer
+	binary.Write(&ihdr, binary.BigEndian, uint32(w))
+	binary.Write(&ihdr, binary.BigEndian, uint32(h))
+	ihdr.Write([]byte{8, 2, 0, 0, 0}) // 8-bit truecolor
+
+	var out bytes.Buffer
+	out.Write([]byte{0x89, 'P', 'N', 'G', '\r', '\n', 0x1a, '\n'})
+	out.Write(chunk("IHDR", ihdr.Bytes()))
+	out.Write(chunk("IDAT", comp.Bytes()))
+	out.Write(chunk("IEND", nil))
+	return out.Bytes()
+}
+
+// liveEnv 是一套完整但完全独立的 agent 运行环境。
+type liveEnv struct {
+	agent    *Agent
+	io       *agentIO.IOManager
+	mediaSt  *media.Store
+	docStore *document.Store
+	graph    *memory.GraphDB
+	dir      string
+}
+
+// newLiveEnv 构造真 Agent：真 provider、真 CAS、真图库、真文档库。
+//
+// 不注册任何插件：本测试关心记忆链路，插件会引入无关的外部副作用
+// （网络轮询、写文件），而且生产插件目录里的进程不该被测试碰到。
+func newLiveEnv(t *testing.T, c liveCfg) *liveEnv {
+	t.Helper()
+	dir := t.TempDir()
+
+	vm := luaVM.NewVM(filepath.Join(dir, "adapters"))
+	if err := vm.Start(); err != nil {
+		t.Fatalf("lua vm: %v", err)
+	}
+	t.Cleanup(vm.Stop)
+
+	// Vision: true —— 能力是声明的，不是探测的。网关可能静默剥离
+	// image_url 后仍返回 200，从响应无法推断它到底看见了没有。
+	prov := agentAPI.NewLuaAdaptedProvider(agentAPI.BaseConfig{
+		Model: c.model, BaseURL: c.baseURL, APIKey: c.apiKey,
+		MaxTokens: 1200, Temperature: 0.3, Vision: true,
+	}, vm, "medialive", c.adapter)
+
+	pm := agentAPI.NewProviderManager()
+	pm.Register("medialive", prov)
+	if err := pm.SetDefault("medialive"); err != nil {
+		t.Fatalf("set default provider: %v", err)
+	}
+
+	ms, err := media.New(filepath.Join(dir, "media"))
+	if err != nil {
+		t.Fatalf("media store: %v", err)
+	}
+	t.Cleanup(func() { ms.Close() })
+
+	graph, err := memory.NewGraphDB(filepath.Join(dir, "graph.db"))
+	if err != nil {
+		t.Fatalf("graph: %v", err)
+	}
+	t.Cleanup(func() { graph.Close() })
+
+	docStore := document.NewStore(filepath.Join(dir, "docs"), memory.TokenizeWords)
+	if err := docStore.Start(); err != nil {
+		t.Fatalf("doc store: %v", err)
+	}
+	t.Cleanup(docStore.Stop)
+
+	io := agentIO.NewIOManager()
+
+	a := New(AgentConfig{
+		ID:              types.AgentID("medialive"),
+		SystemPrompt:    "你是一个有长期记忆的助手。回答简洁准确。",
+		Provider:        prov,
+		ProviderManager: pm,
+		IO:              io,
+		Memory:          graph,
+		DocStore:        docStore,
+		MediaStore:      ms,
+		StageHost:       NewStageHost(),
+		MaxContextSize:  3, // 故意压低：第二轮就能触发 Prune 归档
+		InputProcessing: types.InputProcessingConfig{},
+	})
+
+	// 排空 outputCh：容量 256，但长跑不消费会堵住 emitResponse。
+	go func() {
+		for {
+			select {
+			case <-io.OutputChan():
+			case <-a.ctx.Done():
+				return
+			}
+		}
+	}()
+
+	return &liveEnv{agent: a, io: io, mediaSt: ms, docStore: docStore, graph: graph, dir: dir}
+}
+
+// TestMediaLive_AutoTriggerChain 全自动触发链：只注入事件，不手工调任何一步。
+func TestMediaLive_AutoTriggerChain(t *testing.T) {
+	c := requireLiveCfg(t)
+	env := newLiveEnv(t, c)
+	a := env.agent
+	defer a.Stop()
+
+	img := livePNG(t, 96, 96, [][3]byte{{128, 0, 255}, {0, 64, 255}, {255, 0, 0}})
+	t.Logf("测试图片: %d 字节（紫/蓝/红三色带）", len(img))
+
+	// ── 阶段 1：注入 image 事件，验证 CAS 自动落盘 ──
+	//
+	// 直接调 handleInput 而不启 eventLoop：eventLoop 是纯转发（select →
+	// handleInput），走同一条代码路径，但同步调用让断言不必猜时序。
+	evt := &agentIO.InputEvent{
+		RequestID:     "live-1",
+		Source:        "test_channel",
+		Type:          "image",
+		OutputChannel: "test_channel",
+		Payload: map[string]interface{}{
+			"data": mediaB64(img),
+			"mime": "image/png",
+			"alt":  "一张测试图片",
+		},
+	}
+
+	t0 := time.Now()
+	a.handleInput(evt)
+	t.Logf("第一轮（含真实 LLM 往返）耗时 %.1fs", time.Since(t0).Seconds())
+
+	// 媒体不再有文字描述：CAS 里只有字节、元数据与向量。
+	// 这里直接按 digest 定位刚落的图（不再有 Pending 队列）。
+	st := env.mediaSt.Stats()
+	if st["count"].(int) != 1 {
+		t.Fatalf("CAS 应自动收到 1 张图，实际 %v 张（captureBlockMedia 未被触发？）", st["count"])
+	}
+	var digest string
+	var found bool
+	for _, e := range a.context.Recent(0) {
+		for _, b := range e.Blocks {
+			digest, found = b.PayloadDigest, true
+		}
+	}
+	if !found {
+		t.Fatal("无法从上下文块定位刚落盘的图")
+	}
+	it0, err := env.mediaSt.Stat(digest)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Logf("✓ 阶段1 CAS 自动落盘: digest=%s size=%d tool=%s",
+		digest[:12], it0.Size, it0.Tool)
+
+	stored, err := env.mediaSt.Get(digest)
+	if err != nil || !bytes.Equal(stored, img) {
+		t.Fatalf("落盘内容与原图不一致 (err=%v)", err)
+	}
+
+	// ── 阶段 2：一等记忆块自动挂到 ContextEvent 上 ──
+	//
+	// 这一步验证 bindEventMedia：事件必须拿到 ID 并直接持有块；
+	// 事件文本必须保持原样（不再往正文里贴媒体标记）。
+	var evtID string
+	for _, e := range a.context.Recent(0) {
+		if len(e.Blocks) > 0 {
+			evtID = e.ID
+			if strings.Contains(e.Input, digest[:12]) {
+				t.Error("事件 Input 里被写入了媒体标记——描述式索引链应该已经拆除")
+			}
+			if e.Blocks[0].PayloadDigest != digest {
+				t.Fatalf("事件持有的块 digest 不对: %+v", e.Blocks)
+			}
+			break
+		}
+	}
+	if evtID == "" {
+		t.Fatal("没有任何 ContextEvent 挂上媒体（bindEventMedia 未被触发）")
+	}
+	t.Logf("✓ 阶段2 块自动绑定: event=%s", evtID)
+
+	// ── 阶段 3：媒体只按自己的向量被索引，不再生成任何描述 ──
+	if it, err := env.mediaSt.Stat(digest); err != nil {
+		t.Fatal(err)
+	} else if len(it.Vec) == 0 {
+		// 未配置多模态空间时就没有向量——这是合法的降级状态，
+		// 但要明确报出来，而不是靠描述文本假装能检索。
+		t.Log("未配置多模态空间：本图无向量，之后只能靠块结构召回 digest")
+	} else {
+		t.Logf("✓ 阶段3 已写入原生向量: dim=%d", len(it.Vec))
+	}
+
+	// ── 阶段 4：Prune 自动把块从 L0 迁移到 L2 ──
+	//
+	// MaxContextSize=3，多注入几轮文本把带图事件挤出活跃上下文。
+	// 迁移的是块本身（同一身份换层）；L0 中不该再留下它。
+	// 填充数量必须 > Prune 内部固定的 10 条保护窗口。
+	//
+	// Prune 无条件保护最后 10 条事件（protected := events[len-10:]），
+	// 只在更早的部分里挑归档对象。填 4 条时总数才 5，全落进保护窗口、
+	// candidates 为空、直接返回 0——这不是缺陷，是"最近的对话不该被归档"
+	// 的设计。带图事件必须被推到第 11 条之前才可能被归档。
+	const fillerCount = 14
+	for i := 0; i < fillerCount; i++ {
+		a.context.Append(ContextEvent{
+			Timestamp: time.Now(),
+			Source:    "filler",
+			Input:     fmt.Sprintf("无关的填充对话 %d，用来把带图事件挤出活跃窗口", i),
+			Response:  "好的。",
+		})
+	}
+	archived := a.context.Prune("当前输入", a.maxContextSize-1, env.docStore)
+	t.Logf("Prune 归档 %d 条事件", archived)
+	if archived == 0 {
+		t.Fatal("Prune 未归档任何事件，无法验证引用转移")
+	}
+
+	docRefsFound := ""
+	for _, d := range env.docStore.RecentDocs(20) {
+		for _, b := range d.Blocks {
+			if b.PayloadDigest == digest {
+				docRefsFound = d.ID
+			}
+		}
+	}
+	if docRefsFound == "" {
+		t.Fatal("块未随归档事件迁移到 L2 文档")
+	}
+	// 同一块不能同时留在 L0。
+	for _, e := range a.context.Recent(0) {
+		for _, b := range e.Blocks {
+			if b.PayloadDigest == digest {
+				t.Errorf("块仍留在 L0（evt %s），违反单层不变量", e.ID)
+			}
+		}
+	}
+	t.Logf("✓ 阶段4 块自动迁移: context/%s → document/%s", evtID, docRefsFound)
+
+	// 迁移全程内容必须可读：块虽换了层，字节仍在。
+	if _, err := env.mediaSt.Get(digest); err != nil {
+		t.Fatalf("迁移后内容不可读: %v", err)
+	}
+
+	// ── 阶段 5：archiveColdDocs 自动把块连到 L3 文档节点 ──
+	//
+	// FindColdDocs(72h, 2) 要求文档足够"冷"，测试里新建的文档不满足，
+	// 因此把 LastAccess 往前推——这是为了触发生产代码路径，
+	// 而不是替代它（commitTriplesWithMedia/linkBlocksToDocument 全由它自己调）。
+	for _, d := range env.docStore.RecentDocs(20) {
+		if d.ID == docRefsFound {
+			d.LastAccess = time.Now().Add(-100 * time.Hour)
+			d.AccessCount = 0
+		}
+	}
+	a.archiveColdDocs()
+
+	// 块可能以 document --contains--> block（文档归档）或
+	// sentence --contains--> block（对话三元组）两种边存在。
+	sentRefs := 0
+	var boundSentence int64
+	docBound := 0
+	rows, err := env.graph.Recall(nil, nil, 1, "")
+	if err != nil {
+		t.Fatalf("graph recall: %v", err)
+	}
+	t.Logf("图库实体数 %d", len(rows.Entities))
+	docBlocks, err := env.graph.BlocksForNode("document", docRefsFound)
+	if err != nil {
+		t.Fatal(err)
+	}
+	docBound = len(docBlocks)
+	// 句子 id 是自增整数，扫前若干个足够覆盖本测试写入的量
+	for sid := int64(1); sid <= 40; sid++ {
+		blocks, err := env.graph.BlocksForNode("sentence", strconv.FormatInt(sid, 10))
+		if err == nil && len(blocks) > 0 {
+			sentRefs += len(blocks)
+			if boundSentence == 0 {
+				boundSentence = sid
+			}
+		}
+	}
+	if sentRefs == 0 && docBound == 0 {
+		t.Error("L2→L3 未写入任何块边——linkBlocksToDocument 未被 archiveColdDocs 触发")
+	} else if docBound > 0 {
+		t.Logf("✓ 阶段5 L3 自动写入: 文档 %s 持有 %d 个块", docRefsFound, docBound)
+		got := docBlocks
+		if got[0].PayloadDigest != digest {
+			t.Errorf("文档节点持有的块 digest 不对: %+v", got)
+		} else if raw, err := env.mediaSt.Get(got[0].PayloadDigest); err != nil || !bytes.Equal(raw, img) {
+			t.Errorf("从文档块取回的字节与原图不一致 (err=%v)", err)
+		} else {
+			t.Logf("✓ 阶段5 反查取回 %d 字节，与原图逐字节一致", len(raw))
+		}
+	} else {
+		t.Logf("✓ 阶段5 L3 自动写入: %d 个句子块，首个 sentences.id=%d", sentRefs, boundSentence)
+
+		got, err := env.agent.RecallBlocksForSentence(boundSentence)
+		if err != nil || len(got) == 0 || got[0].PayloadDigest != digest {
+			t.Errorf("从句子反查块失败: got=%+v err=%v", got, err)
+		} else if raw, err := env.mediaSt.Get(got[0].PayloadDigest); err != nil || !bytes.Equal(raw, img) {
+			t.Errorf("从句子取回的字节与原图不一致 (err=%v)", err)
+		} else {
+			t.Logf("✓ 阶段5 反查取回 %d 字节，与原图逐字节一致", len(raw))
+		}
+	}
+
+	// ── 阶段 6：内容随块存在，不被单独清理 ──
+	if _, err := env.mediaSt.Stat(digest); err != nil {
+		t.Fatalf("被记忆块持有的内容不存在了: %v", err)
+	}
+	t.Logf("✓ 阶段6 被持有内容仍在")
+
+	// ── 阶段 7：E2E — 第二轮提问，验证 agent 真能召回 ──
+	//
+	// 不再提供图片，只问"还记得吗"。能答出三色说明记忆链路端到端可用。
+	// L2 文档此刻已被 archiveColdDocs 删除（归档的语义就是搬完删源），
+	// 所以这一轮只能靠 L3 图库召回——而自动注入路径依赖 indexer。
+	// 生产由 main.go 注入并周期 Sync；测试里手工建一个并同步一次。
+	a.indexer = memory.NewIndexer(env.graph)
+	if err := a.indexer.Sync(); err != nil {
+		t.Fatalf("indexer sync: %v", err)
+	}
+	if mc := a.buildMemoryContext("测试图片", 0); mc != "" {
+		t.Logf("注入的记忆上下文: %s", truncRunes(mc, 200))
+	} else {
+		t.Log("图库召回为空（本测试不再依赖文本描述，仅记录现状）")
+	}
+
+	ask := &agentIO.InputEvent{
+		RequestID:     "live-2",
+		Source:        "test_channel",
+		Type:          "text",
+		OutputChannel: "test_channel",
+		Payload: map[string]interface{}{
+			"content": "你还记得我之前发给你的那张图片吗？它是什么样子的？请说出具体颜色。",
+		},
+	}
+	respCh := make(chan *agentIO.OutputEvent, 4)
+	ask.ResponseCh = respCh
+
+	t2 := time.Now()
+	a.handleInput(ask)
+	t.Logf("第二轮耗时 %.1fs", time.Since(t2).Seconds())
+
+	// 第二轮仍走真实 LLM：这里只验证链路不报错、有回复。
+	// 不再断言"答出紫/蓝/红"：图片的颜色信息只在原生向量里，
+	// 未配置多模态空间时模型本来就无从得知——那不属于记忆接线缺陷。
+	var answer string
+	select {
+	case out := <-respCh:
+		answer, _ = out.Payload["content"].(string)
+	case <-time.After(5 * time.Second):
+		t.Fatal("第二轮没有收到回复")
+	}
+	t.Logf("agent 回答: %s", truncRunes(answer, 220))
+	if strings.HasPrefix(answer, "处理错误:") {
+		t.Skipf("上游 LLM 调用失败，端到端召回无法判定: %s", truncRunes(answer, 160))
+	}
+	t.Logf("✓ 阶段7 E2E 链路贯通（召回能力取决于是否配置多模态向量空间）")
+
+	st = env.mediaSt.Stats()
+	t.Logf("收尾: %v 条 / %v 字节 / 类型 %v",
+		st["count"], st["total_bytes"], st["by_kind"])
+}
+
+// TestMediaLive_NegativeControl 阴性对照：没有媒体记忆时不该"记得"。
+//
+// 没有这条对照，任何"答出了具体内容"的结果都可能只是模型先验，
+// 无法区分真召回与猜测。
+func TestMediaLive_NegativeControl(t *testing.T) {
+	c := requireLiveCfg(t)
+	env := newLiveEnv(t, c)
+	a := env.agent
+	defer a.Stop()
+
+	ask := &agentIO.InputEvent{
+		RequestID:     "neg-1",
+		Source:        "test_channel",
+		Type:          "text",
+		OutputChannel: "test_channel",
+		Payload: map[string]interface{}{
+			"content": "你还记得我之前发给你的那张图片吗？它是什么样子的？请说出具体颜色。",
+		},
+	}
+	respCh := make(chan *agentIO.OutputEvent, 4)
+	ask.ResponseCh = respCh
+
+	a.handleInput(ask)
+
+	var answer string
+	select {
+	case out := <-respCh:
+		answer, _ = out.Payload["content"].(string)
+	case <-time.After(5 * time.Second):
+		t.Fatal("阴性对照没有收到回复")
+	}
+	t.Logf("无记忆时的回答: %s", truncRunes(answer, 200))
+
+	// 上游不可用时这条对照没有意义：它只能证明"没答出颜色"，
+	// 而原因是调用失败而非缺少记忆。据此判 PASS 属于假阳性。
+	if strings.HasPrefix(answer, "处理错误:") {
+		t.Skipf("上游 LLM 调用失败，阴性对照无法判定: %s", truncRunes(answer, 160))
+	}
+
+	guessed := strings.Contains(answer, "紫") &&
+		strings.Contains(answer, "蓝") &&
+		strings.Contains(answer, "红")
+	if guessed {
+		t.Errorf("无任何媒体记忆却猜中紫/蓝/红——"+
+			"说明阳性用例的通过可能只是先验偏好而非真召回: %s", truncRunes(answer, 300))
+	}
+}
+
+// mediaB64 返回不带 data URL 前缀的 base64（processMediaInput 自己拼前缀）。
+func mediaB64(b []byte) string {
+	return media.DataURL("image/png", b)[len("data:image/png;base64,"):]
+}
+
+func truncRunes(s string, n int) string {
+	r := []rune(strings.ReplaceAll(s, "\n", " "))
+	if len(r) <= n {
+		return string(r)
+	}
+	return string(r[:n]) + "…"
+}

internal/agent/core/medialoop.go

@@ -0,0 +1,199 @@
+package core
+
+import (
+	"errors"
+	"log"
+	"sync"
+	"sync/atomic"
+
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/vector"
+)
+
+// 媒体与记忆块的生命周期辅助。
+//
+// 媒体不单独做生命周期管理（没有 GC、没有引用计数）：blob 是记忆块的内容，
+// 块的创建/迁移/删除由记忆系统本身决定，块被永久删除时内容随之删除。
+// 图片不靠文本描述索引——它只按自己的统一空间向量被检索。
+
+// heldMediaDigests 汇总三层记忆当前持有的媒体 digest 集合。
+//
+// CAS 是全库字节存储，它的检索结果不等于「记忆里的媒体」——
+// 召回前用它把已无处可归的内容过滤掉。
+func (a *Agent) heldMediaDigests() map[string]bool {
+	held := map[string]bool{}
+	collect := func(blocks []memory.MemoryBlock) {
+		for _, b := range blocks {
+			if b.PayloadDigest != "" {
+				held[b.PayloadDigest] = true
+			}
+		}
+	}
+	if a.context != nil {
+		collect(a.context.Blocks())
+	}
+	if a.docStore != nil {
+		collect(a.docStore.Blocks())
+	}
+	if a.memory != nil {
+		if blocks, err := a.memory.MemoryBlocks(); err == nil {
+			collect(blocks)
+		}
+	}
+	return held
+}
+
+// payloadHeld 报告某个 digest 是否仍被三层记忆中的一等块持有。
+// 这是删除前的一次活查询（不是持久化账本）：同一份字节可能同时被多个块共享。
+func (a *Agent) payloadHeld(digest string) bool {
+	if digest == "" {
+		return false
+	}
+	if a.context != nil {
+		for _, b := range a.context.Blocks() {
+			if b.PayloadDigest == digest {
+				return true
+			}
+		}
+	}
+	if a.docStore != nil {
+		for _, b := range a.docStore.Blocks() {
+			if b.PayloadDigest == digest {
+				return true
+			}
+		}
+	}
+	if a.memory != nil {
+		if blocks, err := a.memory.MemoryBlocks(); err == nil {
+			for _, b := range blocks {
+				if b.PayloadDigest == digest {
+					return true
+				}
+			}
+		}
+	}
+	return false
+}
+
+// forgetPayloads 在记忆块被永久删除后删除它们的内容。
+//
+// 与文本块一致：删除块即删除内容。只有确认没有任何存活块仍共享该 digest
+// 时才删字节（同一张图可能被多个块引用）。
+func (a *Agent) forgetPayloads(digests []string) {
+	if a.mediaStore == nil {
+		return
+	}
+	for _, d := range digests {
+		if d == "" || a.payloadHeld(d) {
+			continue
+		}
+		if err := a.mediaStore.Delete(d); err != nil {
+			log.Printf("[media] 删除内容失败 %s: %v", shortDigest(d), err)
+		}
+	}
+}
+
+// reembedStaleMedia 在启动时批量迁移历史媒体向量到当前向量空间。
+//
+// 触发场景（任一变化都会导致旧向量无法参与查询）：
+//   - 切换模型（模型 A→模型 B，fp 变了）
+//   - 切换向量维度（ONNX→HTTP dim 512→1024）
+//   - 首次部署嵌入服务（历史无向量的媒体补算）
+//   - 嵌入服务离线后重新上线（失败条目 vec_model 仍为空）
+//
+// 并发策略：启动时用 worker pool 并行迁移，避免上千张图片串行耗时过长。
+// 并发数在 ONNX 内嵌路径下不超 CPU 核心数（避免 ONNX 并发限流），
+// 外部 API 路径下不超 8（避免打爆外部服务）。
+func (a *Agent) reembedStaleMedia() {
+	if a.multimodalSpace == nil || a.mediaStore == nil {
+		return
+	}
+	fp := a.multimodalSpace.Fingerprint()
+	digests, err := a.mediaStore.StaleVecDigestsAll(fp)
+	if err != nil {
+		log.Printf("[media] 查询需重算向量的媒体失败: %v", err)
+		return
+	}
+	if len(digests) == 0 {
+		log.Printf("[media] 无需迁移向量（所有媒体已与当前空间对齐 fp=%s）", shortFP(fp))
+		return
+	}
+
+	// 并发度：ONNX 内嵌不超过 4，外部 API 不超过 8（由配置或实际环境动态定）
+	workers := 4
+	if fp[:min(4, len(fp))] == "http:" {
+		workers = 8
+	}
+	log.Printf("[media] 启动向量迁移: %d 条 → 新空间 fp=%s dim=%d workers=%d",
+		len(digests), shortFP(fp), a.multimodalSpace.Dim(), workers)
+
+	jobs := make(chan string, workers*2)
+	var done, failed, unsupported int64
+	var failedMu sync.Mutex
+	var wg sync.WaitGroup
+
+	for i := 0; i < workers; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for d := range jobs {
+				switch err := a.reembedOne(d, fp); {
+				case err == nil:
+					atomic.AddInt64(&done, 1)
+				case errors.Is(err, vector.ErrModalityUnsupported):
+					// 该模态不在本空间内（如音频）：不重试、不计失败，
+					// 也不拿另一个模型的向量顶替。
+					atomic.AddInt64(&unsupported, 1)
+				default:
+					failedMu.Lock()
+					failed++
+					failedMu.Unlock()
+				}
+			}
+		}()
+	}
+
+	for i, d := range digests {
+		jobs <- d
+		// 每迁移 20 条输出进度日志，让用户看到迁移在推进
+		if (i+1)%20 == 0 {
+			log.Printf("[media] 向量迁移进度: %d/%d (done=%d failed=%d)", i+1, len(digests), atomic.LoadInt64(&done), failed)
+		}
+	}
+	close(jobs)
+	wg.Wait()
+	log.Printf("[media] 向量迁移完成: 成功=%d 失败=%d 不在本空间=%d 总计=%d fp=%s",
+		done, failed, unsupported, len(digests), shortFP(fp))
+}
+
+// reembedOne 为单条媒体重新计算向量并写入（stat/get 失败时跳过该条目）。
+//
+// 模态不在本空间覆盖范围时返回 ErrModalityUnsupported，调用方据此区分
+// 「永久无向量」与「本次失败重试」。
+func (a *Agent) reembedOne(digest, fp string) error {
+	it, err := a.mediaStore.Stat(digest)
+	if err != nil {
+		return err
+	}
+	data, err := a.mediaStore.Get(digest)
+	if err != nil {
+		return err
+	}
+	mime := it.MIME
+	if mime == "" {
+		mime = "image/png"
+	}
+	vec, err := a.multimodalSpace.EmbedImageDense(data, mime)
+	if err != nil {
+		return err
+	}
+	return a.mediaStore.SetVec(digest, vec, fp)
+}
+
+// shortFP 截断 fingerprint 为可读日志格式。
+func shortFP(fp string) string {
+	if len(fp) > 12 {
+		return fp[:12]
+	}
+	return fp
+}

internal/agent/core/medialoop_test.go

@@ -0,0 +1,187 @@
+package core
+
+import (
+	"context"
+	"fmt"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/document"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/media"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/vector"
+)
+
+// 媒体与记忆块的生命周期测试。
+//
+// 媒体没有独立生命周期管理（没有 GC、没有引用计数）：blob 是记忆块的内容，
+// 块的创建/迁移/删除由记忆系统决定。图片也不靠文本描述索引。
+
+func newMediaLoopAgent(t *testing.T) (*Agent, *media.Store) {
+	t.Helper()
+	dir := t.TempDir()
+	ms, err := media.New(filepath.Join(dir, "media"))
+	if err != nil {
+		t.Fatalf("media.New: %v", err)
+	}
+	t.Cleanup(func() { ms.Close() })
+
+	a := &Agent{mediaStore: ms}
+	a.ctx, a.cancel = context.WithCancel(context.Background())
+	t.Cleanup(a.cancel)
+	return a, ms
+}
+
+// heldMediaDigests 汇总三层记忆持有的媒体：只有这些才可被召回。
+func TestHeldMediaDigests_CollectsAcrossLayers(t *testing.T) {
+	a, ms := newMediaLoopAgent(t)
+	d1, _ := ms.Put([]byte("ctx-layer"), media.Item{MIME: "image/png"})
+	d2, _ := ms.Put([]byte("doc-layer"), media.Item{MIME: "image/png"})
+	d3, _ := ms.Put([]byte("graph-layer"), media.Item{MIME: "image/png"})
+	d4, _ := ms.Put([]byte("orphan"), media.Item{MIME: "image/png"})
+
+	a.context = NewRelevanceContext("", memory.NewStaticEmbedder(""))
+	a.context.Append(ContextEvent{Input: "带图的一轮", Blocks: []memory.MemoryBlock{
+		{ID: "blk_ctx", Modality: memory.BlockImage, PayloadDigest: d1},
+	}})
+
+	dir := t.TempDir()
+	bo, ok := a.blockFromDigest(d2)
+	if !ok {
+		t.Fatal("blockFromDigest 失败")
+	}
+	ds := document.NewStore(filepath.Join(dir, "docs"), memory.TokenizeWords)
+	if err := ds.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer ds.Stop()
+	if err := ds.Insert(&document.Doc{ID: "doc_1", Summary: "s", Blocks: []memory.MemoryBlock{bo}}); err != nil {
+		t.Fatal(err)
+	}
+	a.docStore = ds
+
+	g, err := memory.NewGraphDB(filepath.Join(dir, "graph.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer g.Close()
+	if err := g.PutMemoryBlocks([]memory.MemoryBlock{
+		{ID: "blk_g", Modality: memory.BlockImage, PayloadDigest: d3},
+	}); err != nil {
+		t.Fatal(err)
+	}
+	a.memory = g
+
+	held := a.heldMediaDigests()
+	for _, want := range []string{d1, d2, d3} {
+		if !held[want] {
+			t.Errorf("层次持有 %s 却不在结果里: %v", shortDigest(want), held)
+		}
+	}
+	if held[d4] {
+		t.Errorf("无人持有的 %s 不该出现在结果里", shortDigest(d4))
+	}
+}
+
+// fakeSpace 是一个只覆盖图像的假统一空间，用来验证「不在本空间」与
+// 「本次失败」必须被区分对待。
+type fakeSpace struct{}
+
+func (fakeSpace) VectorizeDense(string) ([]float64, error) { return []float64{1, 0}, nil }
+
+func (fakeSpace) EmbedImageDense(_ []byte, mime string) ([]float64, error) {
+	if strings.HasPrefix(mime, "audio/") || strings.HasPrefix(mime, "video/") {
+		return nil, fmt.Errorf("%w: %s", vector.ErrModalityUnsupported, mime)
+	}
+	return []float64{1, 0}, nil
+}
+
+func (fakeSpace) Fingerprint() string { return "fake-space" }
+func (fakeSpace) Dim() int            { return 2 }
+func (fakeSpace) Loaded() bool        { return true }
+func (fakeSpace) Close()              {}
+
+// TestReembedStaleMedia_SkipsUnsupportedWithoutFaking 验证向量迁移不会：
+//   - 把音频当失败反复重试；
+//   - 更不能拿另一个模型的向量顶替音频（那会污染统一空间且静默）。
+func TestReembedStaleMedia_SkipsUnsupportedWithoutFaking(t *testing.T) {
+	a, ms := newMediaLoopAgent(t)
+	img, _ := ms.Put([]byte("img-bytes"), media.Item{MIME: "image/png"})
+	aud, _ := ms.Put([]byte("aud-bytes"), media.Item{MIME: "audio/wav"})
+
+	a.multimodalSpace = fakeSpace{}
+	a.reembedStaleMedia()
+
+	it, err := ms.Stat(img)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(it.Vec) != 2 || it.VecModel != "fake-space" {
+		t.Fatalf("图像应拿到本空间向量，实际 vec=%v model=%q", it.Vec, it.VecModel)
+	}
+
+	audIt, err := ms.Stat(aud)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(audIt.Vec) != 0 || audIt.VecModel != "" {
+		t.Fatalf("音频不得被写入任何向量（不能用别的模型顶替），实际 vec=%v model=%q",
+			audIt.Vec, audIt.VecModel)
+	}
+}
+
+// payloadHeld 是删除前的活查询。
+func TestPayloadHeld(t *testing.T) {
+	a, ms := newMediaLoopAgent(t)
+	d, _ := ms.Put([]byte("held"), media.Item{MIME: "image/png"})
+	if a.payloadHeld(d) {
+		t.Fatal("尚无块持有时不该报已持有")
+	}
+
+	a.context = NewRelevanceContext("", memory.NewStaticEmbedder(""))
+	a.context.Append(ContextEvent{Input: "x", Blocks: []memory.MemoryBlock{
+		{ID: "blk_1", Modality: memory.BlockImage, PayloadDigest: d},
+	}})
+	if !a.payloadHeld(d) {
+		t.Fatal("L0 持有却报未持有")
+	}
+	if a.payloadHeld("") {
+		t.Fatal("空 digest 应为 false")
+	}
+}
+
+// TestForgetPayloads_DeletesOnlyUnheldContent 验证删除语义：
+// 块被删除后内容才被删；仍被其它记忆块共享的 digest 不会被误删。
+func TestForgetPayloads_DeletesOnlyUnheldContent(t *testing.T) {
+	dir := t.TempDir()
+	ms, err := media.New(filepath.Join(dir, "media"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer ms.Close()
+
+	d1, _ := ms.Put([]byte("held-by-graph"), media.Item{MIME: "image/png"})
+	d2, _ := ms.Put([]byte("being-forgotten"), media.Item{MIME: "image/png"})
+
+	g, err := memory.NewGraphDB(filepath.Join(dir, "graph.db"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer g.Close()
+	if err := g.PutMemoryBlocks([]memory.MemoryBlock{
+		{ID: "blk_keep", Modality: memory.BlockImage, PayloadDigest: d1},
+	}); err != nil {
+		t.Fatal(err)
+	}
+
+	a := &Agent{mediaStore: ms, memory: g}
+	a.forgetPayloads([]string{d1, d2})
+
+	if _, err := ms.Stat(d1); err != nil {
+		t.Fatalf("仍被 L3 块持有的内容不该被删: %v", err)
+	}
+	if _, err := ms.Stat(d2); err == nil {
+		t.Fatal("无人持有的内容应被删除")
+	}
+}

internal/agent/core/mediaref.go

@@ -0,0 +1,210 @@
+package core
+
+import (
+	"fmt"
+	"log"
+	"strings"
+	"sync/atomic"
+	"time"
+
+	agentAPI "gitcode.com/JianFeeeee/HomeAgent/internal/agent/api"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/media"
+)
+
+// blockSeq 保证块 ID 全局唯一（Graph memory_blocks 以 id 为主键）。
+var blockSeq int64
+
+func newBlockID() string {
+	return fmt.Sprintf("blk_%d_%d", time.Now().UnixNano(), atomic.AddInt64(&blockSeq, 1))
+}
+
+// blockModalityOf 把 CAS 媒体大类映射为一等记忆块模态。
+func blockModalityOf(k media.Kind) memory.BlockModality {
+	switch k {
+	case media.KindImage:
+		return memory.BlockImage
+	case media.KindVideo:
+		return memory.BlockVideo
+	case media.KindAudio:
+		return memory.BlockAudio
+	default:
+		return memory.BlockText
+	}
+}
+
+// blockFromDigest 把一份已入库媒体变成一等记忆块。
+// 块携带 digest/向量/fingerprint；CAS 只提供字节与元数据，不参与生命周期。
+func (a *Agent) blockFromDigest(digest string) (memory.MemoryBlock, bool) {
+	if a.mediaStore == nil || digest == "" {
+		return memory.MemoryBlock{}, false
+	}
+	it, err := a.mediaStore.Stat(digest)
+	if err != nil || it == nil {
+		return memory.MemoryBlock{}, false
+	}
+	return memory.MemoryBlock{
+		ID:            newBlockID(),
+		Modality:      blockModalityOf(it.Kind),
+		PayloadDigest: it.Digest,
+		MIME:          it.MIME,
+		Size:          it.Size,
+		Width:         it.Width,
+		Height:        it.Height,
+		Vector:        it.Vec,
+		Fingerprint:   it.VecModel,
+		Tool:          it.Tool,
+		CreatedAt:     it.FirstSeen,
+	}, true
+}
+
+// 媒体记忆接线：把对话里出现的图片/音频落进内容寻址存储（CAS），
+// 并让 L0 的 ContextEvent 直接持有一等记忆块。
+//
+// 媒体进入对话有两条路：用户直接发图（ContentBlock data URL）、插件注入
+// （SetToolBlocks）。两条都在这里收口：从 data URL 取出字节存进 CAS，
+// 用其向量构造一等记忆块挂到当轮 ContextEvent 上；事件被 Prune 时
+// 块随之迁移到 L2 文档。
+//
+// 不再生成任何描述文本，也不再往正文写 media marker：图片只按自己的
+// 统一空间向量被检索，描述式索引是将就方案。
+
+// captureBlockMedia 把 blocks 里的 data URL 媒体落进 CAS，返回 digest 列表。
+//
+// 只处理 data URL：http(s) URL 拿不到字节就无法做内容寻址，
+// 而"下载它再存"会把一次对话变成一次网络请求（超时、鉴权、SSRF 全来了），
+// 不在本层解决。
+func (a *Agent) captureBlockMedia(blocks []agentAPI.ContentBlock, tool string) []string {
+	if a.mediaStore == nil || len(blocks) == 0 {
+		return nil
+	}
+
+	var digests []string
+	for _, b := range blocks {
+		var url string
+		switch {
+		case b.ImageURL != nil && b.ImageURL.URL != "":
+			url = b.ImageURL.URL
+		case b.AudioURL != nil && b.AudioURL.URL != "":
+			url = b.AudioURL.URL
+		default:
+			continue
+		}
+
+		mime, data, ok := media.ParseDataURL(url)
+		if !ok {
+			continue // http(s) URL 或格式不认，跳过
+		}
+
+		d, err := a.mediaStore.Put(data, media.Item{
+			MIME: mime,
+			Tool: tool,
+		})
+		if err != nil {
+			// 媒体存不进去不该让对话失败——它是记忆增强，不是对话必需品
+			log.Printf("[media] 落盘失败 (tool=%s mime=%s): %v", tool, mime, err)
+			continue
+		}
+
+		// 入库即算一次多模态坐标并缓存（多模态空间可用时）。
+		// 之后 doc_query / memory_recall / 内部召回直接复用 SetVec 的缓存坐标，
+		// 不重复跑 ONNX；模型切换由启动时的 reembedStaleMedia 补算。
+		a.embedMediaOnIngest(d, mime, data)
+		digests = append(digests, d)
+	}
+	return digests
+}
+
+// embedMediaOnIngest 给刚入库的图片立即计算多模态坐标并缓存。
+// 只在 多模态空间可用且为图像时执行；音频/未配置时静默跳过（保持既有行为）。
+func (a *Agent) embedMediaOnIngest(digest, mime string, data []byte) {
+	if a.multimodalSpace == nil || !a.multimodalSpace.Loaded() {
+		return
+	}
+	if !strings.HasPrefix(mime, "image/") {
+		return
+	}
+	vec, err := a.multimodalSpace.EmbedImageDense(data, mime)
+	if err != nil {
+		log.Printf("[media] 入库嵌入失败 %s: %v", shortDigest(digest), err)
+		return
+	}
+	if err := a.mediaStore.SetVec(digest, vec, a.multimodalSpace.Fingerprint()); err != nil {
+		log.Printf("[media] 入库写向量失败 %s: %v", shortDigest(digest), err)
+	}
+}
+
+// stageMediaDigests 累积本轮捕获的 digest，等 ContextEvent 建好后一起挂上。
+//
+// 为何要缓存而不是当场建块：媒体在 process() 执行期间被捕获，而承载它的
+// ContextEvent 要等 process() 返回后才 Append——此刻还没有 owner_id。
+// 与既有的 a.pendingMedia 同一手法（都在 a.mu 保护下）。
+func (a *Agent) stageMediaDigests(digests ...string) {
+	if len(digests) == 0 {
+		return
+	}
+	a.pendingMediaDigests = append(a.pendingMediaDigests, digests...)
+}
+
+// drainMediaDigests 取出并清空本轮累积的 digest。
+func (a *Agent) drainMediaDigests() []string {
+	if len(a.pendingMediaDigests) == 0 {
+		return nil
+	}
+	out := a.pendingMediaDigests
+	a.pendingMediaDigests = nil
+	return out
+}
+
+// bindEventMedia 把本轮捕获的媒体变成一等记忆块，直接挂到 ContextEvent 上。
+//
+// 块存储在事件自身（随 context.json 持久化），不再写 media_refs：
+// 存活与否由“三层记忆块是否持有这个 digest”决定，不维护引用账本。
+func (a *Agent) bindEventMedia(evt *ContextEvent, digests []string) {
+	if a.mediaStore == nil || evt == nil || len(digests) == 0 {
+		return
+	}
+	if evt.ID == "" {
+		evt.ID = newEventID()
+	}
+	for _, d := range digests {
+		b, ok := a.blockFromDigest(d)
+		if !ok {
+			log.Printf("[media] 块构造失败 (%s)", shortDigest(d))
+			continue
+		}
+		evt.Blocks = append(evt.Blocks, b)
+	}
+}
+
+// mediaLabel 渲染一行媒体标签，供提示词告知"这条记忆带着哪份媒体"。
+//
+// 不再包含任何生成的描述文本：图片只按自己的向量被检索，标签仅提供
+// MIME 与短 digest，让模型知道有这份媒体、可据 digest 取回字节。
+// 查不到返回空串：内容可能已被删除，不该造出一条指向虚无的标签。
+func mediaLabel(it *media.Item) string {
+	if it == nil {
+		return ""
+	}
+	label := string(it.Kind)
+	if it.MIME != "" {
+		label = it.MIME
+	}
+	return fmt.Sprintf("[%s %s]", label, shortDigest(it.Digest))
+}
+
+// newEventID 生成 ContextEvent 的稳定标识。
+//
+// 沿用 document.Store 的 doc_<unixnano> 手法（同一份代码库里保持一致，
+// 也避免为此引入 uuid 依赖）。纳秒精度足够：同一 Agent 的事件由
+// a.mu 串行化 Append，不存在同纳秒两条。
+func newEventID() string {
+	return fmt.Sprintf("evt_%d", time.Now().UnixNano())
+}
+
+func shortDigest(d string) string {
+	if len(d) > 12 {
+		return d[:12]
+	}
+	return d
+}

internal/agent/core/mediaref_test.go

@@ -0,0 +1,333 @@
+package core
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+
+	agentAPI "gitcode.com/JianFeeeee/HomeAgent/internal/agent/api"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/document"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/media"
+)
+
+// 媒体记忆接线测试：验证媒体从对话进入 CAS、挂到 L0 事件、
+// 随归档转到 L2 文档的完整链路。
+//
+// 核心断言不是"函数被调用了"，而是不变量：
+//   1. 媒体存不进去时对话照常（它是记忆增强，不是对话必需品）
+//   2. 引用转移期间内容始终可读（先挂后销，不留归零窗口）
+//   3. mediaStore 为 nil 时全链路静默跳过，行为与本特性上线前一致
+
+func newTestAgentWithMedia(t *testing.T) (*Agent, *media.Store) {
+	t.Helper()
+	dir := t.TempDir()
+	ms, err := media.New(filepath.Join(dir, "media"))
+	if err != nil {
+		t.Fatalf("media.New: %v", err)
+	}
+	t.Cleanup(func() { ms.Close() })
+
+	emb := memory.NewStaticEmbedder()
+	a := &Agent{
+		mediaStore: ms,
+		context:    NewRelevanceContext(filepath.Join(dir, "context.json"), emb),
+	}
+	return a, ms
+}
+
+// imageBlockURL 造一个带指定 URL 的图片块。
+// 名字带 URL 后缀是为了不与 modalfallback_test.go 里固定用 testPNG 的
+// imageBlock() 撞名——两者用途不同：那个验回退链，这个验入库。
+func imageBlockURL(dataURL string) agentAPI.ContentBlock {
+	return agentAPI.ContentBlock{
+		Type:     "image_url",
+		ImageURL: &agentAPI.ImageURL{URL: dataURL, Detail: "auto"},
+	}
+}
+
+func TestCaptureBlockMedia_StoresDataURL(t *testing.T) {
+	a, ms := newTestAgentWithMedia(t)
+
+	raw := []byte{0x89, 'P', 'N', 'G', 1, 2, 3}
+	blocks := []agentAPI.ContentBlock{
+		{Type: "text", Text: "看这张图"},
+		imageBlockURL(media.DataURL("image/png", raw)),
+	}
+
+	digests := a.captureBlockMedia(blocks, "multimodal_see_picture")
+	if len(digests) != 1 {
+		t.Fatalf("应捕获 1 个媒体，实际 %d", len(digests))
+	}
+
+	got, err := ms.Get(digests[0])
+	if err != nil {
+		t.Fatalf("回读失败: %v", err)
+	}
+	if string(got) != string(raw) {
+		t.Fatal("内容不一致")
+	}
+	it, _ := ms.Stat(digests[0])
+	if it.MIME != "image/png" || it.Tool != "multimodal_see_picture" || it.Kind != media.KindImage {
+		t.Fatalf("元数据不对: %+v", it)
+	}
+}
+
+func TestCaptureBlockMedia_SkipsHTTPURL(t *testing.T) {
+	// http(s) URL 拿不到字节就无法内容寻址；"下载它再存"会把一次对话
+	// 变成一次网络请求（超时、鉴权、SSRF 全来了），不在本层解决。
+	a, _ := newTestAgentWithMedia(t)
+
+	blocks := []agentAPI.ContentBlock{
+		imageBlockURL("https://example.com/x.png"),
+	}
+	if d := a.captureBlockMedia(blocks, "t"); len(d) != 0 {
+		t.Fatalf("http URL 不该被捕获，实际 %d 个", len(d))
+	}
+}
+
+func TestCaptureBlockMedia_NilStoreIsNoop(t *testing.T) {
+	// mediaStore 未启用时全链路静默跳过，不能 panic 也不能报错——
+	// 行为必须与本特性上线前完全一致。
+	a := &Agent{}
+	blocks := []agentAPI.ContentBlock{imageBlockURL(media.DataURL("image/png", []byte("x")))}
+	if d := a.captureBlockMedia(blocks, "t"); d != nil {
+		t.Fatalf("nil store 应返回 nil，实际 %v", d)
+	}
+	a.stageMediaDigests("deadbeef")
+	if got := a.drainMediaDigests(); len(got) != 1 {
+		t.Fatal("stage/drain 不依赖 store，应正常工作")
+	}
+	// bindEventMedia 对 nil store 也必须安全
+	evt := &ContextEvent{}
+	a.bindEventMedia(evt, []string{"deadbeef"})
+	if len(evt.Blocks) != 0 || evt.ID != "" {
+		t.Fatalf("nil store 时不该改动事件: %+v", evt)
+	}
+	if s := mediaLabel(nil); s != "" {
+		t.Fatalf("nil 媒体应产出空标签，得到 %q", s)
+	}
+}
+
+func TestCaptureBlockMedia_AudioAndVideo(t *testing.T) {
+	a, ms := newTestAgentWithMedia(t)
+
+	blocks := []agentAPI.ContentBlock{
+		imageBlockURL(media.DataURL("image/jpeg", []byte("frame"))),
+		{Type: "audio_url", AudioURL: &agentAPI.AudioURL{URL: media.DataURL("audio/wav", []byte("sound"))}},
+	}
+	digests := a.captureBlockMedia(blocks, "multimodal_see_video")
+	if len(digests) != 2 {
+		t.Fatalf("应捕获 2 个，实际 %d", len(digests))
+	}
+
+	kinds := map[media.Kind]int{}
+	for _, d := range digests {
+		it, err := ms.Stat(d)
+		if err != nil {
+			t.Fatal(err)
+		}
+		kinds[it.Kind]++
+	}
+	if kinds[media.KindImage] != 1 || kinds[media.KindAudio] != 1 {
+		t.Fatalf("大类归属不对: %v", kinds)
+	}
+}
+
+func TestStageDrainMediaDigests(t *testing.T) {
+	a, _ := newTestAgentWithMedia(t)
+
+	a.stageMediaDigests("a", "b")
+	a.stageMediaDigests("c")
+	got := a.drainMediaDigests()
+	if len(got) != 3 {
+		t.Fatalf("应累积 3 个，实际 %d", len(got))
+	}
+	// drain 后必须清空——否则下一轮对话会把上一轮的媒体又挂一遍
+	if again := a.drainMediaDigests(); again != nil {
+		t.Fatalf("drain 后应为空，实际 %v", again)
+	}
+}
+
+func TestBindEventMedia_CreatesBlocks(t *testing.T) {
+	a, ms := newTestAgentWithMedia(t)
+
+	d, err := ms.Put([]byte("img"), media.Item{MIME: "image/png"})
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	evt := &ContextEvent{Timestamp: time.Now(), Source: "qq", Input: "看图"}
+	a.bindEventMedia(evt, []string{d})
+
+	if evt.ID == "" {
+		t.Fatal("应懒生成事件 ID")
+	}
+	if len(evt.Blocks) != 1 || evt.Blocks[0].PayloadDigest != d {
+		t.Fatalf("事件应持有一等记忆块: %+v", evt.Blocks)
+	}
+	if evt.Blocks[0].Modality != memory.BlockImage || evt.Blocks[0].MIME != "image/png" {
+		t.Fatalf("块元数据不对: %+v", evt.Blocks[0])
+	}
+}
+
+func TestBindEventMedia_LazyIDOnlyWhenNeeded(t *testing.T) {
+	// 绝大多数对话没有媒体，不该为它们都生成 ID 塞进 context.json
+	a, _ := newTestAgentWithMedia(t)
+	evt := &ContextEvent{Input: "纯文本"}
+	a.bindEventMedia(evt, nil)
+	if evt.ID != "" {
+		t.Fatalf("无媒体时不该生成 ID，得到 %q", evt.ID)
+	}
+}
+
+func TestMediaLabel_NoGeneratedDescription(t *testing.T) {
+	// 标签只用来告诉模型「这条记忆带着哪份媒体、可用该 digest 取回字节」。
+	// 它不包含任何生成的描述：描述式索引是把就机制，已彻底废弃。
+	a, ms := newTestAgentWithMedia(t)
+
+	d, _ := ms.Put([]byte("img"), media.Item{MIME: "image/png"})
+	it, err := ms.Stat(d)
+	if err != nil {
+		t.Fatal(err)
+	}
+	s := mediaLabel(it)
+	if s == "" {
+		t.Fatal("应产出标签")
+	}
+	if !strings.Contains(s, "image/png") {
+		t.Fatalf("标签应含 MIME 标注: %q", s)
+	}
+	if !strings.Contains(s, shortDigest(d)) {
+		t.Fatalf("标签应含短 digest 供反查: %q", s)
+	}
+	_ = a
+}
+
+func TestPrune_NilMediaStoreStillArchives(t *testing.T) {
+	// 媒体存储未启用时归档链路必须照常工作
+	dir := t.TempDir()
+	emb := memory.NewStaticEmbedder()
+	docStore := document.NewStore(filepath.Join(dir, "docs"), memory.TokenizeWords)
+	if err := docStore.Start(); err != nil {
+		t.Fatal(err)
+	}
+	rc := NewRelevanceContext(filepath.Join(dir, "context.json"), emb)
+
+	for i := 0; i < 15; i++ {
+		rc.Append(ContextEvent{
+			Timestamp: time.Now().Add(time.Duration(i) * time.Second),
+			Source:    "qq",
+			Input:     "内容",
+		})
+	}
+	if n := rc.Prune("查询", 5, docStore); n == 0 {
+		t.Fatal("无媒体存储时归档也应正常")
+	}
+}
+
+func TestContextEvent_BlocksFieldRoundTrip(t *testing.T) {
+	// context.json 加字段必须向后兼容：存量文件读回来 Blocks 为空、ID 为空，
+	// 不影响任何既有行为。
+	dir := t.TempDir()
+	path := filepath.Join(dir, "context.json")
+
+	// 写一份"存量格式"（无 id / blocks 字段）
+	legacy := `[{"timestamp":"2026-09-04T10:00:00Z","source":"qq","input":"老数据","response":"回复"}]`
+	if err := os.WriteFile(path, []byte(legacy), 0644); err != nil {
+		t.Fatal(err)
+	}
+
+	emb := memory.NewStaticEmbedder()
+	rc := NewRelevanceContext(path, emb)
+	if rc.Len() != 1 {
+		t.Fatalf("应读回 1 条，实际 %d", rc.Len())
+	}
+
+	// 新写入带记忆块的事件，再读回
+	ms, err := media.New(filepath.Join(dir, "media"))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer ms.Close()
+	a := &Agent{mediaStore: ms, context: rc}
+	d, _ := ms.Put([]byte("img"), media.Item{MIME: "image/png"})
+	evt := ContextEvent{Timestamp: time.Now(), Source: "qq", Input: "新数据"}
+	a.bindEventMedia(&evt, []string{d})
+	rc.Append(evt)
+	rc.flush()
+
+	rc2 := NewRelevanceContext(path, emb)
+	if rc2.Len() != 2 {
+		t.Fatalf("应有 2 条，实际 %d", rc2.Len())
+	}
+	var persisted int
+	for _, e := range rc2.Recent(10) {
+		persisted += len(e.Blocks)
+	}
+	if persisted != 1 {
+		t.Fatalf("块应随 context.json 持久化，实际 %d 个", persisted)
+	}
+}
+
+func TestPruneMigratesBlocksToDocument(t *testing.T) {
+	// 一等记忆块的 L0→L2 迁移：块随事件离开 Context、进入 Document，
+	// 身份（ID/模态/digest/向量）原样保留；同一块不能同时留在两层。
+	// 这条路径不依赖 media_refs/ref_count。
+	dir := t.TempDir()
+	emb := memory.NewStaticEmbedder()
+	docStore := document.NewStore(filepath.Join(dir, "docs"), memory.TokenizeWords)
+	if err := docStore.Start(); err != nil {
+		t.Fatal(err)
+	}
+	rc := NewRelevanceContext(filepath.Join(dir, "context.json"), emb)
+
+	block := memory.MemoryBlock{
+		ID: "blk_migrate_1", Modality: memory.BlockImage,
+		PayloadDigest: "deadbeef", MIME: "image/png", Size: 42,
+		Vector: []float64{0.1, 0.2, 0.3}, Fingerprint: "qwen:test",
+	}
+	rc.Append(ContextEvent{
+		Timestamp: time.Now().Add(-time.Hour),
+		Source:    "qq", Input: "很久以前的一张图",
+		Blocks: []memory.MemoryBlock{block},
+	})
+	for i := 0; i < 12; i++ {
+		rc.Append(ContextEvent{
+			Timestamp: time.Now().Add(time.Duration(i) * time.Second),
+			Source:    "qq", Input: "无关内容",
+		})
+	}
+
+	if n := rc.Prune("完全不相关的查询", 5, docStore); n == 0 {
+		t.Fatal("应有事件被归档")
+	}
+
+	// 块应已到达 L2，且身份不变。
+	var found *document.Doc
+	for _, d := range docStore.RecentDocs(20) {
+		if len(d.Blocks) > 0 {
+			found = d
+			break
+		}
+	}
+	if found == nil {
+		t.Fatal("归档文档应持有一等记忆块")
+	}
+	if len(found.Blocks) != 1 {
+		t.Fatalf("文档应有 1 个块，实际 %d", len(found.Blocks))
+	}
+	got := found.Blocks[0]
+	if got.ID != block.ID || got.Modality != block.Modality || got.PayloadDigest != block.PayloadDigest || got.Fingerprint != block.Fingerprint || len(got.Vector) != len(block.Vector) {
+		t.Fatalf("块身份应原样迁移:\n got  %+v\n want %+v", got, block)
+	}
+
+	// 同一块不能同时留在 L0。
+	for _, e := range rc.Recent(100) {
+		if len(e.Blocks) > 0 {
+			t.Fatalf("块仍留在 L0（同一块同时存在于两层）: %+v", e.Blocks)
+		}
+	}
+}

internal/agent/core/output.go

@@ -4,8 +4,8 @@ import (
 	"fmt"
 	"strings"
 
-	agentIO "gitcode.com/JianFeeeee/HomeAgent/internal/agent/io"
 	agentAPI "gitcode.com/JianFeeeee/HomeAgent/internal/agent/api"
+	agentIO "gitcode.com/JianFeeeee/HomeAgent/internal/agent/io"
 	sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk"
 )
 
@@ -78,7 +78,10 @@ func (a *Agent) executeOutputSendTool(tc agentAPI.ToolCall) string {
 				return fmt.Sprintf("[%s] 通道发送结果未确认：%s", channel, note)
 			}
 		}
-		return fmt.Sprintf("已通过 [%s] 通道发送: %v", channel, result)
+		// 成功回执：只返回极简标记，不回传完整插件响应。
+		// 「已通过 [qq] 通道发送: map[status:sent message_id:xxx]」这类富回执
+		// 会驱动模型继续调用 output_send（回声效应），是 output loop 的根源之一。
+		return "ok"
 	}
 
 	a.io.EmitTextTo("agent_io", channel, payload)

internal/agent/core/process.go

@@ -15,6 +15,90 @@ import (
 	pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
 )
 
+// continuationPlaceholder 是工具轮之后补的 user 占位内容。
+//
+// zen 兼容网关要求请求最后一条必须是 user（thinking 续写模式校验），工具轮
+// 产出 assistant/tool 结尾会被 400 拒绝；首轮 system 结尾不补，否则会覆盖
+// 真实用户输入。
+//
+// 用独立常量 + 精确等值判定，是因为这条消息是**核心自己插入的**、不是用户输入，
+// 所以可以安全地按内容识别并在补位前移除上一条，保证至多一条。
+const continuationPlaceholder = "请根据以上工具结果继续。"
+
+// replyDeliveredPlaceholder 是「本批工具调用全部是输出通道发送」之后补的占位。
+//
+// 为何不能继续用通用的「请继续」：异步通道（qq/wechat）的回复**只能**经
+// output_send__* 交付（纯文本不送达，见 buildSystemPrompt 的输出规则）。于是
+// 模型「已经回复完了」的表达形式就是一个工具调用，而紧随其后的
+// 「请根据以上工具结果继续。」会被读成「还要再做一步」——能做的「一步」恰好
+// 还是再发一条消息。两者叠加成自我强化的发送循环：生产实测单轮 34 次
+// output_send__qq、持续 514 秒，直到 QQ 插件自己的循环保险拒绝发送才停下。
+//
+// 所以这里换成一条明确的终止许可：已回复完就直接返回纯文本收尾。
+const replyDeliveredPlaceholder = "若你的回复已完成，直接返回纯文本即可结束本轮，无需再调用任何工具。"
+
+// continuationFor 选择工具轮之后补位的 user 占位文案。
+// replyOnly 表示上一批工具调用全部是输出通道发送（即模型刚交付了回复）。
+func continuationFor(replyOnly bool) string {
+	if replyOnly {
+		return replyDeliveredPlaceholder
+	}
+	return continuationPlaceholder
+}
+
+// isOutputDeliveryTool 判断工具是否是「向输出通道交付内容」。
+// output_send__{channel}_help 只是查询用法，不算交付。
+func isOutputDeliveryTool(name string) bool {
+	return strings.HasPrefix(name, "output_send__") && !strings.HasSuffix(name, "_help")
+}
+
+// isContinuationPlaceholder 判断一条 user 消息是否是本机制插入的占位。
+// 只按两个常量精确匹配，不碰任何真实用户消息。
+func isContinuationPlaceholder(m agentAPI.Message) bool {
+	return m.Role == "user" &&
+		(m.Content == continuationPlaceholder || m.Content == replyDeliveredPlaceholder)
+}
+
+// toolOutputForQuery 返回用于相关性计算的工具输出**有效内容**。
+//
+// 为什么要过 Cleaner 而不是直接用原始 result：ContextPolicy=prune 的入参是
+// **相关性查询向量**——它决定保留/归档哪些上下文事件。原始工具输出里混着
+// ANSI 转义、base64、JSON 包装等噪声，直接拿去向量化会让打分失真。
+// 而 ToolDef.Cleaner 的契约本就写着“仅在向量化/jieba/蒸馏时调用”，裁剪正是
+// 在向量化，所以这里必须过它（此前只在构建事件向量时用了，裁剪查询漏了）。
+//
+// Cleaner 未注册或 RPC 失败时回退原文（清洗是计算层优化，不能因此丢内容）；
+// 返回空串时也回退——空串会让查询向量退化成零向量，裁剪就失去判据。
+func (a *Agent) toolOutputForQuery(toolName, raw string) string {
+	if a.stageHost == nil {
+		return raw
+	}
+	cleaner := a.stageHost.ToolDefCleaner(toolName)
+	if cleaner == nil {
+		return raw
+	}
+	if cleaned := cleaner(raw); cleaned != "" {
+		return cleaned
+	}
+	return raw
+}
+
+// dropContinuationPlaceholders 移除此前由本机制插入的 user 占位。
+//
+// 为什么必须移除而不仅仅是“不再追加”：`msgs` 在循环外创建、循环内只增不减，
+// 占位是核心自己插的、不是用户说的话。不移除的话，prompt 里就会线性叠上
+// N 条一模一样的“继续”，把前缀上下文（含记忆注入）往后挤。
+func dropContinuationPlaceholders(msgs []agentAPI.Message) []agentAPI.Message {
+	out := msgs[:0]
+	for _, m := range msgs {
+		if isContinuationPlaceholder(m) {
+			continue
+		}
+		out = append(out, m)
+	}
+	return out
+}
+
 func (a *Agent) process(input string, stageCtx *sdk.StageContext) (response string, toolsUsed []string, toolResults []ToolResultItem, err error) {
 	a.mu.Lock()
 	defer a.mu.Unlock()
@@ -63,6 +147,9 @@ func (a *Agent) process(input string, stageCtx *sdk.StageContext) (response stri
 		}
 	}
 
+	// lastBatchReplyOnly 记录上一批工具调用是否全部是输出通道发送。
+	lastBatchReplyOnly := false
+
 	for turn := 0; ; turn++ {
 		for _, interrupt := range a.drainInterrupts() {
 			msgs = append(msgs, agentAPI.Message{
@@ -75,10 +162,17 @@ func (a *Agent) process(input string, stageCtx *sdk.StageContext) (response stri
 		// 工具轮产出的 tool/assistant 消息作结尾会被 400 拒绝,故补一条 user 占位。
 		// 注意:仅当尾部确为工具轮产物(assistant/tool)时才补位;首轮 system 上下文结尾不补,
 		// 否则会错误覆盖实际用户输入(如 injectSourceContext 追加的 system 说明)。
+		//
+		// 补位前先移除前面轮次插入的同类占位，保证占位**不随轮次线性累积**——
+		// 占位是核心插的传输层附加物，不是用户发言，不该在 prompt 里叠成 N 条。
+		//
+		// 文案分情况：上一批全是 output_send__* 时不能说“继续”，详见
+		// replyDeliveredPlaceholder 的说明。
+		msgs = dropContinuationPlaceholders(msgs)
 		if last := msgs[len(msgs)-1]; last.Role == "assistant" || last.Role == "tool" {
 			msgs = append(msgs, agentAPI.Message{
 				Role:    "user",
-				Content: "请根据以上工具结果继续。",
+				Content: continuationFor(lastBatchReplyOnly),
 			})
 		}
 
@@ -243,6 +337,17 @@ func (a *Agent) process(input string, stageCtx *sdk.StageContext) (response stri
 			return resp.Content, toolsUsed, toolResults, nil
 		}
 
+		// 本批是否全部是输出通道发送（=模型刚交付了给用户的回复）。
+		// 必须在执行前判定：执行过程中的中断/拒绝分支会 continue/break，
+		// 放在循环里统计会漏。
+		replyOnly := true
+		for _, tc := range resp.ToolCalls {
+			if !isOutputDeliveryTool(tc.Name) {
+				replyOnly = false
+				break
+			}
+		}
+
 		contentOnce := true
 		for _, tc := range resp.ToolCalls {
 			if len(a.interceptCh) > 0 {
@@ -305,6 +410,18 @@ func (a *Agent) process(input string, stageCtx *sdk.StageContext) (response stri
 					result = r
 				}
 			}
+			// ContextPolicy: prune 工具调用后执行上下文裁剪（§13.8）
+			if def := a.stageHost.ToolDef(tc.Name); def != nil && def.ContextPolicy == "prune" {
+				if a.context != nil {
+					topK := a.maxContextSize - 1
+					if topK < 1 {
+						topK = 1
+					}
+					// 查询向量取**清洗后**的有效内容，否则噪声（ANSI/base64/JSON
+					// 包装）会把相关性打分带偏，裁掉本该保留的事件。
+					a.context.Prune(a.toolOutputForQuery(tc.Name, result), topK, a.docStore)
+				}
+			}
 
 			msgContent := ""
 			if contentOnce {
@@ -344,6 +461,11 @@ func (a *Agent) process(input string, stageCtx *sdk.StageContext) (response stri
 					}
 				}
 				if len(blocks) > 0 {
+					// 先落进 CAS：无论下面走直视还是回退转写，媒体本体都该进记忆。
+					// 不存的后果是 ToolResultItem.Output 只剩那句
+					// "[已将图片注入后续对话] /tmp/x.png"，文件一删线索就断了。
+					a.stageMediaDigests(a.captureBlockMedia(blocks, tc.Name)...)
+
 					if native, fallbackText := a.prepareToolBlocks(blocks); len(native) > 0 {
 						// 能直视：另起一条 user message 承载媒体，并补一句来源说明，
 						// 否则模型会把它当成用户新发的图而不是工具拉回来的。
@@ -385,6 +507,9 @@ func (a *Agent) process(input string, stageCtx *sdk.StageContext) (response stri
 				break
 			}
 		}
+
+		// 供下一轮顶部选择补位文案。
+		lastBatchReplyOnly = replyOnly
 	}
 }
 

internal/agent/core/prunepolicy_test.go

@@ -0,0 +1,119 @@
+package core
+
+import (
+	"testing"
+
+	agentIO "gitcode.com/JianFeeeee/HomeAgent/internal/agent/io"
+	pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
+)
+
+// 这一组测试锁死「默认不裁剪」这条语义。
+//
+// 改动前：每条非中断输入都无条件 Prune 一次，没有任何声明能关掉它。
+// 这是破坏性行为（低相关事件被归档并从上下文移走），却无法从调用点看出
+// 「谁触发的裁剪」。改成需声明后，必须逐条验证默认值确实是不裁剪。
+func TestPruneDeclared_DefaultsToNoPrune(t *testing.T) {
+	m := agentIO.NewIOManager()
+	a := &Agent{io: m}
+
+	evt := &agentIO.InputEvent{Source: "unknown_source", Payload: map[string]interface{}{}}
+	if a.pruneDeclared(evt) {
+		t.Fatal("既没有通道声明也没有注入声明的输入，默认必须不裁剪")
+	}
+
+	// 通道注册了、但策略是 none / 空：仍然不裁剪。
+	m.RegisterInputChannel("quiet", pubsdk.ChannelDef{ContextPolicy: pubsdk.ContextPolicyNone})
+	if a.pruneDeclared(&agentIO.InputEvent{Source: "quiet", Payload: map[string]interface{}{}}) {
+		t.Fatal("ChannelDef.ContextPolicy=none 不应裁剪")
+	}
+	m.RegisterInputChannel("empty", pubsdk.ChannelDef{})
+	if a.pruneDeclared(&agentIO.InputEvent{Source: "empty", Payload: map[string]interface{}{}}) {
+		t.Fatal("ChannelDef 未设 ContextPolicy 不应裁剪")
+	}
+}
+
+// 通道显式声明 prune 才裁剪。
+func TestPruneDeclared_ChannelOptIn(t *testing.T) {
+	m := agentIO.NewIOManager()
+	m.RegisterInputChannel("noisy", pubsdk.ChannelDef{ContextPolicy: pubsdk.ContextPolicyPrune})
+	a := &Agent{io: m}
+
+	if !a.pruneDeclared(&agentIO.InputEvent{Source: "noisy", Payload: map[string]interface{}{}}) {
+		t.Fatal("通道声明 prune 后应裁剪")
+	}
+}
+
+// 注入点声明的优先级高于通道定义：同一通道下的不同注入可以有不同意图。
+func TestPruneDeclared_InjectionOverridesChannel(t *testing.T) {
+	m := agentIO.NewIOManager()
+	a := &Agent{io: m}
+	m.RegisterInputChannel("chan", pubsdk.ChannelDef{ContextPolicy: pubsdk.ContextPolicyPrune})
+
+	// 注入点说 none → 即使通道说 prune 也不裁。
+	evt := &agentIO.InputEvent{Source: "chan", Payload: map[string]interface{}{
+		"context_policy": pubsdk.ContextPolicyNone,
+	}}
+	if a.pruneDeclared(evt) {
+		t.Fatal("注入点声明 none 应覆盖通道的 prune")
+	}
+
+	// 通道没说，注入点说 prune → 裁。
+	m.RegisterInputChannel("plain", pubsdk.ChannelDef{})
+	evt = &agentIO.InputEvent{Source: "plain", Payload: map[string]interface{}{
+		"context_policy": pubsdk.ContextPolicyPrune,
+	}}
+	if !a.pruneDeclared(evt) {
+		t.Fatal("注入点声明 prune 应生效")
+	}
+}
+
+// 没有 context 时不能 panic，也不该裁剪。
+func TestPruneOnInput_NilContextIsSafe(t *testing.T) {
+	m := agentIO.NewIOManager()
+	m.RegisterInputChannel("noisy", pubsdk.ChannelDef{ContextPolicy: pubsdk.ContextPolicyPrune})
+	a := &Agent{io: m}
+	if got := a.pruneOnInput(&agentIO.InputEvent{Source: "noisy", Payload: map[string]interface{}{}}, "x"); got != 0 {
+		t.Fatalf("nil context 应返回 0，实际 %d", got)
+	}
+}
+
+// cleanInputFor 的优先级：注入点声明的 cleaner > 按 source 查的 cleaner > 原文。
+func TestCleanInputFor_Priority(t *testing.T) {
+	m := agentIO.NewIOManager()
+	m.RegisterInputChannel("src", pubsdk.ChannelDef{
+		Cleaner: func(s string) string { return "by-source:" + s },
+	})
+	m.RegisterInputChannel("explicit", pubsdk.ChannelDef{
+		Cleaner: func(s string) string { return "by-name:" + s },
+	})
+	a := &Agent{io: m}
+
+	// 无声明 → 用 source 的 cleaner
+	evt := &agentIO.InputEvent{Source: "src", Payload: map[string]interface{}{}}
+	if got := a.cleanInputFor(evt, "raw"); got != "by-source:raw" {
+		t.Fatalf("应回退到 source 的 cleaner，实际 %q", got)
+	}
+
+	// 注入点指定 cleaner_name → 覆盖 source 的
+	evt = &agentIO.InputEvent{Source: "src", Payload: map[string]interface{}{"cleaner_name": "explicit"}}
+	if got := a.cleanInputFor(evt, "raw"); got != "by-name:raw" {
+		t.Fatalf("注入点声明的 cleaner 应优先，实际 %q", got)
+	}
+
+	// 完全没有 cleaner → 原文
+	evt = &agentIO.InputEvent{Source: "nobody", Payload: map[string]interface{}{}}
+	if got := a.cleanInputFor(evt, "raw"); got != "raw" {
+		t.Fatalf("没有 cleaner 时应返回原文，实际 %q", got)
+	}
+
+	// 声明的名字查不到 → 回退到 source 的 cleaner（并记日志），不能 panic、不能丢内容
+	evt = &agentIO.InputEvent{Source: "src", Payload: map[string]interface{}{"cleaner_name": "missing"}}
+	if got := a.cleanInputFor(evt, "raw"); got != "by-source:raw" {
+		t.Fatalf("未知 cleaner_name 应回退，实际 %q", got)
+	}
+
+	// nil IOManager 不能 panic
+	if got := (&Agent{}).cleanInputFor(evt, "raw"); got != "raw" {
+		t.Fatalf("nil io 应返回原文，实际 %q", got)
+	}
+}

internal/agent/core/prunequery_test.go

@@ -0,0 +1,65 @@
+package core
+
+import (
+	"testing"
+
+	sdk "gitcode.com/JianFeeeee/HomeAgent/internal/sdk"
+)
+
+// ContextPolicy=prune 的查询向量必须取**清洗后**的有效内容。
+//
+// 裁剪的入参是相关性查询向量，它决定保留/归档哪些上下文事件。原始工具输出里
+// 混着 ANSI 转义、base64、JSON 包装等噪声，直接向量化会让打分失真，裁掉本该
+// 保留的事件。ToolDef.Cleaner 的契约本就写着「仅在向量化/jieba/蒸馏时调用」，
+// 裁剪正是在向量化——此前只在构建事件向量时用了它，裁剪查询漏了。
+func TestToolOutputForQueryAppliesCleaner(t *testing.T) {
+	host := NewStageHost()
+	called := 0
+	if err := host.RegisterTool("demo_tool", sdk.ToolDef{
+		Name: "demo_tool",
+		Cleaner: func(s string) string {
+			called++
+			return "cleaned:" + s
+		},
+	}, func(map[string]interface{}) (interface{}, error) { return nil, nil }); err != nil {
+		t.Fatalf("RegisterTool: %v", err)
+	}
+
+	a := &Agent{stageHost: host}
+	raw := "\x1b[31mresult\x1b[0m"
+
+	got := a.toolOutputForQuery("demo_tool", raw)
+	if called != 1 {
+		t.Fatalf("Cleaner 应被调用恰好一次，实际 %d", called)
+	}
+	if got != "cleaned:"+raw {
+		t.Fatalf("查询应使用清洗结果，实际 %q", got)
+	}
+
+	// 未注册 Cleaner 的工具：回退原文。
+	if got := a.toolOutputForQuery("no_such_tool", raw); got != raw {
+		t.Fatalf("无 Cleaner 应回退原文，实际 %q", got)
+	}
+
+	// 无 StageHost（如裸 Agent）：不能 panic，回退原文。
+	if got := (&Agent{}).toolOutputForQuery("demo_tool", raw); got != raw {
+		t.Fatalf("nil stageHost 应回退原文，实际 %q", got)
+	}
+}
+
+// Cleaner 返回空串时必须回退原文：空串会让查询向量退化成零向量，
+// 所有事件相关性相同，裁剪就失去判据（等于随机裁）。
+func TestToolOutputForQueryEmptyCleanFallsBack(t *testing.T) {
+	host := NewStageHost()
+	if err := host.RegisterTool("t", sdk.ToolDef{
+		Name:    "t",
+		Cleaner: func(string) string { return "" },
+	}, func(map[string]interface{}) (interface{}, error) { return nil, nil }); err != nil {
+		t.Fatalf("RegisterTool: %v", err)
+	}
+
+	a := &Agent{stageHost: host}
+	if got := a.toolOutputForQuery("t", "raw"); got != "raw" {
+		t.Fatalf("Cleaner 返回空应回退原文，实际 %q", got)
+	}
+}

internal/agent/core/spawn.go

@@ -9,6 +9,42 @@ import (
 	agentAPI "gitcode.com/JianFeeeee/HomeAgent/internal/agent/api"
 )
 
+// childTaskState 是一个子任务的生命周期状态。
+//
+// delivered 代替了早期的“读到即删”：完成通知会写进持久上下文
+// （formatMergedTimeline 每轮重新注入），模型之后还会再查。读一次就删的
+// 话，第二次查询返回“不存在或已过期”——那是一个**永远不会成功的可操作
+// 信号**，模型只能一遍遍地重试/汇报，循环永不结束。
+type childTaskState struct {
+	running   bool
+	result    string
+	delivered bool  // 结果是否已交付过（用于幂等应答）
+	seq       int64 // 完成顺序，用于有界淘汰
+}
+
+// maxRetainedChildTasks 是保留的已完成子任务上限（防结果无限占用内存）。
+const maxRetainedChildTasks = 20
+
+// evictChildTasksLocked 淘汰最旧的已完成子任务。调用方必须持有 childMu。
+func (a *Agent) evictChildTasksLocked() {
+	for len(a.childTasks) > maxRetainedChildTasks {
+		oldestID := ""
+		var oldestSeq int64
+		for id, st := range a.childTasks {
+			if st.running {
+				continue
+			}
+			if oldestID == "" || st.seq < oldestSeq {
+				oldestID, oldestSeq = id, st.seq
+			}
+		}
+		if oldestID == "" {
+			return // 剩下全是运行中的，不淘汰
+		}
+		delete(a.childTasks, oldestID)
+	}
+}
+
 func (a *Agent) executeSpawnChild(tc agentAPI.ToolCall) string {
 	task, _ := tc.Arguments["task"].(string)
 	if task == "" {
@@ -41,11 +77,11 @@ func (a *Agent) executeSpawnChild(tc agentAPI.ToolCall) string {
 	}
 
 	a.childMu.Lock()
-	a.childRunning[taskID] = true
+	a.childTasks[taskID] = &childTaskState{running: true}
 	a.childMu.Unlock()
 	go a.runChildTask(taskID, task, parentChannel, maxTurns)
 
-	return fmt.Sprintf("子任务已启动（ID: %s，最多 %d 轮），完成后会自动通知你，届时请使用 child_result 工具查看输出", taskID, maxTurns)
+	return fmt.Sprintf("子任务已启动（ID: %s，最多 %d 轮）。完成后会自动通知你，届时用 child_result 查看输出即可（**只需查询一次**）", taskID, maxTurns)
 }
 
 // defaultChildMaxTurns 子 Agent 默认工具轮数（可被 spawn_child 的 max_turns 参数覆盖）。
@@ -126,19 +162,30 @@ func (a *Agent) runChildTask(taskID, task string, parentChannel string, maxTurns
 	}
 
 	a.childMu.Lock()
-	a.childResults[taskID] = finalResult
-	delete(a.childRunning, taskID)
+	if st := a.childTasks[taskID]; st != nil {
+		st.running = false
+		st.result = finalResult
+		a.childSeq++
+		st.seq = a.childSeq
+	}
+	a.evictChildTasksLocked()
 	a.childMu.Unlock()
 
 	log.Printf("[child] %s done: %s", taskID, truncateStr(finalResult, 100))
 
-	notification := fmt.Sprintf("子任务 %s 已完成，请调用 child_result 工具查看输出", taskID)
+	notification := fmt.Sprintf("子任务 %s 已完成。请用 child_result 工具查看输出（只需查询一次；重复查询不会返回失败）。", taskID)
 	a.injectSelfChannel(selfInputMsg{
 		text:    notification,
 		channel: parentChannel, // 回到父对话通道，正常处理（写入上下文 + emit 响应）
 	})
 }
 
+// executeChildResultTool 取回子任务结果。
+//
+// **幂等**：结果不会被“读到即删”，重复查询返回同一结果或一条明确提示。
+// 这一点至关重要——完成通知会长期留在持久上下文里（formatMergedTimeline
+// 每轮重新注入），如果重复查询返回“不存在”这种失败信号，模型会认定任务
+// 未完成而无限重试（实测单轮 35 次工具调用、持续 514 秒）。
 func (a *Agent) executeChildResultTool(tc agentAPI.ToolCall) string {
 	taskID, _ := tc.Arguments["task_id"].(string)
 	if taskID == "" {
@@ -146,18 +193,25 @@ func (a *Agent) executeChildResultTool(tc agentAPI.ToolCall) string {
 	}
 
 	a.childMu.Lock()
-	result, ok := a.childResults[taskID]
-	if ok {
-		delete(a.childResults, taskID)
+	st, ok := a.childTasks[taskID]
+	if !ok {
 		a.childMu.Unlock()
-		return fmt.Sprintf("【子任务 %s 结果】\n%s", taskID, result)
+		return fmt.Sprintf("子任务 %s 不存在：从未创建该 ID（请核对 spawn_child 返回的 ID 拼写）", taskID)
 	}
-	if a.childRunning[taskID] {
+	if st.running {
 		a.childMu.Unlock()
 		return fmt.Sprintf("子任务 %s 仍在运行中，尚未完成。请等待完成通知后再查询。", taskID)
 	}
+	first := !st.delivered
+	st.delivered = true
+	result := st.result
 	a.childMu.Unlock()
-	return fmt.Sprintf("子任务 %s 不存在或已过期", taskID)
+
+	if first {
+		return fmt.Sprintf("【子任务 %s 结果】\n%s", taskID, result)
+	}
+	// 重复查询不是失败：明确告诉模型“任务已完成、结果已给过”，让它停止重试。
+	return fmt.Sprintf("【子任务 %s 已完成】结果已在上文提供（见先前的 child_result 工具结果），无需重复查询；请直接基于上文结果继续。", taskID)
 }
 
 func (a *Agent) executeLLMTool(tc agentAPI.ToolCall) string {

internal/agent/core/spawn_test.go

@@ -0,0 +1,88 @@
+package core
+
+import (
+	"fmt"
+	"strings"
+	"testing"
+
+	agentAPI "gitcode.com/JianFeeeee/HomeAgent/internal/agent/api"
+)
+
+// child_result 必须幂等——这是 "任务已结束但核心循环不结束" 的根因修复。
+//
+// 子任务完成通知会写进持久上下文（formatMergedTimeline 每轮重新注入），
+// 模型之后还会再查。若第二次查询返回 "不存在或已过期" 这种**永久失败信号**，
+// 模型会认定任务未完成而无限重试/汇报（生产实测：单轮 35 次工具调用、
+// 持续 514 秒）。
+func TestChildResultIsIdempotent(t *testing.T) {
+	a := New(AgentConfig{ID: "t"})
+
+	a.childMu.Lock()
+	a.childTasks["child_1"] = &childTaskState{result: "任务完成：已创建 3 个日程", seq: 1}
+	a.childMu.Unlock()
+
+	call := func(id string) string {
+		return a.executeChildResultTool(agentAPI.ToolCall{
+			Name:      "child_result",
+			Arguments: map[string]interface{}{"task_id": id},
+		})
+	}
+
+	first := call("child_1")
+	if !strings.Contains(first, "任务完成：已创建 3 个日程") {
+		t.Fatalf("首次查询应返回结果，实际: %q", first)
+	}
+
+	second := call("child_1")
+	if strings.Contains(second, "不存在") {
+		t.Fatalf("重复查询不能返回失败信号（会驱动模型无限重试），实际: %q", second)
+	}
+	if !strings.Contains(second, "已完成") {
+		t.Fatalf("重复查询应明确告知「已完成、结果已提供」，实际: %q", second)
+	}
+
+	// 只有从未创建过的 ID 才应报 "不存在"。
+	missing := call("child_999")
+	if !strings.Contains(missing, "不存在") {
+		t.Fatalf("未知 ID 应报不存在，实际: %q", missing)
+	}
+}
+
+// 运行中与已完成必须给出不同答复，否则模型无法判断该等还是该继续。
+func TestChildResultRunningVsDone(t *testing.T) {
+	a := New(AgentConfig{ID: "t"})
+
+	a.childMu.Lock()
+	a.childTasks["child_run"] = &childTaskState{running: true}
+	a.childMu.Unlock()
+
+	got := a.executeChildResultTool(agentAPI.ToolCall{
+		Name:      "child_result",
+		Arguments: map[string]interface{}{"task_id": "child_run"},
+	})
+	if !strings.Contains(got, "仍在运行中") {
+		t.Fatalf("运行中的任务应提示仍在运行，实际: %q", got)
+	}
+}
+
+// 保留的结果必须有界，不能随子任务数量无限增长。
+func TestChildTaskRetentionBounded(t *testing.T) {
+	a := New(AgentConfig{ID: "t"})
+
+	a.childMu.Lock()
+	for i := 0; i < maxRetainedChildTasks*3; i++ {
+		a.childSeq++
+		a.childTasks[fmt.Sprintf("child_%d", i)] = &childTaskState{result: "r", seq: a.childSeq}
+	}
+	a.evictChildTasksLocked()
+	n := len(a.childTasks)
+	a.childMu.Unlock()
+
+	if n > maxRetainedChildTasks {
+		t.Fatalf("保留子任务数=%d，超过上限 %d", n, maxRetainedChildTasks)
+	}
+	// 淘汰应保留最新的：最早的那批必须已不在
+	if _, ok := a.childTasks["child_0"]; ok {
+		t.Fatal("淘汰应优先丢弃最旧的已完成任务")
+	}
+}

internal/agent/core/status.go

@@ -73,6 +73,8 @@ func collectKernelStatus(
 			BuildTime:     meta.BuildTime,
 			SDKCompatible: meta.SDKCompatibleVersion,
 			KernelName:    meta.KernelName,
+			// AGPL-3.0 §13：状态页向网络使用者展示取得源码的入口。
+			SourceURL: meta.SourceURL,
 		},
 		Runtime: RuntimeStatus{
 			Goroutines: runtime.NumGoroutine(),

internal/agent/core/toolcall.go

@@ -150,6 +150,14 @@ func (a *Agent) executeMemoryTool(tc agentAPI.ToolCall) string {
 			}
 			parts = append(parts, fmt.Sprintf("- %s →(%s)→ %s", r.SourceName, r.RelationType, r.TargetName))
 		}
+		// 命中的关系若挂着媒体块，把媒体说明附在结果末尾。
+		//
+		// 关系行只有实体名和关系类型，看不出"这条记忆当时还带了一张图"。
+		// 媒体块以结构边与句子相连，需经关系→句子反查。
+		// 不附上的后果：agent 显式查了图记忆，却仍然不知道有图。
+		if mc := a.mediaContextForRelations(result.Relations); mc != "" {
+			parts = append(parts, "", "关联媒体:", mc)
+		}
 		return strings.Join(parts, "\n")
 
 	case "memory_block_merge":
@@ -177,9 +185,21 @@ func (a *Agent) executeMemoryTool(tc agentAPI.ToolCall) string {
 		for _, td := range triplesData {
 			if m, ok := td.(map[string]interface{}); ok {
 				t := memory.Triple{
-					Subject:  getString(m, "subject"),
-					Relation: getString(m, "relation"),
-					Object:   getString(m, "object"),
+					Subject:      getString(m, "subject"),
+					Relation:     getString(m, "relation"),
+					Object:       getString(m, "object"),
+					SentenceText: getString(m, "sentence_text"),
+				}
+				// 模型显式关联的媒体：结构化字段随三元组一起提交，
+				// 由 commitTriplesWithMedia 变成 L3 一等块并与句子建边——
+				// 不再把 marker 写进句子文本。
+				if digests := getStringSlice(m, "media_digests"); len(digests) > 0 {
+					t.MediaDigests = a.resolveMediaDigests(digests)
+					// 块边需要句子作端点。模型没给原句时用三元组本身拼一句
+					// 自然语言——不能造一段 marker 文本，那正是被废弃的东西。
+					if t.SentenceText == "" && len(t.MediaDigests) > 0 {
+						t.SentenceText = fmt.Sprintf("%s%s%s。", t.Subject, t.Relation, t.Object)
+					}
 				}
 				if t.Subject != "" && t.Relation != "" && t.Object != "" {
 					triples = append(triples, t)
@@ -189,10 +209,15 @@ func (a *Agent) executeMemoryTool(tc agentAPI.ToolCall) string {
 		if len(triples) == 0 {
 			return "没有有效的三元组"
 		}
-		ec, rc, err := a.memory.Commit(triples, string(a.id), 0)
+		// remember 工具是用户/模型显式写入，不涉及归档删除，
+		// 因此不需要 mediaBound——没有旧引用要释放。
+		ec, rc, mb, err := a.commitTriplesWithMedia(triples, string(a.id), 0, nil)
 		if err != nil {
 			return fmt.Sprintf("记忆写入失败: %v", err)
 		}
+		if mb > 0 {
+			return fmt.Sprintf("已写入 %d 个实体和 %d 条关系，关联 %d 份媒体", ec, rc, mb)
+		}
 		return fmt.Sprintf("已写入 %d 个实体和 %d 条关系", ec, rc)
 
 	case "memory_introspect":
@@ -511,6 +536,11 @@ func (a *Agent) executeDocTool(tc agentAPI.ToolCall) string {
 			if len(content) > 2000 {
 				content = content[:2000] + "..."
 			}
+			// 媒体块标签单独一行进冷存事件：正文可能被上面的 2000 字截断，
+			// 截掉之后模型就不知道这篇文档带过图。
+			if labels := a.blockLabelsForDoc(d); labels != "" {
+				content = content + "\n关联媒体: " + labels
+			}
 			a.context.InsertByTimestamp(ContextEvent{
 				Timestamp: d.CreatedAt,
 				Source:    "cold_storage",
@@ -541,14 +571,27 @@ func (a *Agent) executeDocTool(tc agentAPI.ToolCall) string {
 		}
 
 		doc := &document.Doc{
-			Summary:   summary,
-			Content:   content,
-			Tags:      tags,
-			Source:    "manual",
+			Summary: summary,
+			Content: content,
+			Tags:    tags,
+			Source:  "manual",
 		}
+
+		// 模型显式关联的媒体：直接变成文档持有的一等块。
+		// 不再往正文写 marker——文档向量会融合这些块的媒体向量，
+		// 图片按自己的向量被检索。
+		for _, d := range a.resolveMediaDigests(getStringSlice(tc.Arguments, "media_digests")) {
+			if b, ok := a.blockFromDigest(d); ok {
+				doc.Blocks = append(doc.Blocks, b)
+			}
+		}
+
 		if err := a.docStore.Insert(doc); err != nil {
 			return fmt.Sprintf("文档写入失败: %v", err)
 		}
+		if n := len(doc.Blocks); n > 0 {
+			return fmt.Sprintf("文档已提交 (id: %s, 摘要: %s, 关联 %d 份媒体)", doc.ID, summary, n)
+		}
 		return fmt.Sprintf("文档已提交 (id: %s, 摘要: %s)", doc.ID, summary)
 
 	default:

internal/agent/core/tooldefs.go

@@ -13,6 +13,24 @@ func (a *Agent) buildMemoryContext(input string, maxTokens int) string {
 	}
 	injected := a.indexer.BuildContext(input)
 	s := a.indexer.FormatContext(injected)
+
+	// 图库召回命中的实体若关联着带媒体的句子，把媒体说明一并注入。
+	//
+	// 不做这一步的后果：媒体描述进了 L3，agent 却拿不出来。图库句子里
+	// 写着 [image/png a1b2c3d4e5f6] 这样的短标记，但没有任何东西告诉
+	// 模型那份内容是否还在、能否重新查看——描述永存而 blob 可能已被
+	// 删除，两者状态不同，必须显式告知。
+	//
+	// 注意不能直接用 injected.Relations：BuildContext 刻意把它置为 nil
+	//（自动注入只给实体索引以省 token，细节留给 memory_recall）。
+	// 因此这里用命中的实体名再查一次关系，只为拿到 sentence_id。
+	if mc := a.mediaContextForInjectedEntities(injected); mc != "" {
+		if s != "" {
+			s += "\n"
+		}
+		s += "【关联媒体】\n" + mc
+	}
+
 	if maxTokens > 0 {
 		s = TruncateByTokens(s, maxTokens)
 	}
@@ -37,15 +55,13 @@ func (a *Agent) buildSystemPrompt(memContext string, userInput string) string {
 
 	prompt += "\n\n【记忆清理指令】当用户要求整理或清理记忆时，你必须实际调用 memory_ 工具执行操作，不能只回复文本。先用 memory_introspect 查看概况，再用 memory_recall 获取详情。有同义实体则用 memory_merge 合并（source 会被彻底删除），有无用噪音实体则用 memory_delete_entity 直接删除，也可用 memory_purge 批量清理，用 memory_edit 修正错误，用 memory_block_merge 标记不合并。如果工具执行成功，把结果告知用户；不要只描述计划而不执行。"
 
+	// 跨模态召回：文本路（fastText/TF-IDF 文档层，媒体描述文本已随记忆进入）
+	// + 视觉路（多模态文本编码 → 媒体库坐标）两路归一化融合。
+	// 未配置多模态空间时视觉路为空，等价旧的 docStore.Query。
 	if a.docStore != nil {
-		docs := a.docStore.Query(userInput, 3)
-		if len(docs) > 0 {
-			var parts []string
-			parts = append(parts, "【相关记忆文档】")
-			for i, d := range docs {
-				parts = append(parts, fmt.Sprintf("  [%d] %s", i+1, d.Summary))
-			}
-			prompt += "\n\n" + strings.Join(parts, "\n")
+		hits := a.retrieveCrossModal(userInput, 3, a.fusionCfg)
+		if md := a.crossModalMarkdown(hits); md != "" {
+			prompt += "\n\n" + md
 		}
 	}
 
@@ -57,7 +73,7 @@ func (a *Agent) buildSystemPrompt(memContext string, userInput string) string {
 	prompt += "- 同步通道（webui / cli / 终端）：直接返回纯文本，内核会把文本交给等待方显示，无需调用工具。\n"
 	prompt += "- 异步通道（qq / wechat / 群聊等）：返回纯文本**【不会】**自动送达用户，必须调用 output_send__{通道名} 工具（注意 meta 里带上正确的 user_id 或 group_id）才能真正把消息发出去。\n"
 	prompt += "- 不确定当前通道的发送方式时，先用 output_send__{通道名}_help 查看该通道的 meta 格式和 type 枚举，再决定。\n"
-	prompt += "- 同一轮对话中可多次调用输出门工具。长消息应当分多次发出，而不是一口气发完。\n"
+	prompt += "- 每轮对话**通常只需调用一次** output_send__{通道名} 即可完成回复。仅在内容确实超过单条消息长度上限（如 >4000 字）时才拆分为多条；拆分时每条应是完整段落，不要碎片化。\n"
 	prompt += "- 需要多步执行的长任务：**必须先**向当前对话通道发一条确认消息告诉用户已收到（异步通道用输出门工具，同步通道直接返回文本），**然后再**执行具体排查工具。确认消息不代表任务完成，发出后仍需继续执行实际工具并最终汇报结果。\n"
 	prompt += "- 用户从其他渠道发来「在哪里/怎么样了」这类追问时，先回忆上次任务的通道与上下文，再回同一通道。"
 
@@ -108,8 +124,8 @@ func (a *Agent) buildToolCatalog() string {
 	}
 	// 仅注入插件/通道能力摘要，避免全量工具定义污染 system prompt。
 	// 每个插件列：名称 + 能力描述 + 工具数。完整工具定义由 get_plugin_tools 按需拉取。
-	byPlugin := map[string]int{}          // plugin -> 工具数
-	pluginDesc := map[string]string{}     // plugin -> 首个工具描述(作能力概览)
+	byPlugin := map[string]int{}      // plugin -> 工具数
+	pluginDesc := map[string]string{} // plugin -> 首个工具描述(作能力概览)
 	var order []string
 	for _, t := range defs {
 		fn, ok := t.(map[string]interface{})["function"].(map[string]interface{})
@@ -302,7 +318,7 @@ func (a *Agent) buildToolDefs() []interface{} {
 				"parameters": map[string]interface{}{
 					"type": "object",
 					"properties": map[string]interface{}{
-						"name": map[string]interface{}{"type": "string", "description": "知识名称（用作目录名）"},
+						"name":    map[string]interface{}{"type": "string", "description": "知识名称（用作目录名）"},
 						"content": map[string]interface{}{"type": "string", "description": "知识内容，支持 Markdown"},
 					},
 					"required": []string{"name", "content"},
@@ -356,6 +372,11 @@ func (a *Agent) buildToolDefs() []interface{} {
 							"description": "标签列表",
 							"items":       map[string]interface{}{"type": "string"},
 						},
+						"media_digests": map[string]interface{}{
+							"type":        "array",
+							"description": "可选：这篇文档关联的媒体 digest（对话或 memory_recall 的「关联媒体」里显示的十六进制串，短的即可）。填了以后检索到这篇文档就能看到并取回原图/音频。",
+							"items":       map[string]interface{}{"type": "string"},
+						},
 					},
 					"required": []string{"content"},
 				},

internal/agent/core/tooloop_test.go

@@ -0,0 +1,117 @@
+package core
+
+import (
+	"strings"
+	"testing"
+
+	agentAPI "gitcode.com/JianFeeeee/HomeAgent/internal/agent/api"
+)
+
+// appendPlaceholder 复刻 process() 循环顶部的补位逻辑。
+func appendPlaceholder(msgs []agentAPI.Message, replyOnly bool) []agentAPI.Message {
+	msgs = dropContinuationPlaceholders(msgs)
+	if last := msgs[len(msgs)-1]; last.Role == "assistant" || last.Role == "tool" {
+		msgs = append(msgs, agentAPI.Message{Role: "user", Content: continuationFor(replyOnly)})
+	}
+	return msgs
+}
+
+func countPlaceholders(msgs []agentAPI.Message) int {
+	n := 0
+	for _, m := range msgs {
+		if isContinuationPlaceholder(m) {
+			n++
+		}
+	}
+	return n
+}
+
+// 占位是核心插入的传输层附加物，不是用户发言——它不能随轮次线性累积。
+//
+// 旧实现每轮无条件追加而从不移除，跑 N 轮 prompt 里就叠了 N 条一模一样的
+// “继续”，把前缀上下文（含记忆注入）往后挤。
+func TestPlaceholderDoesNotAccumulate(t *testing.T) {
+	msgs := []agentAPI.Message{{Role: "user", Content: "用户请求"}}
+
+	const rounds = 20
+	for turn := 0; turn < rounds; turn++ {
+		msgs = append(msgs, agentAPI.Message{Role: "assistant", Content: "调用工具"})
+		msgs = append(msgs, agentAPI.Message{Role: "tool", Content: "结果"})
+
+		// 交替普通工具轮 / 纯发送轮，确保两种文案都参与去重。
+		msgs = appendPlaceholder(msgs, turn%2 == 1)
+
+		if n := countPlaceholders(msgs); n != 1 {
+			t.Fatalf("第 %d 轮后占位数=%d，期望恰好 1 条（旧实现会累积到 %d 条）", turn+1, n, turn+1)
+		}
+	}
+
+	// 末尾那一轮是纯发送轮，留下的应是“允许收尾”的文案。
+	if last := msgs[len(msgs)-1]; last.Content != replyDeliveredPlaceholder {
+		t.Fatalf("最后应是回复已交付的文案，实际: %q", last.Content)
+	}
+}
+
+// 首轮 system/真实用户输入结尾不补位：补了会覆盖实际用户输入。
+func TestPlaceholderNotAppendedOnFirstTurn(t *testing.T) {
+	msgs := []agentAPI.Message{
+		{Role: "system", Content: "系统说明"},
+		{Role: "user", Content: "真实用户输入"},
+	}
+	got := appendPlaceholder(msgs, false)
+	if len(got) != 2 {
+		t.Fatalf("首轮不应补位，得到 %d 条: %+v", len(got), got)
+	}
+	if got[1].Content != "真实用户输入" {
+		t.Fatalf("真实用户输入被覆盖: %q", got[1].Content)
+	}
+}
+
+// 内容相近的真实用户消息不能被当作占位删掉。
+func TestDropOnlyExactPlaceholder(t *testing.T) {
+	msgs := []agentAPI.Message{
+		{Role: "user", Content: continuationPlaceholder + "补充"},
+		{Role: "user", Content: replyDeliveredPlaceholder + "补充"},
+		{Role: "user", Content: continuationPlaceholder},
+	}
+	got := dropContinuationPlaceholders(msgs)
+	if len(got) != 2 {
+		t.Fatalf("只应删掉精确匹配的那条，得到 %d 条: %+v", len(got), got)
+	}
+}
+
+// 纯输出通道调用之后的补位不能再是「请继续」。
+//
+// 异步通道的回复只能经 output_send__* 交付，所以模型「已完成回复」的形式就是
+// 一个工具调用；紧跟一句「请继续」会被读成「还要再做一步」，而能做的
+// 「一步」恰好还是再发一条消息。（生产实测：单轮 34 次发送、514 秒）
+func TestContinuationForReplyDoesNotPushToContinue(t *testing.T) {
+	reply := continuationFor(true)
+	if reply == continuationPlaceholder {
+		t.Fatal("回复已交付后不应再补「请继续」，会驱动重复发送")
+	}
+	if !strings.Contains(reply, "纯文本") || !strings.Contains(reply, "结束") {
+		t.Fatalf("应明确告知可返回纯文本收尾，实际: %q", reply)
+	}
+
+	if got := continuationFor(false); got != continuationPlaceholder {
+		t.Fatalf("普通工具轮补位应保持不变，实际: %q", got)
+	}
+}
+
+// 只有真正的发送动作算「交付回复」；_help 是查询用法。
+func TestIsOutputDeliveryTool(t *testing.T) {
+	cases := map[string]bool{
+		"output_send__qq":      true,
+		"output_send__webui":   true,
+		"output_send__qq_help": false,
+		"output_list_channels": false,
+		"cmd_run":              false,
+		"qq_get_message":       false,
+	}
+	for name, want := range cases {
+		if got := isOutputDeliveryTool(name); got != want {
+			t.Errorf("isOutputDeliveryTool(%q) = %v, want %v", name, got, want)
+		}
+	}
+}

internal/agent/core/utils.go

@@ -29,6 +29,24 @@ func getFloat(m map[string]interface{}, key string) float64 {
 	return 0
 }
 
+// getStringSlice 从工具参数里取字符串数组。
+//
+// 需要单独一个 helper 而不是直接断言 []string：LLM 的参数经 JSON 解码后是
+// []interface{}，直接断言 []string 恒失败——静默拿到 nil，参数像没传一样。
+func getStringSlice(m map[string]interface{}, key string) []string {
+	raw, ok := m[key].([]interface{})
+	if !ok {
+		return nil
+	}
+	var out []string
+	for _, v := range raw {
+		if s, ok := v.(string); ok && s != "" {
+			out = append(out, s)
+		}
+	}
+	return out
+}
+
 func truncateStr(s string, max int) string {
 	if utf8.RuneCountInString(s) <= max {
 		return s

internal/agent/io/channel.go

@@ -25,11 +25,11 @@ const (
 type OutputCapability int
 
 const (
-	CapText      OutputCapability = 1 << iota // 文本
-	CapFile                                   // 文件
-	CapImage                                  // 图片
-	CapAudio                                  // 音频
-	CapStructured                             // 结构化数据（JSON/卡片）
+	CapText       OutputCapability = 1 << iota // 文本
+	CapFile                                    // 文件
+	CapImage                                   // 图片
+	CapAudio                                   // 音频
+	CapStructured                              // 结构化数据（JSON/卡片）
 )
 
 func (c OutputCapability) Supports(cap OutputCapability) bool {
@@ -242,6 +242,52 @@ func (m *IOManager) InjectInputSyncTo(source, outputChannel, eventType string, p
 	return <-ch
 }
 
+// InjectOptions 声明一次注入在记忆层与上下文层的表现。
+//
+// 零值 = 记入记忆 + 不裁剪上下文，与历史的三参数注入方法完全一致。
+// 别名到公共 SDK 而非另建一套：内置插件与外部插件必须用同一套结构，
+// 否则内核要认两种类型，而漏认会静默丢失标志位。
+type InjectOptions = pubsdk.InjectOptions
+
+// applyInjectOpts 把注入标志位写进事件 payload。
+//
+// 只在非零时写：零值与旧 payload 逐字节一致，事件订阅方与旧内核
+// （不认识这两个键）都不会受影响。
+//
+// 为什么不把标志位当独立参数传到底：eventloop 与各注入路径都按 payload 取字段
+// （no_memory 本来就是这么走的），payload 是这里唯一已有的携带面。
+func applyInjectOpts(payload map[string]interface{}, opts InjectOptions) {
+	if opts.NoMemory {
+		payload["no_memory"] = true
+	}
+	if opts.ContextPolicy != "" {
+		payload["context_policy"] = opts.ContextPolicy
+	}
+	if opts.CleanerName != "" {
+		payload["cleaner_name"] = opts.CleanerName
+	}
+}
+
+func (m *IOManager) InjectInputOpts(source, eventType string, payload map[string]interface{}, opts InjectOptions) {
+	applyInjectOpts(payload, opts)
+	m.InjectInput(source, eventType, payload)
+}
+
+func (m *IOManager) InjectInputToOpts(source, outputChannel, eventType string, payload map[string]interface{}, opts InjectOptions) {
+	applyInjectOpts(payload, opts)
+	m.InjectInputTo(source, outputChannel, eventType, payload)
+}
+
+func (m *IOManager) InjectInputSyncToOpts(source, outputChannel, eventType string, payload map[string]interface{}, opts InjectOptions) *OutputEvent {
+	applyInjectOpts(payload, opts)
+	return m.InjectInputSyncTo(source, outputChannel, eventType, payload)
+}
+
+func (m *IOManager) InjectInterruptOpts(source, channel string, payload map[string]interface{}, opts InjectOptions) {
+	applyInjectOpts(payload, opts)
+	m.InjectInterrupt(source, channel, payload)
+}
+
 func (m *IOManager) InjectText(source string, text string) {
 	m.InjectInput(source, "text", map[string]interface{}{
 		"content": text,
@@ -293,10 +339,31 @@ func (m *IOManager) InjectInterrupt(source, channel string, payload map[string]i
 }
 
 func (m *IOManager) InjectInterruptText(source, channel, text string) {
-	m.InjectInterrupt(source, channel, map[string]interface{}{
+	m.InjectInterruptTextOpts(source, channel, text, InjectOptions{})
+}
+
+// InjectInterruptTextOpts 注入中断文本，并声明本次注入的记忆/裁剪行为。
+//
+// 中断也允许声明 ContextPolicyPrune：中断同样携带内容进入上下文。
+func (m *IOManager) InjectInterruptTextOpts(source, channel, text string, opts InjectOptions) {
+	m.InjectInterruptOpts(source, channel, map[string]interface{}{
 		"type":    "text",
 		"content": text,
-	})
+	}, opts)
+}
+
+// InjectTextOpts 注入排队文本，并声明本次注入的记忆/裁剪行为。
+func (m *IOManager) InjectTextOpts(source, channel, text string, opts InjectOptions) {
+	m.InjectInputToOpts(source, channel, "text", map[string]interface{}{
+		"content": text,
+	}, opts)
+}
+
+// InjectTextSyncOpts 同步注入文本并声明记忆/裁剪行为。
+func (m *IOManager) InjectTextSyncOpts(source, outputChannel, text string, opts InjectOptions) *OutputEvent {
+	return m.InjectInputSyncToOpts(source, outputChannel, "text", map[string]interface{}{
+		"content": text,
+	}, opts)
 }
 
 func (m *IOManager) InputInterruptChan() <-chan *InputEvent { return m.interruptCh }
@@ -308,6 +375,33 @@ func (m *IOManager) InjectTextSyncTo(source, outputChannel, text string) *Output
 	})
 }
 
+// ---- 带标志位的注入（记忆/裁剪行为由调用点声明）----
+
+// InjectInputMediaOpts 注入带媒体块的输入，并声明记忆/裁剪行为。
+func (m *IOManager) InjectInputMediaOpts(source, outputChannel, text string, blocks []pubsdk.ContentBlock, opts InjectOptions) {
+	m.InjectInputToOpts(source, outputChannel, "text", map[string]interface{}{
+		"content":      text,
+		"media_blocks": blocks,
+	}, opts)
+}
+
+// InjectInputMediaSyncOpts 注入带媒体块的输入并同步等待回复，同时声明记忆/裁剪行为。
+func (m *IOManager) InjectInputMediaSyncOpts(source, outputChannel, text string, blocks []pubsdk.ContentBlock, opts InjectOptions) *OutputEvent {
+	return m.InjectInputSyncToOpts(source, outputChannel, "text", map[string]interface{}{
+		"content":      text,
+		"media_blocks": blocks,
+	}, opts)
+}
+
+// InjectInterruptMediaOpts 注入带媒体块的中断，并声明记忆/裁剪行为。
+func (m *IOManager) InjectInterruptMediaOpts(source, channel, text string, blocks []pubsdk.ContentBlock, opts InjectOptions) {
+	m.InjectInterruptOpts(source, channel, map[string]interface{}{
+		"type":         "text",
+		"content":      text,
+		"media_blocks": blocks,
+	}, opts)
+}
+
 func (m *IOManager) EmitOutput(target string, outputType string, payload map[string]interface{}) {
 	m.outputCh <- &OutputEvent{
 		RequestID: "",
@@ -343,7 +437,7 @@ func (m *IOManager) EmitTextTo(target, outputChannel, text string) {
 	})
 }
 
-func (m *IOManager) InputChan() <-chan *InputEvent  { return m.inputCh }
+func (m *IOManager) InputChan() <-chan *InputEvent   { return m.inputCh }
 func (m *IOManager) OutputChan() <-chan *OutputEvent { return m.outputCh }
 
 // RegisterInputChannel 注册输入通道的记忆行为
@@ -463,12 +557,14 @@ func NewMicrophone(name string, sampleRate int, io *IOManager) *Microphone {
 	return &Microphone{name: name, sampleRate: sampleRate, io: io}
 }
 
-func (d *Microphone) Name() string             { return d.name }
-func (d *Microphone) Type() DeviceType         { return DeviceInput }
+func (d *Microphone) Name() string                         { return d.name }
+func (d *Microphone) Type() DeviceType                     { return DeviceInput }
 func (d *Microphone) OutputCapabilities() OutputCapability { return 0 } // 纯输入
-func (d *Microphone) Description() string { return fmt.Sprintf("麦克风 (%s, %dHz)", d.name, d.sampleRate) }
-func (d *Microphone) Start() error        { return nil }
-func (d *Microphone) Stop() error         { return nil }
+func (d *Microphone) Description() string {
+	return fmt.Sprintf("麦克风 (%s, %dHz)", d.name, d.sampleRate)
+}
+func (d *Microphone) Start() error           { return nil }
+func (d *Microphone) Stop() error            { return nil }
 func (d *Microphone) ChannelDef() ChannelDef { return ChannelDef{} }
 
 func (d *Microphone) Tools() []ToolDef {
@@ -498,13 +594,13 @@ func NewSpeaker(name string, io *IOManager) *Speaker {
 	return &Speaker{name: name, io: io}
 }
 
-func (d *Speaker) Name() string        { return d.name }
-func (d *Speaker) Type() DeviceType    { return DeviceOutput }
+func (d *Speaker) Name() string                         { return d.name }
+func (d *Speaker) Type() DeviceType                     { return DeviceOutput }
 func (d *Speaker) OutputCapabilities() OutputCapability { return CapText | CapAudio }
-func (d *Speaker) Description() string { return fmt.Sprintf("扬声器 (%s)", d.name) }
-func (d *Speaker) Start() error        { return nil }
-func (d *Speaker) Stop() error         { return nil }
-func (d *Speaker) ChannelDef() ChannelDef { return ChannelDef{} }
+func (d *Speaker) Description() string                  { return fmt.Sprintf("扬声器 (%s)", d.name) }
+func (d *Speaker) Start() error                         { return nil }
+func (d *Speaker) Stop() error                          { return nil }
+func (d *Speaker) ChannelDef() ChannelDef               { return ChannelDef{} }
 
 func (d *Speaker) Tools() []ToolDef {
 	return []ToolDef{{
@@ -535,13 +631,13 @@ func NewCamera(name string, io *IOManager) *Camera {
 	return &Camera{name: name, io: io}
 }
 
-func (d *Camera) Name() string        { return d.name }
-func (d *Camera) Type() DeviceType    { return DeviceInput }
+func (d *Camera) Name() string                         { return d.name }
+func (d *Camera) Type() DeviceType                     { return DeviceInput }
 func (d *Camera) OutputCapabilities() OutputCapability { return CapImage } // 可返回图片
-func (d *Camera) Description() string { return fmt.Sprintf("摄像头 (%s)", d.name) }
-func (d *Camera) Start() error        { return nil }
-func (d *Camera) Stop() error         { return nil }
-func (d *Camera) ChannelDef() ChannelDef { return ChannelDef{} }
+func (d *Camera) Description() string                  { return fmt.Sprintf("摄像头 (%s)", d.name) }
+func (d *Camera) Start() error                         { return nil }
+func (d *Camera) Stop() error                          { return nil }
+func (d *Camera) ChannelDef() ChannelDef               { return ChannelDef{} }
 
 func (d *Camera) Tools() []ToolDef {
 	return []ToolDef{
@@ -583,13 +679,13 @@ func NewRobotArm(name string, io *IOManager) *RobotArm {
 	return &RobotArm{name: name, io: io}
 }
 
-func (d *RobotArm) Name() string        { return d.name }
-func (d *RobotArm) Type() DeviceType    { return DeviceIO }
+func (d *RobotArm) Name() string                         { return d.name }
+func (d *RobotArm) Type() DeviceType                     { return DeviceIO }
 func (d *RobotArm) OutputCapabilities() OutputCapability { return CapStructured }
-func (d *RobotArm) Description() string { return fmt.Sprintf("机械臂 (%s)", d.name) }
-func (d *RobotArm) Start() error        { return nil }
-func (d *RobotArm) Stop() error         { return nil }
-func (d *RobotArm) ChannelDef() ChannelDef { return ChannelDef{} }
+func (d *RobotArm) Description() string                  { return fmt.Sprintf("机械臂 (%s)", d.name) }
+func (d *RobotArm) Start() error                         { return nil }
+func (d *RobotArm) Stop() error                          { return nil }
+func (d *RobotArm) ChannelDef() ChannelDef               { return ChannelDef{} }
 
 func (d *RobotArm) Tools() []ToolDef {
 	return []ToolDef{
@@ -635,13 +731,13 @@ func NewGPIODevice(name string, pins []int, io *IOManager) *GPIODevice {
 	return &GPIODevice{name: name, pins: pins, io: io}
 }
 
-func (d *GPIODevice) Name() string        { return d.name }
-func (d *GPIODevice) Type() DeviceType    { return DeviceIO }
+func (d *GPIODevice) Name() string                         { return d.name }
+func (d *GPIODevice) Type() DeviceType                     { return DeviceIO }
 func (d *GPIODevice) OutputCapabilities() OutputCapability { return CapStructured }
-func (d *GPIODevice) Description() string { return "GPIO 通用引脚" }
-func (d *GPIODevice) Start() error        { return nil }
-func (d *GPIODevice) Stop() error         { return nil }
-func (d *GPIODevice) ChannelDef() ChannelDef { return ChannelDef{} }
+func (d *GPIODevice) Description() string                  { return "GPIO 通用引脚" }
+func (d *GPIODevice) Start() error                         { return nil }
+func (d *GPIODevice) Stop() error                          { return nil }
+func (d *GPIODevice) ChannelDef() ChannelDef               { return ChannelDef{} }
 
 func (d *GPIODevice) Tools() []ToolDef {
 	return []ToolDef{

internal/agent/io/injectopts_test.go

@@ -0,0 +1,111 @@
+package io
+
+import (
+	"testing"
+
+	pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
+)
+
+// drainOne 取出一条注入事件；没有则 Fatal。
+func drainOne(t *testing.T, ch <-chan *InputEvent) *InputEvent {
+	t.Helper()
+	select {
+	case evt := <-ch:
+		return evt
+	default:
+		t.Fatal("没有拿到注入事件")
+		return nil
+	}
+}
+
+// 零值 InjectOptions 必须与历史的三参数注入产出**完全一致**的 payload。
+//
+// 这是兼容性底线：任何按 payload 取字段的下游（事件订阅方、旧内核、
+// 工具链测试）都不能因为这次改造而看到新键。
+func TestInjectTextOpts_ZeroValueMatchesLegacyPayload(t *testing.T) {
+	m := NewIOManager()
+	m.InjectText("src", "hello")
+	legacy := drainOne(t, m.InputChan())
+
+	m2 := NewIOManager()
+	m2.InjectTextOpts("src", "chan", "hello", InjectOptions{})
+	withOpts := drainOne(t, m2.InputChan())
+
+	if len(withOpts.Payload) != len(legacy.Payload) {
+		t.Fatalf("零值注入多出了键：legacy=%v opts=%v", legacy.Payload, withOpts.Payload)
+	}
+	for k, v := range legacy.Payload {
+		if withOpts.Payload[k] != v {
+			t.Fatalf("键 %q 不一致：legacy=%v opts=%v", k, v, withOpts.Payload[k])
+		}
+	}
+}
+
+// 标志位必须出现在事件 payload 上——eventloop 就是从那里读的。
+func TestInjectTextOpts_CarriesFlags(t *testing.T) {
+	m := NewIOManager()
+	m.InjectTextOpts("src", "chan", "hello", InjectOptions{
+		NoMemory:      true,
+		ContextPolicy: "prune",
+		CleanerName:   "clean_me",
+	})
+	evt := drainOne(t, m.InputChan())
+
+	if evt.Payload["no_memory"] != true {
+		t.Errorf("no_memory 未传递: %v", evt.Payload["no_memory"])
+	}
+	if evt.Payload["context_policy"] != "prune" {
+		t.Errorf("context_policy 未传递: %v", evt.Payload["context_policy"])
+	}
+	if evt.Payload["cleaner_name"] != "clean_me" {
+		t.Errorf("cleaner_name 未传递: %v", evt.Payload["cleaner_name"])
+	}
+	if evt.Payload["content"] != "hello" {
+		t.Errorf("content 丢失: %v", evt.Payload["content"])
+	}
+	if evt.OutputChannel != "chan" {
+		t.Errorf("输出通道 = %q，期望 chan", evt.OutputChannel)
+	}
+}
+
+// 中断注入走另一条队列，标志位同样要带上（用户已确认中断允许声明 prune）。
+func TestInjectInterruptTextOpts_CarriesFlags(t *testing.T) {
+	m := NewIOManager()
+	m.InjectInterruptTextOpts("src", "chan", "alert", InjectOptions{ContextPolicy: "prune"})
+	evt := drainOne(t, m.InputInterruptChan())
+
+	if evt.Payload["context_policy"] != "prune" {
+		t.Errorf("中断注入的 context_policy 未传递: %v", evt.Payload)
+	}
+	if evt.Payload["type"] != "text" || evt.Payload["content"] != "alert" {
+		t.Errorf("中断注入的基本字段不对: %v", evt.Payload)
+	}
+	if _, has := evt.Payload["no_memory"]; has {
+		t.Errorf("未声明的 no_memory 不应出现: %v", evt.Payload)
+	}
+}
+
+// 带媒体的注入同样要带标志位。
+func TestInjectInputMediaOpts_CarriesFlags(t *testing.T) {
+	m := NewIOManager()
+	blocks := []pubsdk.ContentBlock{{Type: "image_url", ImageURL: &pubsdk.ImageURL{URL: "data:image/png;base64,AA"}}}
+	m.InjectInputMediaOpts("src", "chan", "看图", blocks, InjectOptions{NoMemory: true})
+	evt := drainOne(t, m.InputChan())
+
+	if evt.Payload["no_memory"] != true {
+		t.Errorf("媒体的 no_memory 未传递: %v", evt.Payload)
+	}
+	if _, ok := evt.Payload["media_blocks"]; !ok {
+		t.Errorf("媒体块丢失: %v", evt.Payload)
+	}
+}
+
+// 旧方法必须继续等价工作（它们是 Opts 变体的零值糖）。
+func TestLegacyNoMemoryMethodStillSetsFlag(t *testing.T) {
+	m := NewIOManager()
+	m.InjectTextNoMemoryTo("src", "chan", "quiet")
+	evt := drainOne(t, m.InputChan())
+	if evt.Payload["no_memory"] != true {
+		t.Fatalf("旧 NoMemory 方法应置位: %v", evt.Payload)
+	}
+}

internal/config/registry.go

@@ -482,9 +482,30 @@ func (r *ConfigRegistry) SeedDefaults(dataDir string) {
 }
 
 func (r *ConfigRegistry) seedDBValues(dataDir string) {
-	var count int
-	r.db.QueryRow(`SELECT COUNT(*) FROM config`).Scan(&count)
-	if count > 0 {
+	// 新鲜度判据不能是「config 表非空」。
+	//
+	// 发行包的 postinst 会先跑 setup.sh → initconfig，而 initconfig 会写一行
+	// webui.listen_addr。于是**全新安装**的 DB 看上去"已经有内容"，整个默认值
+	// 播种被跳过：core.plugin.dir、core.memory.*、多模态 provider 一个都没写。
+	// 现场表现是装完 0 个插件、随包的模型与运行库成死重量。
+	//
+	// 也不能改成"每次都补缺键"：老安装升级时被注进新默认值，会让它突然
+	// 去加载一个 1.8GB 的模型——那是刻意要避免的行为（静默变重）。
+	//
+	// 故用显式标记区分三种情形：
+	//   有标记               → 已经播过种，直接返回
+	//   无标记但有 core.daemon.data_dir → 老安装（本键历来由播种写入），
+	//                        只补标记、不播种
+	//   两者都没有           → 全新安装，播种并打标记
+	const markerKey = "core.internal.seed_version"
+	var hasMarker, hasLegacy int
+	r.db.QueryRow(`SELECT COUNT(*) FROM config WHERE key = ?`, markerKey).Scan(&hasMarker)
+	if hasMarker > 0 {
+		return
+	}
+	r.db.QueryRow(`SELECT COUNT(*) FROM config WHERE key = 'core.daemon.data_dir'`).Scan(&hasLegacy)
+	if hasLegacy > 0 {
+		r.db.Exec(`INSERT OR IGNORE INTO config (key, value) VALUES (?, ?)`, markerKey, "1")
 		return
 	}
 
@@ -544,6 +565,14 @@ func (r *ConfigRegistry) seedDBValues(dataDir string) {
 	set("core.memory.graph", filepath.Join(dataDir, "memory", "graph.db"))
 	set("core.memory.text", filepath.Join(dataDir, "memory", "text"))
 	set("core.memory.documents", filepath.Join(dataDir, "memory", "documents"))
+	set("core.memory.media.dir", filepath.Join(dataDir, "memory", "media"))
+	// 发行版默认启用本地向量空间。用 chineseclip（text+image、512 维、实测
+	// 常驻 1.15GB、Apache-2.0）而不是 qwen3vl（9.4GB）：多数机器装不下后者。
+	// 产物不在仓库里，用 scripts/export_chineseclip_onnx.py 生成到这个路径；
+	// 产物缺失时 homed 会打印明确错误并退回 fastText 文本路径（不静默假装启用）。
+	set("core.memory.multimodal_space.provider", "chineseclip")
+	set("core.memory.multimodal_space.options.model_dir",
+		filepath.Join(dataDir, "models", "chinese-clip-vit-b16-onnx"))
 	set("core.knowledge.path", filepath.Join(dataDir, "knowledge"))
 	set("core.log.path", filepath.Join(dataDir, "log"))
 
@@ -596,6 +625,8 @@ WebUI 概览页展示你的立绘，可通过 /mascot.webp 直接访问。如输
 	set("core.input_processing.audio.fallback_model", "")
 	set("core.input_processing.audio.describe_prompt", "请转写这段音频的内容。")
 
+	set(markerKey, "1")
+
 	tx.Commit()
 }
 
@@ -648,6 +679,16 @@ func (r *ConfigRegistry) seedCoreDefs(dataDir string) {
 	reg(ConfigDef{Key: "core.memory.graph", Default: filepath.Join(dataDir, "memory", "graph.db"), Type: "string", DisplayName: "图数据库路径", Description: "长期记忆（图数据库）存储路径", Category: "paths"})
 	reg(ConfigDef{Key: "core.memory.text", Default: filepath.Join(dataDir, "memory", "text"), Type: "string", DisplayName: "文本记忆路径", Description: "短期文本记忆存储目录", Category: "paths"})
 	reg(ConfigDef{Key: "core.memory.documents", Default: filepath.Join(dataDir, "memory", "documents"), Type: "string", DisplayName: "文档记忆路径", Description: "文档记忆存储目录", Category: "paths"})
+	reg(ConfigDef{Key: "core.memory.media.enabled", Default: "true", Type: "bool", DisplayName: "媒体记忆", Description: "把对话里出现的图片/音频变成一等记忆块，内容按 sha256 落盘去重。关闭后媒体仅在当前对话内可见，下一轮起只剩路径或 alt 文本", Category: "memory"})
+	reg(ConfigDef{Key: "core.memory.media.dir", Default: filepath.Join(dataDir, "memory", "media"), Type: "string", DisplayName: "媒体存储路径", Description: "媒体内容寻址存储目录（内含 media.db 与 blobs/）", Category: "paths"})
+	reg(ConfigDef{Key: "core.memory.multimodal_space.provider", Default: "chineseclip", Type: "string", DisplayName: "多模态向量 provider", Description: "从公共 provider 注册表（pkg/embedding）按名字打开的多模态向量空间。内置：chineseclip（默认，text+image，512 维，实测常驻 1.15GB，Apache-2.0）、qwen3vl（text+image，2048 维，常驻 9.4GB；视频已实现但未纳入契约）、http（外部向量 API）。也可是第三方注册的名字。两者均需 onnxruntime 构建标签。留空禁用多模态向量检索，只保留 fastText 文本路径。provider 的模型文件、预处理与运行时全在 provider 内部，核心不做任何模型假设。修改后需重启生效。", Category: "memory"})
+	reg(ConfigDef{Key: "core.memory.multimodal_space.options.model_dir", Default: filepath.Join(dataDir, "models", "chinese-clip-vit-b16-onnx"), Type: "string", DisplayName: "provider 模型目录", Description: "provider 自定义选项（以 options. 开头的键会去掉前缀后原样传给 provider，核心不解释其含义）。对内置 chineseclip：Chinese-CLIP 产物目录（用 scripts/export_chineseclip_onnx.py 生成）。对内置 qwen3vl：Qwen3-VL ONNX 产物目录（用 scripts/export_qwen3vl_embedding_onnx.py 生成）。", Category: "memory"})
+	reg(ConfigDef{Key: "core.memory.multimodal_space.options.endpoint", Default: "", Type: "string", DisplayName: "provider 服务端点", Description: "provider 自定义选项。对内置 http：外部多模态向量服务的端点 URL（POST，接受 modality/side/text/data/mime，返回 embedding）。", Category: "memory"})
+	reg(ConfigDef{Key: "core.memory.multimodal_space.options.api_key", Default: "", Type: "password", DisplayName: "provider 服务密钥", Description: "provider 自定义选项。对内置 http：作为 Bearer token 发送。可选。", Category: "memory"})
+	reg(ConfigDef{Key: "core.memory.multimodal_space.options.model", Default: "", Type: "string", DisplayName: "provider 模型标识", Description: "provider 自定义选项。对内置 http：外部服务使用的模型名，作为 vec_model 持久化。", Category: "memory"})
+	reg(ConfigDef{Key: "core.memory.multimodal_space.options.dimension", Default: "0", Type: "int", DisplayName: "provider 向量维度", Description: "provider 自定义选项。对内置 http：服务返回的特征向量维度，必须与实际返回值一致。", Category: "memory"})
+	reg(ConfigDef{Key: "core.memory.multimodal_space.options.timeout", Default: "30s", Type: "duration", DisplayName: "provider 请求超时", Description: "provider 自定义选项。对内置 http：单次向量请求的超时时间。", Category: "memory"})
+	reg(ConfigDef{Key: "core.memory.multimodal_space.options.fingerprint", Default: "", Type: "string", DisplayName: "provider 空间指纹", Description: "provider 自定义选项。对内置 http：向量空间版本标识（留空时根据 model+dim 自动生成）。指纹变化会触发历史向量重算。", Category: "memory"})
 	reg(ConfigDef{Key: "core.knowledge.path", Default: filepath.Join(dataDir, "knowledge"), Type: "string", DisplayName: "知识库路径", Description: "知识库存储目录", Category: "paths"})
 	reg(ConfigDef{Key: "core.log.path", Default: filepath.Join(dataDir, "log"), Type: "string", DisplayName: "日志目录", Description: "日志文件输出目录", Category: "paths"})
 

internal/config/registry_test.go

@@ -188,6 +188,65 @@ func TestSeedDefaultsToConfig(t *testing.T) {
 	r.Close()
 }
 
+// 发行包全新安装：postinst 先跑 setup.sh → initconfig，而 initconfig 只写
+// webui.listen_addr。于是 config 表已经非空，旧实现据此判定“已有配置”并整体
+// 跳过播种——装完没有 core.plugin.dir（0 个插件）、也没有随包模型对应的
+// 多模态 provider（754MB 产物 + 24MB 运行库全成死重量）。
+func TestSeedDefaultsAfterInitconfigPrepopulate(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.db")
+
+	r := NewConfigRegistry(path)
+	// 精确复现 initconfig 的唯一一笔写入
+	if _, err := r.db.Exec(`INSERT INTO config (key, value) VALUES ('webui.listen_addr', ':8080')`); err != nil {
+		t.Fatalf("预置 initconfig 行: %v", err)
+	}
+
+	r.SeedDefaults(dir)
+
+	for _, k := range []string{"core.daemon.data_dir", "core.plugin.dir", "core.memory.multimodal_space.provider"} {
+		if r.GetString(k, "") == "" {
+			t.Fatalf("全新安装（initconfig 已写 webui.listen_addr）后 %s 仍为空：默认值播种被跳过", k)
+		}
+	}
+	if got := r.GetString("core.memory.multimodal_space.provider", ""); got != "chineseclip" {
+		t.Fatalf("随包默认 provider 应为 chineseclip，实为 %q", got)
+	}
+	r.Close()
+}
+
+// 老安装升级：绝不能因为新版本加了默认值就把它注进现有 DB——那会让升级即
+// 静默加载一个 1.8GB 的模型。判据是 core.daemon.data_dir 在场（老安装由播种
+// 写入）而 seed 标记缺失。
+func TestSeedDefaultsDoesNotInjectIntoLegacyInstall(t *testing.T) {
+	dir := t.TempDir()
+	path := filepath.Join(dir, "config.db")
+
+	r := NewConfigRegistry(path)
+	if _, err := r.db.Exec(`INSERT INTO config (key, value) VALUES ('core.daemon.data_dir', ?)`, dir); err != nil {
+		t.Fatalf("预置老安装行: %v", err)
+	}
+
+	r.SeedDefaults(dir)
+
+	if got := r.GetString("core.memory.multimodal_space.provider", ""); got != "" {
+		t.Fatalf("老安装升级被注入新默认值 provider=%q（升级后会静默加载大模型）", got)
+	}
+	if got := r.GetString("core.plugin.dir", ""); got != "" {
+		t.Fatalf("老安装升级被注入新默认值 core.plugin.dir=%q", got)
+	}
+
+	// 但标记必须补上，否则每次启动都会重走判断
+	var n int
+	if err := r.db.QueryRow(`SELECT COUNT(*) FROM config WHERE key = 'core.internal.seed_version'`).Scan(&n); err != nil {
+		t.Fatalf("查 seed 标记: %v", err)
+	}
+	if n != 1 {
+		t.Fatalf("老安装应补上 seed 标记，实际 count=%d", n)
+	}
+	r.Close()
+}
+
 func TestGetHelpers(t *testing.T) {
 	r := NewConfigRegistry("")
 	r.Set("str_key", "hello")

internal/knowledge/knowledge.go

@@ -201,6 +201,13 @@ func (s *Store) Add(name, content string) error {
 	}
 	s.items[id] = k
 
+	// 覆盖同名条目时必须先摘掉旧向量。
+	//
+	// vector.Store.Insert 是**追加**语义（s.docs = append + index.Add），不按 id
+	// 去重。少了这一步，更新一条知识会在向量索引里留下上一版的副本：条目数看起来
+	// 是对的，只有向量数比条目数多——而检索可能因此命中已被替换掉的旧内容。
+	s.vec.Remove(id)
+
 	vec := s.vectorize(name + " " + content)
 	s.vec.Insert(id, name+": "+content, vec, map[string]string{
 		"name": name, "path": path,

internal/knowledge/knowledge_test.go

@@ -44,6 +44,51 @@ func TestAddAndSearch(t *testing.T) {
 	}
 }
 
+// 覆盖同名条目必须把旧向量摘掉，而不是再插一份。
+//
+// 这条是从一次真实的知识库更新里发现的：在线上实例更新一个已有条目后，
+// knowledge_count=32 但 vector_count=33 ——多出来的那一条是上一版的副本。
+// 成因是 vector.Store.Insert 为追加语义（s.docs = append + index.Add），不按 id 去重。
+// 危害不在于多占一份内存：检索可能命中**已被替换掉的旧内容**。
+func TestAddOverwriteReplacesVector(t *testing.T) {
+	dir, err := os.MkdirTemp("", "know_overwrite_*")
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer os.RemoveAll(dir)
+
+	s := NewStore(dir)
+	s.Start()
+	defer s.Stop()
+
+	if err := s.Add("recent", "第一版内容：旧的多模态描述式索引"); err != nil {
+		t.Fatal(err)
+	}
+	if got := s.Stats()["vector_count"].(int); got != 1 {
+		t.Fatalf("首次写入后 vector_count 应为 1，实为 %d", got)
+	}
+
+	if err := s.Add("recent", "第二版内容：媒体已成为图记忆的一等节点"); err != nil {
+		t.Fatal(err)
+	}
+
+	if n := s.Stats()["knowledge_count"].(int); n != 1 {
+		t.Fatalf("同名覆盖后 knowledge_count 应为 1，实为 %d", n)
+	}
+	if n := s.Stats()["vector_count"].(int); n != 1 {
+		t.Fatalf("同名覆盖后 vector_count 应为 1（多了就是旧版没被摘掉），实为 %d", n)
+	}
+
+	// 目录里也只应有一份内容，且是新的那份
+	b, err := os.ReadFile(dir + "/recent/content.md")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if string(b) != "第二版内容：媒体已成为图记忆的一等节点" {
+		t.Fatalf("content.md 未被新内容覆盖，实为 %q", string(b))
+	}
+}
+
 func TestList(t *testing.T) {
 	dir, err := os.MkdirTemp("", "know_list_*")
 	if err != nil {

internal/memory/bilingual_test.go

@@ -7,11 +7,11 @@ import (
 )
 
 type bilingualEvent struct {
-	idx     int
-	source  string
-	topic   string
-	text    string // cleaned text for vectorization
-	label   string // short description
+	idx    int
+	source string
+	topic  string
+	text   string // cleaned text for vectorization
+	label  string // short description
 }
 
 func TestBilingualPruningAccuracy(t *testing.T) {
@@ -40,16 +40,16 @@ func TestBilingualPruningAccuracy(t *testing.T) {
 			t.Logf("%s: %d words", cfg.name, len(e.words))
 
 			type scored struct {
-				idx    int
-				topic  string
-				label  string
-				score  float64
+				idx   int
+				topic string
+				label string
+				score float64
 			}
 
 			queries := []struct {
-				q       string
-				qTopic  string
-				desc    string
+				q      string
+				qTopic string
+				desc   string
 			}{
 				{"老大说了关于 React 组件的事情", "老大私聊", "中英混合:老大+React"},
 				{"帮我查一下 Nginx 反向代理配置", "服务器运维", "中英混合:Nginx+反向代理"},
@@ -189,10 +189,10 @@ func TestBilingualVectorizeClean(t *testing.T) {
 
 func genBilingualEvents() []bilingualEvent {
 	entries := []struct {
-		topic   string
-		zh      string // Chinese description
-		en      string // English terms mixed in
-		source  string
+		topic  string
+		zh     string // Chinese description
+		en     string // English terms mixed in
+		source string
 	}{
 		{"大学招生", "河南医药大学录取分数线", "", "qq"},
 		{"大学招生", "医学院专业排名", "medical university ranking", "agent"},

internal/memory/block.go

@@ -0,0 +1,271 @@
+package memory
+
+import (
+	"database/sql"
+	"encoding/json"
+	"fmt"
+	"time"
+)
+
+// BlockModality 是一等记忆块的原生模态。
+type BlockModality string
+
+const (
+	BlockText  BlockModality = "text"
+	BlockImage BlockModality = "image"
+	BlockVideo BlockModality = "video"
+	BlockAudio BlockModality = "audio"
+)
+
+// MemoryBlock 是 Context、Document、Graph 三层共同使用的记忆块值。
+//
+// 它不携带 Layer、Owner 或 RefCount：块当前由哪个层的容器持有，哪个层就是
+// 唯一事实源。Context→Document→Graph 迁移的是这个值本身，不建立平行保活账本。
+// PayloadDigest 仅用于定位内容寻址的原始字节，不表示另一条逻辑记忆。
+type MemoryBlock struct {
+	ID            string        `json:"id"`
+	Modality      BlockModality `json:"modality"`
+	Text          string        `json:"text,omitempty"`
+	PayloadDigest string        `json:"payload_digest,omitempty"`
+	MIME          string        `json:"mime,omitempty"`
+	Size          int64         `json:"size,omitempty"`
+	Width         int           `json:"width,omitempty"`
+	Height        int           `json:"height,omitempty"`
+	Vector        []float64     `json:"vector,omitempty"`
+	Fingerprint   string        `json:"fingerprint,omitempty"`
+	Source        string        `json:"source,omitempty"`
+	Tool          string        `json:"tool,omitempty"`
+	CreatedAt     time.Time     `json:"created_at"`
+	UpdatedAt     time.Time     `json:"updated_at"`
+}
+
+// MemoryBlockEdge 是 L3 中连接一等记忆节点的结构化语义边。
+// source/target kind 当前允许 block、entity、sentence、document。
+type MemoryBlockEdge struct {
+	ID         int64     `json:"id"`
+	SourceKind string    `json:"source_kind"`
+	SourceID   string    `json:"source_id"`
+	TargetKind string    `json:"target_kind"`
+	TargetID   string    `json:"target_id"`
+	Type       string    `json:"type"`
+	CreatedAt  time.Time `json:"created_at"`
+}
+
+func validBlockModality(modality BlockModality) bool {
+	return modality == BlockText || modality == BlockImage || modality == BlockVideo || modality == BlockAudio
+}
+
+// PutMemoryBlocks 将完成 L2→L3 迁移的块写成 GraphDB 原生节点。
+// 调用方只有在本事务成功后才能从 Document 删除这些块。
+func (g *GraphDB) PutMemoryBlocks(blocks []MemoryBlock) error {
+	if len(blocks) == 0 {
+		return nil
+	}
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	tx, err := g.db.Begin()
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback()
+
+	for _, block := range blocks {
+		if block.ID == "" {
+			return fmt.Errorf("memory block id is required")
+		}
+		if !validBlockModality(block.Modality) {
+			return fmt.Errorf("memory block %s has invalid modality %q", block.ID, block.Modality)
+		}
+		vectorJSON, err := json.Marshal(block.Vector)
+		if err != nil {
+			return fmt.Errorf("marshal memory block %s vector: %w", block.ID, err)
+		}
+		now := time.Now()
+		if block.CreatedAt.IsZero() {
+			block.CreatedAt = now
+		}
+		_, err = tx.Exec(`INSERT INTO memory_blocks (
+			id, modality, text_content, payload_digest, mime, size, width, height,
+			vector, fingerprint, source, tool, created_at, updated_at
+		) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		ON CONFLICT(id) DO UPDATE SET
+			modality = excluded.modality,
+			text_content = excluded.text_content,
+			payload_digest = excluded.payload_digest,
+			mime = excluded.mime,
+			size = excluded.size,
+			width = excluded.width,
+			height = excluded.height,
+			vector = excluded.vector,
+			fingerprint = excluded.fingerprint,
+			source = excluded.source,
+			tool = excluded.tool,
+			updated_at = excluded.updated_at`,
+			block.ID, block.Modality, block.Text, block.PayloadDigest, block.MIME,
+			block.Size, block.Width, block.Height, string(vectorJSON), block.Fingerprint,
+			block.Source, block.Tool, block.CreatedAt, now)
+		if err != nil {
+			return fmt.Errorf("put memory block %s: %w", block.ID, err)
+		}
+	}
+	return tx.Commit()
+}
+
+// PutDocumentNode 在 L3 登记一个文档节点，作为 document --contains--> block
+// 结构边的端点。文档正文已蒸馏为实体/关系，这里只保留身份与摘要。
+func (g *GraphDB) PutDocumentNode(id, summary string) error {
+	if id == "" {
+		return fmt.Errorf("document node id is required")
+	}
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	_, err := g.db.Exec(`INSERT INTO documents (id, summary) VALUES (?, ?)
+		ON CONFLICT(id) DO UPDATE SET summary = excluded.summary`, id, summary)
+	return err
+}
+
+// MemoryBlocks 查询 Graph 层实际持有的一等记忆节点。
+func (g *GraphDB) MemoryBlocks() ([]MemoryBlock, error) {
+	g.mu.RLock()
+	defer g.mu.RUnlock()
+	rows, err := g.db.Query(`SELECT id, modality, text_content, payload_digest, mime,
+		size, width, height, vector, fingerprint, source, tool, created_at, updated_at
+		FROM memory_blocks ORDER BY created_at, id`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var blocks []MemoryBlock
+	for rows.Next() {
+		var block MemoryBlock
+		var vectorJSON string
+		if err := rows.Scan(&block.ID, &block.Modality, &block.Text, &block.PayloadDigest,
+			&block.MIME, &block.Size, &block.Width, &block.Height, &vectorJSON,
+			&block.Fingerprint, &block.Source, &block.Tool, &block.CreatedAt,
+			&block.UpdatedAt); err != nil {
+			return nil, err
+		}
+		if vectorJSON != "" && vectorJSON != "null" {
+			if err := json.Unmarshal([]byte(vectorJSON), &block.Vector); err != nil {
+				return nil, fmt.Errorf("decode memory block %s vector: %w", block.ID, err)
+			}
+		}
+		blocks = append(blocks, block)
+	}
+	return blocks, rows.Err()
+}
+
+func validGraphNodeKind(kind string) bool {
+	return kind == "block" || kind == "entity" || kind == "sentence" || kind == "document"
+}
+
+func graphNodeExists(tx *sql.Tx, kind, id string) (bool, error) {
+	var n int
+	var err error
+	switch kind {
+	case "block":
+		err = tx.QueryRow(`SELECT COUNT(*) FROM memory_blocks WHERE id = ?`, id).Scan(&n)
+	case "entity":
+		err = tx.QueryRow(`SELECT COUNT(*) FROM entities WHERE CAST(id AS TEXT) = ?`, id).Scan(&n)
+	case "sentence":
+		err = tx.QueryRow(`SELECT COUNT(*) FROM sentences WHERE CAST(id AS TEXT) = ?`, id).Scan(&n)
+	case "document":
+		err = tx.QueryRow(`SELECT COUNT(*) FROM documents WHERE id = ?`, id).Scan(&n)
+	default:
+		return false, fmt.Errorf("invalid graph node kind %q", kind)
+	}
+	return n == 1, err
+}
+
+// AddMemoryBlockEdge 建立 contains、depicts、derived_from 等原生图边。
+// 端点必须是真实 Graph 节点，不能用 owner 字符串伪装关系。
+func (g *GraphDB) AddMemoryBlockEdge(sourceKind, sourceID, targetKind, targetID, edgeType string) error {
+	if !validGraphNodeKind(sourceKind) || !validGraphNodeKind(targetKind) {
+		return fmt.Errorf("invalid memory block edge kinds %q -> %q", sourceKind, targetKind)
+	}
+	if sourceID == "" || targetID == "" || edgeType == "" {
+		return fmt.Errorf("memory block edge endpoints and type are required")
+	}
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	tx, err := g.db.Begin()
+	if err != nil {
+		return err
+	}
+	defer tx.Rollback()
+	for _, endpoint := range []struct{ kind, id string }{{sourceKind, sourceID}, {targetKind, targetID}} {
+		exists, err := graphNodeExists(tx, endpoint.kind, endpoint.id)
+		if err != nil {
+			return err
+		}
+		if !exists {
+			return fmt.Errorf("%s graph node %s does not exist", endpoint.kind, endpoint.id)
+		}
+	}
+	_, err = tx.Exec(`INSERT OR IGNORE INTO memory_block_edges
+		(source_kind, source_id, target_kind, target_id, edge_type)
+		VALUES (?, ?, ?, ?, ?)`, sourceKind, sourceID, targetKind, targetID, edgeType)
+	if err != nil {
+		return err
+	}
+	return tx.Commit()
+}
+
+func (g *GraphDB) MemoryBlockEdges() ([]MemoryBlockEdge, error) {
+	g.mu.RLock()
+	defer g.mu.RUnlock()
+	rows, err := g.db.Query(`SELECT id, source_kind, source_id, target_kind, target_id,
+		edge_type, created_at FROM memory_block_edges ORDER BY id`)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var edges []MemoryBlockEdge
+	for rows.Next() {
+		var edge MemoryBlockEdge
+		if err := rows.Scan(&edge.ID, &edge.SourceKind, &edge.SourceID, &edge.TargetKind,
+			&edge.TargetID, &edge.Type, &edge.CreatedAt); err != nil {
+			return nil, err
+		}
+		edges = append(edges, edge)
+	}
+	return edges, rows.Err()
+}
+
+// BlocksForNode 返回与某个图节点通过任意边相连的一等记忆块。
+// 例：sentence --contains--> block；entity --depicts--> block。
+func (g *GraphDB) BlocksForNode(nodeKind, nodeID string) ([]MemoryBlock, error) {
+	g.mu.RLock()
+	defer g.mu.RUnlock()
+	rows, err := g.db.Query(`SELECT b.id, b.modality, b.text_content, b.payload_digest,
+		b.mime, b.size, b.width, b.height, b.vector, b.fingerprint, b.source, b.tool,
+		b.created_at, b.updated_at
+		FROM memory_block_edges e
+		JOIN memory_blocks b ON (
+			(e.source_kind = 'block' AND e.source_id = b.id AND e.target_kind = ? AND e.target_id = ?)
+			OR (e.target_kind = 'block' AND e.target_id = b.id AND e.source_kind = ? AND e.source_id = ?))
+		ORDER BY b.created_at, b.id`, nodeKind, nodeID, nodeKind, nodeID)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+	var blocks []MemoryBlock
+	for rows.Next() {
+		var block MemoryBlock
+		var vectorJSON string
+		if err := rows.Scan(&block.ID, &block.Modality, &block.Text, &block.PayloadDigest,
+			&block.MIME, &block.Size, &block.Width, &block.Height, &vectorJSON,
+			&block.Fingerprint, &block.Source, &block.Tool, &block.CreatedAt,
+			&block.UpdatedAt); err != nil {
+			return nil, err
+		}
+		if vectorJSON != "" && vectorJSON != "null" {
+			if err := json.Unmarshal([]byte(vectorJSON), &block.Vector); err != nil {
+				return nil, fmt.Errorf("decode memory block %s vector: %w", block.ID, err)
+			}
+		}
+		blocks = append(blocks, block)
+	}
+	return blocks, rows.Err()
+}

internal/memory/clean_stress_test.go

@@ -28,13 +28,13 @@ func cleanQQTemplate(text string) string {
 }
 
 type cleanTestEvent struct {
-	idx     int
-	source  string
-	input   string
-	response string
-	rawText string
+	idx         int
+	source      string
+	input       string
+	response    string
+	rawText     string
 	cleanedText string
-	topic  string
+	topic       string
 }
 
 func TestCleanStressPrecision(t *testing.T) {
@@ -59,53 +59,53 @@ func TestCleanStressPrecision(t *testing.T) {
 			}
 			t.Logf("topics: %v, events: %d", usedTopics, len(events))
 
-	for _, qTopic := range usedTopics {
-		query := queryForTopic(qTopic)
-		qVec := e.Vectorize(query)
+			for _, qTopic := range usedTopics {
+				query := queryForTopic(qTopic)
+				qVec := e.Vectorize(query)
 
-		type scored struct {
-			idx   int
-			topic string
-			text  string
-			score float64
-		}
-		all := make([]scored, len(events))
-		for i, ev := range events {
-			text := ev.rawText
-			if cleanMode {
-				text = ev.cleanedText
+				type scored struct {
+					idx   int
+					topic string
+					text  string
+					score float64
+				}
+				all := make([]scored, len(events))
+				for i, ev := range events {
+					text := ev.rawText
+					if cleanMode {
+						text = ev.cleanedText
+					}
+					vec := e.Vectorize(text)
+					all[i] = scored{idx: i, topic: ev.topic, text: text, score: cosineSim(qVec, vec)}
+				}
+				sort.Slice(all, func(i, j int) bool { return all[i].score > all[j].score })
+
+				topK := len(usedTopics) * 2
+				if topK > len(all) {
+					topK = len(all)
+				}
+
+				intraHits := 0
+				for _, s := range all[:topK] {
+					if s.topic == qTopic {
+						intraHits++
+					}
+				}
+				expected := countTopicEvents(events, qTopic)
+				if expected > topK {
+					expected = topK
+				}
+				recall := float64(intraHits) / float64(expected)
+
+				if recall < 0.3 {
+					t.Logf("  [LOW] query=%q topK=%d intra=%d/%d recall=%.2f", qTopic, topK, intraHits, expected, recall)
+					for _, s := range all[:8] {
+						t.Logf("    [%.4f] %s", s.score, trimLen(s.text, 60))
+					}
+				} else {
+					t.Logf("  [OK] query=%q topK=%d intra=%d/%d recall=%.2f", qTopic, topK, intraHits, expected, recall)
+				}
 			}
-			vec := e.Vectorize(text)
-			all[i] = scored{idx: i, topic: ev.topic, text: text, score: cosineSim(qVec, vec)}
-		}
-		sort.Slice(all, func(i, j int) bool { return all[i].score > all[j].score })
-
-		topK := len(usedTopics) * 2
-		if topK > len(all) {
-			topK = len(all)
-		}
-
-		intraHits := 0
-		for _, s := range all[:topK] {
-			if s.topic == qTopic {
-				intraHits++
-			}
-		}
-		expected := countTopicEvents(events, qTopic)
-		if expected > topK {
-			expected = topK
-		}
-		recall := float64(intraHits) / float64(expected)
-
-		if recall < 0.3 {
-			t.Logf("  [LOW] query=%q topK=%d intra=%d/%d recall=%.2f", qTopic, topK, intraHits, expected, recall)
-			for _, s := range all[:8] {
-				t.Logf("    [%.4f] %s", s.score, trimLen(s.text, 60))
-			}
-		} else {
-			t.Logf("  [OK] query=%q topK=%d intra=%d/%d recall=%.2f", qTopic, topK, intraHits, expected, recall)
-		}
-	}
 		})
 	}
 }
@@ -252,11 +252,11 @@ func genStressEvents(n int) []cleanTestEvent {
 		keywords []string
 		sources  []string
 	}{
-		"大学招生": {[]string{"河南医药大学", "录取分数线", "专业排名", "高考志愿", "招生简章"}, []string{"qq", "qq", "agent"}},
-		"老大私聊": {[]string{"老大私聊消息", "回复老大", "任务安排", "汇报工作", "收到"}, []string{"qq", "agent", "agent"}},
-		"前端开发": {[]string{"前端组件封装", "页面路由配置", "界面布局设计", "交互逻辑开发", "代码调试优化"}, []string{"cli", "cli", "agent"}},
+		"大学招生":  {[]string{"河南医药大学", "录取分数线", "专业排名", "高考志愿", "招生简章"}, []string{"qq", "qq", "agent"}},
+		"老大私聊":  {[]string{"老大私聊消息", "回复老大", "任务安排", "汇报工作", "收到"}, []string{"qq", "agent", "agent"}},
+		"前端开发":  {[]string{"前端组件封装", "页面路由配置", "界面布局设计", "交互逻辑开发", "代码调试优化"}, []string{"cli", "cli", "agent"}},
 		"服务器运维": {[]string{"反向代理配置", "容器部署方案", "证书续期", "数据库备份恢复", "监控告警处理"}, []string{"cli", "agent", "agent"}},
-		"股票基金": {[]string{"基金定投策略", "股票涨跌分析", "理财收益计算", "市场行情分析", "投资风险管理"}, []string{"qq", "qq", "agent"}},
+		"股票基金":  {[]string{"基金定投策略", "股票涨跌分析", "理财收益计算", "市场行情分析", "投资风险管理"}, []string{"qq", "qq", "agent"}},
 	}
 
 	for i := 0; i < n; i++ {
@@ -292,13 +292,13 @@ func genStressEvents(n int) []cleanTestEvent {
 		cleaned := cleanEventText(src, input, response)
 		raw := rawEventText(src, input, response)
 		events = append(events, cleanTestEvent{
-			idx:     i,
-			source:  src,
-			input:   input,
-			response: response,
-			rawText: raw,
+			idx:         i,
+			source:      src,
+			input:       input,
+			response:    response,
+			rawText:     raw,
 			cleanedText: cleaned,
-			topic:  tp,
+			topic:       tp,
 		})
 	}
 	return events

internal/memory/cut.go

@@ -13,26 +13,26 @@ import (
 
 // contentPOS 有实义的词性标签：只保留名词/动词/形容词/专名等
 var contentPOS = map[string]bool{
-	"n":  true, // 普通名词
-	"nr": true, // 人名
-	"ns": true, // 地名
-	"nt": true, // 机构名
-	"nw": true, // 作品名/URL
-	"nz": true, // 其他专名
-	"v":  true, // 动词
-	"vd": true, // 副动词
-	"vn": true, // 名动词
-	"a":  true, // 形容词
-	"ad": true, // 副形词
-	"an": true, // 名形词
-	"i":  true, // 成语
-	"l":  true, // 习用语
-	"j":  true, // 简称
-	"s":  true, // 处所词
-	"f":  true, // 方位词
-	"b":  true, // 区别词
-	"z":  true, // 状态词
-	"t":  true, // 时间词
+	"n":   true, // 普通名词
+	"nr":  true, // 人名
+	"ns":  true, // 地名
+	"nt":  true, // 机构名
+	"nw":  true, // 作品名/URL
+	"nz":  true, // 其他专名
+	"v":   true, // 动词
+	"vd":  true, // 副动词
+	"vn":  true, // 名动词
+	"a":   true, // 形容词
+	"ad":  true, // 副形词
+	"an":  true, // 名形词
+	"i":   true, // 成语
+	"l":   true, // 习用语
+	"j":   true, // 简称
+	"s":   true, // 处所词
+	"f":   true, // 方位词
+	"b":   true, // 区别词
+	"z":   true, // 状态词
+	"t":   true, // 时间词
 	"eng": true, // 英文
 	"x":   true, // 非语素字
 	"zg":  true, // 其他
@@ -53,7 +53,7 @@ func GetJieba() *gojieba.Jieba {
 		}()
 		d := jiebaDictDir()
 		if d == "" {
-			log.Printf("[jieba] no dictionary directory found, jieba disabled")
+			log.Printf("[jieba] 未找到词库目录（内嵌落盘失败且模块缓存也不存在），jieba disabled")
 			return
 		}
 		jiebaInst = gojieba.NewJieba(
@@ -68,9 +68,24 @@ func GetJieba() *gojieba.Jieba {
 }
 
 func jiebaDictDir() string {
+	// 首选内嵌词库：它是产物的一部分，与二进制同版本、不依赖宿主环境。
+	//
+	// 以前这里只猜 GOMODCACHE/GOPATH/~/go/pkg/mod，部署机上通常没有 Go 模块缓存，
+	// 于是分词与关键词提取会**静默退回空列表**（详见 jieba_embed.go 的说明）。
+	if dir, err := materializeJiebaDict(); err == nil && dir != "" {
+		return dir
+	}
+	log.Printf("[jieba] 内嵌词库落盘失败，回退到模块缓存查找（内嵌失败通常意味着缓存目录不可写）")
+
+	// 回退：开发机上存在的模块缓存（仅作为兵底，不应依赖它）。
+	//
 	// GOMODCACHE is typically $GOPATH/pkg/mod. When set, Go writes modules
 	// under <GOMODCACHE>/github.com/... . Look first at GOMODCACHE, then
 	// derive from GOPATH, then try common locations.
+	return jiebaDictDirFromModuleCache()
+}
+
+func jiebaDictDirFromModuleCache() string {
 	candidates := []string{
 		os.Getenv("GOMODCACHE"),
 	}

internal/memory/document/document.go

@@ -4,6 +4,7 @@ import (
 	"encoding/json"
 	"fmt"
 	"log"
+	"math"
 	"os"
 	"path/filepath"
 	"sort"
@@ -13,6 +14,7 @@ import (
 
 	"gitcode.com/JianFeeeee/HomeAgent/internal/memory"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/vector"
+	"gitcode.com/JianFeeeee/HomeAgent/internal/tfidf"
 )
 
 // ChannelCleaner 按事件来源查找输入通道的 Cleaner 函数。
@@ -21,63 +23,77 @@ type ChannelCleaner func(source string) func(string) string
 
 // Doc — 记忆文档：由上下文提炼而来
 type Doc struct {
-	ID          string            `json:"id"`
-	Summary     string            `json:"summary"`
-	Content     string            `json:"content"`
-	Tags        []string          `json:"tags"`
-	Entities    []string          `json:"entities"`
-	CreatedAt   time.Time         `json:"created_at"`
-	UpdatedAt   time.Time         `json:"updated_at"`
-	Source      string            `json:"source"` // context / graph / manual
-	Meta        map[string]string `json:"meta,omitempty"`
-	AccessCount int               `json:"access_count"`    // 访问次数
-	LastAccess  time.Time         `json:"last_access"`     // 最后访问时间
-	Vector      vector.Vector     `json:"vector,omitempty"` // 预计算向量（与 context 同空间），nil 则用 TF-IDF 兜底
+	ID          string               `json:"id"`
+	Summary     string               `json:"summary"`
+	Content     string               `json:"content"`
+	Tags        []string             `json:"tags"`
+	Entities    []string             `json:"entities"`
+	CreatedAt   time.Time            `json:"created_at"`
+	UpdatedAt   time.Time            `json:"updated_at"`
+	Source      string               `json:"source"`
+	Meta        map[string]string    `json:"meta,omitempty"`
+	AccessCount int                  `json:"access_count"`
+	LastAccess  time.Time            `json:"last_access"`
+	Blocks      []memory.MemoryBlock `json:"blocks,omitempty"`    // 一等记忆块（text/image/video/audio）
+	Vector      tfidf.Vector         `json:"vector,omitempty"`    // TF-IDF 稀疏向量（fallback 时持久化）
+	DenseVec    []float64            `json:"dense_vec,omitempty"` // 多模态稠密向量（主路径）
+	DenseFP     string               `json:"dense_fp,omitempty"`  // DenseVec 所属统一空间指纹，变化时触发重算
 }
 
-// Store — 文档记忆存储，包含向量索引
+// Store — 文档记忆存储。
+// 主路径：denseSpace（稠密多模态向量，与媒体共享空间）。
+// Fallback：tfidf（TF-IDF 倒排索引，仅稠密空间不可用时加载）。
 type Store struct {
-	dir    string
-	vec    *vector.Store
-	veczer *vector.TFIDFVectorizer
-	mu     sync.RWMutex
-
-	docs       map[string]*Doc
-	summaries  []string // 用于训练向量化器，最大 10000 条
-	vectorizer vector.Vectorizer // 可选：与 context 同空间的向量化器
-
+	dir   string
+	mu    sync.RWMutex
+	docs  map[string]*Doc
 	dirty bool
-}
 
-func (s *Store) SetVectorizer(v vector.Vectorizer) {
-	s.vectorizer = v
-}
+	// fallback 路径（仅稠密空间不可用时加载）
+	tfidfEmb   *tfidf.Embedder
+	tfidfIdx   *tfidf.SearchableIndex
+	trainTexts []string // 缓存训练文本，延迟训练
+	tfidfOnce  sync.Once
 
-// ReindexWithVectorizer 用给定的向量化器重建所有文档的向量索引
-func (s *Store) ReindexWithVectorizer(v vector.Vectorizer) {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-
-	log.Printf("[document memory] reindex with vectorizer (%d docs)", len(s.docs))
-	s.vec = vector.NewStore()
-	for _, doc := range s.docs {
-		doc.Vector = v.Vectorize(doc.Summary + " " + doc.Content)
-		s.vec.Insert(doc.ID, doc.Summary, doc.Vector, doc.Meta)
-	}
-	log.Printf("[document memory] reindex with vectorizer complete (%d vectors)", s.vec.Size())
+	// 主路径
+	denseSpace vector.MultimodalEmbedder
 }
 
 const maxSummaries = 10000
 
-func NewStore(dir string) *Store {
+// NewStore 创建文档存储。tokenizer 由外层注入（如 jieba），核心不直接依赖分词库。
+func NewStore(dir string, tokenizer tfidf.Tokenizer) *Store {
 	return &Store{
-		dir:    dir,
-		vec:    vector.NewStore(),
-		veczer: vector.NewTFIDFVectorizer(memory.TokenizeWords),
-		docs:   make(map[string]*Doc),
+		dir:  dir,
+		docs: make(map[string]*Doc),
+		// tfidf 延迟初始化：只在需要 fallback 时创建
+		tfidfEmb: tfidf.NewEmbedder(tokenizer, 4096),
 	}
 }
 
+// ensureTFIDF 延迟初始化 TF-IDF 索引（仅 fallback 路径）。
+// 调用方已持有 s.mu。
+func (s *Store) ensureTFIDF() {
+	s.tfidfOnce.Do(func() {
+		s.tfidfIdx = tfidf.NewSearchableIndex(s.tfidfEmb)
+		// 延迟训练：用缓存的文本建立索引
+		texts := make(map[string]string, len(s.trainTexts)/2)
+		for i := 0; i+1 < len(s.trainTexts); i += 2 {
+			texts[s.trainTexts[i]] = s.trainTexts[i+1]
+		}
+		s.tfidfIdx.Train(texts)
+		s.trainTexts = nil // 释放缓存
+		s.tfidfEmb.Train(func() []string {
+			out := make([]string, 0, len(texts))
+			for _, t := range texts {
+				out = append(out, t)
+			}
+			return out
+		}())
+		log.Printf("[document memory] tfidf fallback loaded: %d docs", len(texts))
+	})
+}
+
 func (s *Store) Start() error {
 	if err := os.MkdirAll(s.dir, 0755); err != nil {
 		return fmt.Errorf("document store dir: %w", err)
@@ -85,15 +101,95 @@ func (s *Store) Start() error {
 	if err := s.loadAll(); err != nil {
 		log.Printf("[document memory] load error: %v", err)
 	}
-	log.Printf("[document memory] started with %d docs, %d vectors", len(s.docs), s.vec.Size())
+	log.Printf("[document memory] started with %d docs", len(s.docs))
 	return nil
 }
 
-func (s *Store) Stop() {
-	s.flush()
+func (s *Store) Stop() { s.flush() }
+
+// SetDenseSpace 设置稠密多模态向量空间（主路径）。
+func (s *Store) SetDenseSpace(ds vector.MultimodalEmbedder) {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.denseSpace = ds
+}
+
+// BuildDenseIndex 为所有文档计算稠密向量（文本 ⊕ 媒体块）。
+func (s *Store) BuildDenseIndex(ds vector.MultimodalEmbedder) {
+	if ds == nil || !ds.Loaded() {
+		return
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	log.Printf("[document memory] building dense index for %d docs (dim=%d)", len(s.docs), ds.Dim())
+	count := 0
+	for _, doc := range s.docs {
+		if doc.DenseVec != nil && len(doc.DenseVec) == ds.Dim() && doc.DenseFP == ds.Fingerprint() {
+			continue
+		}
+		vec := s.denseFor(doc)
+		if vec == nil {
+			continue
+		}
+		doc.DenseVec = vec
+		doc.DenseFP = ds.Fingerprint()
+		count++
+	}
+	if count > 0 {
+		// 迁移结果必须落盘。否则磁盘上的 DenseFP 永远对不上当前空间，
+		// 判定条件永远成立：每次启动都重算同一批文档，磁盘状态永不收敛。
+		// 迁移是一次性的昂贵操作（实测 200 篇约 7s），所以当场写盘，
+		// 而不是只依赖关停时的 flush——被 kill -9 也不会白算。
+		s.dirty = true
+		s.flushLocked()
+	}
+	log.Printf("[document memory] dense index built: %d new vectors", count)
+}
+
+// denseFor 计算文档的稠密向量：文本向量与其一等记忆块的媒体向量融合。
+//
+// 只有与当前统一空间同指纹的块向量才参与融合：不同模型/维度的旧向量
+// 属于另一个坐标系，混进去会算出一个两边都不像的方向。
+// 任意一路缺失时退化为另一路；都不可用返回 nil。
+func (s *Store) denseFor(doc *Doc) []float64 {
+	if s.denseSpace == nil || !s.denseSpace.Loaded() {
+		return nil
+	}
+	fp := s.denseSpace.Fingerprint()
+	dim := s.denseSpace.Dim()
+	var parts [][]float64
+	if tv, err := s.denseSpace.VectorizeDense(doc.Summary + " " + doc.Content); err == nil && len(tv) > 0 {
+		parts = append(parts, tv)
+	}
+	for _, b := range doc.Blocks {
+		// 只比指纹不够：指纹相同但**维度不同**的块会被 FuseVectors 按
+		// 「最大维度」拼成错维度向量（并覆盖掉文本向量），而结果又被
+		// 标上当前指纹——于是该文档在检索侧被长度守卫永久跳过，
+		// 且每次启动都会重算。维度不符的块一律不参与融合。
+		if len(b.Vector) == dim && b.Fingerprint == fp {
+			parts = append(parts, b.Vector)
+		}
+	}
+	return vector.FuseVectors(parts...)
+}
+
+// Reindex 重建 TF-IDF 索引（fallback 路径变更时调用）。
+func (s *Store) Reindex() {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	s.tfidfOnce = sync.Once{} // 重置延迟初始化
+	texts := make(map[string]string, len(s.docs))
+	for _, doc := range s.docs {
+		texts[doc.ID] = doc.Summary + " " + doc.Content
+	}
+	// 缓存文本供 ensureTFIDF 延迟训练
+	s.trainTexts = make([]string, 0, len(texts)*2)
+	for id, t := range texts {
+		s.trainTexts = append(s.trainTexts, id, t)
+	}
+	s.ensureTFIDF()
 }
 
-// Insert 创建/更新文档
 func (s *Store) Insert(doc *Doc) error {
 	s.mu.Lock()
 	defer s.mu.Unlock()
@@ -107,36 +203,35 @@ func (s *Store) Insert(doc *Doc) error {
 	if doc.AccessCount == 0 {
 		doc.AccessCount = 1
 	}
-
 	s.docs[doc.ID] = doc
 
-	// 增量训练向量化器并加入向量索引
-	s.addSummary(doc.Summary)
-	vec := doc.Vector
-	if vec == nil {
-		vec = s.veczer.Vectorize(doc.Summary + " " + doc.Content)
-	}
-	s.vec.Insert(doc.ID, doc.Summary, vec, doc.Meta)
+	text := doc.Summary + " " + doc.Content
+
+	// 主路径：稠密向量（文本 ⊕ 媒体块）
+	if s.denseSpace != nil && s.denseSpace.Loaded() && len(doc.DenseVec) == 0 {
+		doc.DenseVec = s.denseFor(doc)
+		doc.DenseFP = s.denseSpace.Fingerprint()
+	}
+
+	// Fallback 路径：缓存文本，延迟训练
+	if s.tfidfIdx != nil {
+		s.tfidfIdx.Add(doc.ID, text)
+	} else {
+		s.trainTexts = append(s.trainTexts, doc.ID, text)
+	}
 
-	// 立即写盘
 	path := filepath.Join(s.dir, doc.ID+".json")
 	data, _ := json.MarshalIndent(doc, "", "  ")
 	os.WriteFile(path, data, 0644)
-
 	s.dirty = true
 	return nil
 }
 
-// ContextToDoc — 将一段上下文对话历史提炼为文档（带内容去重）
-// cleanFn 可选，在计算层前统一过滤文本，不影响原文存储。
-// toolCleanFn 可选，func(name, output string) string，按工具名对输出进行过滤/清洗：
-//   - 返回 "" → 跳过该工具输出（NoMemory）
-//   - 返回清洗后文本 → 用于计算层（Cleaner），原文不受影响
-func (s *Store) ContextToDoc(source string, entries []ContextEntry, vec vector.Vectorizer, cleanFn func(string) string, toolCleanFn func(name, output string) string, channelCleaner ChannelCleaner) (*Doc, error) {
+// ContextToDoc 将上下文对话历史提炼为文档。
+func (s *Store) ContextToDoc(source string, entries []ContextEntry, _ interface{}, cleanFn func(string) string, toolCleanFn func(name, output string) string, channelCleaner ChannelCleaner) (*Doc, error) {
 	if len(entries) == 0 {
 		return nil, nil
 	}
-
 	if cleanFn == nil {
 		cleanFn = func(text string) string { return text }
 	}
@@ -154,14 +249,13 @@ func (s *Store) ContextToDoc(source string, entries []ContextEntry, vec vector.V
 	}
 	content := strings.Join(parts, "\n")
 	contentHash := simpleHash(content)
-
 	summary := summarizeEntries(entries, cleanFn, toolCleanFn, channelCleaner)
 	tags := extractTags(entries, cleanFn, toolCleanFn, channelCleaner)
 	entities := extractEntities(entries, cleanFn, toolCleanFn, channelCleaner)
 
 	s.mu.Lock()
+	defer s.mu.Unlock()
 
-	// 去重
 	for _, d := range s.docs {
 		if d.Meta != nil && d.Meta["content_hash"] == contentHash {
 			d.UpdatedAt = time.Now()
@@ -171,66 +265,73 @@ func (s *Store) ContextToDoc(source string, entries []ContextEntry, vec vector.V
 			d.Summary = summary
 			d.Tags = tags
 			d.Entities = entities
+			d.Blocks = blocksFromEntries(entries)
+			d.DenseVec = s.denseFor(d)
+			if s.denseSpace != nil {
+				d.DenseFP = s.denseSpace.Fingerprint()
+			}
 			s.dirty = true
-			s.mu.Unlock()
 			return d, nil
 		}
 	}
 
 	id := fmt.Sprintf("doc_%d", time.Now().UnixNano())
-	var docVec vector.Vector
-	if vec != nil {
-		docVec = vec.Vectorize(summary + " " + content)
-	} else {
-		docVec = s.veczer.Vectorize(summary + " " + content)
-	}
-		meta := map[string]string{"content_hash": contentHash}
+	meta := map[string]string{"content_hash": contentHash}
 	if source == "context_archived" {
 		meta["is_archived_context"] = "true"
 	}
 	doc := &Doc{
-		ID:          id,
-		Summary:     summary,
-		Content:     content,
-		Tags:        tags,
-		Entities:    entities,
-		CreatedAt:   time.Now(),
-		UpdatedAt:   time.Now(),
-		LastAccess:  time.Now(),
-		AccessCount: 1,
-		Source:      source,
-		Meta:        meta,
-		Vector:      docVec,
+		ID: id, Summary: summary, Content: content, Tags: tags,
+		Entities: entities, CreatedAt: time.Now(), UpdatedAt: time.Now(),
+		LastAccess: time.Now(), AccessCount: 1, Source: source, Meta: meta,
+		Blocks: blocksFromEntries(entries),
 	}
 	s.docs[id] = doc
+	doc.DenseVec = s.denseFor(doc)
+	if s.denseSpace != nil {
+		doc.DenseFP = s.denseSpace.Fingerprint()
+	}
+	text := summary + " " + content
+	if s.tfidfIdx != nil {
+		s.tfidfIdx.Add(id, text)
+	} else {
+		s.trainTexts = append(s.trainTexts, id, text)
+	}
 
-	// 加入向量索引
-	s.addSummary(summary)
-	s.vec.Insert(id, summary, doc.Vector, nil)
-
-	s.dirty = true
-	s.mu.Unlock()
-
-	// 立即写盘
 	path := filepath.Join(s.dir, id+".json")
 	data, _ := json.MarshalIndent(doc, "", "  ")
 	os.WriteFile(path, data, 0644)
-
+	s.dirty = true
 	return doc, nil
 }
 
-// Consume — 向量相似度查询并移除文档（召回后即从冷存储删除，避免重复记忆）
+// Consume 向量相似度查询并移除文档
 func (s *Store) Consume(text string, topK int) []*Doc {
 	s.mu.Lock()
 	defer s.mu.Unlock()
-
 	if topK <= 0 {
 		topK = 5
 	}
 
-	vec := s.vectorizeQuery(text)
-	results := s.vec.Search(vec, topK)
+	// 主路径：稠密检索
+	if s.denseSpace != nil && s.denseSpace.Loaded() {
+		if qv, err := s.denseSpace.VectorizeDense(text); err == nil {
+			results := s.denseSearchScored(qv, topK)
+			var docs []*Doc
+			for _, r := range results {
+				if d, ok := s.docs[r.Doc.ID]; ok {
+					s.removeDoc(r.Doc.ID)
+					s.dirty = true
+					docs = append(docs, d)
+				}
+			}
+			return docs
+		}
+	}
 
+	// Fallback：TF-IDF 倒排检索（延迟初始化）
+	s.ensureTFIDF()
+	results := s.tfidfIdx.Search(text, topK)
 	var docs []*Doc
 	for _, r := range results {
 		if d, ok := s.docs[r.ID]; ok {
@@ -242,75 +343,124 @@ func (s *Store) Consume(text string, topK int) []*Doc {
 	return docs
 }
 
-// vectorizeQuery 用语义向量化器（首选）或 TF-IDF（兜底）处理查询文本
-func (s *Store) vectorizeQuery(text string) vector.Vector {
-	if s.vectorizer != nil {
-		return s.vectorizer.Vectorize(text)
+func (s *Store) Query(text string, topK int) []*Doc {
+	hits := s.QueryScored(text, topK)
+	out := make([]*Doc, len(hits))
+	for i, h := range hits {
+		out[i] = h.Doc
 	}
-	return s.veczer.Vectorize(text)
+	return out
 }
 
-// Query — 向量相似度查询文档
-func (s *Store) Query(text string, topK int) []*Doc {
+// DocHit 是一篇文档记忆的相似度候选及原始分数。
+type DocHit struct {
+	Doc   *Doc
+	Score float64
+}
+
+func (s *Store) QueryScored(text string, topK int) []DocHit {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
-
 	if topK <= 0 {
 		topK = 5
 	}
 
-	vec := s.vectorizeQuery(text)
-	results := s.vec.Search(vec, topK)
+	// 主路径
+	if s.denseSpace != nil && s.denseSpace.Loaded() {
+		if qv, err := s.denseSpace.VectorizeDense(text); err == nil {
+			results := s.denseSearchScored(qv, topK)
+			for i := range results {
+				if d, ok := s.docs[results[i].Doc.ID]; ok {
+					d.AccessCount++
+					d.LastAccess = time.Now()
+					results[i].Doc = d
+				}
+			}
+			return results
+		}
+	}
 
-	var docs []*Doc
+	// Fallback（需要写锁来 ensureTFIDF）
+	s.mu.RUnlock()
+	s.mu.Lock()
+	s.ensureTFIDF()
+	s.mu.Unlock()
+	s.mu.RLock()
+
+	results := s.tfidfIdx.Search(text, topK)
+	var out []DocHit
 	for _, r := range results {
 		if d, ok := s.docs[r.ID]; ok {
 			d.AccessCount++
 			d.LastAccess = time.Now()
-			docs = append(docs, d)
+			out = append(out, DocHit{Doc: d, Score: r.Score})
 		}
 	}
-	return docs
+	return out
 }
 
-// Reindex — 重新训练并重建向量索引
-func (s *Store) Reindex() {
-	s.mu.Lock()
-	defer s.mu.Unlock()
-
-	log.Printf("[document memory] reindexing %d docs", len(s.docs))
-
-	s.veczer.Train(s.summaries)
-
-	s.vec = vector.NewStore()
-	for _, doc := range s.docs {
-		vec := doc.Vector
-		if vec == nil {
-			vec = s.veczer.Vectorize(doc.Summary + " " + doc.Content)
-		}
-		s.vec.Insert(doc.ID, doc.Summary, vec, doc.Meta)
+func (s *Store) denseSearchScored(queryVec []float64, topK int) []DocHit {
+	if len(queryVec) == 0 {
+		return nil
 	}
+	type scored struct {
+		did   string
+		score float64
+	}
+	var results []scored
+	for _, doc := range s.docs {
+		if len(doc.DenseVec) != len(queryVec) {
+			continue
+		}
+		score := denseCosine(queryVec, doc.DenseVec)
+		if score > 0.01 {
+			results = append(results, scored{doc.ID, score})
+		}
+	}
+	if len(results) == 0 {
+		return nil
+	}
+	sort.Slice(results, func(i, j int) bool { return results[i].score > results[j].score })
+	if len(results) > topK {
+		results = results[:topK]
+	}
+	out := make([]DocHit, len(results))
+	for i, r := range results {
+		out[i] = DocHit{Doc: s.docs[r.did], Score: r.score}
+	}
+	return out
+}
 
-	log.Printf("[document memory] reindex complete (%d vectors)", s.vec.Size())
+func denseCosine(a, b []float64) float64 {
+	var dot, na, nb float64
+	for i := range a {
+		dot += a[i] * b[i]
+		na += a[i] * a[i]
+		nb += b[i] * b[i]
+	}
+	if na == 0 || nb == 0 {
+		return 0
+	}
+	return dot / math.Sqrt(na*nb)
 }
 
 func (s *Store) Stats() map[string]interface{} {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
-
+	idxSize := 0
+	if s.tfidfIdx != nil {
+		idxSize = s.tfidfIdx.Size()
+	}
 	return map[string]interface{}{
-		"doc_count":     len(s.docs),
-		"vector_count":  s.vec.Size(),
-		"summary_count": len(s.summaries),
-		"dir":           s.dir,
+		"doc_count":   len(s.docs),
+		"index_count": idxSize,
+		"dir":         s.dir,
 	}
 }
 
-// FindColdDocs — 查找冷文档：超过 maxAge 未访问且访问次数 <= minAccess
 func (s *Store) FindColdDocs(maxAge time.Duration, minAccess int) []*Doc {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
-
 	cutoff := time.Now().Add(-maxAge)
 	var cold []*Doc
 	for _, d := range s.docs {
@@ -321,60 +471,53 @@ func (s *Store) FindColdDocs(maxAge time.Duration, minAccess int) []*Doc {
 	return cold
 }
 
+// Get 返回指定文档（不存在时为 nil）。
+func (s *Store) Get(id string) *Doc {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.docs[id]
+}
+
+// Blocks 返回全部文档持有的一等记忆块（供跨层存活判定）。
+func (s *Store) Blocks() []memory.MemoryBlock {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	var out []memory.MemoryBlock
+	for _, d := range s.docs {
+		out = append(out, d.Blocks...)
+	}
+	return out
+}
+
 func (s *Store) RecentDocs(n int) []*Doc {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
-
 	var list []*Doc
 	for _, d := range s.docs {
 		list = append(list, d)
 	}
-	sort.Slice(list, func(i, j int) bool {
-		return list[i].CreatedAt.After(list[j].CreatedAt)
-	})
+	sort.Slice(list, func(i, j int) bool { return list[i].CreatedAt.After(list[j].CreatedAt) })
 	if len(list) > n {
 		list = list[:n]
 	}
 	return list
 }
 
-// Remove 从文档存储中删除指定 ID 的文档
 func (s *Store) Remove(id string) {
 	s.mu.Lock()
 	defer s.mu.Unlock()
-
 	if _, ok := s.docs[id]; ok {
 		s.removeDoc(id)
 		s.dirty = true
 	}
 }
 
-// ——— internal ———
-
-// addSummary 添加一条摘要到训练集，超限时截断并触发重索引。
-// 调用方必须已持有 s.mu 写锁。
-func (s *Store) addSummary(summary string) {
-	s.summaries = append(s.summaries, summary)
-	if len(s.summaries) > maxSummaries {
-		n := maxSummaries / 2
-		copy(s.summaries, s.summaries[len(s.summaries)-n:])
-		s.summaries = s.summaries[:n]
-		s.veczer.Train(s.summaries)
-		s.vec = vector.NewStore()
-		for _, doc := range s.docs {
-			vec := s.veczer.Vectorize(doc.Summary + " " + doc.Content)
-			s.vec.Insert(doc.ID, doc.Summary, vec, nil)
-		}
-	}
-}
-
-// removeDoc 从内存索引和磁盘删除文档。
-// 调用方必须已持有 s.mu 写锁。
 func (s *Store) removeDoc(id string) {
 	delete(s.docs, id)
-	s.vec.Remove(id)
-	path := filepath.Join(s.dir, id+".json")
-	os.Remove(path)
+	if s.tfidfIdx != nil {
+		s.tfidfIdx.Remove(id)
+	}
+	os.Remove(filepath.Join(s.dir, id+".json"))
 }
 
 func (s *Store) loadAll() error {
@@ -382,63 +525,51 @@ func (s *Store) loadAll() error {
 	if err != nil {
 		return err
 	}
-
 	for _, e := range entries {
-		if !strings.HasSuffix(e.Name(), ".json") || !strings.HasPrefix(e.Name(), "doc_") {
+		// 只要求 .json：Insert 接受任意 ID 并落盘为 <id>.json，若这里再按
+		// doc_ 前缀过滤，传自定义 ID 的文档重启后会静默消失。
+		// 空 ID 仍会被下面的校验跳过。
+		if !strings.HasSuffix(e.Name(), ".json") {
 			continue
 		}
-		path := filepath.Join(s.dir, e.Name())
-		data, err := os.ReadFile(path)
+		data, err := os.ReadFile(filepath.Join(s.dir, e.Name()))
 		if err != nil {
 			continue
 		}
 		var doc Doc
-		if err := json.Unmarshal(data, &doc); err != nil {
+		if json.Unmarshal(data, &doc) != nil || doc.ID == "" {
 			continue
 		}
 		s.docs[doc.ID] = &doc
-		s.summaries = append(s.summaries, doc.Summary)
+		// 缓存文本，延迟训练（确保TFIDF在首次需要时才加载）
+		s.trainTexts = append(s.trainTexts, doc.ID, doc.Summary+" "+doc.Content)
 	}
-
-	// 训练向量化器
-	if len(s.summaries) > 0 {
-		s.veczer.Train(s.summaries)
-	}
-
-	// 重建向量索引
-	for _, doc := range s.docs {
-		vec := doc.Vector
-		if vec == nil {
-			vec = s.veczer.Vectorize(doc.Summary + " " + doc.Content)
-		}
-		s.vec.Insert(doc.ID, doc.Summary, vec, nil)
-	}
-
 	return nil
 }
 
 func (s *Store) flush() {
 	s.mu.Lock()
 	defer s.mu.Unlock()
+	s.flushLocked()
+}
 
+// flushLocked 是 flush 的核心，调用方必须已持有 s.mu。
+func (s *Store) flushLocked() {
 	if !s.dirty {
 		return
 	}
-
 	for _, doc := range s.docs {
-		path := filepath.Join(s.dir, doc.ID+".json")
-		data, err := json.MarshalIndent(doc, "", "  ")
-		if err != nil {
-			continue
-		}
-		os.WriteFile(path, data, 0644)
+		data, _ := json.MarshalIndent(doc, "", "  ")
+		os.WriteFile(filepath.Join(s.dir, doc.ID+".json"), data, 0644)
 	}
 	s.dirty = false
 }
 
+// ——— 内部工具函数（从上下文提炼文档所需）———
+
 type ToolResultItem struct {
-	Name   string
-	Output string
+	Name   string `json:"name"`
+	Output string `json:"output"`
 }
 
 type ContextEntry struct {
@@ -447,6 +578,23 @@ type ContextEntry struct {
 	Content     string
 	Response    string
 	ToolResults []ToolResultItem
+	Blocks      []memory.MemoryBlock // 一等记忆块随事件一起迁移到文档
+}
+
+func blocksFromEntries(entries []ContextEntry) []memory.MemoryBlock {
+	seen := make(map[string]bool)
+	var out []memory.MemoryBlock
+	for _, e := range entries {
+		for i := range e.Blocks {
+			b := e.Blocks[i]
+			if b.ID == "" || seen[b.ID] {
+				continue
+			}
+			seen[b.ID] = true
+			out = append(out, b)
+		}
+	}
+	return out
 }
 
 func summarizeEntries(entries []ContextEntry, cleanText func(string) string, toolCleanFn func(name, output string) string, channelCleaner ChannelCleaner) string {
@@ -478,14 +626,12 @@ func summarizeEntries(entries []ContextEntry, cleanText func(string) string, too
 			topics = append(topics, toolWords...)
 		}
 	}
-
 	summary := fmt.Sprintf("来自 %d 个来源的 %d 条对话", len(sources), len(entries))
 	var srcList []string
 	for s := range sources {
 		srcList = append(srcList, s)
 	}
 	summary += " (" + strings.Join(srcList, ", ") + ")"
-
 	if len(topics) > 0 {
 		seen := make(map[string]bool)
 		var uniq []string
@@ -500,7 +646,6 @@ func summarizeEntries(entries []ContextEntry, cleanText func(string) string, too
 		}
 		summary += " 涉及: " + strings.Join(uniq, ", ")
 	}
-
 	return summary
 }
 
@@ -573,25 +718,20 @@ func extractEntities(entries []ContextEntry, cleanText func(string) string, tool
 			}
 		}
 	}
-	if len(entities) > 20 {
-		entities = entities[:20]
-	}
 	return entities
 }
 
 func truncate(s string, max int) string {
-	runes := []rune(s)
-	if len(runes) > max {
-		return string(runes[:max]) + "..."
+	if len([]rune(s)) <= max {
+		return s
 	}
-	return s
+	return string([]rune(s)[:max]) + "..."
 }
 
 func simpleHash(s string) string {
-	// 简单的基于内容的哈希，用于去重
-	h := 0
-	for _, r := range s {
-		h = h*31 + int(r)
+	h := fmt.Sprintf("%x", len(s))
+	for _, c := range s {
+		h += fmt.Sprintf("%x", c)
 	}
-	return fmt.Sprintf("h%08x", h)
+	return h
 }

internal/memory/document/document_test.go

@@ -15,7 +15,7 @@ func TestInsertAndQuery(t *testing.T) {
 	}
 	defer os.RemoveAll(dir)
 
-	s := NewStore(dir)
+	s := NewStore(dir, memory.TokenizeWords)
 	if err := s.Start(); err != nil {
 		t.Fatal(err)
 	}
@@ -48,7 +48,7 @@ func TestQuery(t *testing.T) {
 	}
 	defer os.RemoveAll(dir)
 
-	s := NewStore(dir)
+	s := NewStore(dir, memory.TokenizeWords)
 	s.Start()
 	defer s.Stop()
 
@@ -73,7 +73,7 @@ func TestContextToDoc(t *testing.T) {
 	}
 	defer os.RemoveAll(dir)
 
-	s := NewStore(dir)
+	s := NewStore(dir, memory.TokenizeWords)
 	s.Start()
 	defer s.Stop()
 
@@ -104,7 +104,7 @@ func TestFindColdDocs(t *testing.T) {
 	}
 	defer os.RemoveAll(dir)
 
-	s := NewStore(dir)
+	s := NewStore(dir, memory.TokenizeWords)
 	s.Start()
 	defer s.Stop()
 
@@ -136,7 +136,7 @@ func TestRecentDocs(t *testing.T) {
 	}
 	defer os.RemoveAll(dir)
 
-	s := NewStore(dir)
+	s := NewStore(dir, memory.TokenizeWords)
 	s.Start()
 	defer s.Stop()
 
@@ -160,7 +160,7 @@ func TestReindex(t *testing.T) {
 	}
 	defer os.RemoveAll(dir)
 
-	s := NewStore(dir)
+	s := NewStore(dir, memory.TokenizeWords)
 	s.Start()
 	defer s.Stop()
 
@@ -211,7 +211,7 @@ func TestInsertEmptyDoc(t *testing.T) {
 	}
 	defer os.RemoveAll(dir)
 
-	s := NewStore(dir)
+	s := NewStore(dir, memory.TokenizeWords)
 	s.Start()
 	defer s.Stop()
 
@@ -232,13 +232,13 @@ func TestPersistence(t *testing.T) {
 	defer os.RemoveAll(dir)
 
 	// 写
-	s1 := NewStore(dir)
+	s1 := NewStore(dir, memory.TokenizeWords)
 	s1.Start()
 	s1.Insert(&Doc{Summary: "持久化测试", Content: "应该被保存到磁盘", Source: "manual"})
 	s1.Stop()
 
 	// 读
-	s2 := NewStore(dir)
+	s2 := NewStore(dir, memory.TokenizeWords)
 	s2.Start()
 	defer s2.Stop()
 
@@ -269,7 +269,7 @@ func TestFlushNoDirty(t *testing.T) {
 	}
 	defer os.RemoveAll(dir)
 
-	s := NewStore(dir)
+	s := NewStore(dir, memory.TokenizeWords)
 	s.Start()
 
 	// 不插任何文档，flush 不应报错
@@ -283,7 +283,7 @@ func TestRemove(t *testing.T) {
 	}
 	defer os.RemoveAll(dir)
 
-	s := NewStore(dir)
+	s := NewStore(dir, memory.TokenizeWords)
 	s.Start()
 	defer s.Stop()
 
@@ -329,7 +329,7 @@ func TestRemoveNonexistent(t *testing.T) {
 	}
 	defer os.RemoveAll(dir)
 
-	s := NewStore(dir)
+	s := NewStore(dir, memory.TokenizeWords)
 	s.Start()
 	defer s.Stop()
 
@@ -437,7 +437,7 @@ func TestContextToDocContentPreservesRawToolOutput(t *testing.T) {
 	}
 	defer os.RemoveAll(dir)
 
-	s := NewStore(dir)
+	s := NewStore(dir, memory.TokenizeWords)
 	s.Start()
 	defer s.Stop()
 
@@ -467,3 +467,188 @@ func TestContextToDocContentPreservesRawToolOutput(t *testing.T) {
 		t.Error("summary should not be empty")
 	}
 }
+
+// ———— 回归：向量迁移的落盘与维度一致性 ————
+//
+// 以下四条来自 v1.2.0-beta.2 的压测（报告 /var/tmp/stress/REPORT.md）：
+// 迁移结果不落盘（每次启动白算一遍）、块指纹对但维度错时污染文档向量、
+// 以及 Insert 与 loadAll 的 ID 约定不对称。
+
+// fakeSpace 是可控的统一向量空间；calls 记录被真正要求算向量的次数，
+// 用来直接证明「已对齐的文档不再重算」——比读日志断言可靠。
+type fakeSpace struct {
+	fp    string
+	dim   int
+	calls int
+}
+
+func (f *fakeSpace) VectorizeDense(string) ([]float64, error) {
+	f.calls++
+	v := make([]float64, f.dim)
+	for i := range v {
+		v[i] = float64(i + 1)
+	}
+	return v, nil
+}
+func (f *fakeSpace) EmbedImageDense([]byte, string) ([]float64, error) { return f.VectorizeDense("") }
+func (f *fakeSpace) Fingerprint() string                               { return f.fp }
+func (f *fakeSpace) Dim() int                                          { return f.dim }
+func (f *fakeSpace) Loaded() bool                                      { return true }
+func (f *fakeSpace) Close()                                            {}
+
+// 迁移结果必须落盘：迁移后换一个 Store 实例（模拟重启）读到的应是新空间向量，
+// 且再跑一次迁移不应重算任何文档。
+func TestBuildDenseIndexPersistsAcrossRestart(t *testing.T) {
+	dir := t.TempDir()
+	sp := &fakeSpace{fp: "space-NEW-8", dim: 8}
+
+	s1 := NewStore(dir, memory.TokenizeWords)
+	if err := s1.Start(); err != nil {
+		t.Fatal(err)
+	}
+	// 模拟上个向量空间留下的状态：维度与指纹都对不上
+	stale := make([]float64, 999)
+	for i := range stale {
+		stale[i] = 0.01
+	}
+	if err := s1.Insert(&Doc{ID: "doc_persist", Summary: "迁移", Content: "落盘",
+		DenseVec: stale, DenseFP: "space-OLD-999"}); err != nil {
+		t.Fatal(err)
+	}
+	s1.SetDenseSpace(sp)
+	s1.BuildDenseIndex(sp)
+	if got := s1.Get("doc_persist"); got == nil || len(got.DenseVec) != 8 || got.DenseFP != sp.fp {
+		t.Fatalf("迁移未在内存生效: %+v", got)
+	}
+	// 不调用 Stop 就另开一个实例：体现「迁移当场落盘」，不依赖关停
+	s2 := NewStore(dir, memory.TokenizeWords)
+	if err := s2.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer s2.Stop()
+	loaded := s2.Get("doc_persist")
+	if loaded == nil {
+		t.Fatal("重启后文档不见了")
+	}
+	if len(loaded.DenseVec) != 8 || loaded.DenseFP != sp.fp {
+		t.Fatalf("迁移结果未落盘：期望 dim=8 fp=%q，实际 dim=%d fp=%q"+
+			"（后果：每次启动都重算同一批文档，磁盘状态永不收敛）",
+			sp.fp, len(loaded.DenseVec), loaded.DenseFP)
+	}
+	// 已对齐 → 一次向量计算都不该发生
+	sp2 := &fakeSpace{fp: sp.fp, dim: 8}
+	s2.SetDenseSpace(sp2)
+	s2.BuildDenseIndex(sp2)
+	if sp2.calls != 0 {
+		t.Fatalf("已对齐的文档被重算了 %d 次（期望 0）", sp2.calls)
+	}
+}
+
+// 块向量维度与当前空间不符时不得参与融合：否则 512 维文本 + 2048 维块
+// 会被 FuseVectors 按最大维度拼成 2048 维、并带上当前指纹，导致该文档在
+// 检索侧被长度守卫永久跳过且每次启动重算。
+func TestDenseForIgnoresBlockWithMismatchedDim(t *testing.T) {
+	dir := t.TempDir()
+	sp := &fakeSpace{fp: "space-NEW-8", dim: 8}
+	s := NewStore(dir, memory.TokenizeWords)
+	if err := s.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer s.Stop()
+
+	bad := make([]float64, 2048)
+	for i := range bad {
+		bad[i] = 0.02
+	}
+	good := make([]float64, 8)
+	for i := range good {
+		good[i] = 0.5
+	}
+	doc := &Doc{ID: "doc_bad", Summary: "坏块", Content: "文本向量应当生效",
+		Blocks: []memory.MemoryBlock{
+			{ID: "blk_bad", Vector: bad, Fingerprint: sp.fp},   // 指纹对、维度错 → 必须忽略
+			{ID: "blk_good", Vector: good, Fingerprint: sp.fp}, // 指纹与维度都对 → 参与融合
+		}}
+	if err := s.Insert(doc); err != nil {
+		t.Fatal(err)
+	}
+	s.SetDenseSpace(sp)
+	s.BuildDenseIndex(sp)
+
+	got := s.Get("doc_bad")
+	if got == nil {
+		t.Fatal("文档未加载")
+	}
+	if len(got.DenseVec) != 8 {
+		t.Fatalf("坏块污染了文档向量：期望 %d 维，实际 %d 维（指纹 %q）",
+			8, len(got.DenseVec), got.DenseFP)
+	}
+	// 同维度的正常块仍须参与融合：不应因为这次修复而整体失效
+	textOnly := &fakeSpace{fp: sp.fp, dim: 8}
+	textVec, _ := textOnly.VectorizeDense(doc.Summary + " " + doc.Content)
+	if equalFloats(got.DenseVec, textVec) {
+		t.Fatal("同维度的媒体块没有参与融合（修复过度）")
+	}
+}
+
+func equalFloats(a, b []float64) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}
+
+// Insert 接受任意 ID，loadAll 就必须把它读回来，否则自定义 ID 的文档
+// 重启后静默消失。
+func TestLoadAllLoadsCustomID(t *testing.T) {
+	dir := t.TempDir()
+	s1 := NewStore(dir, memory.TokenizeWords)
+	if err := s1.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := s1.Insert(&Doc{ID: "my-notes", Summary: "自定义 ID", Content: "内容"}); err != nil {
+		t.Fatal(err)
+	}
+	s1.Stop()
+
+	s2 := NewStore(dir, memory.TokenizeWords)
+	if err := s2.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer s2.Stop()
+	if s2.Get("my-notes") == nil {
+		t.Fatal("自定义 ID 的文档重启后消失（Insert 与 loadAll 的 ID 约定不对称）")
+	}
+}
+
+// Stop 必须把内存态变更写盘（关停链上没有它时 flush 形同虚设）。
+func TestStopFlushesDirtyDocs(t *testing.T) {
+	dir := t.TempDir()
+	s1 := NewStore(dir, memory.TokenizeWords)
+	if err := s1.Start(); err != nil {
+		t.Fatal(err)
+	}
+	if err := s1.Insert(&Doc{ID: "doc_flush", Summary: "关停落盘", Content: "内容"}); err != nil {
+		t.Fatal(err)
+	}
+	// 直接改内存并置脏，模拟「只在内存里发生的变更」
+	s1.mu.Lock()
+	s1.docs["doc_flush"].Summary = "关停落盘（已改）"
+	s1.dirty = true
+	s1.mu.Unlock()
+	s1.Stop()
+
+	s2 := NewStore(dir, memory.TokenizeWords)
+	if err := s2.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer s2.Stop()
+	if got := s2.Get("doc_flush"); got == nil || got.Summary != "关停落盘（已改）" {
+		t.Fatalf("Stop 未落盘: %+v", got)
+	}
+}

internal/memory/graph.go

@@ -2,6 +2,7 @@ package memory
 
 import (
 	"database/sql"
+	"encoding/json"
 	"fmt"
 	"strings"
 	"sync"
@@ -37,13 +38,17 @@ type Relation struct {
 }
 
 type Triple struct {
-	Subject     string  `json:"subject"`
-	Relation    string  `json:"relation"`
-	Object      string  `json:"object"`
-	Confidence  float64 `json:"confidence,omitempty"`
-	SubjectType string  `json:"subject_type,omitempty"`
-	ObjectType  string  `json:"object_type,omitempty"`
-	SentenceText string `json:"sentence_text,omitempty"` // 原始句子文本，Commit时写入sentences表
+	Subject      string  `json:"subject"`
+	Relation     string  `json:"relation"`
+	Object       string  `json:"object"`
+	Confidence   float64 `json:"confidence,omitempty"`
+	SubjectType  string  `json:"subject_type,omitempty"`
+	ObjectType   string  `json:"object_type,omitempty"`
+	SentenceText string  `json:"sentence_text,omitempty"` // 原始句子文本，Commit时写入sentences表
+	// MediaDigests 是该三元组显式携带的媒体 digest（完整或前缀）。
+	// 媒体不再靠正文 marker 反解：结构化字段直接给出归属，
+	// 由调用方（core）把它变成 L3 一等块并与句子建立结构边。
+	MediaDigests []string `json:"media_digests,omitempty"`
 }
 
 type GraphDB struct {
@@ -107,6 +112,41 @@ func (g *GraphDB) initSchema() error {
 			FOREIGN KEY (target_id) REFERENCES entities(id),
 			UNIQUE(source_id, target_id, relation_type, session_id)
 		)`,
+		`CREATE TABLE IF NOT EXISTS memory_blocks (
+			id TEXT PRIMARY KEY,
+			modality TEXT NOT NULL,
+			text_content TEXT DEFAULT '',
+			payload_digest TEXT DEFAULT '',
+			mime TEXT DEFAULT '',
+			size INTEGER DEFAULT 0,
+			width INTEGER DEFAULT 0,
+			height INTEGER DEFAULT 0,
+			vector TEXT DEFAULT '',
+			fingerprint TEXT DEFAULT '',
+			source TEXT DEFAULT '',
+			tool TEXT DEFAULT '',
+			created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+			updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+		)`,
+		`CREATE TABLE IF NOT EXISTS memory_block_edges (
+			id INTEGER PRIMARY KEY AUTOINCREMENT,
+			source_kind TEXT NOT NULL,
+			source_id TEXT NOT NULL,
+			target_kind TEXT NOT NULL,
+			target_id TEXT NOT NULL,
+			edge_type TEXT NOT NULL,
+			created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+			UNIQUE(source_kind, source_id, target_kind, target_id, edge_type)
+		)`,
+		`CREATE TABLE IF NOT EXISTS documents (
+			id         TEXT PRIMARY KEY,
+			summary    TEXT DEFAULT '',
+			created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+		)`,
+		`CREATE INDEX IF NOT EXISTS idx_memory_blocks_modality ON memory_blocks(modality)`,
+		`CREATE INDEX IF NOT EXISTS idx_memory_blocks_digest ON memory_blocks(payload_digest)`,
+		`CREATE INDEX IF NOT EXISTS idx_memory_block_edges_source ON memory_block_edges(source_kind, source_id)`,
+		`CREATE INDEX IF NOT EXISTS idx_memory_block_edges_target ON memory_block_edges(target_kind, target_id)`,
 		`CREATE INDEX IF NOT EXISTS idx_entity_name ON entities(name)`,
 		`CREATE INDEX IF NOT EXISTS idx_entity_type ON entities(type)`,
 		`CREATE INDEX IF NOT EXISTS idx_relation_source ON relations(source_id)`,
@@ -192,13 +232,37 @@ func (g *GraphDB) migrateRelationUnique(tx *sql.Tx) error {
 	return nil
 }
 
+// Commit 把三元组写入图库，返回新建的实体数与关系数。
 func (g *GraphDB) Commit(triples []Triple, sessionID string, turnID int) (int, int, error) {
+	_, ec, rc, err := g.commit(triples, sessionID, turnID, false)
+	return ec, rc, err
+}
+
+// CommitWithMedia 与 Commit 相同，但额外返回每条句子文本对应的 sentences.id。
+//
+// 为何单独开一个方法而不改 Commit 的签名：Commit 有十个非测试调用点
+// 加二十多个测试调用点，为了一个多数调用方都不需要的返回值去改全部签名
+// 不划算。这里让 Commit 内部转调，两者共享同一份落库逻辑。
+//
+// 返回的 map 只包含本次真正写入了 sentences 表的句子。调用方据此把媒体
+// 变成 L3 一等块，并以 sentence --contains--> block 边与句子相连；
+// 关系行本身不持有媒体。
+func (g *GraphDB) CommitWithMedia(triples []Triple, sessionID string, turnID int) (map[string]int64, int, int, error) {
+	return g.commit(triples, sessionID, turnID, true)
+}
+
+func (g *GraphDB) commit(triples []Triple, sessionID string, turnID int, trackSentences bool) (map[string]int64, int, int, error) {
 	g.mu.Lock()
 	defer g.mu.Unlock()
 
+	var sentenceIDs map[string]int64
+	if trackSentences {
+		sentenceIDs = make(map[string]int64)
+	}
+
 	tx, err := g.db.Begin()
 	if err != nil {
-		return 0, 0, err
+		return nil, 0, 0, err
 	}
 	defer tx.Rollback()
 
@@ -229,24 +293,24 @@ func (g *GraphDB) Commit(triples []Triple, sessionID string, turnID int) (int, i
 
 		ec, err := g.upsertEntity(tx, t.Subject, subjType)
 		if err != nil {
-			return 0, 0, err
+			return nil, 0, 0, err
 		}
 		entitiesCreated += ec
 
 		ec, err = g.upsertEntity(tx, t.Object, objType)
 		if err != nil {
-			return 0, 0, err
+			return nil, 0, 0, err
 		}
 		entitiesCreated += ec
 
 		var sourceID, targetID int64
 		err = tx.QueryRow("SELECT id FROM entities WHERE name = ?", t.Subject).Scan(&sourceID)
 		if err != nil {
-			return 0, 0, fmt.Errorf("subject %q: %w", t.Subject, err)
+			return nil, 0, 0, fmt.Errorf("subject %q: %w", t.Subject, err)
 		}
 		err = tx.QueryRow("SELECT id FROM entities WHERE name = ?", t.Object).Scan(&targetID)
 		if err != nil {
-			return 0, 0, fmt.Errorf("object %q: %w", t.Object, err)
+			return nil, 0, 0, fmt.Errorf("object %q: %w", t.Object, err)
 		}
 
 		// 写入/查找句子
@@ -255,11 +319,13 @@ func (g *GraphDB) Commit(triples []Triple, sessionID string, turnID int) (int, i
 			_, err = tx.Exec(
 				`INSERT OR IGNORE INTO sentences (text) VALUES (?)`, t.SentenceText)
 			if err != nil {
-				return 0, 0, fmt.Errorf("insert sentence: %w", err)
+				return nil, 0, 0, fmt.Errorf("insert sentence: %w", err)
 			}
 			err = tx.QueryRow("SELECT id FROM sentences WHERE text = ?", t.SentenceText).Scan(&sentenceID)
 			if err != nil {
 				sentenceID = 0
+			} else if sentenceIDs != nil {
+				sentenceIDs[t.SentenceText] = sentenceID
 			}
 		}
 
@@ -275,11 +341,11 @@ func (g *GraphDB) Commit(triples []Triple, sessionID string, turnID int) (int, i
 				sourceID, targetID, t.Relation, confidence, sessionID, turnID, dateBucket, sentenceID,
 			)
 			if err != nil {
-				return 0, 0, err
+				return nil, 0, 0, err
 			}
 			relationsCreated++
 		} else if err != nil {
-			return 0, 0, err
+			return nil, 0, 0, err
 		} else {
 			// 同一(会话内)三元组已存在：仅刷新置信度与时间戳，不重复计数
 			_, err = tx.Exec(
@@ -288,16 +354,16 @@ func (g *GraphDB) Commit(triples []Triple, sessionID string, turnID int) (int, i
 				confidence, sourceID, targetID, t.Relation, sessionID,
 			)
 			if err != nil {
-				return 0, 0, err
+				return nil, 0, 0, err
 			}
 		}
 	}
 
 	if err := tx.Commit(); err != nil {
-		return 0, 0, err
+		return nil, 0, 0, err
 	}
 
-	return entitiesCreated, relationsCreated, nil
+	return sentenceIDs, entitiesCreated, relationsCreated, nil
 }
 
 func validEntityName(name string) bool {
@@ -688,9 +754,58 @@ func (g *GraphDB) GraphData() (map[string]interface{}, error) {
 		return nil, err
 	}
 
+	brows, err := g.db.Query(`SELECT id, modality, text_content, payload_digest, mime,
+		size, width, height, vector, fingerprint, source, tool, created_at, updated_at
+		FROM memory_blocks ORDER BY created_at, id`)
+	if err != nil {
+		return nil, err
+	}
+	defer brows.Close()
+	var blocks []MemoryBlock
+	for brows.Next() {
+		var block MemoryBlock
+		var vectorJSON string
+		if err := brows.Scan(&block.ID, &block.Modality, &block.Text, &block.PayloadDigest,
+			&block.MIME, &block.Size, &block.Width, &block.Height, &vectorJSON,
+			&block.Fingerprint, &block.Source, &block.Tool, &block.CreatedAt,
+			&block.UpdatedAt); err != nil {
+			return nil, err
+		}
+		if vectorJSON != "" && vectorJSON != "null" {
+			if err := json.Unmarshal([]byte(vectorJSON), &block.Vector); err != nil {
+				return nil, fmt.Errorf("decode memory block %s vector: %w", block.ID, err)
+			}
+		}
+		blocks = append(blocks, block)
+	}
+	if err := brows.Err(); err != nil {
+		return nil, err
+	}
+
+	berows, err := g.db.Query(`SELECT id, source_kind, source_id, target_kind, target_id,
+		edge_type, created_at FROM memory_block_edges ORDER BY id`)
+	if err != nil {
+		return nil, err
+	}
+	defer berows.Close()
+	var blockEdges []MemoryBlockEdge
+	for berows.Next() {
+		var edge MemoryBlockEdge
+		if err := berows.Scan(&edge.ID, &edge.SourceKind, &edge.SourceID,
+			&edge.TargetKind, &edge.TargetID, &edge.Type, &edge.CreatedAt); err != nil {
+			return nil, err
+		}
+		blockEdges = append(blockEdges, edge)
+	}
+	if err := berows.Err(); err != nil {
+		return nil, err
+	}
+
 	return map[string]interface{}{
-		"nodes": entities,
-		"edges": relations,
+		"nodes":              entities,
+		"edges":              relations,
+		"memory_blocks":      blocks,
+		"memory_block_edges": blockEdges,
 	}, nil
 }
 
@@ -873,17 +988,42 @@ func (g *GraphDB) ClearSentenceID(relationID int64) error {
 	return err
 }
 
-// CleanupOrphanedSentences 删除没有任何关系引用的句子，返回删除数
+// CleanupOrphanedSentences 删除既无关系引用、也无媒体块边的句子，返回删除数。
+//
+// 两个条件都必须看：旧媒体实体被迁移成原生块后，那些句子可能只靠
+// sentence --contains--> block 存活，若只看 relations 引用就会被误删，
+// 连带把块边变成悬空引用。
 func (g *GraphDB) CleanupOrphanedSentences() (int, error) {
-	result, err := g.db.Exec(
-		`DELETE FROM sentences WHERE id NOT IN (
-			SELECT DISTINCT sentence_id FROM relations WHERE sentence_id != 0
-		)`,
-	)
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	tx, err := g.db.Begin()
 	if err != nil {
 		return 0, err
 	}
-	n, _ := result.RowsAffected()
+	defer tx.Rollback()
+
+	// 先清掉指向将被删除句子的块边，避免留下悬空端点。
+	if _, err := tx.Exec(`DELETE FROM memory_block_edges
+		WHERE source_kind = 'sentence' AND source_id NOT IN (
+			SELECT CAST(id AS TEXT) FROM sentences
+			WHERE id IN (SELECT DISTINCT sentence_id FROM relations WHERE sentence_id != 0)
+			   OR id IN (SELECT CAST(source_id AS INTEGER) FROM memory_block_edges WHERE source_kind = 'sentence')
+		)`); err != nil {
+		return 0, err
+	}
+
+	res, err := tx.Exec(`DELETE FROM sentences WHERE id NOT IN (
+			SELECT DISTINCT sentence_id FROM relations WHERE sentence_id != 0
+		) AND id NOT IN (
+			SELECT CAST(source_id AS INTEGER) FROM memory_block_edges WHERE source_kind = 'sentence'
+		)`)
+	if err != nil {
+		return 0, err
+	}
+	n, _ := res.RowsAffected()
+	if err := tx.Commit(); err != nil {
+		return 0, err
+	}
 	return int(n), nil
 }
 

internal/memory/graph_test.go

@@ -2,8 +2,8 @@ package memory
 
 import (
 	"database/sql"
-	"path/filepath"
 	"os"
+	"path/filepath"
 	"testing"
 )
 
@@ -434,6 +434,84 @@ func TestMergeEntitiesNonexistent(t *testing.T) {
 	}
 }
 
+func TestMemoryBlocksAreFirstClassGraphNodes(t *testing.T) {
+	g := newTestGraph(t)
+	defer os.Remove(g.dbPath)
+	defer g.Close()
+
+	image := MemoryBlock{
+		ID: "block_image_1", Modality: BlockImage,
+		PayloadDigest: "0123456789abcdef", MIME: "image/png", Size: 1234,
+		Width: 768, Height: 512, Vector: []float64{0.1, 0.2, 0.3},
+		Fingerprint: "qwen:test", Source: "qq", Tool: "upload",
+	}
+	text := MemoryBlock{ID: "block_text_1", Modality: BlockText, Text: "用户上传了一张架构图"}
+	if err := g.PutMemoryBlocks([]MemoryBlock{image, text}); err != nil {
+		t.Fatalf("PutMemoryBlocks: %v", err)
+	}
+	if err := g.AddMemoryBlockEdge("block", text.ID, "block", image.ID, "contains"); err != nil {
+		t.Fatalf("AddMemoryBlockEdge: %v", err)
+	}
+
+	blocks, err := g.MemoryBlocks()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(blocks) != 2 {
+		t.Fatalf("memory blocks=%d, want 2", len(blocks))
+	}
+	var gotImage *MemoryBlock
+	for i := range blocks {
+		if blocks[i].ID == image.ID {
+			gotImage = &blocks[i]
+		}
+	}
+	if gotImage == nil || gotImage.Modality != BlockImage || gotImage.PayloadDigest != image.PayloadDigest || gotImage.Fingerprint != image.Fingerprint || len(gotImage.Vector) != 3 {
+		t.Fatalf("image block not round-tripped: %+v", gotImage)
+	}
+
+	edges, err := g.MemoryBlockEdges()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(edges) != 1 || edges[0].Type != "contains" || edges[0].SourceID != text.ID || edges[0].TargetID != image.ID {
+		t.Fatalf("memory block edges=%+v", edges)
+	}
+
+	graph, err := g.GraphData()
+	if err != nil {
+		t.Fatal(err)
+	}
+	graphBlocks, ok := graph["memory_blocks"].([]MemoryBlock)
+	if !ok || len(graphBlocks) != 2 {
+		t.Fatalf("GraphData memory_blocks=%T %+v", graph["memory_blocks"], graph["memory_blocks"])
+	}
+	graphEdges, ok := graph["memory_block_edges"].([]MemoryBlockEdge)
+	if !ok || len(graphEdges) != 1 {
+		t.Fatalf("GraphData memory_block_edges=%T %+v", graph["memory_block_edges"], graph["memory_block_edges"])
+	}
+}
+
+func TestMemoryBlockEdgeRejectsMissingEndpoint(t *testing.T) {
+	g := newTestGraph(t)
+	defer os.Remove(g.dbPath)
+	defer g.Close()
+
+	if err := g.PutMemoryBlocks([]MemoryBlock{{ID: "known", Modality: BlockText, Text: "known"}}); err != nil {
+		t.Fatal(err)
+	}
+	if err := g.AddMemoryBlockEdge("block", "known", "block", "missing", "derived_from"); err == nil {
+		t.Fatal("edge to missing node must fail")
+	}
+	edges, err := g.MemoryBlockEdges()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(edges) != 0 {
+		t.Fatalf("failed transaction left edges: %+v", edges)
+	}
+}
+
 func TestPlaceholders(t *testing.T) {
 	if placeholders(0) != "NULL" {
 		t.Errorf("expected NULL for n=0, got %s", placeholders(0))

internal/memory/indexer.go

@@ -10,19 +10,19 @@ import (
 )
 
 type Indexer struct {
-	db     *GraphDB
-	vec    *vector.Store
-	veczer *vector.TFIDFVectorizer
-	mu     sync.RWMutex
-	trained     bool
-	recalled    map[string]bool // 已通过工具调用显式召回的实体名，自动注入时跳过
+	db       *GraphDB
+	vec      *vector.Store
+	veczer   *vector.TFIDFVectorizer
+	mu       sync.RWMutex
+	trained  bool
+	recalled map[string]bool // 已通过工具调用显式召回的实体名，自动注入时跳过
 }
 
 func NewIndexer(db *GraphDB) *Indexer {
 	return &Indexer{
-		db:      db,
-		vec:     vector.NewStore(),
-		veczer:  vector.NewTFIDFVectorizer(TokenizeWords),
+		db:       db,
+		vec:      vector.NewStore(),
+		veczer:   vector.NewTFIDFVectorizer(TokenizeWords),
 		recalled: make(map[string]bool),
 	}
 }
@@ -174,7 +174,9 @@ func (idx *Indexer) BuildToolPrompt() string {
 ### memory_commit
 将三元组写入图记忆。
 参数:
-- triples: [{"subject": "实体名", "relation": "关系类型", "object": "目标实体"}]
+- triples: [{"subject": "实体名", "relation": "关系类型", "object": "目标实体",
+            "sentence_text": "原始句子（可选）", "media_digests": ["图片digest（可选）"]}]
+  填了 media_digests，日后从这条记忆就能取回当时那张图/那段音频。
 
 ### memory_introspect
 查看记忆统计信息。
@@ -261,6 +263,15 @@ func (idx *Indexer) GetToolDefinitions() []map[string]interface{} {
 									"subject":  map[string]interface{}{"type": "string"},
 									"relation": map[string]interface{}{"type": "string"},
 									"object":   map[string]interface{}{"type": "string"},
+									"sentence_text": map[string]interface{}{
+										"type":        "string",
+										"description": "可选：这条三元组的原始句子。填了才能日后从图谱回到原文。",
+									},
+									"media_digests": map[string]interface{}{
+										"type":        "array",
+										"description": "可选：这条记忆关联的媒体 digest（对话或 memory_recall 的「关联媒体」里显示的十六进制串，短的即可）。填了以后从这条记忆能取回原图/音频。",
+										"items":       map[string]interface{}{"type": "string"},
+									},
 								},
 								"required": []string{"subject", "relation", "object"},
 							},

internal/memory/jieba_embed.go

@@ -0,0 +1,123 @@
+// Package memory 的 jieba 词库内嵌。
+//
+// 为什么要把词库嵌进二进制，而不是像以前那样去猜 Go 模块缓存路径：
+//
+// 原实现是 `jiebaDictDir()` 依次试 GOMODCACHE / GOPATH / ~/go/pkg/mod，去找
+// `github.com/yanyiwu/gojieba@v1.4.7/deps/cppjieba/dict`。部署机上通常**没有**
+// Go 模块缓存，于是返回 ""，`GetJieba()` 返回 nil，四个分词/关键词函数
+// **一律静默返回空列表**（只在首次打一行「jieba disabled」）。
+//
+// 后果不是「少了个优化」而是**能力整体消失**：图记忆的关键词提取、文档
+// TF-IDF 分词、NLP 依存解析（进而 doc→graph 三元组抽取）全部退化为空。
+// 而本机之所以看起来正常，只是因为开发机与生产机重合、恰好有那份模块缓存。
+//
+// 内嵌后词库成为产物的一部分：与二进制同版本、随二进制分发、不依赖宿主环境。
+// 代价是包体大 ~11.6MB（jieba.dict.utf8 5.1M + idf.utf8 6.0M + hmm_model 0.5M + …），
+// 这是可接受的——它换来的是「装到哪都能用」。
+//
+// 关于 POS：gojieba 的 Tag() 不读 `pos_dict/` 目录，而是从主词典每行的
+// 词性列取 tag（cppjieba 的 PosTagger::LookupTag 走 dict->Find(...)->tag），
+// 取不到时用 SpecialRule 按字符类型兜底。所以这 5 个文件已足够同时支撑
+// Cut 与 Tag，无需再嵌 pos_dict/。
+package memory
+
+import (
+	"crypto/sha256"
+	"embed"
+	"encoding/hex"
+	"fmt"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sort"
+)
+
+//go:embed jiebadict/*
+var jiebaDictFS embed.FS
+
+// jiebaDictFiles 是 gojieba.NewJieba 需要的 5 个文件，顺序与它的参数一致：
+// dict, hmm, user, idf, stop_words。
+var jiebaDictFiles = []string{
+	"jieba.dict.utf8",
+	"hmm_model.utf8",
+	"user.dict.utf8",
+	"idf.utf8",
+	"stop_words.utf8",
+}
+
+// materializeJiebaDict 把内嵌词库落盘，返回目录路径。
+//
+// gojieba 的 C++ API 只接受**文件路径**（NewJieba 会对每个路径 os.Stat，
+// 缺失就 panic），所以必须先落盘再传路径。
+//
+// 落盘位置与幂等性：
+//   - 用内容哈希命名目录：词库升级后不会复用旧文件（否则会出现「新旧词库混用」
+//     这种最难查的一类问题——分词结果与版本对不上）。
+//   - 已存在且大小一致就跳过写入：正常启动只做几次 stat。
+func materializeJiebaDict() (string, error) {
+	sum, err := jiebaDictDigest()
+	if err != nil {
+		return "", err
+	}
+	base, err := os.UserCacheDir()
+	if err != nil || base == "" {
+		base = os.TempDir()
+	}
+	dir := filepath.Join(base, "homeagent", "jieba-"+sum)
+
+	if jiebaDictComplete(dir) {
+		return dir, nil
+	}
+	if err := os.MkdirAll(dir, 0o755); err != nil {
+		return "", fmt.Errorf("创建词库目录: %w", err)
+	}
+	for _, name := range jiebaDictFiles {
+		data, err := jiebaDictFS.ReadFile("jiebadict/" + name)
+		if err != nil {
+			return "", fmt.Errorf("读取内嵌词库 %s: %w", name, err)
+		}
+		path := filepath.Join(dir, name)
+		// 先写临时文件再 rename：避免并发启动时读到写了一半的词库。
+		tmp := path + ".tmp"
+		if err := os.WriteFile(tmp, data, 0o644); err != nil {
+			return "", fmt.Errorf("写出词库 %s: %w", name, err)
+		}
+		if err := os.Rename(tmp, path); err != nil {
+			return "", fmt.Errorf("落位词库 %s: %w", name, err)
+		}
+	}
+	return dir, nil
+}
+
+// jiebaDictDigest 对全部内嵌词库内容求哈希，作为落盘目录名的一部分。
+func jiebaDictDigest() (string, error) {
+	h := sha256.New()
+	// 按固定顺序喂入：embed.FS 的遍历顺序不保证稳定，顺序变了哈希就变，
+	// 会导致每次启动都重建一份词库。
+	names := append([]string(nil), jiebaDictFiles...)
+	sort.Strings(names)
+	for _, name := range names {
+		data, err := jiebaDictFS.ReadFile("jiebadict/" + name)
+		if err != nil {
+			return "", fmt.Errorf("读取内嵌词库 %s: %w", name, err)
+		}
+		fmt.Fprintf(h, "%s:%d:", name, len(data))
+		h.Write(data)
+	}
+	return hex.EncodeToString(h.Sum(nil))[:16], nil
+}
+
+// jiebaDictComplete 判断目录下 5 个词库是否齐全且大小与内嵌版本一致。
+func jiebaDictComplete(dir string) bool {
+	for _, name := range jiebaDictFiles {
+		want, err := fs.Stat(jiebaDictFS, "jiebadict/"+name)
+		if err != nil {
+			return false
+		}
+		got, err := os.Stat(filepath.Join(dir, name))
+		if err != nil || got.Size() != want.Size() {
+			return false
+		}
+	}
+	return true
+}

internal/memory/jieba_embed_test.go

@@ -0,0 +1,98 @@
+package memory
+
+import (
+	"os"
+	"path/filepath"
+	"sync"
+	"testing"
+)
+
+// 内嵌词库必须自足：把 GOMODCACHE/GOPATH/HOME 全部指向不存在的路径，
+// 分词与关键词提取仍然要工作。
+//
+// 这正是修复前的故障场景：原实现只去猜 Go 模块缓存，部署机上没有那份缓存时
+// GetJieba() 返回 nil，四个函数静默返回空列表——关键词提取、文档 TF-IDF 分词、
+// NLP 依存解析（进而 doc→graph 三元组抽取）一起失效，且只有一行日志。
+func TestEmbeddedJiebaDictIsSelfContained(t *testing.T) {
+	t.Setenv("GOMODCACHE", filepath.Join(t.TempDir(), "nonexistent"))
+	t.Setenv("GOPATH", filepath.Join(t.TempDir(), "nonexistent"))
+	t.Setenv("HOME", filepath.Join(t.TempDir(), "nonexistent"))
+	// 清掉可能已被其它测试初始化过的单例。
+	jiebaOnce = sync.Once{}
+	jiebaInst = nil
+	t.Cleanup(func() {
+		jiebaOnce = sync.Once{}
+		jiebaInst = nil
+	})
+
+	if x := GetJieba(); x == nil {
+		t.Fatal("模块缓存不可见时 jieba 必须仍能初始化（词库应来自内嵌副本）")
+	}
+
+	words := TokenizeWords("今天天气很好，我们去公园散步")
+	if len(words) == 0 {
+		t.Fatal("分词结果为空：内嵌词库没有真正生效")
+	}
+	t.Logf("分词结果: %v", words)
+
+	// 内容词（名词/动词/形容词）——依赖词典里的词性列，顺便验证 Tag 路径可用。
+	content := TokenizeContentWords("北京是中国的首都，这里有很多历史建筑")
+	if len(content) == 0 {
+		t.Fatal("内容词为空：Tag（词性标注）路径失效")
+	}
+	t.Logf("内容词: %v", content)
+
+	if kw := ExtractKeywords("机器学习模型训练需要大量数据和算力"); len(kw) == 0 {
+		t.Fatal("关键词为空")
+	}
+}
+
+// 落盘目录必须幂等：第二次调用不应重写文件（正常启动只做几次 stat）。
+func TestMaterializeJiebaDictIsIdempotent(t *testing.T) {
+	dir, err := materializeJiebaDict()
+	if err != nil {
+		t.Fatalf("materializeJiebaDict: %v", err)
+	}
+	for _, name := range jiebaDictFiles {
+		p := filepath.Join(dir, name)
+		fi, err := os.Stat(p)
+		if err != nil {
+			t.Fatalf("缺少词库文件 %s: %v", name, err)
+		}
+		if fi.Size() == 0 {
+			t.Fatalf("词库文件 %s 为空", name)
+		}
+	}
+
+	// 记下 mtime，再调一次，必须完全没动过。
+	before, _ := os.Stat(filepath.Join(dir, "jieba.dict.utf8"))
+	dir2, err := materializeJiebaDict()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if dir2 != dir {
+		t.Fatalf("目录名不稳定：%s vs %s（会导致每次启动重建词库）", dir, dir2)
+	}
+	after, _ := os.Stat(filepath.Join(dir, "jieba.dict.utf8"))
+	if !before.ModTime().Equal(after.ModTime()) {
+		t.Fatal("已存在完整词库时不应重写文件")
+	}
+}
+
+// 词库内容哈希必须稳定：否则目录名每次都变，等于每次启动都重建。
+func TestJiebaDictDigestStable(t *testing.T) {
+	a, err := jiebaDictDigest()
+	if err != nil {
+		t.Fatal(err)
+	}
+	b, err := jiebaDictDigest()
+	if err != nil {
+		t.Fatal(err)
+	}
+	if a != b {
+		t.Fatalf("哈希不稳定: %s vs %s", a, b)
+	}
+	if len(a) != 16 {
+		t.Fatalf("哈希长度异常: %q", a)
+	}
+}

internal/memory/jiebadict/user.dict.utf8

@@ -0,0 +1,4 @@
+云计算
+韩玉鉴赏
+蓝翔 nz
+区块链 10 nz

internal/memory/media/base64.go

@@ -0,0 +1,14 @@
+package media
+
+import "encoding/base64"
+
+// base64 编解码单独抽出来，让 media.go 的 import 块只留业务依赖。
+// 用 StdEncoding：data URL 规范用的是标准表（含 + / =），不是 URL-safe 表。
+
+func base64Decode(s string) ([]byte, error) {
+	return base64.StdEncoding.DecodeString(s)
+}
+
+func base64Encode(b []byte) string {
+	return base64.StdEncoding.EncodeToString(b)
+}

internal/memory/media/media.go

@@ -0,0 +1,662 @@
+// Package media 是记忆系统的内容寻址媒体存储（CAS）。
+//
+// 为何需要它：此前四层记忆全是纯文本载体——L0 `ContextEvent`、L1 `text.Event`、
+// L2 `document.Doc`、L3 图库的 `sentences.text TEXT UNIQUE`——没有任何一层能
+// 存二进制。multimodal 插件注入的图片在本轮对话内可见（走 message 数组，不经
+// 记忆），下一轮起就只剩 `ToolResultItem.Output` 里那句
+// "[已将图片注入后续对话] /tmp/x.png"，即一条路径字符串。那个文件被删或被
+// 覆盖之后连线索都断了。
+//
+// 为何是内容寻址而不是存路径：
+//   - 路径会失效。/tmp 下的探针图、下载缓存、其他进程的临时产物，记忆里留个
+//     路径等于留个悬空指针。
+//   - 同一张图往往被反复注入（用户连问几轮同一张截图、see_video 相邻帧高度
+//     相似）。按 sha256 寻址天然去重，同一份字节只存一遍。
+//   - 内容即身份，跟 L3 图库 `sentences.text UNIQUE` 的思路一致：文本节点用
+//     文本本身做身份，媒体节点用内容摘要做身份。
+package media
+
+import (
+	"crypto/sha256"
+	"database/sql"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"io"
+	"math"
+	"os"
+	"path/filepath"
+	"sort"
+	"strings"
+	"sync"
+	"time"
+
+	_ "github.com/mattn/go-sqlite3"
+)
+
+// digestHexLen 是 sha256 的十六进制串长度。
+const digestHexLen = sha256.Size * 2
+
+// Kind 是媒体大类。刻意只分三类而不细分具体格式：
+// 记忆检索关心的是“这是张图还是段音频”，具体编码交给 MIME 字段。
+type Kind string
+
+const (
+	KindImage Kind = "image"
+	KindAudio Kind = "audio"
+	KindVideo Kind = "video"
+	KindOther Kind = "other"
+)
+
+// Item 是一条媒体记录。
+//
+// Digest 既是主键也是磁盘文件名，所以没有单独的 Path 字段——路径可由
+// Store 根据 Digest 推导，不落库（落了就又是个会失效的引用）。
+type Item struct {
+	// Digest 是内容 sha256 的十六进制串（64 字符），媒体的唯一身份。
+	Digest string `json:"digest"`
+	// Kind 是大类，供检索时按模态筛选。
+	Kind Kind `json:"kind"`
+	// MIME 是原始 MIME 类型，如 image/png。
+	MIME string `json:"mime"`
+	// Size 是字节数。
+	Size int64 `json:"size"`
+	// Width/Height 是像素尺寸，未知或不适用时为 0。
+	Width  int `json:"width,omitempty"`
+	Height int `json:"height,omitempty"`
+	// OriginPath 是首次入库时的来源路径，仅供人类溯源与调试。
+	// **不可用于读取内容**——它随时可能失效，这正是本包存在的理由。
+	OriginPath string `json:"origin_path,omitempty"`
+	// Tool 是注入这条媒体的工具名（如 multimodal_see_picture）。
+	Tool string `json:"tool,omitempty"`
+	// FirstSeen/LastSeen 是首末次入库时间。
+	FirstSeen time.Time `json:"first_seen"`
+	LastSeen  time.Time `json:"last_seen"`
+	// --- 多模态嵌入（v1.2.0）---
+	// Vec 是视觉嵌入向量的序列化（JSON []float64），nil 表示未嵌入。
+	Vec []float64 `json:"vec,omitempty"`
+	// VecModel 是产生 Vec 的模型标识（如 "clip-vit-b32"），
+	// 用于模型切换后判断是否需要重算。
+	VecModel string `json:"vec_model,omitempty"`
+}
+
+// Store 管理媒体的元数据（SQLite）与内容（磁盘 CAS 目录）。
+//
+// 元数据与内容分离而不是把 blob 塞进 SQLite：单张图动辄几 MB，塞进库会让
+// 每次 VACUUM/备份都拖着几百 MB 走，也让 WAL 迅速膨胀。CAS 目录用两级
+// 前缀分桶（ab/cdef...）避免单目录几万文件。
+type Store struct {
+	mu      sync.RWMutex
+	db      *sql.DB
+	blobDir string
+}
+
+// New 打开（或初始化）媒体存储。
+// dir 下会建 media.db 与 blobs/ 两个条目。
+func New(dir string) (*Store, error) {
+	if err := os.MkdirAll(filepath.Join(dir, "blobs"), 0755); err != nil {
+		return nil, fmt.Errorf("media: create blob dir: %w", err)
+	}
+	dbPath := filepath.Join(dir, "media.db")
+	db, err := sql.Open("sqlite3", dbPath+"?_journal_mode=WAL&_busy_timeout=5000")
+	if err != nil {
+		return nil, fmt.Errorf("media: open db: %w", err)
+	}
+	s := &Store{db: db, blobDir: filepath.Join(dir, "blobs")}
+	if err := s.initSchema(); err != nil {
+		db.Close()
+		return nil, err
+	}
+	return s, nil
+}
+
+func (s *Store) initSchema() error {
+	stmts := []string{
+		// digest 作主键：内容即身份，重复 Put 同一内容不重复落盘。
+		`CREATE TABLE IF NOT EXISTS media (
+			digest       TEXT PRIMARY KEY,
+			kind         TEXT NOT NULL,
+			mime         TEXT NOT NULL,
+			size         INTEGER NOT NULL,
+			width        INTEGER DEFAULT 0,
+			height       INTEGER DEFAULT 0,
+			origin_path  TEXT,
+			tool         TEXT,
+			first_seen   TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+			last_seen    TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+		)`,
+		`CREATE INDEX IF NOT EXISTS idx_media_kind ON media(kind)`,
+		`CREATE INDEX IF NOT EXISTS idx_media_last_seen ON media(last_seen)`,
+	}
+	for _, q := range stmts {
+		if _, err := s.db.Exec(q); err != nil {
+			return fmt.Errorf("media: schema %q: %w", truncate(q, 60), err)
+		}
+	}
+	// v1.2.0 迁移：给 media 表加 vec（视觉嵌入向量 JSON）和 vec_model（模型标识）。
+	migrations := []string{
+		`ALTER TABLE media ADD COLUMN vec TEXT`,
+		`ALTER TABLE media ADD COLUMN vec_model TEXT`,
+	}
+	for _, q := range migrations {
+		_, _ = s.db.Exec(q) // 列已存在时返回 "duplicate column name"，可忽略
+	}
+	return nil
+}
+
+// blobPath 按两级前缀分桶推导内容路径。
+func (s *Store) blobPath(digest string) string {
+	if len(digest) < 4 {
+		return filepath.Join(s.blobDir, digest)
+	}
+	return filepath.Join(s.blobDir, digest[:2], digest[2:])
+}
+
+// Put 落盘并登记一段媒体内容，返回其 digest。
+//
+// 幂等：同一内容重复 Put 不重复落盘，只更新 last_seen 与可选的新元数据
+// （描述、尺寸等——后来者可能带着前一次没有的信息）。
+func (s *Store) Put(data []byte, meta Item) (string, error) {
+	if len(data) == 0 {
+		return "", fmt.Errorf("media: empty content")
+	}
+	sum := sha256.Sum256(data)
+	digest := hex.EncodeToString(sum[:])
+
+	s.mu.Lock()
+	defer s.mu.Unlock()
+
+	path := s.blobPath(digest)
+	if _, err := os.Stat(path); os.IsNotExist(err) {
+		if err := os.MkdirAll(filepath.Dir(path), 0755); err != nil {
+			return "", fmt.Errorf("media: mkdir: %w", err)
+		}
+		// 先写临时文件再 rename：中途崩溃不会留下半个 blob 被后续
+		// 当成完整内容读走（digest 校验能发现，但那时已经把坏数据喂给模型了）。
+		tmp := path + ".tmp"
+		if err := os.WriteFile(tmp, data, 0644); err != nil {
+			return "", fmt.Errorf("media: write blob: %w", err)
+		}
+		if err := os.Rename(tmp, path); err != nil {
+			os.Remove(tmp)
+			return "", fmt.Errorf("media: commit blob: %w", err)
+		}
+	}
+
+	now := time.Now()
+	if meta.Kind == "" {
+		meta.Kind = KindFromMIME(meta.MIME)
+	}
+	_, err := s.db.Exec(`
+		INSERT INTO media (digest, kind, mime, size, width, height,
+		                   origin_path, tool, first_seen, last_seen)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+		ON CONFLICT(digest) DO UPDATE SET
+			last_seen    = excluded.last_seen,
+			width        = CASE WHEN media.width  = 0 THEN excluded.width  ELSE media.width  END,
+			height       = CASE WHEN media.height = 0 THEN excluded.height ELSE media.height END,
+			tool         = CASE WHEN COALESCE(media.tool,'') = '' THEN excluded.tool ELSE media.tool END
+	`, digest, string(meta.Kind), meta.MIME, int64(len(data)), meta.Width, meta.Height,
+		meta.OriginPath, meta.Tool, now, now)
+	if err != nil {
+		return "", fmt.Errorf("media: upsert meta: %w", err)
+	}
+	return digest, nil
+}
+
+// Get 读取内容并校验 digest。
+//
+// 校验不是多余的：CAS 的全部保证建立在"文件名 == 内容摘要"上，磁盘位翻转
+// 或外部误改会让这条保证失效，而把损坏的图喂给模型只会得到无从追溯的幻觉。
+func (s *Store) Get(digest string) ([]byte, error) {
+	s.mu.RLock()
+	path := s.blobPath(digest)
+	s.mu.RUnlock()
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("media: read %s: %w", shortDigest(digest), err)
+	}
+	sum := sha256.Sum256(data)
+	if got := hex.EncodeToString(sum[:]); got != digest {
+		return nil, fmt.Errorf("media: digest mismatch for %s (content corrupted)", shortDigest(digest))
+	}
+	return data, nil
+}
+
+// Stat 返回元数据，不读内容。
+func (s *Store) Stat(digest string) (*Item, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	return s.scanOne(s.db.QueryRow(`
+		SELECT digest, kind, mime, size, width, height, origin_path, tool,
+		       first_seen, last_seen,
+		       vec, vec_model
+		FROM media WHERE digest = ?`, digest))
+}
+
+// Stat 返回元数据，不读内容。
+//
+// 这不是 GC，也不看引用计数：调用方是记忆系统本身——当它把一个记忆块
+// 永久地从三层记忆中删掉（而非在层间迁移）时，媒体作为块的内容一并删除。
+// 文本块就是这么管理的：删除块即删除内容。
+func (s *Store) Delete(digest string) error {
+	if digest == "" {
+		return nil
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	if err := os.Remove(s.blobPath(digest)); err != nil && !os.IsNotExist(err) {
+		return fmt.Errorf("media: remove blob %s: %w", shortDigest(digest), err)
+	}
+	if _, err := s.db.Exec(`DELETE FROM media WHERE digest = ?`, digest); err != nil {
+		return fmt.Errorf("media: delete meta %s: %w", shortDigest(digest), err)
+	}
+	return nil
+}
+
+// Stats 返回条目统计，供 WebUI / healthcheck 展示。
+func (s *Store) Stats() map[string]interface{} {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	out := map[string]interface{}{"blob_dir": s.blobDir}
+	var count int
+	var total int64
+	s.db.QueryRow(`SELECT COUNT(*), COALESCE(SUM(size),0) FROM media`).Scan(&count, &total)
+	out["count"] = count
+	out["total_bytes"] = total
+
+	byKind := map[string]int{}
+	rows, err := s.db.Query(`SELECT kind, COUNT(*) FROM media GROUP BY kind`)
+	if err == nil {
+		defer rows.Close()
+		for rows.Next() {
+			var k string
+			var n int
+			if rows.Scan(&k, &n) == nil {
+				byKind[k] = n
+			}
+		}
+	}
+	out["by_kind"] = byKind
+	return out
+}
+
+func (s *Store) Close() error {
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	return s.db.Close()
+}
+
+// ---- 多模态嵌入（v1.2.0） ----
+
+// SetVec 给一条已入库的媒体设置视觉嵌入向量。
+//
+// 设计选择：vec 是 TEXT（JSON 序列化的 []float64）而非 BLOB，
+// 因为 Go 的 json.Marshal/Unmarshal 对 []float64 是自然的，
+// 而 SQLite 的 BLOB 是 []byte，序列化多一层反而复杂。
+// 量级：一条 vec 最多 1536 维 × ~15 字节 ≈ 23KB，TEXT 合适。
+func (s *Store) SetVec(digest string, vec []float64, model string) error {
+	vecJSON, err := json.Marshal(vec)
+	if err != nil {
+		return fmt.Errorf("media: marshal vec: %w", err)
+	}
+	s.mu.Lock()
+	defer s.mu.Unlock()
+	_, err = s.db.Exec(`UPDATE media SET vec = ?, vec_model = ? WHERE digest = ?`,
+		string(vecJSON), model, digest)
+	return err
+}
+
+// StaleVecDigests 返回所有需要重新嵌入的图片 digest：
+// vec_model 不等于 currentModel（模型切换）或 vec_model 为空（从未嵌入）。
+// 调用方使用返回的 digest 列表调用 Get/EmbedImage/SetVec 完成重算。
+func (s *Store) StaleVecDigests(currentModel string) ([]string, error) {
+	return s.staleVecDigests(currentModel, "image")
+}
+
+// StaleVecDigestsAll 返回所有需要重新嵌入的媒体 digest（不限 kind），
+// 供模型切换后全量迁移向量空间（image + audio + video 等）。
+func (s *Store) StaleVecDigestsAll(currentModel string) ([]string, error) {
+	return s.staleVecDigests(currentModel, "")
+}
+
+// staleVecDigests 是 StaleVecDigests 的核心实现，kind=” 时不按 kind 过滤。
+// 废弃了"只迁移图片"的限定：模型切换后所有模态都应迁移到新向量空间。
+func (s *Store) staleVecDigests(currentModel string, kind string) ([]string, error) {
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	query := `
+		SELECT digest FROM media
+		WHERE (COALESCE(vec_model,'') = '' OR vec_model != ?)`
+	if kind != "" {
+		query += ` AND kind = ?`
+	}
+	query += ` ORDER BY last_seen`
+
+	var args []interface{}
+	args = append(args, currentModel)
+	if kind != "" {
+		args = append(args, kind)
+	}
+
+	rows, err := s.db.Query(query, args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	var digests []string
+	for rows.Next() {
+		var d string
+		if err := rows.Scan(&d); err == nil {
+			digests = append(digests, d)
+		}
+	}
+	return digests, rows.Err()
+}
+
+// QueryMedia 用查询向量对所有已嵌入媒体做余弦相似度检索，返回 topK 个最相似的 Item。
+//
+// 这是跨模态检索的关键：查询可以是图片也可以是文本（经文本向量化后调用此方法），
+// 被查的媒体库里的每个 item 也有一个视觉向量。两者在同一空间比对，
+// 谁的相似度更高就召回谁——不再区分「这是一张图的查询」还是「这是一段文字的查询」，
+// 由向量空间的相似度自动判断。
+func (s *Store) QueryMedia(queryVec []float64, model string, topK int) ([]*Item, error) {
+	hits, err := s.QueryMediaScored(queryVec, model, topK)
+	if err != nil {
+		return nil, err
+	}
+	if hits == nil {
+		return nil, nil
+	}
+	out := make([]*Item, len(hits))
+	for i, h := range hits {
+		out[i] = h.Item
+	}
+	return out, nil
+}
+
+// MediaHit 是一条媒体相似度候选及其分数。
+// 跨模态融合需要原始分数做归一化，仅返回 Item 会丢掉尺度信息。
+type MediaHit struct {
+	Item  *Item
+	Score float64
+}
+
+// QueryMediaScored 用查询向量对所有已嵌入媒体做余弦相似度检索，
+// 返回 topK 个最相似的候选及其原始 cosine 分数（供跨模态归一化）。
+//
+// 分数只做排序，不在存储层设绝对阈值：多模态文本→图像的绝对 cosine 随模型、
+// 语言与数据域漂移，真实标定中有效命中可以低至 0.015。相关性门控在融合器中
+// 使用当前候选集合的相对分布完成。
+func (s *Store) QueryMediaScored(queryVec []float64, model string, topK int) ([]MediaHit, error) {
+	return s.queryMediaScored(queryVec, model, topK)
+}
+
+func (s *Store) queryMediaScored(queryVec []float64, model string, topK int) ([]MediaHit, error) {
+	if topK <= 0 {
+		topK = 20
+	}
+	if len(queryVec) == 0 {
+		return nil, nil
+	}
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+
+	query := `SELECT digest, kind, mime, size, width, height,
+		origin_path, tool, first_seen, last_seen,
+		vec, vec_model
+		FROM media WHERE vec IS NOT NULL AND vec != ''`
+	var args []interface{}
+	if model != "" {
+		query += ` AND vec_model = ?`
+		args = append(args, model)
+	}
+	rows, err := s.db.Query(query, args...)
+	if err != nil {
+		return nil, err
+	}
+	defer rows.Close()
+
+	type scored struct {
+		item  *Item
+		score float64
+	}
+	var candidates []scored
+	for rows.Next() {
+		var it Item
+		var kind string
+		var origin, tool, vecJSON, vecModel sql.NullString
+		if err := rows.Scan(&it.Digest, &kind, &it.MIME, &it.Size, &it.Width, &it.Height,
+			&origin, &tool, &it.FirstSeen, &it.LastSeen,
+			&vecJSON, &vecModel); err != nil {
+			continue
+		}
+		it.Kind = Kind(kind)
+		it.OriginPath = origin.String
+		it.Tool = tool.String
+		if !vecJSON.Valid || vecJSON.String == "" {
+			continue
+		}
+		var itemVec []float64
+		if err := json.Unmarshal([]byte(vecJSON.String), &itemVec); err != nil || len(itemVec) == 0 {
+			continue
+		}
+		if len(itemVec) != len(queryVec) {
+			continue // 维度不一致，跳过
+		}
+		score := cosineSimilaritySlice(queryVec, itemVec)
+		if score > 0.05 {
+			candidates = append(candidates, scored{&it, score})
+		}
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+
+	// 按分数降序排序
+	sort.Slice(candidates, func(i, j int) bool {
+		return candidates[i].score > candidates[j].score
+	})
+	if len(candidates) > topK {
+		candidates = candidates[:topK]
+	}
+	out := make([]MediaHit, len(candidates))
+	for i, c := range candidates {
+		out[i] = MediaHit{Item: c.item, Score: c.score}
+	}
+	return out, nil
+}
+
+// cosineSimilaritySlice 计算两个 []float64 向量的余弦相似度。
+func cosineSimilaritySlice(a, b []float64) float64 {
+	var dot, normA, normB float64
+	for i := range a {
+		dot += a[i] * b[i]
+		normA += a[i] * a[i]
+		normB += b[i] * b[i]
+	}
+	if normA == 0 || normB == 0 {
+		return 0
+	}
+	return dot / (math.Sqrt(normA) * math.Sqrt(normB))
+}
+
+// ---- 扫描辅助 ----
+
+type rowScanner interface {
+	Scan(dest ...interface{}) error
+}
+
+func (s *Store) scanOne(r rowScanner) (*Item, error) {
+	it, err := scanItem(r)
+	if err == sql.ErrNoRows {
+		return nil, fmt.Errorf("media: unknown digest")
+	}
+	return it, err
+}
+
+func (s *Store) scanRows(r rowScanner) (*Item, error) { return scanItem(r) }
+
+func scanItem(r rowScanner) (*Item, error) {
+	var it Item
+	var kind string
+	var origin, tool, vecJSON, vecModel sql.NullString
+	if err := r.Scan(&it.Digest, &kind, &it.MIME, &it.Size, &it.Width, &it.Height,
+		&origin, &tool, &it.FirstSeen, &it.LastSeen,
+		&vecJSON, &vecModel); err != nil {
+		return nil, err
+	}
+	it.Kind = Kind(kind)
+	it.OriginPath = origin.String
+	it.Tool = tool.String
+	if vecJSON.Valid && vecJSON.String != "" {
+		var v []float64
+		if err := json.Unmarshal([]byte(vecJSON.String), &v); err == nil {
+			it.Vec = v
+		}
+	}
+	it.VecModel = vecModel.String
+	return &it, nil
+}
+
+// ---- 工具函数 ----
+
+// KindFromMIME 把 MIME 归到大类。
+func KindFromMIME(mime string) Kind {
+	m := strings.ToLower(strings.TrimSpace(mime))
+	switch {
+	case strings.HasPrefix(m, "image/"):
+		return KindImage
+	case strings.HasPrefix(m, "audio/"):
+		return KindAudio
+	case strings.HasPrefix(m, "video/"):
+		return KindVideo
+	default:
+		return KindOther
+	}
+}
+
+// ParseDataURL 从 data:<mime>;base64,<data> 提取 MIME 与原始字节。
+//
+// 与 agent/api 里的 parseAudioDataURL 分开实现：那个只认音频且只回 base64
+// 串（它要把串塞回 OpenAI 的 input_audio 字段），这里要的是解码后的字节。
+func ParseDataURL(url string) (mime string, data []byte, ok bool) {
+	const prefix = "data:"
+	if !strings.HasPrefix(url, prefix) {
+		return "", nil, false
+	}
+	rest := url[len(prefix):]
+	comma := strings.IndexByte(rest, ',')
+	if comma < 0 {
+		return "", nil, false
+	}
+	head := rest[:comma]
+	payload := rest[comma+1:]
+	if !strings.HasSuffix(strings.ToLower(head), ";base64") {
+		return "", nil, false
+	}
+	mime = head[:len(head)-len(";base64")]
+	if mime == "" || payload == "" {
+		return "", nil, false
+	}
+	decoded, err := base64Decode(payload)
+	if err != nil {
+		return "", nil, false
+	}
+	return mime, decoded, true
+}
+
+// DataURL 把内容编回 data URL，供重新注入模型对话。
+func DataURL(mime string, data []byte) string {
+	return "data:" + mime + ";base64," + base64Encode(data)
+}
+
+// CopyFrom 从 reader 读全部内容后 Put，用于大文件不便一次性构造 []byte 的场合。
+func (s *Store) CopyFrom(r io.Reader, meta Item) (string, error) {
+	data, err := io.ReadAll(r)
+	if err != nil {
+		return "", fmt.Errorf("media: read source: %w", err)
+	}
+	return s.Put(data, meta)
+}
+
+// MarshalItems 序列化条目列表，供工具返回给模型。
+func MarshalItems(items []*Item) string {
+	b, err := json.Marshal(items)
+	if err != nil {
+		return "[]"
+	}
+	return string(b)
+}
+
+func shortDigest(d string) string {
+	if len(d) > 12 {
+		return d[:12]
+	}
+	return d
+}
+
+func truncate(s string, n int) string {
+	s = strings.Join(strings.Fields(s), " ")
+	if len(s) <= n {
+		return s
+	}
+	return s[:n] + "..."
+}
+
+// ResolvePrefix 把 digest 前缀补全为完整 digest。
+//
+// 日志、事件摘要与图库句子里出现的都是 shortDigest（前 12 位），
+// 因为完整的 64 位 sha256 会把一行文字撑爆、也无助于人眼辨认。
+// 反查时需要这个补全，否则那些短标记只能看不能用。
+//
+// 前缀歧义视为错误而非"取第一个"：挂错引用会让 GC 删掉仍被引用的内容，
+// 宁可这次绑定失败。12 位十六进制的碰撞概率极低，真撞上说明该用更长前缀。
+func (s *Store) ResolvePrefix(prefix string) (string, error) {
+	prefix = strings.ToLower(strings.TrimSpace(prefix))
+	if len(prefix) < 8 {
+		return "", fmt.Errorf("digest 前缀过短（至少 8 位）: %q", prefix)
+	}
+	if len(prefix) == digestHexLen {
+		// 已是完整 digest：仍要确认存在，否则调用方会挂一条孤儿引用
+		if _, err := s.Stat(prefix); err != nil {
+			return "", err
+		}
+		return prefix, nil
+	}
+
+	s.mu.RLock()
+	defer s.mu.RUnlock()
+	rows, err := s.db.Query(
+		`SELECT digest FROM media WHERE digest LIKE ? || '%' LIMIT 2`, prefix)
+	if err != nil {
+		return "", err
+	}
+	defer rows.Close()
+
+	var found []string
+	for rows.Next() {
+		var d string
+		if err := rows.Scan(&d); err != nil {
+			return "", err
+		}
+		found = append(found, d)
+	}
+	if err := rows.Err(); err != nil {
+		return "", err
+	}
+
+	switch len(found) {
+	case 0:
+		return "", fmt.Errorf("digest 前缀 %q 未匹配到媒体", prefix)
+	case 1:
+		return found[0], nil
+	default:
+		return "", fmt.Errorf("digest 前缀 %q 有歧义（至少匹配 %s 和 %s）",
+			prefix, found[0][:16], found[1][:16])
+	}
+}

internal/memory/media/media_test.go

@@ -0,0 +1,278 @@
+package media
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// newTestStore 建一个临时媒体存储。
+// 参数保留只为兼容旧调用点；媒体不再有容量上限（生命周期由记忆块决定）。
+func newTestStore(t *testing.T, _ ...int64) *Store {
+	t.Helper()
+	s, err := New(t.TempDir())
+	if err != nil {
+		t.Fatalf("New: %v", err)
+	}
+	t.Cleanup(func() { s.Close() })
+	return s
+}
+
+func TestPut_ContentAddressedDedup(t *testing.T) {
+	s := newTestStore(t, 0)
+	data := []byte("fake-png-bytes")
+
+	d1, err := s.Put(data, Item{MIME: "image/png", OriginPath: "/tmp/a.png"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	d2, err := s.Put(data, Item{MIME: "image/png", OriginPath: "/tmp/b.png"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if d1 != d2 {
+		t.Fatalf("同一内容应得同一 digest：%s vs %s", d1, d2)
+	}
+
+	// 去重的意义：同一张图反复注入（连问几轮同一截图、see_video 相邻帧）
+	// 只占一份磁盘。
+	st := s.Stats()
+	if st["count"].(int) != 1 {
+		t.Fatalf("同一内容应只有 1 条记录，实际 %v", st["count"])
+	}
+}
+
+func TestPut_KindInferredFromMIME(t *testing.T) {
+	s := newTestStore(t, 0)
+	cases := map[string]Kind{
+		"image/png":  KindImage,
+		"image/jpeg": KindImage,
+		"audio/wav":  KindAudio,
+		"video/mp4":  KindVideo,
+		"text/plain": KindOther,
+	}
+	for mime, want := range cases {
+		d, err := s.Put([]byte("payload-"+mime), Item{MIME: mime})
+		if err != nil {
+			t.Fatal(err)
+		}
+		it, err := s.Stat(d)
+		if err != nil {
+			t.Fatal(err)
+		}
+		if it.Kind != want {
+			t.Fatalf("%s 应归为 %s，实际 %s", mime, want, it.Kind)
+		}
+	}
+}
+
+func TestGet_DetectsCorruption(t *testing.T) {
+	// CAS 的全部保证建立在「文件名 == 内容摘要」上。外部误改或位翻转必须
+	// 被发现——把损坏的图喂给模型只会得到无从追溯的幻觉。
+	s := newTestStore(t, 0)
+	d, err := s.Put([]byte("original-content"), Item{MIME: "image/png"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if _, err := s.Get(d); err != nil {
+		t.Fatalf("正常读取应成功: %v", err)
+	}
+
+	if err := os.WriteFile(s.blobPath(d), []byte("tampered!"), 0644); err != nil {
+		t.Fatal(err)
+	}
+	_, err = s.Get(d)
+	if err == nil {
+		t.Fatal("内容被改后应报 digest 不匹配，却读成功了")
+	}
+	if !strings.Contains(err.Error(), "digest mismatch") {
+		t.Fatalf("错误应指明 digest 不匹配，得到: %v", err)
+	}
+}
+
+func TestPut_NoPartialBlobOnDisk(t *testing.T) {
+	// 先写 .tmp 再 rename：确认落地后目录里不留临时文件。
+	s := newTestStore(t, 0)
+	d, err := s.Put([]byte("some-bytes"), Item{MIME: "image/png"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	dir := filepath.Dir(s.blobPath(d))
+	entries, err := os.ReadDir(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, e := range entries {
+		if strings.HasSuffix(e.Name(), ".tmp") {
+			t.Fatalf("落地后不该留临时文件: %s", e.Name())
+		}
+	}
+}
+
+func TestDelete_RemovesContentAndMetadata(t *testing.T) {
+	// 删除块即删除内容：Delete 同时清掉 blob 与元数据。
+	// 这不是 GC，也不看引用计数——调用方是记忆系统本身。
+	s := newTestStore(t)
+	d, _ := s.Put([]byte("held"), Item{MIME: "image/png"})
+	other, _ := s.Put([]byte("orphaned"), Item{MIME: "image/png"})
+
+	if err := s.Delete(other); err != nil {
+		t.Fatal(err)
+	}
+	if _, err := s.Stat(other); err == nil {
+		t.Fatal("删除后元数据应已移除")
+	}
+	if _, err := s.Get(other); err == nil {
+		t.Fatal("删除后内容应已移除")
+	}
+	// 未被删除的项不受影响
+	if _, err := s.Get(d); err != nil {
+		t.Fatalf("未删除的内容不该受影响: %v", err)
+	}
+}
+
+func TestDelete_UnknownDigestIsNoop(t *testing.T) {
+	s := newTestStore(t)
+	if err := s.Delete(""); err != nil {
+		t.Fatalf("空 digest 应为无操作: %v", err)
+	}
+	if err := s.Delete("ffffffffffffffff"); err != nil {
+		t.Fatalf("不存在的 digest 应为无操作: %v", err)
+	}
+}
+
+func TestDescribe_Removed(t *testing.T) {
+	// 媒体不再有文字描述：描述式索引是废弃的就机制。
+	// 这里只保留一个编译期断言，确保 API 不会静默回归。
+	s := newTestStore(t)
+	if _, err := s.Put([]byte("img"), Item{MIME: "image/png"}); err != nil {
+		t.Fatal(err)
+	}
+}
+
+func TestPut_BackfillsMissingDimensions(t *testing.T) {
+	// 后来者可能带着前一次没有的信息（尺寸、工具名）
+	s := newTestStore(t, 0)
+	data := []byte("img")
+	d, _ := s.Put(data, Item{MIME: "image/png"})
+
+	if _, err := s.Put(data, Item{MIME: "image/png", Width: 640, Height: 480, Tool: "multimodal_see_picture"}); err != nil {
+		t.Fatal(err)
+	}
+	it, _ := s.Stat(d)
+	if it.Width != 640 || it.Height != 480 {
+		t.Fatalf("尺寸应被补写: %dx%d", it.Width, it.Height)
+	}
+	if it.Tool != "multimodal_see_picture" {
+		t.Fatalf("工具名应被补写: %q", it.Tool)
+	}
+}
+
+func TestStats_CountsByKind(t *testing.T) {
+	s := newTestStore(t)
+	s.Put([]byte("i1"), Item{MIME: "image/png"})
+	s.Put([]byte("i2"), Item{MIME: "image/jpeg"})
+	s.Put([]byte("a1"), Item{MIME: "audio/wav"})
+
+	st := s.Stats()
+	if st["count"].(int) != 3 {
+		t.Fatalf("count 应为 3，实际 %v", st["count"])
+	}
+	if _, ok := st["described"]; ok {
+		t.Fatal("媒体已不再有描述计数")
+	}
+	byKind := st["by_kind"].(map[string]int)
+	if byKind["image"] != 2 || byKind["audio"] != 1 {
+		t.Fatalf("by_kind 不对: %v", byKind)
+	}
+}
+
+func TestParseDataURL(t *testing.T) {
+	// 与 agent/api 的 parseAudioDataURL 不同：这里要解码后的字节。
+	raw := []byte{0x89, 'P', 'N', 'G'}
+	url := DataURL("image/png", raw)
+
+	mime, data, ok := ParseDataURL(url)
+	if !ok {
+		t.Fatal("应解析成功")
+	}
+	if mime != "image/png" {
+		t.Fatalf("MIME 应为 image/png，得到 %q", mime)
+	}
+	if string(data) != string(raw) {
+		t.Fatalf("字节应还原，得到 %v", data)
+	}
+
+	for _, bad := range []string{
+		"http://example.com/x.png",  // 不是 data URL
+		"data:image/png,notbase64",  // 缺 ;base64
+		"data:;base64,",             // 空 MIME 与空载荷
+		"data:image/png;base64,!!!", // 非法 base64
+	} {
+		if _, _, ok := ParseDataURL(bad); ok {
+			t.Fatalf("%q 应解析失败", bad)
+		}
+	}
+}
+
+func TestPut_RejectsEmpty(t *testing.T) {
+	s := newTestStore(t)
+	if _, err := s.Put(nil, Item{MIME: "image/png"}); err == nil {
+		t.Fatal("空内容应报错")
+	}
+}
+
+func TestReopen_PersistsAcrossRestart(t *testing.T) {
+	// 记忆的意义就在于跨重启还在。
+	dir := t.TempDir()
+	s1, err := New(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	d, _ := s1.Put([]byte("persistent-img"), Item{MIME: "image/png", OriginPath: "/tmp/x.png"})
+	s1.SetVec(d, []float64{0.1, 0.2}, "test-space")
+	s1.Close()
+
+	s2, err := New(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer s2.Close()
+
+	it, err := s2.Stat(d)
+	if err != nil {
+		t.Fatalf("重开后应能查到: %v", err)
+	}
+	if it.OriginPath != "/tmp/x.png" || len(it.Vec) != 2 || it.VecModel != "test-space" {
+		t.Fatalf("元数据与向量应持久化: %+v", it)
+	}
+	data, err := s2.Get(d)
+	if err != nil || string(data) != "persistent-img" {
+		t.Fatalf("内容应持久化: %v / %q", err, data)
+	}
+}
+
+func TestStaleVecDigests_TracksModelSwitch(t *testing.T) {
+	// 模型切换后旧向量必须被重算：StaleVecDigests 是启动迁移的入口。
+	s := newTestStore(t)
+	d1, _ := s.Put([]byte("a"), Item{MIME: "image/png"})
+	d2, _ := s.Put([]byte("b"), Item{MIME: "image/png"})
+	s.SetVec(d1, []float64{0.1}, "space-a")
+
+	stale, err := s.StaleVecDigestsAll("space-a")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(stale) != 1 || stale[0] != d2 {
+		t.Fatalf("只有未嵌入的 d2 需重算，实际 %v", stale)
+	}
+
+	stale, err = s.StaleVecDigestsAll("space-b")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(stale) != 2 {
+		t.Fatalf("换空间后两条都需重算，实际 %v", stale)
+	}
+}

internal/memory/media/media_vec_test.go

@@ -0,0 +1,176 @@
+package media
+
+import (
+	"math"
+	"testing"
+)
+
+func TestQueryMedia_BasicSimilarity(t *testing.T) {
+	s := newTestStore(t, 0)
+	defer s.Close()
+
+	// 入库三张带向量的媒体：两张图、一段音频
+	d1, _ := s.Put([]byte("img1"), Item{MIME: "image/png"})
+	d2, _ := s.Put([]byte("img2"), Item{MIME: "image/jpeg"})
+	d3, _ := s.Put([]byte("aud1"), Item{MIME: "audio/wav"})
+
+	// 模拟视觉嵌入：img1 和 img2 向量接近，aud1 远离
+	vec1 := []float64{0.9, 0.1, 0.0, 0.0}
+	vec2 := []float64{0.8, 0.2, 0.0, 0.0} // 与 vec1 相似
+	vec3 := []float64{0.0, 0.0, 0.9, 0.1} // 与前两个完全不同
+
+	s.SetVec(d1, vec1, "test-clip")
+	s.SetVec(d2, vec2, "test-clip")
+	s.SetVec(d3, vec3, "test-clip")
+
+	// 用 vec1 作为查询：vec2 最相似，vec3 与 vec1 正交（相似度 0，被阈值过滤）
+	results, err := s.QueryMedia(vec1, "test-clip", 10)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// vec3 与 vec1 正交（余弦相似度 0），被 0.05 阈值正确剔除 → 只召回 2 个
+	if len(results) != 2 {
+		t.Fatalf("expected 2 results (正交的 aud1 被阈值过滤), got %d", len(results))
+	}
+	// 第一个应该是 img2（0.9 vs d1 的 1.0？不，这里算清楚）
+	// vec1·vec2 与 vec1·vec1 比较：
+	//   sim(vec1,vec1) = 1.0（img1 与自身），sim(vec1,vec2) = 0.9*0.8+0.1*0.2 = 0.74
+	// 所以 img1（自相似 1.0）排第一，img2 排第二
+	if results[0].Digest != d1 {
+		t.Errorf("expected d1 (自相似 1.0) as first, got %s", results[0].Digest)
+	}
+	if results[1].Digest != d2 {
+		t.Errorf("expected d2 as second, got %s", results[1].Digest)
+	}
+
+	// 验证分数：img1 与自身是 1.0
+	selfScore := cosineSimilaritySlice(vec1, vec1)
+	if math.Abs(selfScore-1.0) > 1e-10 {
+		t.Errorf("self-similarity should be 1.0, got %f", selfScore)
+	}
+
+	// img1 与 aud1 的相似度应该很低
+	crossScore := cosineSimilaritySlice(vec1, vec3)
+	if crossScore > 0.1 {
+		t.Errorf("cross-modality similarity should be low, got %f", crossScore)
+	}
+}
+
+func TestQueryMedia_EmptyVecSkipped(t *testing.T) {
+	s := newTestStore(t, 0)
+	defer s.Close()
+
+	d1, _ := s.Put([]byte("img1"), Item{MIME: "image/png"})
+	_, _ = s.Put([]byte("img2"), Item{MIME: "image/png"})
+
+	// d1 有向量，d2 没有
+	s.SetVec(d1, []float64{0.5, 0.5}, "test")
+	// d2 留空
+
+	results, err := s.QueryMedia([]float64{0.5, 0.5}, "test", 10)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(results) != 1 {
+		t.Fatalf("expected 1 result (d2 has no vec), got %d", len(results))
+	}
+	if results[0].Digest != d1 {
+		t.Errorf("expected d1, got %s", results[0].Digest)
+	}
+}
+
+func TestQueryMedia_DimensionMismatchSkipped(t *testing.T) {
+	s := newTestStore(t, 0)
+	defer s.Close()
+
+	d1, _ := s.Put([]byte("img1"), Item{MIME: "image/png"})
+	s.SetVec(d1, []float64{0.5, 0.5}, "model-A") // 2 维
+
+	// 查询用 3 维向量：维度不匹配，应该返回空
+	results, err := s.QueryMedia([]float64{0.3, 0.3, 0.3}, "model-A", 10)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(results) != 0 {
+		t.Fatalf("expected 0 results (dim mismatch), got %d", len(results))
+	}
+}
+
+func TestQueryMedia_EmptyQueryReturnsNil(t *testing.T) {
+	s := newTestStore(t, 0)
+	defer s.Close()
+
+	results, err := s.QueryMedia(nil, "", 10)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if results != nil {
+		t.Fatalf("expected nil, got %d results", len(results))
+	}
+}
+
+func TestSetVec_PersistsCorrectly(t *testing.T) {
+	s := newTestStore(t, 0)
+	defer s.Close()
+
+	d, _ := s.Put([]byte("hello"), Item{MIME: "image/png"})
+	vec := []float64{0.1, 0.2, 0.3, 0.4}
+	s.SetVec(d, vec, "clip-vit-b32")
+
+	it, err := s.Stat(d)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if it.VecModel != "clip-vit-b32" {
+		t.Errorf("VecModel = %q, want clip-vit-b32", it.VecModel)
+	}
+	if len(it.Vec) != 4 {
+		t.Fatalf("Vec len = %d, want 4", len(it.Vec))
+	}
+	for i, v := range vec {
+		if math.Abs(it.Vec[i]-v) > 1e-10 {
+			t.Errorf("Vec[%d] = %f, want %f", i, it.Vec[i], v)
+		}
+	}
+}
+
+func TestStaleVecDigests(t *testing.T) {
+	s := newTestStore(t, 0)
+	defer s.Close()
+
+	// 有向量且 vec_model 匹配 → 非 stale
+	d1, _ := s.Put([]byte("img1"), Item{MIME: "image/png"})
+	s.SetVec(d1, []float64{0.1}, "space-a")
+
+	// 有向量但 vec_model 旧 → stale
+	d2, _ := s.Put([]byte("img2"), Item{MIME: "image/png"})
+	s.SetVec(d2, []float64{0.2}, "space-old")
+
+	// 从未嵌入（vec_model 空）→ stale
+	d3, _ := s.Put([]byte("img3"), Item{MIME: "image/png"})
+
+	// 与向量/描述无关的图片同样应被迁移：图片独立参与向量空间
+	d4, _ := s.Put([]byte("img4"), Item{MIME: "image/png"})
+
+	// 音频不参与图片迁移（StaleVecDigests 只查 kind='image'）
+	s.Put([]byte("aud1"), Item{MIME: "audio/wav"})
+
+	stale, err := s.StaleVecDigests("space-a")
+	if err != nil {
+		t.Fatal(err)
+	}
+	// d1 匹配模型 → 非 stale；d2 旧模型 + d3 未嵌入 + d4 无描述图片 = 3 stale；aud1 不算
+	if len(stale) != 3 {
+		t.Fatalf("expected 3 stale digests (d2 旧模型 + d3 未嵌入 + d4 无描述), got %d: %v", len(stale), stale)
+	}
+	got := map[string]bool{}
+	for _, d := range stale {
+		got[d] = true
+	}
+	if !got[d2] || !got[d3] || !got[d4] {
+		t.Errorf("expected d2, d3, d4 stale, got %v", stale)
+	}
+	if got[d1] {
+		t.Errorf("d1 (匹配模型) 不应 stale")
+	}
+}

internal/memory/media/smoke_test.go

@@ -0,0 +1,277 @@
+package media
+
+import (
+	"bytes"
+	"compress/zlib"
+	"encoding/binary"
+	"fmt"
+	"hash/crc32"
+	"testing"
+)
+
+// 冒烟测试：走真实数据路径的端到端场景，而非孤立的 API 单测。
+//
+// 媒体存储现在只做内容寻址（CAS）：字节 + 元数据 + 向量。
+// “哪些字节还活着”由三层记忆持有的一等记忆块决定，调用方把该集合传给
+// GC/检索，本层不维护 media_refs/ref_count 这类平行账本。
+
+// makePNG 生成一张 w×h 的条带 PNG，用真 PNG 而不是随机字节，
+// 让入库/回读/digest 走的是与生产一致的数据形态。
+func makePNG(w, h, variant int) []byte {
+	palette := [][3]byte{
+		{255, 0, 0}, {0, 192, 0}, {0, 0, 255}, {255, 220, 0}, {160, 0, 200},
+	}
+	var raw bytes.Buffer
+	for y := 0; y < h; y++ {
+		raw.WriteByte(0) // 每行的滤波器字节
+		c := palette[(variant+y*3/h)%len(palette)]
+		for x := 0; x < w; x++ {
+			raw.Write(c[:])
+		}
+	}
+	// 把 variant 写进首行头几个像素，确保不同 variant 字节必然不同。
+	b := raw.Bytes()
+	if len(b) > 8 {
+		b[1] = byte(variant)
+		b[2] = byte(variant >> 8)
+	}
+
+	var z bytes.Buffer
+	zw := zlib.NewWriter(&z)
+	zw.Write(b)
+	zw.Close()
+
+	chunk := func(typ string, data []byte) []byte {
+		var out bytes.Buffer
+		binary.Write(&out, binary.BigEndian, uint32(len(data)))
+		out.WriteString(typ)
+		out.Write(data)
+		binary.Write(&out, binary.BigEndian, crc32.ChecksumIEEE(append([]byte(typ), data...)))
+		return out.Bytes()
+	}
+	var ihdr bytes.Buffer
+	binary.Write(&ihdr, binary.BigEndian, uint32(w))
+	binary.Write(&ihdr, binary.BigEndian, uint32(h))
+	ihdr.Write([]byte{8, 2, 0, 0, 0}) // 8bit 深度、truecolor
+
+	var out bytes.Buffer
+	out.Write([]byte{0x89, 'P', 'N', 'G', '\r', '\n', 0x1a, '\n'})
+	out.Write(chunk("IHDR", ihdr.Bytes()))
+	out.Write(chunk("IDAT", z.Bytes()))
+	out.Write(chunk("IEND", nil))
+	return out.Bytes()
+}
+
+func TestSmoke_SamePictureAcrossTurns(t *testing.T) {
+	// 场景：用户连问几轮同一张截图。multimodal 每轮都会重新注入，
+	// 内容寻址天然去重，磁盘上只应有一份。
+	s := newTestStore(t, 50*1024*1024)
+	png := makePNG(400, 400, 0)
+
+	var d0 string
+	for turn := 1; turn <= 5; turn++ {
+		// 走 data URL：这是 SetToolBlocks 实际给出的形态
+		url := DataURL("image/png", png)
+		mime, data, ok := ParseDataURL(url)
+		if !ok {
+			t.Fatalf("第 %d 轮 data URL 解析失败", turn)
+		}
+		d, err := s.Put(data, Item{
+			MIME: mime, Width: 400, Height: 400,
+			OriginPath: fmt.Sprintf("/tmp/probe_%d.png", turn),
+			Tool:       "multimodal_see_picture",
+		})
+		if err != nil {
+			t.Fatalf("第 %d 轮 Put: %v", turn, err)
+		}
+		if d0 == "" {
+			d0 = d
+		} else if d != d0 {
+			t.Fatalf("同一张图第 %d 轮 digest 变了", turn)
+		}
+	}
+
+	st := s.Stats()
+	if st["count"].(int) != 1 {
+		t.Fatalf("5 轮同图应只存 1 份，实际 %v 条", st["count"])
+	}
+	if total := st["total_bytes"].(int64); total != int64(len(png)) {
+		t.Fatalf("字节数应等于单张原图 %d，实际 %d", len(png), total)
+	}
+	// 三层记忆持有它；内容应仍可读
+	if _, err := s.Get(d0); err != nil {
+		t.Fatalf("内容应仍可读: %v", err)
+	}
+}
+
+func TestSmoke_VideoFramesDistinct(t *testing.T) {
+	// 场景：see_video 抽 6 帧，帧间内容不同，应各存一份。
+	s := newTestStore(t, 50*1024*1024)
+	keep := map[string]bool{}
+	for i := 0; i < 6; i++ {
+		d, err := s.Put(makePNG(320, 240, i), Item{
+			MIME: "image/jpeg", Width: 320, Height: 240, Tool: "multimodal_see_video",
+		})
+		if err != nil {
+			t.Fatalf("第 %d 帧: %v", i, err)
+		}
+		keep[d] = true
+	}
+
+	if st := s.Stats(); st["count"].(int) != 6 {
+		t.Fatalf("6 帧应各存一份，实际 %v 条", st["count"])
+	}
+}
+
+func TestSmoke_NearestNeighborVectorRetrieve(t *testing.T) {
+	// 场景 C：图片只按自己的原生向量被检索。
+	// 没有描述文本参与——描述式索引是废弃的就机制。
+	s := newTestStore(t)
+
+	pic, _ := s.Put(makePNG(400, 400, 0), Item{MIME: "image/png", Tool: "multimodal_see_picture"})
+	s.SetVec(pic, []float64{1, 0, 0, 0}, "space")
+	var frames []string
+	for i := 0; i < 6; i++ {
+		d, _ := s.Put(makePNG(320, 240, i), Item{MIME: "image/jpeg", Tool: "multimodal_see_video"})
+		s.SetVec(d, []float64{1, 1, float64(i) / 10, 0}, "space")
+		frames = append(frames, d)
+	}
+
+	hits, err := s.QueryMediaScored([]float64{1, 0, 0, 0}, "space", 10)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(hits) != 7 {
+		t.Fatalf("7 份媒体都有同空间向量，应全部可召，实际 %d", len(hits))
+	}
+	if hits[0].Item.Digest != pic {
+		t.Fatalf("与查询同向的应是第一命中，实际 %s", shortDigest(hits[0].Item.Digest))
+	}
+
+	// 不同向量空间/模型的条目不得参与：坐标系不同，余弦无意义。
+	foreign := frames[0]
+	if err := s.SetVec(foreign, []float64{1, 0, 0, 0}, "other-space"); err != nil {
+		t.Fatal(err)
+	}
+	hits, err = s.QueryMediaScored([]float64{1, 0, 0, 0}, "space", 10)
+	if err != nil {
+		t.Fatal(err)
+	}
+	for _, h := range hits {
+		if h.Item.Digest == foreign {
+			t.Fatal("另一套空间（other-space）的向量不该被 space 查询召回")
+		}
+	}
+}
+
+func TestSmoke_ContentSurvivesLayerMigration(t *testing.T) {
+	// 场景：同一份媒体随记忆块从 Context 迁移到 Document 再到 Graph。
+	// 迁移的是块本身，digest 不变，因此内容在整条链路上始终可读。
+	s := newTestStore(t, 50*1024*1024)
+	png := makePNG(400, 400, 0)
+	d, _ := s.Put(png, Item{MIME: "image/png", Tool: "multimodal_see_picture"})
+
+	// 迁移过程中该 digest 始终可读
+	for _, layer := range []string{"context", "document", "graph"} {
+		if got, err := s.Get(d); err != nil || !bytes.Equal(got, png) {
+			t.Fatalf("迁移到 %s 时内容应完好: %v", layer, err)
+		}
+	}
+}
+
+func TestSmoke_DeleteRemovesOnlyThatContent(t *testing.T) {
+	// 场景：某个工具产出的一次性图片所在的记忆块被删除时，
+	// 只有它自己的内容被删；其他块的内容一个都不能少。
+	s := newTestStore(t)
+
+	held, _ := s.Put(makePNG(400, 400, 0), Item{MIME: "image/png"})
+	var frames []string
+	for i := 0; i < 6; i++ {
+		d, _ := s.Put(makePNG(320, 240, i), Item{MIME: "image/jpeg"})
+		frames = append(frames, d)
+	}
+	var ephemeral []string
+	for i := 0; i < 20; i++ {
+		d, _ := s.Put(makePNG(100, 100, 1000+i), Item{MIME: "image/png", Tool: "cmd_run"})
+		ephemeral = append(ephemeral, d)
+	}
+
+	before := s.Stats()["count"].(int)
+	for _, d := range ephemeral {
+		if err := s.Delete(d); err != nil {
+			t.Fatal(err)
+		}
+	}
+	after := s.Stats()["count"].(int)
+	if after != before-20 {
+		t.Fatalf("条目数应从 %d 降到 %d，实际 %d", before, before-20, after)
+	}
+	if _, err := s.Get(held); err != nil {
+		t.Fatalf("被保留的内容被误删: %v", err)
+	}
+	for i, f := range frames {
+		if _, err := s.Get(f); err != nil {
+			t.Fatalf("第 %d 帧被误删: %v", i, err)
+		}
+	}
+}
+
+func TestSmoke_FullLifecycleAcrossRestart(t *testing.T) {
+	// 端到端：入库 → 嵌入 → 删除一些内容 → 重启 → 向量检索，
+	// 并确认磁盘与元数据不出现双向孤儿。记忆的意义就在于跨重启还在。
+	dir := t.TempDir()
+	s, err := New(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	png := makePNG(400, 400, 0)
+	pic, _ := s.Put(png, Item{MIME: "image/png", Width: 400, Height: 400, Tool: "multimodal_see_picture"})
+	s.SetVec(pic, []float64{1, 0, 0}, "space")
+	for i := 0; i < 6; i++ {
+		d, _ := s.Put(makePNG(320, 240, i), Item{MIME: "image/jpeg", Tool: "multimodal_see_video"})
+		s.SetVec(d, []float64{0, 1, float64(i)}, "space")
+	}
+	for i := 0; i < 10; i++ {
+		d, _ := s.Put(makePNG(64, 64, 2000+i), Item{MIME: "image/png", Tool: "cmd_run"})
+		if err := s.Delete(d); err != nil {
+			t.Fatal(err)
+		}
+	}
+	beforeCount := s.Stats()["count"].(int)
+	s.Close()
+
+	s2, err := New(dir)
+	if err != nil {
+		t.Fatalf("重开失败: %v", err)
+	}
+	defer s2.Close()
+
+	if got := s2.Stats()["count"].(int); got != beforeCount {
+		t.Fatalf("重开后条目数变了: %d → %d", beforeCount, got)
+	}
+	it, err := s2.Stat(pic)
+	if err != nil {
+		t.Fatalf("重开后查不到: %v", err)
+	}
+	if len(it.Vec) != 3 || it.VecModel != "space" {
+		t.Fatalf("向量未持久化: %+v", it)
+	}
+	data, err := s2.Get(pic)
+	if err != nil || !bytes.Equal(data, png) {
+		t.Fatalf("重开后内容不一致: %v", err)
+	}
+	hits, err := s2.QueryMediaScored([]float64{1, 0, 0}, "space", 10)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(hits) == 0 || hits[0].Item.Digest != pic {
+		t.Fatal("重开后向量检索应仍能命中")
+	}
+
+	// 磁盘文件数 == 元数据条数：无「元数据在文件没了」也无「文件在元数据没了」
+	if n := blobFileCount(t, s2); n != beforeCount {
+		t.Fatalf("磁盘 blob=%d 与元数据=%d 不一致", n, beforeCount)
+	}
+	t.Logf("跨重启：%d 条目、向量与内容全部完好", beforeCount)
+}

internal/memory/media/soak_test.go

@@ -0,0 +1,166 @@
+package media
+
+import (
+	"bytes"
+	"crypto/rand"
+	"fmt"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// TestSoak_SustainedMixedLoad 长稳测试：持续混合负载下不变量不破。
+// 用 -run TestSoak -timeout 300s 单独跑，默认 short 模式跳过。
+//
+// 媒体没有独立生命周期管理：blob 是记忆块的内容，块被删除时内容随之删除。
+func TestSoak_SustainedMixedLoad(t *testing.T) {
+	if testing.Short() {
+		t.Skip("long soak test; run with -run TestSoak")
+	}
+	dur := 60 * time.Second
+	s := newTestStore(t)
+
+	// 常驻受保护区：全程被记忆块持有，模拟 Graph L3 中的块
+	const keepN = 20
+	keep := make([]string, keepN)
+	keepData := make([][]byte, keepN)
+	for i := range keep {
+		d := make([]byte, 4096)
+		rand.Read(d)
+		d = append([]byte(fmt.Sprintf("keep-%d-", i)), d...)
+		dg, err := s.Put(d, Item{MIME: "image/png"})
+		if err != nil {
+			t.Fatal(err)
+		}
+		keep[i] = dg
+		keepData[i] = d
+	}
+
+	stop := make(chan struct{})
+	var wg sync.WaitGroup
+	var puts, gets, deletes, embeds, searches atomic.Int64
+	var fatal atomic.Int64
+
+	worker := func(name string, fn func(iter int) error) {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for i := 0; ; i++ {
+				select {
+				case <-stop:
+					return
+				default:
+				}
+				if err := fn(i); err != nil {
+					fatal.Add(1)
+					t.Errorf("%s 第 %d 次失败: %v", name, i, err)
+					return
+				}
+			}
+		}()
+	}
+
+	// 写入者 ×3：持续写入一次性内容（无人持有）
+	for w := 0; w < 3; w++ {
+		wid := w
+		worker(fmt.Sprintf("put-%d", wid), func(i int) error {
+			b := make([]byte, 2048)
+			rand.Read(b)
+			b = append([]byte(fmt.Sprintf("eph-%d-%d-", wid, i)), b...)
+			if _, err := s.Put(b, Item{MIME: "image/png", Tool: "cmd_run"}); err != nil {
+				return err
+			}
+			puts.Add(1)
+			return nil
+		})
+	}
+
+	// 读取者 ×3：受保护集必须始终完好
+	for r := 0; r < 3; r++ {
+		worker("get", func(i int) error {
+			idx := i % keepN
+			got, err := s.Get(keep[idx])
+			if err != nil {
+				return err
+			}
+			if !bytes.Equal(got, keepData[idx]) {
+				return fmt.Errorf("内容被改 %s", shortDigest(keep[idx]))
+			}
+			gets.Add(1)
+			return nil
+		})
+	}
+
+	// 删除者：持续删除一次性内容（模拟块创建后又被遗忘）
+	worker("delete", func(i int) error {
+		b := make([]byte, 2048)
+		rand.Read(b)
+		b = append([]byte(fmt.Sprintf("del-%d-", i)), b...)
+		d, err := s.Put(b, Item{MIME: "image/png", Tool: "cmd_run"})
+		if err != nil {
+			return err
+		}
+		if err := s.Delete(d); err != nil {
+			return err
+		}
+		deletes.Add(1)
+		time.Sleep(time.Millisecond)
+		return nil
+	})
+
+	// 向量写入者：持续给新内容嵌入并删除（模拟启动迁移/短命媒体）
+	worker("embed", func(i int) error {
+		b := make([]byte, 1024)
+		rand.Read(b)
+		b = append([]byte(fmt.Sprintf("emb-%d-", i)), b...)
+		d, err := s.Put(b, Item{MIME: "image/png", Tool: "cmd_run"})
+		if err != nil {
+			return err
+		}
+		if err := s.SetVec(d, []float64{1, float64(i % 7)}, "soak-space"); err != nil {
+			return err
+		}
+		embeds.Add(1)
+		time.Sleep(time.Millisecond)
+		return nil
+	})
+
+	// 检索者
+	worker("search", func(i int) error {
+		if _, err := s.QueryMediaScored([]float64{1, 0}, "soak-space", 20); err != nil {
+			return err
+		}
+		if _, err := s.Stat(keep[i%keepN]); err != nil {
+			return err
+		}
+		searches.Add(1)
+		time.Sleep(2 * time.Millisecond)
+		return nil
+	})
+
+	time.Sleep(dur)
+	close(stop)
+	wg.Wait()
+
+	if n := fatal.Load(); n > 0 {
+		t.Fatalf("%d 个 worker 报致命错误", n)
+	}
+
+	t.Logf("%v 内: put=%d get=%d delete=%d embed=%d search=%d",
+		dur, puts.Load(), gets.Load(), deletes.Load(), embeds.Load(), searches.Load())
+
+	// 收尾断言
+	for i, d := range keep {
+		got, err := s.Get(d)
+		if err != nil {
+			t.Fatalf("受保护项丢失 %s: %v", shortDigest(d), err)
+		}
+		if !bytes.Equal(got, keepData[i]) {
+			t.Fatalf("受保护项内容变了 %s", shortDigest(d))
+		}
+	}
+
+	st := s.Stats()
+	t.Logf("收尾: 条目=%v 字节=%v 类型=%v", st["count"], st["total_bytes"], st["by_kind"])
+}

internal/memory/media/stress_test.go

@@ -0,0 +1,527 @@
+package media
+
+import (
+	"bytes"
+	"crypto/rand"
+	"fmt"
+	"os"
+	"path/filepath"
+	"strings"
+	"sync"
+	"sync/atomic"
+	"testing"
+	"time"
+)
+
+// 压力测试与冒烟测试。
+//
+// 关注点不是吞吐数字，而是并发下的不变量是否被破坏：
+//   1. GC 与读写并发时，被记忆块持有的内容绝不能被删
+//   2. 同内容并发 Put 只落一份磁盘、digest 一致
+//   3. SQLite 在多 goroutine 下不出现 "database is locked"
+//
+// 存活判定不再依赖 media_refs/ref_count：调用方把「三层记忆当前持有的
+// digest 集合」传给 GC，本层只做 CAS。
+
+func randBytes(t *testing.T, n int) []byte {
+	t.Helper()
+	b := make([]byte, n)
+	if _, err := rand.Read(b); err != nil {
+		t.Fatalf("rand: %v", err)
+	}
+	return b
+}
+
+// blobFileCount 统计 CAS 目录下的实际文件数（不含 .tmp）。
+func blobFileCount(t *testing.T, s *Store) int {
+	t.Helper()
+	n := 0
+	filepath.Walk(s.blobDir, func(path string, info os.FileInfo, err error) error {
+		if err != nil || info == nil || info.IsDir() {
+			return nil
+		}
+		if strings.HasSuffix(path, ".tmp") {
+			t.Errorf("残留临时文件: %s", path)
+			return nil
+		}
+		n++
+		return nil
+	})
+	return n
+}
+
+func TestStress_ConcurrentPutSameContent(t *testing.T) {
+	// 同一内容被 N 个 goroutine 同时 Put：digest 必须一致，磁盘只一份。
+	// 现实对应：see_video 抽出的相邻帧、用户连发同一张图。
+	s := newTestStore(t, 0)
+	data := randBytes(t, 64*1024)
+
+	const workers = 32
+	var wg sync.WaitGroup
+	digests := make([]string, workers)
+	errs := make([]error, workers)
+	for i := 0; i < workers; i++ {
+		wg.Add(1)
+		go func(idx int) {
+			defer wg.Done()
+			d, err := s.Put(data, Item{MIME: "image/png", OriginPath: fmt.Sprintf("/tmp/%d.png", idx)})
+			digests[idx] = d
+			errs[idx] = err
+		}(i)
+	}
+	wg.Wait()
+
+	for i, err := range errs {
+		if err != nil {
+			t.Fatalf("worker %d Put 失败: %v", i, err)
+		}
+	}
+	first := digests[0]
+	for i, d := range digests {
+		if d != first {
+			t.Fatalf("worker %d digest 不一致: %s vs %s", i, d, first)
+		}
+	}
+	if n := blobFileCount(t, s); n != 1 {
+		t.Fatalf("同一内容应只落一份 blob，实际 %d 个文件", n)
+	}
+	if got, err := s.Get(first); err != nil || !bytes.Equal(got, data) {
+		t.Fatalf("内容应可完整读回: err=%v len=%d", err, len(got))
+	}
+}
+
+func TestStress_ConcurrentPutDistinctContent(t *testing.T) {
+	// 大量不同内容并发入库：不丢条目、不串内容。
+	s := newTestStore(t, 0)
+	const workers = 16
+	const perWorker = 25
+
+	var wg sync.WaitGroup
+	var failed atomic.Int64
+	type rec struct {
+		digest string
+		data   []byte
+	}
+	recCh := make(chan rec, workers*perWorker)
+
+	for w := 0; w < workers; w++ {
+		wg.Add(1)
+		go func(wid int) {
+			defer wg.Done()
+			for i := 0; i < perWorker; i++ {
+				data := []byte(fmt.Sprintf("w%d-i%d-", wid, i))
+				data = append(data, randBytes(t, 512)...)
+				d, err := s.Put(data, Item{MIME: "image/png"})
+				if err != nil {
+					failed.Add(1)
+					continue
+				}
+				recCh <- rec{digest: d, data: data}
+			}
+		}(w)
+	}
+	wg.Wait()
+	close(recCh)
+
+	if n := failed.Load(); n > 0 {
+		t.Fatalf("%d 次 Put 失败", n)
+	}
+
+	var records []rec
+	for r := range recCh {
+		records = append(records, r)
+	}
+	if len(records) != workers*perWorker {
+		t.Fatalf("应有 %d 条记录，实际 %d", workers*perWorker, len(records))
+	}
+
+	// 逐条回读校验内容没串
+	for _, r := range records {
+		got, err := s.Get(r.digest)
+		if err != nil {
+			t.Fatalf("读 %s 失败: %v", shortDigest(r.digest), err)
+		}
+		if !bytes.Equal(got, r.data) {
+			t.Fatalf("内容串了: %s", shortDigest(r.digest))
+		}
+	}
+
+	st := s.Stats()
+	if st["count"].(int) != len(records) {
+		t.Fatalf("库内条目应为 %d，实际 %v", len(records), st["count"])
+	}
+}
+
+func TestStress_ConcurrentDeleteAndPut(t *testing.T) {
+	// 删除与写入并发：核心断言是被保留的内容永远可读，
+	// 删除只影响目标 digest，不误伤其他内容。
+	s := newTestStore(t)
+
+	const heldCount = 8
+	held := make([]string, heldCount)
+	for i := range held {
+		d, err := s.Put([]byte(fmt.Sprintf("payload-%d", i)), Item{MIME: "image/png"})
+		if err != nil {
+			t.Fatal(err)
+		}
+		held[i] = d
+	}
+
+	const workers = 16
+	const rounds = 30
+	var wg sync.WaitGroup
+	for w := 0; w < workers; w++ {
+		wg.Add(1)
+		go func(wid int) {
+			defer wg.Done()
+			for r := 0; r < rounds; r++ {
+				d, err := s.Put([]byte(fmt.Sprintf("tmp-%d-%d", wid, r)), Item{MIME: "image/png"})
+				if err != nil {
+					t.Errorf("Put: %v", err)
+					return
+				}
+				if err := s.Delete(d); err != nil {
+					t.Errorf("Delete: %v", err)
+					return
+				}
+			}
+		}(w)
+	}
+	// 并发读取被保留内容
+	for rdr := 0; rdr < 4; rdr++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for r := 0; r < rounds; r++ {
+				for i, d := range held {
+					if _, err := s.Get(d); err != nil {
+						t.Errorf("内容 %d 被误删: %v", i, err)
+						return
+					}
+				}
+			}
+		}()
+	}
+	wg.Wait()
+
+	for i, d := range held {
+		if _, err := s.Get(d); err != nil {
+			t.Fatalf("仍被保留的第 %d 项不可读: %v", i, err)
+		}
+	}
+}
+
+func TestStress_DeleteConcurrentWithReads(t *testing.T) {
+	// 删除与读取并发。最重要的断言：被保留的内容在整个过程中始终可读。
+	s := newTestStore(t)
+
+	const protectedCount = 10
+	protected := make([]string, protectedCount)
+	protectedData := make([][]byte, protectedCount)
+	for i := range protected {
+		data := append([]byte(fmt.Sprintf("protected-%d-", i)), randBytes(t, 256)...)
+		d, err := s.Put(data, Item{MIME: "image/png"})
+		if err != nil {
+			t.Fatal(err)
+		}
+		protected[i] = d
+		protectedData[i] = data
+	}
+
+	stop := make(chan struct{})
+	var wg sync.WaitGroup
+	var readErr atomic.Int64
+	var deleteCount atomic.Int64
+	var putCount atomic.Int64
+
+	// 写入者：持续 Put 一次性内容再删除（模拟块创建后又被遗忘）
+	for w := 0; w < 4; w++ {
+		wg.Add(1)
+		go func(wid int) {
+			defer wg.Done()
+			i := 0
+			for {
+				select {
+				case <-stop:
+					return
+				default:
+				}
+				data := append([]byte(fmt.Sprintf("ephemeral-%d-%d-", wid, i)), randBytes(t, 128)...)
+				d, err := s.Put(data, Item{MIME: "image/png"})
+				if err != nil {
+					continue
+				}
+				putCount.Add(1)
+				if err := s.Delete(d); err == nil {
+					deleteCount.Add(1)
+				}
+				i++
+			}
+		}(w)
+	}
+
+	// 读取者：反复读受保护内容，任何一次失败都是致命的
+	for r := 0; r < 4; r++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for {
+				select {
+				case <-stop:
+					return
+				default:
+				}
+				for i, d := range protected {
+					got, err := s.Get(d)
+					if err != nil {
+						readErr.Add(1)
+						t.Errorf("受保护内容读失败 %s: %v", shortDigest(d), err)
+						return
+					}
+					if !bytes.Equal(got, protectedData[i]) {
+						readErr.Add(1)
+						t.Errorf("受保护内容被改 %s", shortDigest(d))
+						return
+					}
+				}
+			}
+		}()
+	}
+
+	time.Sleep(1500 * time.Millisecond)
+	close(stop)
+	wg.Wait()
+
+	if n := readErr.Load(); n > 0 {
+		t.Fatalf("受保护内容读取失败 %d 次", n)
+	}
+	t.Logf("并发窗口内: Put=%d Delete=%d", putCount.Load(), deleteCount.Load())
+
+	// 收尾确认：受保护的一个都没少
+	for i, d := range protected {
+		got, err := s.Get(d)
+		if err != nil || !bytes.Equal(got, protectedData[i]) {
+			t.Fatalf("收尾检查失败 %s: %v", shortDigest(d), err)
+		}
+	}
+}
+
+func TestStress_SetVecConcurrentWithQuery(t *testing.T) {
+	// 嵌入写入与向量检索并发（启动时的向量迁移就会长期这样跑）。
+	s := newTestStore(t)
+	const n = 60
+	digests := make([]string, n)
+	for i := range digests {
+		d, err := s.Put([]byte(fmt.Sprintf("img-%d", i)), Item{MIME: "image/png"})
+		if err != nil {
+			t.Fatal(err)
+		}
+		digests[i] = d
+	}
+
+	var wg sync.WaitGroup
+	var writeErr, queryErr atomic.Int64
+
+	// 向量写入者
+	for w := 0; w < 4; w++ {
+		wg.Add(1)
+		go func(wid int) {
+			defer wg.Done()
+			for i := wid; i < n; i += 4 {
+				vec := []float64{1, float64(i) / 100, 0}
+				if err := s.SetVec(digests[i], vec, "space"); err != nil {
+					writeErr.Add(1)
+				}
+			}
+		}(w)
+	}
+
+	// 检索者
+	for r := 0; r < 3; r++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			for i := 0; i < 50; i++ {
+				if _, err := s.QueryMediaScored([]float64{1, 0, 0}, "space", 20); err != nil {
+					queryErr.Add(1)
+				}
+			}
+		}()
+	}
+	wg.Wait()
+
+	if v := writeErr.Load(); v > 0 {
+		t.Fatalf("SetVec 失败 %d 次", v)
+	}
+	if v := queryErr.Load(); v > 0 {
+		t.Fatalf("QueryMediaScored 失败 %d 次", v)
+	}
+
+	// 全部应已嵌入，且都在同一空间
+	stale, err := s.StaleVecDigestsAll("space")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(stale) != 0 {
+		t.Fatalf("应全部已嵌入，仍有 %d 条未嵌入", len(stale))
+	}
+	got, err := s.QueryMediaScored([]float64{1, 0, 0}, "space", 1000)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(got) != n {
+		t.Fatalf("应检索到 %d 条，实际 %d", n, len(got))
+	}
+}
+
+func TestStress_DeleteUnderLoad(t *testing.T) {
+	// 持续写入 + 删除下，被保留的项必须始终可读。
+	s := newTestStore(t)
+
+	const keepN = 3
+	keepList := make([]string, keepN)
+	for i := range keepList {
+		data := append([]byte(fmt.Sprintf("keep-%d-", i)), randBytes(t, 32*1024)...)
+		d, err := s.Put(data, Item{MIME: "image/png"})
+		if err != nil {
+			t.Fatal(err)
+		}
+		keepList[i] = d
+	}
+
+	for round := 0; round < 30; round++ {
+		for i := 0; i < 3; i++ {
+			data := append([]byte(fmt.Sprintf("tmp-%d-%d-", round, i)), randBytes(t, 16*1024)...)
+			d, err := s.Put(data, Item{MIME: "image/png"})
+			if err != nil {
+				t.Fatalf("round %d Put: %v", round, err)
+			}
+			if err := s.Delete(d); err != nil {
+				t.Fatalf("round %d Delete: %v", round, err)
+			}
+		}
+	}
+
+	// 被保留的项必须都在
+	for _, d := range keepList {
+		if _, err := s.Get(d); err != nil {
+			t.Fatalf("被保留项被误删 %s: %v", shortDigest(d), err)
+		}
+	}
+}
+
+func TestStress_ReopenAfterHeavyChurn(t *testing.T) {
+	// 大量写入 + 删除之后重开：元数据与磁盘不该出现互相不认的孤儿。
+	dir := t.TempDir()
+	s1, err := New(dir)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	var kept []string
+	for i := 0; i < 100; i++ {
+		data := append([]byte(fmt.Sprintf("churn-%d-", i)), randBytes(t, 256)...)
+		d, err := s1.Put(data, Item{MIME: "image/png"})
+		if err != nil {
+			t.Fatal(err)
+		}
+		if i%5 == 0 {
+			kept = append(kept, d)
+		} else if err := s1.Delete(d); err != nil {
+			t.Fatal(err)
+		}
+	}
+	beforeStats := s1.Stats()
+	s1.Close()
+
+	s2, err := New(dir)
+	if err != nil {
+		t.Fatalf("重开失败: %v", err)
+	}
+	defer s2.Close()
+
+	afterStats := s2.Stats()
+	if beforeStats["count"] != afterStats["count"] {
+		t.Fatalf("重开后条目数变了: %v → %v", beforeStats["count"], afterStats["count"])
+	}
+
+	// 每条元数据都应有对应磁盘文件（无「元数据在文件没了」的孤儿）
+	rows, err := s2.db.Query(`SELECT digest FROM media`)
+	if err != nil {
+		t.Fatal(err)
+	}
+	var missing int
+	for rows.Next() {
+		var d string
+		if rows.Scan(&d) != nil {
+			continue
+		}
+		if _, err := os.Stat(s2.blobPath(d)); err != nil {
+			missing++
+			if missing <= 3 {
+				t.Errorf("元数据存在但 blob 缺失: %s", shortDigest(d))
+			}
+		}
+	}
+	rows.Close()
+	if missing > 0 {
+		t.Fatalf("%d 条元数据没有对应文件", missing)
+	}
+
+	// 磁盘文件数应等于元数据条数（无「文件在元数据没了」的孤儿）
+	if n := blobFileCount(t, s2); n != afterStats["count"].(int) {
+		t.Fatalf("磁盘文件 %d 与元数据 %v 不一致", n, afterStats["count"])
+	}
+
+	for _, d := range kept {
+		if _, err := s2.Get(d); err != nil {
+			t.Fatalf("被持有项重开后读不到 %s: %v", shortDigest(d), err)
+		}
+	}
+}
+
+func TestStress_LargeBlob(t *testing.T) {
+	// 单个大文件：see_video 10 帧 × 2MB 是现实上限附近。
+	s := newTestStore(t, 0)
+	data := randBytes(t, 4*1024*1024) // 4MB
+
+	d, err := s.Put(data, Item{MIME: "image/jpeg", Width: 1920, Height: 1080})
+	if err != nil {
+		t.Fatalf("4MB Put 失败: %v", err)
+	}
+	got, err := s.Get(d)
+	if err != nil {
+		t.Fatalf("4MB Get 失败: %v", err)
+	}
+	if !bytes.Equal(got, data) {
+		t.Fatal("4MB 内容回读不一致")
+	}
+	it, _ := s.Stat(d)
+	if it.Size != int64(len(data)) {
+		t.Fatalf("Size 记录错: %d vs %d", it.Size, len(data))
+	}
+}
+
+func TestStress_DataURLRoundTripAtScale(t *testing.T) {
+	// data URL 往返是插件注入的实际路径（SetToolBlocks 给的就是 data URL）。
+	s := newTestStore(t, 0)
+	for i := 0; i < 50; i++ {
+		raw := randBytes(t, 2048)
+		url := DataURL("image/png", raw)
+		mime, decoded, ok := ParseDataURL(url)
+		if !ok {
+			t.Fatalf("第 %d 次解析失败", i)
+		}
+		if mime != "image/png" || !bytes.Equal(decoded, raw) {
+			t.Fatalf("第 %d 次往返不一致", i)
+		}
+		d, err := s.Put(decoded, Item{MIME: mime})
+		if err != nil {
+			t.Fatal(err)
+		}
+		back, err := s.Get(d)
+		if err != nil || !bytes.Equal(back, raw) {
+			t.Fatalf("第 %d 次入库回读不一致: %v", i, err)
+		}
+	}
+}

internal/memory/migrate.go

@@ -0,0 +1,193 @@
+package memory
+
+import (
+	"database/sql"
+	"encoding/json"
+	"fmt"
+	"regexp"
+	"strings"
+	"time"
+)
+
+// 旧媒体实体迁移。
+//
+// 历史上媒体进 L3 的方式是把正文 marker 反解成普通实体三元组：
+//
+//	[image/png a1b2c3d4e5f6] 一张紫蓝红三色带图
+//	  → 实体「图片 a1b2c3d4e5f6」(type=Media) -内容-> 「一张紫蓝红三色带图」
+//
+// 这条路径把「媒体」伪装成实体 + 用生成的描述文本当语义索引，正是要废弃的
+// 将就机制。迁移做的事：把每条这类实体还原成原生记忆块，用
+// sentence --contains--> block 结构边挂到它当时所属的句子上，
+// 然后删掉旧实体与它的描述关系。块只按自己的向量被检索。
+//
+// 迁移是幂等的：实体处理完即删除，重复运行不会重复建块。
+
+// legacyMediaDigestPattern 从旧媒体实体名尾部取出短 digest。
+// 名字形如「图片 a1b2c3d4e5f6」——旧实现刻意为每种模态加中文前缀。
+var legacyMediaDigestPattern = regexp.MustCompile(`([0-9a-f]{8,64})$`)
+
+// LegacyMediaEntityDigest 从旧媒体实体名里取出短 digest，取不到返回空串。
+func LegacyMediaEntityDigest(name string) string {
+	name = strings.TrimSpace(name)
+	if !strings.Contains(name, " ") {
+		return ""
+	}
+	m := legacyMediaDigestPattern.FindStringSubmatch(name)
+	if m == nil {
+		return ""
+	}
+	return m[1]
+}
+
+// LegacyMediaResolver 把一个短 digest 解析成可用于 L3 的一等记忆块。
+// 解析失败（内容已不存在）返回 false，该实体将被直接删除而不建块。
+type LegacyMediaResolver func(shortDigest string) (MemoryBlock, bool)
+
+// MigrateLegacyMediaEntities 把 marker 反解出来的旧媒体实体迁移成原生块。
+//
+// 返回迁移的块数与删除的旧实体数。任何一步失败都会回滚整个迁移，
+// 因为半途中断会留下既没有块也没有实体的句子——信息静默消失。
+func (g *GraphDB) MigrateLegacyMediaEntities(resolve LegacyMediaResolver) (blocks, entities int, err error) {
+	if resolve == nil {
+		return 0, 0, nil
+	}
+	g.mu.Lock()
+	defer g.mu.Unlock()
+
+	rows, err := g.db.Query(`SELECT id, name FROM entities WHERE type = 'Media'`)
+	if err != nil {
+		return 0, 0, err
+	}
+	type legacyEntity struct {
+		id   int64
+		name string
+	}
+	var legacy []legacyEntity
+	for rows.Next() {
+		var e legacyEntity
+		if err := rows.Scan(&e.id, &e.name); err != nil {
+			rows.Close()
+			return 0, 0, err
+		}
+		legacy = append(legacy, e)
+	}
+	if err := rows.Err(); err != nil {
+		rows.Close()
+		return 0, 0, err
+	}
+	rows.Close()
+	if len(legacy) == 0 {
+		return 0, 0, nil
+	}
+
+	tx, err := g.db.Begin()
+	if err != nil {
+		return 0, 0, err
+	}
+	defer tx.Rollback()
+
+	// 同一份字节可能被多个旧实体引用（重复注入的同一张图），
+	// 迁移后应指向同一个块：块的身份是内容，不是实体行。
+	blockIDForDigest := make(map[string]string)
+
+	for _, e := range legacy {
+		short := LegacyMediaEntityDigest(e.name)
+		if short != "" {
+			if block, ok := resolve(short); ok && block.PayloadDigest != "" {
+				id, seen := blockIDForDigest[block.PayloadDigest]
+				if !seen {
+					if err := insertMigratedBlock(tx, block); err != nil {
+						return 0, 0, fmt.Errorf("migrate legacy media %s: %w", short, err)
+					}
+					blockIDForDigest[block.PayloadDigest] = block.ID
+					id = block.ID
+					blocks++
+				}
+				n, err := attachBlockToLegacySentences(tx, e.id, id)
+				if err != nil {
+					return 0, 0, err
+				}
+				_ = n
+			}
+		}
+		// 无论能否解析出内容，旧实体与它的描述关系都必须删除：
+		// 留着就等于继续用描述文本当媒体索引。
+		if _, err := tx.Exec(`DELETE FROM relations WHERE source_id = ? OR target_id = ?`, e.id, e.id); err != nil {
+			return 0, 0, err
+		}
+		if _, err := tx.Exec(`DELETE FROM entities WHERE id = ?`, e.id); err != nil {
+			return 0, 0, err
+		}
+		entities++
+	}
+
+	if err := tx.Commit(); err != nil {
+		return 0, 0, err
+	}
+	return blocks, entities, nil
+}
+
+// insertMigratedBlock 写一条迁移来的块（不经过 PutMemoryBlocks，避免重入锁）。
+func insertMigratedBlock(tx *sql.Tx, block MemoryBlock) error {
+	if block.ID == "" {
+		return fmt.Errorf("migrated block id is required")
+	}
+	if !validBlockModality(block.Modality) {
+		return fmt.Errorf("migrated block %s has invalid modality %q", block.ID, block.Modality)
+	}
+	vectorJSON, err := json.Marshal(block.Vector)
+	if err != nil {
+		return err
+	}
+	created := block.CreatedAt
+	if created.IsZero() {
+		created = time.Now()
+	}
+	_, err = tx.Exec(`INSERT INTO memory_blocks (
+		id, modality, text_content, payload_digest, mime, size, width, height,
+		vector, fingerprint, source, tool, created_at, updated_at
+	) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	ON CONFLICT(id) DO NOTHING`,
+		block.ID, block.Modality, block.Text, block.PayloadDigest, block.MIME,
+		block.Size, block.Width, block.Height, string(vectorJSON), block.Fingerprint,
+		block.Source, block.Tool, created, time.Now())
+	return err
+}
+
+// attachBlockToLegacySentences 把迁移出的块挂到该旧实体当时所属的句子上，
+// 并保留那些句子（它们可能只有媒体关系，删实体后就再无关系引用）。
+func attachBlockToLegacySentences(tx *sql.Tx, entityID int64, blockID string) (int, error) {
+	rows, err := tx.Query(`SELECT DISTINCT s.id FROM sentences s
+		JOIN relations r ON r.sentence_id = s.id
+		WHERE r.source_id = ? OR r.target_id = ?`, entityID, entityID)
+	if err != nil {
+		return 0, err
+	}
+	var sids []int64
+	for rows.Next() {
+		var sid int64
+		if err := rows.Scan(&sid); err != nil {
+			rows.Close()
+			return 0, err
+		}
+		sids = append(sids, sid)
+	}
+	if err := rows.Err(); err != nil {
+		rows.Close()
+		return 0, err
+	}
+	rows.Close()
+
+	n := 0
+	for _, sid := range sids {
+		if _, err := tx.Exec(`INSERT OR IGNORE INTO memory_block_edges
+			(source_kind, source_id, target_kind, target_id, edge_type)
+			VALUES ('sentence', ?, 'block', ?, 'contains')`,
+			fmt.Sprintf("%d", sid), blockID); err != nil {
+			return n, err
+		}
+		n++
+	}
+	return n, nil
+}

internal/memory/static_embedder.go

@@ -14,8 +14,8 @@ import (
 	"sync"
 	"unicode/utf8"
 
-	"github.com/yanyiwu/gojieba"
 	"gitcode.com/JianFeeeee/HomeAgent/internal/memory/vector"
+	"github.com/yanyiwu/gojieba"
 )
 
 const downloadMaxWords = 200000
@@ -391,6 +391,13 @@ func (e *StaticEmbedder) Vectorize(text string) vector.Vector {
 	return vec
 }
 
+// EmbedImage 返回 ErrNotSupported：fastText 是纯文本词向量模型，
+// 没有视觉编码器。要用图像嵌入需要外部视觉模型（如 CLIP/MobileCLIP），
+// 那个由 config 里的 EmbeddingModelPath 指定的视觉模型负责。
+func (e *StaticEmbedder) EmbedImage(img []byte, mime string) (vector.Vector, error) {
+	return nil, vector.ErrNotSupported
+}
+
 func (e *StaticEmbedder) Dim() int {
 	e.mu.RLock()
 	defer e.mu.RUnlock()

internal/memory/static_embedder_test.go

@@ -108,7 +108,7 @@ func TestStaticEmbedderSemanticSimilarity(t *testing.T) {
 	e := newSynthEmbedder(t, 300)
 
 	pairs := []struct {
-		a, b  string
+		a, b    string
 		related bool
 	}{
 		{"今天天气怎么样", "明天会不会下雨", true},

internal/memory/vector/fuse.go

@@ -0,0 +1,51 @@
+package vector
+
+import "math"
+
+// FuseVectors 把同一统一空间里的多个向量融合为一个向量：
+// 逐维求和后重新 L2 归一化。
+//
+// 用途：文档/上下文事件既带文本、又带若干一等记忆块（图片/视频），
+// 二者的向量来自同一模型、同一 fingerprint、同一维度。融合后，
+// 一篇文档既能按文字、也能按它携带的图片内容被召回——
+// 图片由自己的向量参与检索，不依赖任何生成的描述文本。
+//
+// 约定：调用方传入的向量应已是 L2 归一化的同空间向量。长度不一致的
+// 向量会被跳过（不同模型/维度的残留）；全空或全零返回 nil。
+func FuseVectors(vectors ...[]float64) []float64 {
+	dim := 0
+	for _, v := range vectors {
+		if len(v) > dim {
+			dim = len(v)
+		}
+	}
+	if dim == 0 {
+		return nil
+	}
+	out := make([]float64, dim)
+	used := 0
+	for _, v := range vectors {
+		if len(v) != dim {
+			continue
+		}
+		for i, x := range v {
+			out[i] += x
+		}
+		used++
+	}
+	if used == 0 {
+		return nil
+	}
+	var norm float64
+	for _, x := range out {
+		norm += x * x
+	}
+	if norm == 0 {
+		return nil
+	}
+	norm = math.Sqrt(norm)
+	for i := range out {
+		out[i] /= norm
+	}
+	return out
+}

internal/memory/vector/http_embedder.go

@@ -0,0 +1,194 @@
+package vector
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+
+	"gitcode.com/JianFeeeee/HomeAgent/pkg/embedding"
+)
+
+func init() {
+	// http 也是一个普通 provider：核心只按名字打开它，不知道它背后是云 API、
+	// 自建服务还是别的语言写的模型。
+	embedding.Register("http", func(cfg embedding.Config) (embedding.Provider, error) {
+		return NewHTTPEmbedder(HTTPEmbedderConfig{
+			Endpoint:    cfg.Options["endpoint"],
+			APIKey:      cfg.Options["api_key"],
+			Model:       cfg.Options["model"],
+			Fingerprint: cfg.Options["fingerprint"],
+			Dimension:   atoiOrZero(cfg.Options["dimension"]),
+			Timeout:     durationOrZero(cfg.Options["timeout"]),
+		})
+	})
+}
+
+func atoiOrZero(s string) int {
+	n := 0
+	for _, r := range strings.TrimSpace(s) {
+		if r < '0' || r > '9' {
+			return 0
+		}
+		n = n*10 + int(r-'0')
+	}
+	return n
+}
+
+func durationOrZero(s string) time.Duration {
+	d, err := time.ParseDuration(strings.TrimSpace(s))
+	if err != nil {
+		return 0
+	}
+	return d
+}
+
+// HTTPEmbedderConfig 配置一个外部多模态向量服务。
+// 服务契约刻意很小：POST Endpoint，输入 modality/data/mime/side，返回 embedding。
+// 任何云 API 或自建服务只需适配这一个协议，即可复用内核全部向量存储与检索链路。
+type HTTPEmbedderConfig struct {
+	Endpoint    string
+	APIKey      string
+	Model       string
+	Dimension   int
+	Timeout     time.Duration
+	Fingerprint string
+}
+
+// HTTPEmbedder 是 MultimodalEmbedder 的外部 API 实现。
+type HTTPEmbedder struct {
+	cfg    HTTPEmbedderConfig
+	client *http.Client
+	mu     sync.Mutex
+	closed bool
+}
+
+type httpEmbedRequest struct {
+	Model    string `json:"model,omitempty"`
+	Modality string `json:"modality"`
+	Side     string `json:"side"`
+	Text     string `json:"text,omitempty"`
+	Data     string `json:"data,omitempty"`
+	MIME     string `json:"mime,omitempty"`
+}
+
+type httpEmbedResponse struct {
+	Embedding []float64 `json:"embedding"`
+	Data      []struct {
+		Embedding []float64 `json:"embedding"`
+	} `json:"data,omitempty"`
+}
+
+func NewHTTPEmbedder(cfg HTTPEmbedderConfig) (*HTTPEmbedder, error) {
+	if strings.TrimSpace(cfg.Endpoint) == "" {
+		return nil, fmt.Errorf("vector: empty HTTP embedding endpoint")
+	}
+	if cfg.Dimension <= 0 {
+		return nil, fmt.Errorf("vector: invalid HTTP embedding dimension %d", cfg.Dimension)
+	}
+	if cfg.Timeout <= 0 {
+		cfg.Timeout = 30 * time.Second
+	}
+	if cfg.Fingerprint == "" {
+		cfg.Fingerprint = "http:" + cfg.Model + fmt.Sprintf(":%d", cfg.Dimension)
+	}
+	return &HTTPEmbedder{cfg: cfg, client: &http.Client{Timeout: cfg.Timeout}}, nil
+}
+
+func (e *HTTPEmbedder) VectorizeDense(text string) ([]float64, error) {
+	return e.embed(context.Background(), httpEmbedRequest{Model: e.cfg.Model, Modality: string(ModalityText), Side: "query", Text: text})
+}
+
+func (e *HTTPEmbedder) EmbedImageDense(img []byte, mime string) ([]float64, error) {
+	return e.embed(context.Background(), httpEmbedRequest{Model: e.cfg.Model, Modality: string(ModalityImage), Side: "document", Data: base64.StdEncoding.EncodeToString(img), MIME: mime})
+}
+
+func (e *HTTPEmbedder) embed(ctx context.Context, payload httpEmbedRequest) ([]float64, error) {
+	e.mu.Lock()
+	closed := e.closed
+	e.mu.Unlock()
+	if closed {
+		return nil, fmt.Errorf("vector: HTTP embedder closed")
+	}
+	body, err := json.Marshal(payload)
+	if err != nil {
+		return nil, err
+	}
+	req, err := http.NewRequestWithContext(ctx, http.MethodPost, e.cfg.Endpoint, bytes.NewReader(body))
+	if err != nil {
+		return nil, err
+	}
+	req.Header.Set("Content-Type", "application/json")
+	if e.cfg.APIKey != "" {
+		req.Header.Set("Authorization", "Bearer "+e.cfg.APIKey)
+	}
+	resp, err := e.client.Do(req)
+	if err != nil {
+		return nil, fmt.Errorf("vector: HTTP embedding request: %w", err)
+	}
+	defer resp.Body.Close()
+	b, err := io.ReadAll(io.LimitReader(resp.Body, 4<<20))
+	if err != nil {
+		return nil, err
+	}
+	if resp.StatusCode < 200 || resp.StatusCode >= 300 {
+		return nil, fmt.Errorf("vector: HTTP embedding status %d: %s", resp.StatusCode, strings.TrimSpace(string(b)))
+	}
+	var out httpEmbedResponse
+	if err := json.Unmarshal(b, &out); err != nil {
+		return nil, fmt.Errorf("vector: decode HTTP embedding: %w", err)
+	}
+	v := out.Embedding
+	if len(v) == 0 && len(out.Data) > 0 {
+		v = out.Data[0].Embedding
+	}
+	if len(v) != e.cfg.Dimension {
+		return nil, fmt.Errorf("vector: HTTP embedding dimension %d, want %d", len(v), e.cfg.Dimension)
+	}
+	return v, nil
+}
+
+func (e *HTTPEmbedder) Fingerprint() string { return e.cfg.Fingerprint }
+func (e *HTTPEmbedder) Dim() int            { return e.cfg.Dimension }
+
+// Embed 实现公共 provider 契约：核心只传模态与不透明字节，本实现负责把它
+// 翻译成外部服务的协议。
+func (e *HTTPEmbedder) Embed(ctx context.Context, in embedding.Input) ([]float64, error) {
+	req := httpEmbedRequest{
+		Model:    e.cfg.Model,
+		Modality: string(in.Modality),
+		Side:     string(in.Purpose),
+		Text:     in.Text,
+		MIME:     in.MIME,
+	}
+	if in.Modality != embedding.ModalityText {
+		req.Data = base64.StdEncoding.EncodeToString(in.Data)
+	}
+	return e.embed(ctx, req)
+}
+
+// Info 声明本 provider 的向量空间身份。外部服务的支持模态无法在本地探测，
+// 因此只声明 text/image 这两条内核真正会走到的路径。
+func (e *HTTPEmbedder) Info() embedding.Info {
+	return embedding.Info{
+		Dimension:   e.cfg.Dimension,
+		Fingerprint: e.cfg.Fingerprint,
+		Modalities:  []embedding.Modality{embedding.ModalityText, embedding.ModalityImage},
+	}
+}
+func (e *HTTPEmbedder) Loaded() bool {
+	e.mu.Lock()
+	defer e.mu.Unlock()
+	return !e.closed
+}
+func (e *HTTPEmbedder) Close() {
+	e.mu.Lock()
+	e.closed = true
+	e.mu.Unlock()
+}

internal/memory/vector/http_embedder_test.go

@@ -0,0 +1,178 @@
+package vector
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"testing"
+)
+
+func TestHTTPEmbedder_RequiresEndpoint(t *testing.T) {
+	_, err := NewHTTPEmbedder(HTTPEmbedderConfig{Dimension: 512})
+	if err == nil {
+		t.Fatal("应拒绝空 endpoint")
+	}
+}
+
+func TestHTTPEmbedder_RequiresDimension(t *testing.T) {
+	_, err := NewHTTPEmbedder(HTTPEmbedderConfig{Endpoint: "http://localhost"})
+	if err == nil {
+		t.Fatal("应拒绝 dimension<=0")
+	}
+}
+
+func TestHTTPEmbedder_TextEmbedding(t *testing.T) {
+	// 模拟返回 4 维向量的外部服务
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		if r.Method != http.MethodPost {
+			t.Errorf("期望 POST，实际 %s", r.Method)
+		}
+		var req httpEmbedRequest
+		if err := json.NewDecoder(r.Body).Decode(&req); err != nil {
+			t.Fatal(err)
+		}
+		if req.Modality != "text" {
+			t.Errorf("期望 modality=text，实际 %s", req.Modality)
+		}
+		if req.Text == "" {
+			t.Fatal("text 不应为空")
+		}
+		w.Header().Set("Content-Type", "application/json")
+		w.Write([]byte(`{"embedding":[0.1,0.2,0.3,0.4]}`))
+	}))
+	defer srv.Close()
+
+	e, err := NewHTTPEmbedder(HTTPEmbedderConfig{
+		Endpoint:  srv.URL,
+		Dimension: 4,
+		Model:     "test-model",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer e.Close()
+
+	if !e.Loaded() {
+		t.Fatal("应处于 loaded 状态")
+	}
+
+	vec, err := e.VectorizeDense("hello world")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(vec) != 4 || vec[0] != 0.1 || vec[3] != 0.4 {
+		t.Errorf("向量不符合预期: %v", vec)
+	}
+	if e.Fingerprint() != "http:test-model:4" {
+		t.Errorf("指纹不符合预期: %s", e.Fingerprint())
+	}
+}
+
+func TestHTTPEmbedder_ImageEmbedding(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		var req httpEmbedRequest
+		json.NewDecoder(r.Body).Decode(&req)
+		if req.Modality != "image" {
+			t.Errorf("期望 modality=image，实际 %s", req.Modality)
+		}
+		if req.MIME != "image/png" {
+			t.Errorf("期望 mime=image/png，实际 %s", req.MIME)
+		}
+		w.Write([]byte(`{"embedding":[0.5,0.5,0.5]}`))
+	}))
+	defer srv.Close()
+
+	e, err := NewHTTPEmbedder(HTTPEmbedderConfig{
+		Endpoint:  srv.URL,
+		Dimension: 3,
+		Model:     "img-model",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer e.Close()
+
+	vec, err := e.EmbedImageDense([]byte("fake-png-data"), "image/png")
+	if err != nil {
+		t.Fatal(err)
+	}
+	if len(vec) != 3 {
+		t.Errorf("期望 3 维，实际 %d", len(vec))
+	}
+}
+
+func TestHTTPEmbedder_CustomFingerprint(t *testing.T) {
+	e, err := NewHTTPEmbedder(HTTPEmbedderConfig{
+		Endpoint:    "http://localhost:1234",
+		Dimension:   512,
+		Fingerprint: "jina-v5-omni-nano:2026",
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer e.Close()
+	if e.Fingerprint() != "jina-v5-omni-nano:2026" {
+		t.Errorf("自定义指纹未生效: %s", e.Fingerprint())
+	}
+}
+
+func TestHTTPEmbedder_DimensionMismatchReturnsError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.Write([]byte(`{"embedding":[1,2]}`)) // 返回 2 维，配置期望 4
+	}))
+	defer srv.Close()
+
+	e, err := NewHTTPEmbedder(HTTPEmbedderConfig{
+		Endpoint:  srv.URL,
+		Dimension: 4,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer e.Close()
+
+	_, err = e.VectorizeDense("test")
+	if err == nil {
+		t.Fatal("维度不匹配时应返回错误")
+	}
+}
+
+func TestHTTPEmbedder_ServerErrorReturnsError(t *testing.T) {
+	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		w.WriteHeader(http.StatusBadGateway)
+		w.Write([]byte("gateway down"))
+	}))
+	defer srv.Close()
+
+	e, err := NewHTTPEmbedder(HTTPEmbedderConfig{
+		Endpoint:  srv.URL,
+		Dimension: 4,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer e.Close()
+
+	_, err = e.VectorizeDense("test")
+	if err == nil {
+		t.Fatal("服务端错误时应返回错误")
+	}
+}
+
+func TestHTTPEmbedder_ClosePreventsFurtherCalls(t *testing.T) {
+	e, err := NewHTTPEmbedder(HTTPEmbedderConfig{
+		Endpoint:  "http://localhost:1234",
+		Dimension: 4,
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	e.Close()
+	if e.Loaded() {
+		t.Fatal("关闭后 Loaded() 应返回 false")
+	}
+	_, err = e.VectorizeDense("test")
+	if err == nil {
+		t.Fatal("关闭后应返回错误")
+	}
+}

internal/memory/vector/provider_adapter.go

@@ -0,0 +1,83 @@
+package vector
+
+import (
+	"context"
+	"sync"
+
+	"gitcode.com/JianFeeeee/HomeAgent/pkg/embedding"
+)
+
+// ProviderAdapter translates the public model-neutral embedding.Provider SPI
+// to the small internal interface used by the existing memory consumers.
+// Model selection, media decoding, preprocessing, and runtime details remain
+// entirely inside the selected provider.
+type ProviderAdapter struct {
+	provider embedding.Provider
+	info     embedding.Info
+
+	mu     sync.RWMutex
+	closed bool
+}
+
+// AdaptProvider validates and wraps a public provider for internal memory use.
+func AdaptProvider(provider embedding.Provider) (*ProviderAdapter, error) {
+	info := provider.Info()
+	if err := embedding.ValidateInfo(info); err != nil {
+		return nil, err
+	}
+	return &ProviderAdapter{provider: provider, info: info}, nil
+}
+
+func (a *ProviderAdapter) VectorizeDense(text string) ([]float64, error) {
+	return a.embed(embedding.Input{
+		Modality: embedding.ModalityText,
+		Purpose:  embedding.PurposeQuery,
+		Text:     text,
+	})
+}
+
+func (a *ProviderAdapter) EmbedImageDense(data []byte, mime string) ([]float64, error) {
+	return a.embed(embedding.Input{
+		Modality: embedding.ModalityImage,
+		Purpose:  embedding.PurposeDocument,
+		Data:     data,
+		MIME:     mime,
+	})
+}
+
+func (a *ProviderAdapter) embed(input embedding.Input) ([]float64, error) {
+	a.mu.RLock()
+	closed := a.closed
+	a.mu.RUnlock()
+	if closed {
+		return nil, context.Canceled
+	}
+	vec, err := a.provider.Embed(context.Background(), input)
+	if err != nil {
+		return nil, err
+	}
+	if err := embedding.ValidateVector(vec, a.info.Dimension); err != nil {
+		return nil, err
+	}
+	return vec, nil
+}
+
+func (a *ProviderAdapter) Fingerprint() string { return a.info.Fingerprint }
+func (a *ProviderAdapter) Dim() int            { return a.info.Dimension }
+
+func (a *ProviderAdapter) Loaded() bool {
+	a.mu.RLock()
+	defer a.mu.RUnlock()
+	return !a.closed
+}
+
+func (a *ProviderAdapter) Close() {
+	a.mu.Lock()
+	if a.closed {
+		a.mu.Unlock()
+		return
+	}
+	a.closed = true
+	a.mu.Unlock()
+	a.provider.Close()
+}

internal/memory/vector/provider_adapter_test.go

@@ -0,0 +1,115 @@
+package vector
+
+import (
+	"context"
+	"errors"
+	"testing"
+
+	"gitcode.com/JianFeeeee/HomeAgent/pkg/embedding"
+)
+
+// recordingProvider 记录核心传给 provider 的原始请求，用来断言
+// 「核心不解释内容、只搬字节」这一契约。
+type recordingProvider struct {
+	got    []embedding.Input
+	dim    int
+	closed bool
+}
+
+func (p *recordingProvider) Embed(_ context.Context, in embedding.Input) ([]float64, error) {
+	p.got = append(p.got, in)
+	return make([]float64, p.dim), nil
+}
+
+func (p *recordingProvider) Info() embedding.Info {
+	return embedding.Info{Dimension: p.dim, Fingerprint: "recording:1"}
+}
+
+func (p *recordingProvider) Close() { p.closed = true }
+
+func TestProviderAdapterPassesOpaqueDataUnchanged(t *testing.T) {
+	inner := &recordingProvider{dim: 3}
+	adapted, err := AdaptProvider(inner)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer adapted.Close()
+
+	// 核心把媒体当作不透明字节搬运：既不解码也不改字节。
+	raw := []byte{0x89, 'P', 'N', 'G', 0x00, 0xff}
+	if _, err := adapted.EmbedImageDense(raw, "image/png"); err != nil {
+		t.Fatal(err)
+	}
+	got := inner.got[0]
+	if string(got.Data) != string(raw) {
+		t.Fatalf("provider 收到的字节被改动: %v", got.Data)
+	}
+	if got.Modality != embedding.ModalityImage || got.MIME != "image/png" {
+		t.Fatalf("模态/MIME 未原样传递: %+v", got)
+	}
+	if got.Purpose != embedding.PurposeDocument {
+		t.Fatalf("用途应为 document: %q", got.Purpose)
+	}
+
+	if _, err := adapted.VectorizeDense("hello"); err != nil {
+		t.Fatal(err)
+	}
+	if inner.got[1].Modality != embedding.ModalityText || inner.got[1].Text != "hello" {
+		t.Fatalf("文本请求不正确: %+v", inner.got[1])
+	}
+}
+
+func TestProviderAdapterRejectsWrongDimensionFromProvider(t *testing.T) {
+	// provider 声明 3 维却返回 2 维：必须在进入存储前被拦下，
+	// 否则一个维度错的向量会污染整个余弦检索。
+	bad := &badDimProvider{}
+	adapted, err := AdaptProvider(bad)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer adapted.Close()
+	if _, err := adapted.VectorizeDense("x"); err == nil {
+		t.Fatal("维度不符时应返回错误")
+	}
+}
+
+type badDimProvider struct{}
+
+func (badDimProvider) Embed(context.Context, embedding.Input) ([]float64, error) {
+	return []float64{1, 2}, nil
+}
+func (badDimProvider) Info() embedding.Info {
+	return embedding.Info{Dimension: 3, Fingerprint: "bad:1"}
+}
+func (badDimProvider) Close() {}
+
+func TestProviderAdapterCloseIsIdempotentAndStopsUse(t *testing.T) {
+	inner := &recordingProvider{dim: 2}
+	adapted, err := AdaptProvider(inner)
+	if err != nil {
+		t.Fatal(err)
+	}
+	adapted.Close()
+	adapted.Close() // 重复关闭不应 panic 或二次 Close provider
+	if !inner.closed {
+		t.Fatal("Close 未传递到 provider")
+	}
+	if _, err := adapted.VectorizeDense("x"); err == nil {
+		t.Fatal("关闭后应拒绝调用")
+	}
+	if adapted.Loaded() {
+		t.Fatal("关闭后 Loaded() 应为 false")
+	}
+}
+
+func TestModalityUnsupportedSentinelIsShared(t *testing.T) {
+	// 内核侧的哨兵与公共契约的哨兵必须是同一个：provider 返回公共哨兵时，
+	// 内核仍能用自己原有的名字识别。
+	if !errors.Is(ErrModalityUnsupported, embedding.ErrUnsupportedModality) {
+		t.Fatal("vector.ErrModalityUnsupported 与 embedding.ErrUnsupportedModality 未打通")
+	}
+	wrapped := errors.Join(embedding.ErrUnsupportedModality, errors.New("audio/wav"))
+	if !errors.Is(wrapped, ErrModalityUnsupported) {
+		t.Fatal("包装后的错误无法用内核哨兵识别")
+	}
+}

internal/memory/vector/store.go

@@ -1,17 +1,73 @@
 package vector
 
 import (
+	"fmt"
 	"math"
 	"sort"
 	"strings"
 	"sync"
+
+	"gitcode.com/JianFeeeee/HomeAgent/pkg/embedding"
 )
 
 // Vectorizer 接口：将文本转为向量
+//
+// 多模态嵌入新增可选的 EmbedImage：支持视觉嵌入的实现者覆写此方法，
+// 不支持的（TF-IDF 等）在默认实现里返回 ErrNotSupported。
 type Vectorizer interface {
 	Vectorize(text string) Vector
+	EmbedImage(img []byte, mime string) (Vector, error)
 }
 
+// MultimodalEmbedder 是稠密多模态编码器的接口。
+//
+// 与 Vectorizer（稀疏词向量，供 TF-IDF/倒排检索）刻意区分：多模态模型产出的
+// 是共享稠密空间，直接用于 media.Store 的稠密余弦检索，
+// **不得**塞进文档/知识层的稀疏 vector.Store（会破坏倒排剪枝与 TF-IDF 语义）。
+//
+// 实现不限：可以是内嵌 ONNX，也可以是外部 HTTP 向量服务——
+// 内核只依赖本接口，两条路径共享同一套检索/存储基础设施。Fingerprint 是模型
+// 空间标识（如模型文件指纹），作为 vec_model 持久化用于切换后重算。
+type MultimodalEmbedder interface {
+	VectorizeDense(text string) ([]float64, error)
+	EmbedImageDense(img []byte, mime string) ([]float64, error)
+	Fingerprint() string
+	Dim() int
+	Loaded() bool
+	Close()
+}
+
+// MultimodalModality 是统一向量空间支持的输入模态。
+// 现内核只消费 text/image；外部 API 路径可能扩展 audio/video，
+// 通过类型断言在接口外按需扩展，不破坏现有契约。
+type MultimodalModality string
+
+const (
+	ModalityText  MultimodalModality = "text"
+	ModalityImage MultimodalModality = "image"
+	ModalityAudio MultimodalModality = "audio"
+	ModalityVideo MultimodalModality = "video"
+)
+
+// ErrNotSupported 表示 Vectorizer 不支持该原生模态；调用方不得以描述文本冒充其向量。
+var ErrNotSupported = fmt.Errorf("vectorizer does not support image embedding")
+
+// ErrModalityUnsupported 表示该模态不在本统一向量空间的原生覆盖范围内。
+//
+// 它与普通错误语义不同：调用方应把它当作「这条媒体本空间永远不会有向量」
+// 而不是「这次失败了、下次重试」。绝不能拿另一个模型的向量顶替——那会把
+// 两套坐标系混进同一空间，检索出来的相似度没有任何意义。
+//
+// 它是公共 provider 契约里那个哨兵值的别名，两者 errors.Is 互通：
+// provider 在自己的包内返回 embedding.ErrUnsupportedModality 即可，
+// 内核侧的判断无需改变。
+var ErrModalityUnsupported = embedding.ErrUnsupportedModality
+
+// 注：曾经这里还有一个可选的 VideoEmbedder 接口（用类型断言探测视频能力）。
+// 已删除：那让核心为每一个新模态长出一套模型专属方法，正是“核心适配模型”的
+// 坏味道。模态能力现在是数据（embedding.Info.Modalities），输入是不透明的
+// Data+MIME（见 pkg/embedding）。
+
 // Vector 是带权特征映射：feature → weight
 type Vector map[string]float64
 
@@ -61,6 +117,26 @@ func (s *Store) Remove(id string) {
 }
 
 func (s *Store) Search(query Vector, topK int) []DocVector {
+	hits := s.SearchScored(query, topK)
+	if len(hits) == 0 {
+		return nil
+	}
+	out := make([]DocVector, len(hits))
+	for i, h := range hits {
+		out[i] = h.Doc
+	}
+	return out
+}
+
+// DocVectorHit 是一篇文档的相似度候选及其原始 cosine 分数。
+// 跨模态融合需要分数做归一化；纯排序的 Search 不暴露它。
+type DocVectorHit struct {
+	Doc   DocVector
+	Score float64
+}
+
+// SearchScored 与 Search 同语义，但返回带原始 cosine 分数的候选。
+func (s *Store) SearchScored(query Vector, topK int) []DocVectorHit {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
 
@@ -100,9 +176,9 @@ func (s *Store) Search(query Vector, topK int) []DocVector {
 		results = results[:topK]
 	}
 
-	out := make([]DocVector, len(results))
+	out := make([]DocVectorHit, len(results))
 	for i, r := range results {
-		out[i] = r.doc
+		out[i] = DocVectorHit{Doc: r.doc, Score: r.score}
 	}
 	return out
 }
@@ -246,9 +322,24 @@ func CosineSimilarity(a, b Vector) float64 {
 	return dot / (math.Sqrt(normA) * math.Sqrt(normB))
 }
 
+// DenseCosine 计算两个 []float64 稠密向量的余弦相似度。
+// 与 CosineSimilarity（稀疏 map）数学等价，但面向稠密多模态向量。
+func DenseCosine(a, b []float64) float64 {
+	var dot, na, nb float64
+	for i := range a {
+		dot += a[i] * b[i]
+		na += a[i] * a[i]
+		nb += b[i] * b[i]
+	}
+	if na == 0 || nb == 0 {
+		return 0
+	}
+	return dot / math.Sqrt(na*nb)
+}
+
 // InvertedIndex 倒排索引，加速向量搜索
 type InvertedIndex struct {
-	mu     sync.RWMutex
+	mu       sync.RWMutex
 	postings map[string]map[string]float64 // feature → {docID: weight}
 }
 

internal/meta/meta.go

@@ -10,10 +10,21 @@ var (
 	// 1.0.0：外部插件从 C ABI 动态库迁到子进程 + 共享内存。
 	// 这是首个不再加载 `.so`/`.dll` 的版本，与 0.9.x 不兼容（存量插件必须
 	// 用新版 plugindev 重编），故跃到主版本号。
+	// 1.1.0：记忆系统支持二进制多媒体节点——CAS 媒体存储 + L0/L2/L3 贯通。
+	// 1.1.1：多模态贯通**插件边界**。内核实现公开 SDK 1.1.0 新增的媒体接口
+	//        （doc.insertWithMedia、io.injectMedia / injectMediaSync /
+	//        injectInterruptMedia），并把 text/image/audio 三条输入路径归一成
+	//        一条 processInput 主干。
+	// 1.2.0：模型中立的多模态 provider SPI（pkg/embedding）——内核不再适配任何
+	//        具体模型，Qwen 实现移到 providers/qwen3vl；插件运行协议升到 2
+	//        （统一共享内存区，fd3 布局改变，不支持滚动升级）；并实现 SDK 1.2.0
+	//        新增的注入行为标志位（InjectOptions：no_memory / context_policy）
+	//        与 ChannelDef.ContextPolicy，使输入/排队注入/中断注入/同步注入都能
+	//        声明「是否记入记忆」与「是否据此裁剪上下文」（默认都是否）。
 	//
-	// 1.0.1：多模态修复。仅内核与内置插件改动，插件 ABI/协议未变，
-	// 1.0.0 编出的 plugin.bin 无需重编。
-	Version = "1.0.3"
+	// ❗main 上此值始终是**下一个未发布中版本**，不随 patch 发布变动
+	//（见 docs/git-branching.md §2.1）；已发布的版本号看对应的 release/vX.Y.x 与 tag。
+	Version = "1.2.0"
 
 	// Commit 是构建时的 Git commit hash。
 	Commit = "unknown"
@@ -25,7 +36,26 @@ var (
 	KernelName = "HomeAgent"
 
 	// SDKCompatibleVersion 是此内核可兼容的最高 SDK 版本（semver）。
-	SDKCompatibleVersion = "1.0.0"
+	//
+	// 1.1.0：本内核实现了 SDK 1.1.0 的全部新增方法。
+	// 1.2.0：本内核实现了 SDK 1.2.0 的全部新增方法（IOInjector 的六个 *Opts
+	//        注入变体、InjectOptions、ChannelDef.ContextPolicy），因此声明为
+	//        1.2.0。用 SDK 1.0.0/1.1.0 编的存量插件照旧可用——新增方法由
+	//        **插件调用、内核实现**，不调就不受影响，无需重编。
+	SDKCompatibleVersion = "1.2.0"
+
+	// SourceURL 是本内核构建所对应的源码地址。
+	//
+	// AGPL-3.0 §13（Remote Network Interaction）要求：当你把修改过的版本
+	// 作为网络服务提供出去时，必须给使用者提供取得 Corresponding Source 的机会。
+	// WebUI 的状态页会把这个值渲染成可见链接，所以：
+	//
+	// ❗**修改后对外部署的分支必须把它改指向自己的源码仓库**，否则链接指向的
+	// 不是你实际运行的那份代码，§13 的提供义务并未履行。
+	//
+	// 构建时可用 -ldflags 覆盖，无需改源码：
+	//   -X gitcode.com/JianFeeeee/HomeAgent/internal/meta.SourceURL=<你的仓库>
+	SourceURL = "https://gitcode.com/JianFeeeee/HomeAgent"
 )
 
 // FullVersion 返回完整的版本字符串。

internal/nlp/onnx.go

@@ -49,9 +49,20 @@ func NewONNXParser(cfg ONNXConfig) (*ONNXParser, error) {
 		}
 	}
 
-	ort.SetSharedLibraryPath(libPath())
-	if err := ort.InitializeEnvironment(); err != nil {
-		return nil, fmt.Errorf("init onnx env: %w", err)
+	// ORT 环境是**进程级单例**，同一进程里可能有多个消费者（多模态向量
+	// provider、本依存解析器）。onnxruntime_go 的行为是：第二次
+	// InitializeEnvironment 报「already been initialized」，而
+	// DestroyEnvironment 会把别人正在用的环境一起拆掉——先初始化的 provider
+	// 会因此拿到失效的会话。所以这里只在未初始化时初始化，并且**永不销毁**
+	// （与 providers/chineseclip、providers/qwen3vl 的约定一致）：环境随进程存活。
+	//
+	// 这个缺陷是在「发行版默认带 onnxruntime 标签」后才暴露的：不带标签时
+	// 两个消费者不会同时存在，重复初始化与误销毁都无法发生。
+	if !ort.IsInitialized() {
+		ort.SetSharedLibraryPath(libPath())
+		if err := ort.InitializeEnvironment(); err != nil {
+			return nil, fmt.Errorf("init onnx env: %w", err)
+		}
 	}
 
 	inputNames := []string{"input_ids"}
@@ -59,7 +70,7 @@ func NewONNXParser(cfg ONNXConfig) (*ONNXParser, error) {
 
 	session, err := ort.NewDynamicAdvancedSession(modelPath, inputNames, outputNames, nil)
 	if err != nil {
-		ort.DestroyEnvironment()
+		// 不在这里 DestroyEnvironment：环境是进程级的，可能正被多模态 provider 使用。
 		return nil, fmt.Errorf("create session: %w", err)
 	}
 
@@ -73,7 +84,7 @@ func NewONNXParser(cfg ONNXConfig) (*ONNXParser, error) {
 func (p *ONNXParser) Close() error {
 	p.close.Do(func() {
 		p.rt.Destroy()
-		ort.DestroyEnvironment()
+		// 不销毁进程级 ORT 环境：多模态 provider 可能仍在使用（见 NewONNXParser）。
 	})
 	return nil
 }

internal/plugin/evtring_test.go

@@ -34,6 +34,9 @@ func TestEventRing_BasicWriteAndConsume(t *testing.T) {
 		},
 	)
 	go consumer.Run()
+	// LIFO：先 Stop（打断阻塞的 Read）再 Wait（等 Run 退出），
+	// 两者都必须在 host.Close（munmap 整个区域）之前完成。
+	defer consumer.Wait()
 	defer consumer.Stop()
 
 	// 订阅 agent_output 事件
@@ -85,11 +88,18 @@ func TestEventRing_OverflowStillDelivers(t *testing.T) {
 		host.EvtfdReadFile(),
 		0,
 		func(evt *pubsdk.Event) error {
-			received <- evt
+			// 非阻塞投递：本用例写入了 8292 条事件，若这里阻塞在
+			// channel 上，drainEvents 会卡在 handler 里，Stop 就无法
+			// 让 Run 退出。
+			select {
+			case received <- evt:
+			default:
+			}
 			return nil
 		},
 	)
 	go consumer.Run()
+	defer consumer.Wait()
 	defer consumer.Stop()
 
 	select {
@@ -125,6 +135,7 @@ func TestEventRing_TypeMaskFiltering(t *testing.T) {
 		},
 	)
 	go consumer.Run()
+	defer consumer.Wait()
 	defer consumer.Stop()
 
 	unsub := er.Subscribe(pubsdk.EventToolCall)

internal/plugin/proc/arena.go

@@ -0,0 +1,538 @@
+package proc
+
+// Exchange Arena：**内核独占管理**的跨进程共享内存块分配器（§13.2 重设计）。
+//
+// ── 所有权模型（架构约束）────────────────────────────────────────────
+//
+//	共享内存由内核全权管理。插件需要使用共享内存时，通过 syscall 风格的
+//	RPC 向内核申请，内核返回偏移与大小；使用完毕后插件再通知内核回收。
+//
+//	因此分配器只存在于**内核进程内**，用一把普通 sync.Mutex 保护即可：
+//	不需要任何跨进程原子操作，也不存在"共享游标被两个进程各自更新"这一
+//	类竞态——这正是前几版（bump 游标 / CAS 位图跨进程分配）失败的根本原因。
+//
+//	共享内存是**内部实现**，不对插件开发者暴露：插件的公开 API 仍是
+//	普通字符串/Map（见 SDK 的 IOInjector / ToolHandler）。模板运行时在
+//	传输层完成全部搬运，开发者无感。
+//
+// ── 为什么是变长块而不是定长槽 ──────────────────────────────────────
+//
+//	定长槽唯一的理由是"跨进程无法安全地做变长分配"。分配器收回内核后这个
+//	约束消失，于是可以采用真正的变长块分配（first-fit + 邻块合并）：
+//
+//	  - 内核可以按需**标定**每块大小（funccall 帧模型）而不是一律给固定槽
+//	  - 大 payload（文件内容、长工具输出）不再受 16KB 槽容量限制
+//	  - 块用尽时插件才请求扩容，而不是事先把池铺满
+//
+// ── 布局 ──────────────────────────────────────────────────────────
+//
+//	┌──────────────────────────────────────────────┐
+//	│ Arena Header 64B                             │
+//	│   magic / version / capacity / blockBase     │
+//	├──────────────────────────────────────────────┤
+//	│ Block 0: [size | state | owner | prevSize]   │
+//	│          [data ...]                          │
+//	│ Block 1: ...                                 │
+//	│ Block N-1: ...（最后一块的 size 到 arena 末尾）│
+//	└──────────────────────────────────────────────┘
+//
+//	块头 16B，size 含头并按 8 字节对齐，因此所有数据起点都是 8 字节对齐的。
+//	prevSize 让 Free 能 O(1) 找到前驱做向后合并（经典分离/合并做法）。
+//
+// ── 安全边界 ──────────────────────────────────────────────────────
+//
+//	插件归还/读取时提交的是 SharedRef（offset 由插件转述）。内核必须把它
+//	当成不可信输入：Free 会重新走一遍块链确认 offset 确实是一个已分配块的
+//	数据起点、owner 匹配，才改动分配器状态；否则伪造的 offset 会直接破坏
+//	块链。Read 同理。
+//
+// ── 惰性物理内存 ──────────────────────────────────────────────────
+//
+//	arena 很大（MB 级）但底层是 memfd：**未触碰的页不占物理内存**。所以
+//	把容量开大不会带来常驻内存开销，只是虚拟地址空间。
+
+import (
+	"fmt"
+	"sync"
+)
+
+const (
+	arenaMagic   uint32 = 0x41524E41 // "ARNA"
+	arenaVersion uint32 = 2          // v2：定长槽 → 变长块
+
+	arenaHeaderSize = 64
+
+	// Arena Header 字段偏移（相对 arena 起始）。
+	arOffMagic     = 0
+	arOffVersion   = 4
+	arOffCapacity  = 8  // arena 可用字节数
+	arOffBlockBase = 12 // 首个块相对 arena 起始的偏移
+	arOffBlockUsed = 16 // 已分配的数据字节数（诊断）
+	arOffReserved  = 20
+
+	// 块头 16B：size 含头，按 8 字节对齐。
+	blockHeaderSize  = 16
+	blockOffSize     = 0  // uint32 总大小（含头）
+	blockOffState    = 4  // uint32 0=free 1=used
+	blockOffOwner    = 8  // uint32 所有者
+	blockOffPrevSize = 12 // uint32 前一块总大小（0=无前块）
+
+	blockFree uint32 = 0
+	blockUsed uint32 = 1
+
+	// minBlockSize 是拆分后允许的最小块（含头）。低于它就不再拆，
+	// 避免产生一堆无法再利用的碎片。
+	minBlockSize = 32
+
+	// SharedRef.Flags 语义位。
+	sharedRefFlagJSON   = 1 << 0 // 载荷是 JSON（工具参数/结果）
+	sharedRefFlagExpand = 1 << 1 // 引用指向插件申请的扩容块（内核需单独归还）
+
+	// OwnerHost 标记由内核分配的块。插件用 Host.NextOwnerID 分配的值。
+	OwnerHost uint32 = 0
+)
+
+// arenaDefaultCapacity 是统一区域里预留给 arena 的字节数。
+//
+// 取 4MB：memfd 惰性分配，未触碰的页不占物理内存，所以开大无成本；
+// 但它让单个工具调用可以承载 MB 级 payload，不必再退回内联 RPC。
+const arenaDefaultCapacity = 4 * 1024 * 1024
+
+// arenaPublishSize 是统一区域里预留给 arena 的字节数。
+var arenaPublishSize = uint32(arenaDefaultCapacity)
+
+// arenaRegion 是块分配器视图。
+//
+// region 始终是**完整**统一区域 mmap：SharedRef.Offset 是相对区域起始的
+// 绝对偏移，因此读写都直接落在 region 上。
+//
+// mu 只在**内核进程内**使用——分配器完全由内核持有（见文件头所有权模型）。
+type arenaRegion struct {
+	mu sync.Mutex
+
+	region []byte
+	base   uint32 // arena 在 region 内的起始偏移
+	cap    uint32 // arena 可用字节数
+}
+
+// arenaMinSize 返回块分配器能工作的最小字节数。
+func arenaMinSize() uint32 {
+	return arenaHeaderSize + blockHeaderSize + minBlockSize
+}
+
+// align8 把 n 向上取整到 8 的倍数（块大小与数据起点都必须 8 字节对齐）。
+func align8(n uint32) uint32 { return (n + 7) &^ 7 }
+
+// initArena 在统一区域的 arena 段上初始化块分配器。
+func initArena(region []byte, base, size uint32) (*arenaRegion, error) {
+	if size < arenaMinSize() {
+		return nil, fmt.Errorf("arena: 段太小（%d 字节，至少需要 %d）", size, arenaMinSize())
+	}
+	if uint64(base)+uint64(size) > uint64(len(region)) {
+		return nil, fmt.Errorf("arena: 越出映射（base=%d size=%d total=%d）", base, size, len(region))
+	}
+
+	a := &arenaRegion{region: region, base: base, cap: size}
+
+	blockBase := align8(arenaHeaderSize)
+	if blockBase+blockHeaderSize+minBlockSize > size {
+		return nil, fmt.Errorf("arena: 头部过大（blockBase=%d size=%d）", blockBase, size)
+	}
+
+	ap := region[base : base+size]
+	putU32(ap[arOffMagic:], arenaMagic)
+	putU32(ap[arOffVersion:], arenaVersion)
+	putU32(ap[arOffCapacity:], size)
+	putU32(ap[arOffBlockBase:], blockBase)
+	putU32(ap[arOffBlockUsed:], 0)
+
+	// 初始状态：一整块 free 覆盖剩余空间。
+	first := blockBase
+	putU32(ap[first+blockOffSize:], size-first)
+	putU32(ap[first+blockOffState:], blockFree)
+	putU32(ap[first+blockOffOwner:], OwnerHost)
+	putU32(ap[first+blockOffPrevSize:], 0)
+
+	return a, nil
+}
+
+// attachArena 从已初始化的区域解析分配器（诊断用）。
+func attachArena(region []byte, base, size uint32) (*arenaRegion, error) {
+	if size < arenaHeaderSize {
+		return nil, fmt.Errorf("arena: 段太小（%d）", size)
+	}
+	if uint64(base)+uint64(arenaHeaderSize) > uint64(len(region)) {
+		return nil, fmt.Errorf("arena: 头部越界（base=%d total=%d）", base, len(region))
+	}
+	ap := region[base : base+size]
+
+	if got := getU32(ap[arOffMagic:]); got != arenaMagic {
+		return nil, fmt.Errorf("arena: 魔数不匹配（0x%x）", got)
+	}
+	if got := getU32(ap[arOffVersion:]); got != arenaVersion {
+		return nil, fmt.Errorf("arena: 版本不匹配（%d，期望 %d）", got, arenaVersion)
+	}
+	capacity := getU32(ap[arOffCapacity:])
+	blockBase := getU32(ap[arOffBlockBase:])
+	if capacity != size {
+		return nil, fmt.Errorf("arena: capacity 不匹配（header=%d mapped=%d）", capacity, size)
+	}
+	if blockBase+blockHeaderSize > size {
+		return nil, fmt.Errorf("arena: blockBase 越界（%d，size=%d）", blockBase, size)
+	}
+	return &arenaRegion{region: region, base: base, cap: size}, nil
+}
+
+// MaxPayload 返回单次分配可承载的最大 payload 字节数（上界）。
+func (a *arenaRegion) MaxPayload() int {
+	return int(a.cap) - arenaHeaderSize - blockHeaderSize
+}
+
+// Capacity 返回 arena 总字节数。
+func (a *arenaRegion) Capacity() uint32 { return a.cap }
+
+// ---- 块头访问（相对 region 的绝对偏移）----
+
+func (a *arenaRegion) blockBase() uint32 {
+	return a.base + getU32(a.region[a.base+arOffBlockBase:])
+}
+
+func (a *arenaRegion) blockEnd() uint32 { return a.base + a.cap }
+
+func (a *arenaRegion) blockSize(off uint32) uint32 {
+	return getU32(a.region[off+blockOffSize:])
+}
+
+func (a *arenaRegion) setBlockSize(off, v uint32) {
+	putU32(a.region[off+blockOffSize:], v)
+}
+
+func (a *arenaRegion) blockState(off uint32) uint32 {
+	return getU32(a.region[off+blockOffState:])
+}
+
+func (a *arenaRegion) setBlockState(off, v uint32) {
+	putU32(a.region[off+blockOffState:], v)
+}
+
+func (a *arenaRegion) blockOwner(off uint32) uint32 {
+	return getU32(a.region[off+blockOffOwner:])
+}
+
+func (a *arenaRegion) setBlockOwner(off, v uint32) {
+	putU32(a.region[off+blockOffOwner:], v)
+}
+
+func (a *arenaRegion) blockPrevSize(off uint32) uint32 {
+	return getU32(a.region[off+blockOffPrevSize:])
+}
+
+func (a *arenaRegion) setBlockPrevSize(off, v uint32) {
+	putU32(a.region[off+blockOffPrevSize:], v)
+}
+
+// blockDataOff 返回块数据区起点（SharedRef.Offset 即此值）。
+func (a *arenaRegion) blockDataOff(off uint32) uint32 { return off + blockHeaderSize }
+
+// nextBlock 返回下一块偏移；到末尾返回 blockEnd()。
+func (a *arenaRegion) nextBlock(off uint32) uint32 {
+	sz := a.blockSize(off)
+	if sz < blockHeaderSize {
+		return a.blockEnd() // 块链损坏：交给 walk 的步数上限兜底
+	}
+	next := off + sz
+	if next > a.blockEnd() {
+		return a.blockEnd()
+	}
+	return next
+}
+
+// DataOffsetOf 返回块偏移对应的数据起点（诊断/测试用）。
+func (a *arenaRegion) DataOffsetOf(off uint32) uint32 { return a.blockDataOff(off) }
+
+// Alloc 分配一块至少 n 字节的块，owner 写入块头。
+//
+// first-fit：从首个块开始找第一个容量足够的空闲块。分配器由内核独占，
+// 因此这里的线性扫描不需要任何跨进程同步。
+func (a *arenaRegion) Alloc(owner uint32, n int, gen uint64) (SharedRef, error) {
+	if n < 0 {
+		return SharedRef{}, fmt.Errorf("arena: 非法长度 %d", n)
+	}
+	need := align8(uint32(n) + blockHeaderSize)
+	if need > a.cap-blockHeaderSize {
+		return SharedRef{}, fmt.Errorf("arena: 请求 %d 字节超出 arena 容量 %d", n, a.MaxPayload())
+	}
+
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	for off := a.blockBase(); off < a.blockEnd(); {
+		sz := a.blockSize(off)
+		if sz < blockHeaderSize {
+			return SharedRef{}, fmt.Errorf("arena: 块链损坏（off=%d size=%d）", off, sz)
+		}
+		if a.blockState(off) == blockFree && sz >= need {
+			a.carveLocked(off, need)
+			a.setBlockState(off, blockUsed)
+			a.setBlockOwner(off, owner)
+			a.accountUsed(int32(align8(uint32(n))))
+			return a.refOf(off, n, gen), nil
+		}
+		off = a.nextBlock(off)
+	}
+	return SharedRef{}, fmt.Errorf("arena: 空间不足（请求 %d 字节，容量 %d）", n, a.MaxPayload())
+}
+
+// carveLocked 把 off 处的空闲块劈成「已用 need + 剩余空闲」，并把剩余块
+// 的头与后继块的 prevSize 维护好。
+func (a *arenaRegion) carveLocked(off, need uint32) {
+	sz := a.blockSize(off)
+	if sz-need < minBlockSize {
+		return // 剩余太小，整块给出去，不拆
+	}
+	rest := off + need
+	restSize := sz - need
+	a.setBlockSize(rest, restSize)
+	a.setBlockState(rest, blockFree)
+	a.setBlockOwner(rest, OwnerHost)
+	a.setBlockPrevSize(rest, need)
+	a.setBlockSize(off, need)
+
+	// rest 的后继块现在以 rest 为前驱
+	if nxt := rest + restSize; nxt < a.blockEnd() {
+		a.setBlockPrevSize(nxt, restSize)
+	}
+}
+
+// refOf 由块偏移构造引用。
+func (a *arenaRegion) refOf(off uint32, n int, gen uint64) SharedRef {
+	return SharedRef{
+		Offset:     a.blockDataOff(off),
+		Length:     uint32(n),
+		Generation: uint32(gen),
+	}
+}
+
+// Put 分配并写入 payload。
+func (a *arenaRegion) Put(owner uint32, payload []byte, gen uint64) (SharedRef, error) {
+	ref, err := a.Alloc(owner, len(payload), gen)
+	if err != nil {
+		return SharedRef{}, err
+	}
+	copy(a.region[ref.Offset:ref.Offset+ref.Length], payload)
+	return ref, nil
+}
+
+// findBlockByData 在块链上找到数据起点等于 dataOff 的块。
+//
+// 这是对**插件提交的不可信 offset** 的校验入口：只有真的走完块链确认
+// 该 offset 是一个块的数据起点，才允许后续改动分配器状态。
+func (a *arenaRegion) findBlockByData(dataOff uint32) (uint32, bool) {
+	steps := 0
+	limit := int(a.cap/minBlockSize) + 4
+	for off := a.blockBase(); off < a.blockEnd(); {
+		if steps++; steps > limit {
+			return 0, false // 链损坏，防死循环
+		}
+		sz := a.blockSize(off)
+		if sz < blockHeaderSize || off+sz > a.blockEnd() {
+			return 0, false
+		}
+		if a.blockDataOff(off) == dataOff {
+			return off, true
+		}
+		off += sz
+	}
+	return 0, false
+}
+
+// findBlockContaining 找到数据区包含 off 的块。
+//
+// 与 findBlockByData 的区别：后者要求 off 恰好是块数据起点（用于 Free），
+// 前者允许 off 落在块数据区的任意位置（用于 Read：调用帧内的结果区就
+// 位于帧块中间，而不是块起点）。
+func (a *arenaRegion) findBlockContaining(off uint32) (uint32, bool) {
+	steps := 0
+	limit := int(a.cap/minBlockSize) + 4
+	for bo := a.blockBase(); bo < a.blockEnd(); {
+		if steps++; steps > limit {
+			return 0, false
+		}
+		sz := a.blockSize(bo)
+		if sz < blockHeaderSize || bo+sz > a.blockEnd() {
+			return 0, false
+		}
+		if off >= a.blockDataOff(bo) && off < bo+sz {
+			return bo, true
+		}
+		bo += sz
+	}
+	return 0, false
+}
+
+// Read 按 SharedRef 读取数据。
+//
+// 校验：generation 与当前区域一致、offset 落在某个**已分配**块的数据区内、
+// 引用不跨越块边界。任一不满足都返回 error（而不是 nil——早期版本返回
+// nil 让调用方分不清“空数据”和“非法引用”）。
+//
+// 允许 offset 不必是块起点：调用帧的结果区就在帧块内部。
+func (a *arenaRegion) Read(ref SharedRef, gen uint64) ([]byte, error) {
+	if ref.IsZero() {
+		return nil, nil
+	}
+	if ref.Generation != uint32(gen) {
+		return nil, fmt.Errorf("arena: 引用 generation 过期（ref=%d now=%d）", ref.Generation, gen)
+	}
+	if uint64(ref.Offset)+uint64(ref.Length) > uint64(len(a.region)) {
+		return nil, fmt.Errorf("arena: 引用越界（offset=%d len=%d total=%d）",
+			ref.Offset, ref.Length, len(a.region))
+	}
+
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	bo, ok := a.findBlockContaining(ref.Offset)
+	if !ok {
+		return nil, fmt.Errorf("arena: 非法引用（offset=%d 不在任何块的数据区）", ref.Offset)
+	}
+	if a.blockState(bo) != blockUsed {
+		return nil, fmt.Errorf("arena: 块（offset=%d）已释放，引用失效", ref.Offset)
+	}
+	if uint64(ref.Offset)+uint64(ref.Length) > uint64(bo+a.blockSize(bo)) {
+		return nil, fmt.Errorf("arena: 引用跨越块边界（offset=%d len=%d blockEnd=%d）",
+			ref.Offset, ref.Length, bo+a.blockSize(bo))
+	}
+	return a.region[ref.Offset : ref.Offset+ref.Length], nil
+}
+
+// Free 归还 owner 名下的块，并与相邻空闲块合并。
+//
+// 会走块链校验 offset 与 owner：伪造引用不能改动分配器状态。
+func (a *arenaRegion) Free(owner uint32, ref SharedRef) error {
+	if ref.IsZero() {
+		return nil
+	}
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	off, ok := a.findBlockByData(ref.Offset)
+	if !ok {
+		return fmt.Errorf("arena: 非法引用（offset=%d 不是块数据起点）", ref.Offset)
+	}
+	if a.blockState(off) != blockUsed {
+		return fmt.Errorf("arena: 块（offset=%d）未分配（重复归还？）", ref.Offset)
+	}
+	if got := a.blockOwner(off); got != owner {
+		return fmt.Errorf("arena: 块（offset=%d）不属于调用者（owner=%d caller=%d）", ref.Offset, got, owner)
+	}
+
+	a.setBlockState(off, blockFree)
+	a.setBlockOwner(off, OwnerHost)
+	a.accountUsed(-int32(align8(ref.Length)))
+	a.coalesceLocked(off)
+	return nil
+}
+
+// coalesceLocked 向后、向前合并相邻空闲块，并修正后继块的 prevSize。
+func (a *arenaRegion) coalesceLocked(off uint32) {
+	// 向后合并
+	for {
+		nxt := a.nextBlock(off)
+		if nxt >= a.blockEnd() || a.blockState(nxt) != blockFree {
+			break
+		}
+		a.setBlockSize(off, a.blockSize(off)+a.blockSize(nxt))
+	}
+	// 向前合并
+	if ps := a.blockPrevSize(off); ps > 0 && off > a.blockBase() {
+		prev := off - ps
+		if prev >= a.blockBase() && a.blockState(prev) == blockFree {
+			a.setBlockSize(prev, a.blockSize(prev)+a.blockSize(off))
+			off = prev
+		}
+	}
+	// 后继块的 prevSize 现在应等于合并后本块的大小
+	if nxt := a.nextBlock(off); nxt < a.blockEnd() {
+		a.setBlockPrevSize(nxt, a.blockSize(off))
+	}
+}
+
+// ReclaimOwner 归还 owner 名下所有块，返回回收块数。
+//
+// 用于插件进程退出：崩溃的插件无法归还自己申请的块，若不管会把 arena
+// 慢慢耗尽，最终让所有走共享内存的调用退化成内联 RPC。
+func (a *arenaRegion) ReclaimOwner(owner uint32) int {
+	if owner == OwnerHost {
+		return 0 // 内核自己的块由正常路径归还，不在此回收
+	}
+	a.mu.Lock()
+	defer a.mu.Unlock()
+
+	// 先收集偏移再逐个归还：归还过程中会做合并，边遍历边改块链不可靠。
+	var targets []uint32
+	var reclaimedBytes uint32
+	limit := int(a.cap/minBlockSize) + 4
+	steps := 0
+	for off := a.blockBase(); off < a.blockEnd(); {
+		if steps++; steps > limit {
+			break
+		}
+		sz := a.blockSize(off)
+		if sz < blockHeaderSize || off+sz > a.blockEnd() {
+			break
+		}
+		if a.blockState(off) == blockUsed && a.blockOwner(off) == owner {
+			targets = append(targets, off)
+		}
+		off += sz
+	}
+
+	for _, off := range targets {
+		if a.blockState(off) != blockUsed {
+			continue // 已被前面的合并吸收
+		}
+		if a.blockOwner(off) != owner {
+			continue
+		}
+		reclaimedBytes += a.blockSize(off) - blockHeaderSize
+		a.setBlockState(off, blockFree)
+		a.setBlockOwner(off, OwnerHost)
+		a.coalesceLocked(off)
+	}
+	if reclaimedBytes > 0 {
+		a.accountUsed(-int32(align8(reclaimedBytes)))
+	}
+	return len(targets)
+}
+
+// Stats 返回 (已用数据字节, 总字节)。已用字节按 8 字节对齐记账。
+func (a *arenaRegion) Stats() (used, total uint32) {
+	return getU32(a.region[a.base+arOffBlockUsed:]), a.cap
+}
+
+// accountUsed 累加/扣减已用字节（相对量，正数表示分配）。
+func (a *arenaRegion) accountUsed(delta int32) {
+	off := a.base + arOffBlockUsed
+	cur := int32(getU32(a.region[off:]))
+	next := cur + delta
+	if next < 0 {
+		next = 0
+	}
+	putU32(a.region[off:], uint32(next))
+}
+
+// BlockCount 返回块链上的块数（诊断/测试用）。
+func (a *arenaRegion) BlockCount() int {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	n, limit := 0, int(a.cap/minBlockSize)+4
+	for off := a.blockBase(); off < a.blockEnd() && n < limit; n++ {
+		sz := a.blockSize(off)
+		if sz < blockHeaderSize {
+			break
+		}
+		off += sz
+	}
+	return n
+}

internal/plugin/proc/arena_test.go

@@ -0,0 +1,307 @@
+package proc
+
+import (
+	"bytes"
+	"sync"
+	"testing"
+)
+
+// newTestArena 构造一个独立块分配器（不经 Host），保持单测快速。
+func newTestArena(t *testing.T, size uint32) *arenaRegion {
+	t.Helper()
+	const base = 64 // 8 字节对齐
+	region := make([]byte, base+size)
+	a, err := initArena(region, base, size)
+	if err != nil {
+		t.Fatalf("initArena: %v", err)
+	}
+	return a
+}
+
+func TestArena_AllocFreeRoundTrip(t *testing.T) {
+	a := newTestArena(t, 8*1024)
+	if used, total := a.Stats(); used != 0 || total != 8*1024 {
+		t.Fatalf("初始 Stats: got (%d,%d), want (0,%d)", used, total, 8*1024)
+	}
+
+	ref, err := a.Put(OwnerHost, []byte("hello"), 0)
+	if err != nil {
+		t.Fatalf("Put: %v", err)
+	}
+	if used, _ := a.Stats(); used == 0 {
+		t.Fatal("Put 后 used 应大于 0")
+	}
+	got, err := a.Read(ref, 0)
+	if err != nil {
+		t.Fatalf("Read: %v", err)
+	}
+	if string(got) != "hello" {
+		t.Fatalf("Read=%q, want hello", got)
+	}
+
+	if err := a.Free(OwnerHost, ref); err != nil {
+		t.Fatalf("Free: %v", err)
+	}
+	if used, _ := a.Stats(); used != 0 {
+		t.Fatalf("Free 后 used=%d, want 0", used)
+	}
+	// 归还后再读必须失败（块已回收）
+	if _, err := a.Read(ref, 0); err == nil {
+		t.Fatal("已释放块的引用应读取失败")
+	}
+}
+
+func TestArena_ConcurrentAllocUnique(t *testing.T) {
+	const workers = 64
+	a := newTestArena(t, 256*1024)
+
+	refs := make(chan SharedRef, workers)
+	var wg sync.WaitGroup
+	for i := 0; i < workers; i++ {
+		wg.Add(1)
+		go func() {
+			defer wg.Done()
+			ref, err := a.Alloc(OwnerHost, 1024, 0)
+			if err != nil {
+				t.Errorf("Alloc: %v", err)
+				return
+			}
+			refs <- ref
+		}()
+	}
+	wg.Wait()
+	close(refs)
+
+	seen := make(map[uint32]bool, workers)
+	for ref := range refs {
+		if seen[ref.Offset] {
+			t.Fatalf("并发分配拿到重复 offset=%d", ref.Offset)
+		}
+		seen[ref.Offset] = true
+	}
+	if len(seen) != workers {
+		t.Fatalf("唯一块数=%d, want %d", len(seen), workers)
+	}
+}
+
+func TestArena_ExhaustionReturnsError(t *testing.T) {
+	a := newTestArena(t, 4*1024)
+	// 第一次分配吃掉几乎整块
+	if _, err := a.Alloc(OwnerHost, 3*1024, 0); err != nil {
+		t.Fatalf("首次 Alloc: %v", err)
+	}
+	// 再申请一大块必然失败
+	if _, err := a.Alloc(OwnerHost, 3*1024, 0); err == nil {
+		t.Fatal("空间不足时 Alloc 应返回错误")
+	}
+}
+
+func TestArena_RejectsOversizePayload(t *testing.T) {
+	a := newTestArena(t, 4*1024)
+	if _, err := a.Alloc(OwnerHost, a.MaxPayload()+1, 0); err == nil {
+		t.Fatal("超出 arena 容量的请求应被拒绝")
+	}
+}
+
+func TestArena_FreeEnforcesOwnership(t *testing.T) {
+	a := newTestArena(t, 8*1024)
+	const ownerA, ownerB = 7, 9
+
+	refA, err := a.Alloc(ownerA, 128, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	// 另一个插件不能释放 A 的块
+	if err := a.Free(ownerB, refA); err == nil {
+		t.Fatal("跨 owner 归还应被拒绝")
+	}
+	if used, _ := a.Stats(); used == 0 {
+		t.Fatal("拒绝归还后块应仍然占用")
+	}
+	// 正确的 owner 可以归还
+	if err := a.Free(ownerA, refA); err != nil {
+		t.Fatalf("同 owner 归还: %v", err)
+	}
+}
+
+func TestArena_FreeRejectsForgedOffset(t *testing.T) {
+	a := newTestArena(t, 8*1024)
+	ref, err := a.Alloc(OwnerHost, 256, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// 未对齐到块数据起点的 offset 必须被拒绝——否则会直接破坏块链。
+	forged := ref
+	forged.Offset += 8
+	if err := a.Free(OwnerHost, forged); err == nil {
+		t.Fatal("伪造 offset 应被拒绝")
+	}
+	// 合法引用仍能正常归还（分配器状态未被破坏）
+	if err := a.Free(OwnerHost, ref); err != nil {
+		t.Fatalf("合法引用不应受影响: %v", err)
+	}
+	if used, _ := a.Stats(); used != 0 {
+		t.Fatalf("归还后 used=%d, want 0", used)
+	}
+}
+
+func TestArena_ReclaimOwnerReleasesOnlyItsBlocks(t *testing.T) {
+	a := newTestArena(t, 64*1024)
+	const ownerA, ownerB = 7, 9
+
+	for i := 0; i < 3; i++ {
+		if _, err := a.Alloc(ownerA, 1024, 0); err != nil {
+			t.Fatal(err)
+		}
+	}
+	for i := 0; i < 2; i++ {
+		if _, err := a.Alloc(ownerB, 1024, 0); err != nil {
+			t.Fatal(err)
+		}
+	}
+	if n := a.ReclaimOwner(ownerA); n != 3 {
+		t.Fatalf("ReclaimOwner(A)=%d, want 3", n)
+	}
+	// B 的两块必须保留：仍能读回
+	if n := a.ReclaimOwner(ownerB); n != 2 {
+		t.Fatalf("ReclaimOwner(B)=%d, want 2（A 的回收不能误伤 B）", n)
+	}
+	if used, _ := a.Stats(); used != 0 {
+		t.Fatalf("全部回收后 used=%d, want 0", used)
+	}
+}
+
+func TestArena_ReclaimHostIsNoop(t *testing.T) {
+	a := newTestArena(t, 4*1024)
+	if _, err := a.Alloc(OwnerHost, 128, 0); err != nil {
+		t.Fatal(err)
+	}
+	if n := a.ReclaimOwner(OwnerHost); n != 0 {
+		t.Fatalf("内核块不应被 ReclaimOwner 回收，实际回收 %d", n)
+	}
+	if used, _ := a.Stats(); used == 0 {
+		t.Fatal("used 应仍大于 0")
+	}
+}
+
+func TestArena_ReadRejectsInvalidRefs(t *testing.T) {
+	a := newTestArena(t, 8*1024)
+	ref, err := a.Put(OwnerHost, []byte("payload"), 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	// generation 过期
+	stale := ref
+	stale.Generation = 99
+	if _, err := a.Read(stale, 0); err == nil {
+		t.Fatal("generation 不匹配应被拒绝")
+	}
+
+	// offset 不是块数据起点
+	badOffset := ref
+	badOffset.Offset += 8
+	if _, err := a.Read(badOffset, 0); err == nil {
+		t.Fatal("offset 不是块数据起点应被拒绝")
+	}
+
+	// Length 超出块容量
+	tooLong := ref
+	tooLong.Length = 1 << 20
+	if _, err := a.Read(tooLong, 0); err == nil {
+		t.Fatal("Length 超容量应被拒绝")
+	}
+}
+
+func TestArena_PutReadLargePayload(t *testing.T) {
+	a := newTestArena(t, 512*1024)
+	payload := bytes.Repeat([]byte("abcdefgh"), 8192) // 64KB
+	ref, err := a.Put(OwnerHost, payload, 3)
+	if err != nil {
+		t.Fatalf("Put: %v", err)
+	}
+	got, err := a.Read(ref, 3)
+	if err != nil {
+		t.Fatalf("Read: %v", err)
+	}
+	if !bytes.Equal(got, payload) {
+		t.Fatalf("读回数据不一致：len(got)=%d len(want)=%d", len(got), len(payload))
+	}
+	// 大 payload 不能被 16KB 定长槽时代的容量假设卡住
+	if len(got) <= 16*1024 {
+		t.Fatalf("本用例应验证超过旧 16KB 槽容量的 payload，实际 %d", len(got))
+	}
+}
+
+func TestArena_FreeCoalescesAdjacentBlocks(t *testing.T) {
+	a := newTestArena(t, 64*1024)
+
+	refs := make([]SharedRef, 0, 8)
+	for i := 0; i < 8; i++ {
+		r, err := a.Alloc(OwnerHost, 4*1024, 0)
+		if err != nil {
+			t.Fatalf("第 %d 次 Alloc: %v", i, err)
+		}
+		refs = append(refs, r)
+	}
+	for _, r := range refs {
+		if err := a.Free(OwnerHost, r); err != nil {
+			t.Fatalf("Free: %v", err)
+		}
+	}
+
+	// 全部归还并合并后，应能再分配一个接近整块的大块。
+	big, err := a.Alloc(OwnerHost, 48*1024, 0)
+	if err != nil {
+		t.Fatalf("合并后应能分配大块: %v", err)
+	}
+	if err := a.Free(OwnerHost, big); err != nil {
+		t.Fatal(err)
+	}
+	if n := a.BlockCount(); n != 1 {
+		t.Fatalf("全部归还并合并后应只剩 1 块，实际 %d", n)
+	}
+}
+
+func TestArena_AttachRejectsCorruptLayout(t *testing.T) {
+	a := newTestArena(t, 4*1024)
+
+	putU32(a.region[a.base+arOffMagic:], 0xDEADBEEF)
+	if _, err := attachArena(a.region, a.base, a.cap); err == nil {
+		t.Fatal("魔数错误应被拒绝")
+	}
+	putU32(a.region[a.base+arOffMagic:], arenaMagic)
+
+	putU32(a.region[a.base+arOffVersion:], 99)
+	if _, err := attachArena(a.region, a.base, a.cap); err == nil {
+		t.Fatal("版本不匹配应被拒绝")
+	}
+	putU32(a.region[a.base+arOffVersion:], arenaVersion)
+
+	putU32(a.region[a.base+arOffCapacity:], 1<<30)
+	if _, err := attachArena(a.region, a.base, a.cap); err == nil {
+		t.Fatal("capacity 不匹配应被拒绝")
+	}
+}
+
+func TestArena_InitRejectsTooSmall(t *testing.T) {
+	const base = 64
+	region := make([]byte, base+arenaMinSize()-8)
+	if _, err := initArena(region, base, arenaMinSize()-8); err == nil {
+		t.Fatal("过小的段应被拒绝")
+	}
+}
+
+func TestArena_DataOffsetsAligned(t *testing.T) {
+	a := newTestArena(t, 64*1024)
+	for i, size := range []uint32{1, 7, 8, 9, 100, 4096} {
+		ref, err := a.Alloc(OwnerHost, int(size), 0)
+		if err != nil {
+			t.Fatalf("第 %d 次 Alloc(size=%d): %v", i, size, err)
+		}
+		if ref.Offset%8 != 0 {
+			t.Fatalf("size=%d 的数据起点 %d 未 8 字节对齐", size, ref.Offset)
+		}
+	}
+}

internal/plugin/proc/bench_test.go

@@ -4,6 +4,7 @@ import (
 	"os"
 	"os/exec"
 	"path/filepath"
+	"strings"
 	"testing"
 
 	pubsdk "gitcode.com/JianFeeeee/homeagent-sdk/sdk"
@@ -29,6 +30,18 @@ import (
 //	EvtRingWritePushConcurrent     83    ns/op    ← 并发不恶化
 //	StageInvokeSharedMemory       132    µs/op    ← 含 3 次进程间往返
 //	SegmentWriteAllReadInto         3.7  µs/op    ← 占 stage 的 2.8%
+//
+// Payload 承载方式对比（2026-09-10，同机；§13.3 取消按大小切内联后补测，
+// -count=3 取中位）：
+//
+//	payload      inline（RPC 报文）   frame（共享内存帧）   差
+//	16 B          26.4 µs/op           48.0 µs/op        +21.6 µs
+//	32 KiB       695.6 µs/op          391.7 µs/op       −303.9 µs
+//
+// 取舍随 payload 大小翻转：小 payload 多付 ~22µs 的帧分配/读写固定开销，
+// 大 payload 省掉整份 JSON 编解码与管道字节拷贝，快 44%。因为线上工具结果
+// 动辄几十 KB，且 22µs 相对 LLM 往返 2-8 秒可忽略，所以统一走帧而不是
+// 按大小分叉——分叉还多一条只在小 payload 上才跑的分支要维护。
 
 // buildBenchPlugin 编译 testdata 里的测试插件（benchmark 版）。
 func buildBenchPlugin(b *testing.B, srcName string) string {
@@ -46,11 +59,33 @@ func buildBenchPlugin(b *testing.B, srcName string) string {
 	return bin
 }
 
-// BenchmarkToolInvoke 测量内核 → 插件的工具调用往返。
+// BenchmarkToolInvoke 对比工具调用 payload 的两种承载方式（§13.3「延迟对比」）。
 //
-// 链路：Call 写 stdin → 插件读循环 → handler → 写 stdout →
-// 内核 readLoop → pending channel 唤醒。对照实验 11 的 19.6µs。
+//	inline — legacy 内联：参数 JSON 直接放进 RPC 报文
+//	frame  — 生产路径：内核 Alloc 帧，payload 全在共享内存，RPC 只传偏移描述符
+//
+// §13.3 取消了按大小切内联的分支，所以 frame 才是线上真实开销；inline 仅留给
+// 直连 RPC 的测试（process/bench 不建 Host，拿不到共享内存）。两者共用同一条
+// RPC 通道，差值就是「把 payload 挪进共享内存」的净成本：小 payload 会因为
+// 多几次分配/拷贝而略慢，大 payload 则省掉整份 JSON 编解码与管道字节拷贝。
+//
+// 两个尺寸都测，是因为这一改动的取舍正好随 payload 大小翻转——只看单点
+// 很容易得出相反结论。对照实验 11 的工具调用 RPC p50 = 19.6µs。
 func BenchmarkToolInvoke(b *testing.B) {
+	for _, sz := range []struct {
+		name string
+		n    int
+	}{
+		{"small", 16},
+		{"large", 32 << 10},
+	} {
+		b.Run("inline/"+sz.name, func(b *testing.B) { benchmarkToolInvokeInline(b, sz.n) })
+		b.Run("frame/"+sz.name, func(b *testing.B) { benchmarkToolInvokeFrame(b, sz.n) })
+	}
+}
+
+// benchmarkToolInvokeInline 是改造前的老路径：参数随 RPC 报文一起过管道。
+func benchmarkToolInvokeInline(b *testing.B, payloadSize int) {
 	bin := buildBenchPlugin(b, "echoplugin.go")
 
 	p, err := Spawn("echo", bin, Options{Handler: noopHandler})
@@ -59,7 +94,7 @@ func BenchmarkToolInvoke(b *testing.B) {
 	}
 	defer p.Kill()
 
-	args := map[string]interface{}{"text": "benchmark"}
+	args := map[string]interface{}{"text": strings.Repeat("a", payloadSize)}
 
 	b.ResetTimer()
 	for i := 0; i < b.N; i++ {
@@ -72,6 +107,42 @@ func BenchmarkToolInvoke(b *testing.B) {
 	}
 }
 
+// benchmarkToolInvokeFrame 是 §13.3 之后的生产路径：内核 Alloc 帧 → 参数写帧
+// 前段 → RPC 只传 {frame, args_len} → 插件从帧读参数、结果写回帧结果区 →
+// 内核读回并归还整帧（调用帧模型，见 plan.md §13.3）。
+func benchmarkToolInvokeFrame(b *testing.B, payloadSize int) {
+	bin := buildBenchPlugin(b, "stageplugin.go")
+	core := newFakeCore()
+
+	host, err := NewHost()
+	if err != nil {
+		b.Fatalf("NewHost: %v", err)
+	}
+	defer host.Close()
+
+	p := New("demo", bin, b.TempDir(), nil, host, nil)
+	if err := p.Start(core); err != nil {
+		b.Fatalf("Start: %v", err)
+	}
+	defer p.Close()
+
+	core.mu.Lock()
+	h, ok := core.tools["demo_big"]
+	core.mu.Unlock()
+	if !ok {
+		b.Fatal("插件应注册 demo_big 工具")
+	}
+
+	args := map[string]interface{}{"text": strings.Repeat("a", payloadSize)}
+
+	b.ResetTimer()
+	for i := 0; i < b.N; i++ {
+		if _, err := h(args); err != nil {
+			b.Fatalf("第 %d 次调用失败: %v", i, err)
+		}
+	}
+}
+
 // BenchmarkStageLockArbitration 测量**内核侧锁仲裁本身**的成本。
 //
 // ⚠️ 不要拿这个数字对照实验 3 的 19.40µs——两者测的不是同一个东西：

internal/plugin/proc/capability.go

@@ -84,6 +84,9 @@ var methodCapability = map[string]Capability{
 	MethodInputRegister:  CapCore,
 	MethodStageLock:      CapCore,
 	MethodStageUnlock:    CapCore,
+	// 共享槽池申请/归还：内部传输层能力，等同于核心基础能力。
+	MethodArenaAlloc: CapCore,
+	MethodArenaFree:  CapCore,
 	// 自身配置读写与元信息属基础能力
 	MethodSettingsGet:         CapCore,
 	MethodSettingsSet:         CapCore,
@@ -101,6 +104,11 @@ var methodCapability = map[string]Capability{
 	MethodIOInjectInterrupt: CapIO,
 	MethodIOInjectTextNoMem: CapIO,
 	MethodIOInjectSync:      CapIO,
+	// 带媒体的注入与纯文本注入同一权限组：能不能发起一轮对话是 IO 能力，
+	// 带不带图不改变这个判断。
+	MethodIOInjectMedia:          CapIO,
+	MethodIOInjectMediaSync:      CapIO,
+	MethodIOInjectInterruptMedia: CapIO,
 
 	// ---- 图记忆 ----
 	MethodMemoryRecall:     CapMemory,
@@ -114,6 +122,8 @@ var methodCapability = map[string]Capability{
 	MethodDocInsert: CapDocMemory,
 	MethodDocRemove: CapDocMemory,
 	MethodDocStats:  CapDocMemory,
+	// 带媒体写入与普通写入同权限：都是往文档记忆里写东西。
+	MethodDocInsertMedia: CapDocMemory,
 
 	// ---- 知识库 ----
 	MethodKnowledgeSearch: CapKnowledge,

internal/plugin/proc/capability_test.go

@@ -19,12 +19,13 @@ func TestCapability_AllMethodsClassified(t *testing.T) {
 	// 与 protocol.go 的 method 常量对齐。内核→插件的 7 个调用不经 Handle，
 	// 故不需要能力归属。
 	kernelToPlugin := map[string]bool{
-		MethodPluginInit:   true,
-		MethodPluginStart:  true,
-		MethodPluginStop:   true,
-		MethodToolInvoke:   true,
-		MethodStageInvoke:  true,
-		MethodOutputInvoke: true,
+		MethodPluginInit:    true,
+		MethodPluginStart:   true,
+		MethodPluginStop:    true,
+		MethodToolInvoke:    true,
+		MethodCleanerInvoke: true,
+		MethodStageInvoke:   true,
+		MethodOutputInvoke:  true,
 	}
 
 	// 插件→内核的全部 method（手工清单，与 protocol.go 对照）
@@ -34,10 +35,12 @@ func TestCapability_AllMethodsClassified(t *testing.T) {
 		MethodAPIRegister, MethodInputRegister,
 		MethodIOInjectText, MethodIOInjectInterrupt, MethodIOInjectTextNoMem,
 		MethodIOInjectSync, MethodIOSetToolBlocks,
+		MethodIOInjectMedia, MethodIOInjectMediaSync, MethodIOInjectInterruptMedia,
 		MethodLifecycleAutoRestart,
 		MethodMemoryRecall, MethodMemoryCommit, MethodMemoryIntrospect,
 		MethodMemoryMerge, MethodMemoryPurge,
 		MethodDocQuery, MethodDocInsert, MethodDocRemove, MethodDocStats,
+		MethodDocInsertMedia,
 		MethodKnowledgeSearch, MethodKnowledgeAdd, MethodKnowledgeList,
 		MethodTextMemoryAppend,
 		MethodSettingsGet, MethodSettingsSet, MethodSettingsRegisterDef,

internal/plugin/proc/contextpolicy_test.go

@@ -0,0 +1,33 @@
+package proc
+
+import (
+	"strings"
+	"testing"
+)
+
+// 非法 context_policy 必须报错，而不是静默当成 none。
+//
+// 为什么这条值得单独测：把拼写错误降级成「不裁剪」不会有任何报错、日志或
+// 行为异常——调用方会一直以为自己声明的裁剪在生效，直到某天上下文被撑爆。
+// 这类静默降级是本次改造要消掉的东西，所以要钉住。
+func TestValidateContextPolicy(t *testing.T) {
+	ok := []string{"", "none", "prune"}
+	for _, policy := range ok {
+		if err := validateContextPolicy("tool.register", policy); err != nil {
+			t.Errorf("合法取值 %q 被拒绝: %v", policy, err)
+		}
+	}
+
+	bad := []string{"prune ", "PRUNE", "True", "None", "always", "裁剪"}
+	for _, policy := range bad {
+		err := validateContextPolicy("io.injectText", policy)
+		if err == nil {
+			t.Errorf("非法取值 %q 应被拒绝", policy)
+			continue
+		}
+		// 报错要指出位置与实际值，否则排查时不知道是谁传错了。
+		if !strings.Contains(err.Error(), "io.injectText") || !strings.Contains(err.Error(), policy) {
+			t.Errorf("错误信息应包含位置与实际值，实际: %v", err)
+		}
+	}
+}

internal/plugin/proc/corehandler.go

@@ -28,12 +28,17 @@ type coreHandler struct {
 	// ❗ 必须是"全部插件共享一个 Host"——每插件一段会退化成副本模型。
 	host *Host
 
+	// owner 是本插件在共享槽池里的身份。内核用它校验 arena.free 的归属，
+	// 并在插件退出时 ReclaimOwner 回收残留槽。
+	owner uint32
+
 	// locks 是 host.locks 的引用，供 stage.lock/unlock 路由。
 	locks *lockRegistry
 
-	// invokeTool/invokeStageFn/invokeOutput 反向调用插件（内核 → 插件）。
+	// invokeTool/invokeCleaner/invokeStageFn/invokeOutput 反向调用插件（内核 → 插件）。
 	// 由 Plugin 注入，注册回调时用它们构造 handler。
 	invokeTool    func(name string, args map[string]interface{}) (interface{}, error)
+	invokeCleaner func(params CleanerInvokeParams) (CleanerInvokeResult, error)
 	invokeStageFn func(ctx context.Context, stage string, seq uint64) error
 	invokeOutput  func(channel string, args map[string]interface{}) (interface{}, error)
 
@@ -91,6 +96,22 @@ type CoreSDK interface {
 	InjectInterruptText(source, channel, text string)
 	InjectTextNoMemory(source, channel, text string)
 	InjectInputSync(source, channel, text string) string
+	// 带媒体的注入：子进程插件也能主动发起一轮带图/音频的对话。
+	InjectInputMedia(source, channel, text string, blocks []pubsdk.ContentBlock)
+	InjectInputMediaSync(source, channel, text string, blocks []pubsdk.ContentBlock) string
+	InjectInterruptMedia(source, channel, text string, blocks []pubsdk.ContentBlock)
+
+	// 带标志位的注入：声明这一次注入是否记入记忆、是否据此裁剪上下文。
+	// 上面的三参数方法是它们的零值糖。
+	InjectTextOpts(source, channel, text string, opts pubsdk.InjectOptions)
+	InjectInterruptTextOpts(source, channel, text string, opts pubsdk.InjectOptions)
+	InjectInputSyncOpts(source, channel, text string, opts pubsdk.InjectOptions) string
+	InjectInputMediaOpts(source, channel, text string, blocks []pubsdk.ContentBlock, opts pubsdk.InjectOptions)
+	InjectInputMediaSyncOpts(source, channel, text string, blocks []pubsdk.ContentBlock, opts pubsdk.InjectOptions) string
+	InjectInterruptMediaOpts(source, channel, text string, blocks []pubsdk.ContentBlock, opts pubsdk.InjectOptions)
+
+	// SetToolBlocks 注入媒体块，内核在下一条 tool message 携带（§3.8）。
+	SetToolBlocks(blocks []pubsdk.ContentBlock)
 
 	SetAutoRestart(enabled bool)
 }
@@ -124,44 +145,120 @@ func (h *coreHandler) Handle(method string, params json.RawMessage) (interface{}
 		return nil, h.sdk.RegisterPluginAPI(p.Name)
 	case MethodInputRegister:
 		var p struct {
-			Name string            `json:"name"`
-			Def  pubsdk.ChannelDef `json:"def"`
+			Name       string            `json:"name"`
+			Def        pubsdk.ChannelDef `json:"def"`
+			HasCleaner bool              `json:"has_cleaner"`
 		}
 		if err := unmarshal(params, &p); err != nil {
 			return nil, err
 		}
-		// 注意 ChannelDef.Cleaner 是函数，无法跨进程传递（§3.5 回调型资源）。
-		// NoMemory 可传；Cleaner 若插件需要，须在插件侧对文本预处理后再注入。
-		return nil, h.sdk.RegisterInputChannel(p.Name, pubsdk.ChannelDef{NoMemory: p.Def.NoMemory})
+		if p.Name == "" {
+			return nil, fmt.Errorf("input.register: 缺少 name")
+		}
+		cleaner, err := h.cleanerProxy(CleanerScopeInput, p.Name, p.HasCleaner)
+		if err != nil {
+			return nil, fmt.Errorf("input.register: %w", err)
+		}
+		if err := validateContextPolicy("input.register", p.Def.ContextPolicy); err != nil {
+			return nil, err
+		}
+		// 整体传 p.Def（只是把函数型的 Cleaner 换成代理），不要手写字段白名单：
+		// 白名单会让新增字段静默丢失。
+		def := p.Def
+		def.Cleaner = cleaner
+		return nil, h.sdk.RegisterInputChannel(p.Name, def)
 
 	// ---- IO 注入（原 case 5/6/7/47）----
+	//
+	// 注入标志位（no_memory / context_policy）由插件在调用点声明，默认
+	// 记入记忆 + 不裁剪。策略值在入口校验：静默降级成 none 会让调用方
+	// 以为自己声明的裁剪在生效。
 	case MethodIOInjectText:
 		var p injectParams
 		if err := unmarshal(params, &p); err != nil {
 			return nil, err
 		}
-		h.sdk.InjectText(p.Source, p.Channel, p.Text)
+		if err := validateContextPolicy("io.injectText", p.ContextPolicy); err != nil {
+			return nil, err
+		}
+		h.sdk.InjectTextOpts(p.Source, p.Channel, h.resolveText(p), pubSdkInjectOpts(p.NoMemory, p.ContextPolicy, p.CleanerName))
 		return nil, nil
 	case MethodIOInjectInterrupt:
 		var p injectParams
 		if err := unmarshal(params, &p); err != nil {
 			return nil, err
 		}
-		h.sdk.InjectInterruptText(p.Source, p.Channel, p.Text)
+		if err := validateContextPolicy("io.injectInterrupt", p.ContextPolicy); err != nil {
+			return nil, err
+		}
+		h.sdk.InjectInterruptTextOpts(p.Source, p.Channel, h.resolveText(p), pubSdkInjectOpts(p.NoMemory, p.ContextPolicy, p.CleanerName))
 		return nil, nil
 	case MethodIOInjectTextNoMem:
 		var p injectParams
 		if err := unmarshal(params, &p); err != nil {
 			return nil, err
 		}
-		h.sdk.InjectTextNoMemory(p.Source, p.Channel, p.Text)
+		if err := validateContextPolicy("io.injectTextNoMem", p.ContextPolicy); err != nil {
+			return nil, err
+		}
+		// 旧 RPC 语义就是「不进记忆」，显式标志位只可能再叠上 context_policy。
+		h.sdk.InjectTextOpts(p.Source, p.Channel, h.resolveText(p), pubSdkInjectOpts(true, p.ContextPolicy, p.CleanerName))
 		return nil, nil
 	case MethodIOInjectSync:
 		var p injectParams
 		if err := unmarshal(params, &p); err != nil {
 			return nil, err
 		}
-		return map[string]interface{}{"reply": h.sdk.InjectInputSync(p.Source, p.Channel, p.Text)}, nil
+		if err := validateContextPolicy("io.injectInputSync", p.ContextPolicy); err != nil {
+			return nil, err
+		}
+		reply := h.sdk.InjectInputSyncOpts(p.Source, p.Channel, h.resolveText(p), pubSdkInjectOpts(p.NoMemory, p.ContextPolicy, p.CleanerName))
+		return map[string]interface{}{"reply": reply}, nil
+
+	case MethodIOInjectMedia:
+		var p injectMediaParams
+		if err := unmarshal(params, &p); err != nil {
+			return nil, err
+		}
+		if err := validateContextPolicy("io.injectMedia", p.ContextPolicy); err != nil {
+			return nil, err
+		}
+		blocks, err := h.resolveBlocks(p)
+		if err != nil {
+			return nil, err
+		}
+		h.sdk.InjectInputMediaOpts(p.Source, p.Channel, p.Text, blocks, pubSdkInjectOpts(p.NoMemory, p.ContextPolicy, p.CleanerName))
+		return nil, nil
+
+	case MethodIOInjectMediaSync:
+		var p injectMediaParams
+		if err := unmarshal(params, &p); err != nil {
+			return nil, err
+		}
+		if err := validateContextPolicy("io.injectMediaSync", p.ContextPolicy); err != nil {
+			return nil, err
+		}
+		blocks, err := h.resolveBlocks(p)
+		if err != nil {
+			return nil, err
+		}
+		reply := h.sdk.InjectInputMediaSyncOpts(p.Source, p.Channel, p.Text, blocks, pubSdkInjectOpts(p.NoMemory, p.ContextPolicy, p.CleanerName))
+		return map[string]interface{}{"reply": reply}, nil
+
+	case MethodIOInjectInterruptMedia:
+		var p injectMediaParams
+		if err := unmarshal(params, &p); err != nil {
+			return nil, err
+		}
+		if err := validateContextPolicy("io.injectInterruptMedia", p.ContextPolicy); err != nil {
+			return nil, err
+		}
+		blocks, err := h.resolveBlocks(p)
+		if err != nil {
+			return nil, err
+		}
+		h.sdk.InjectInterruptMediaOpts(p.Source, p.Channel, p.Text, blocks, pubSdkInjectOpts(p.NoMemory, p.ContextPolicy, p.CleanerName))
+		return nil, nil
 
 	// ---- 生命周期（原 case 8）----
 	case MethodLifecycleAutoRestart:
@@ -283,16 +380,52 @@ func (h *coreHandler) Handle(method string, params json.RawMessage) (interface{}
 			return nil, errUnavailable("doc memory")
 		}
 		var p struct {
-			Doc *pubsdk.Doc `json:"doc"`
+			Doc    *pubsdk.Doc `json:"doc,omitempty"`
+			DocRef SharedRef   `json:"doc_ref,omitempty"`
 		}
 		if err := unmarshal(params, &p); err != nil {
 			return nil, err
 		}
+		// 文档全文可达几十 KB～数 MB，优先走共享内存。
+		if err := h.resolveJSONRef(p.DocRef, &p.Doc); err != nil {
+			return nil, err
+		}
 		if p.Doc == nil {
 			return nil, fmt.Errorf("doc.insert: 缺少 doc 字段")
 		}
 		return nil, dm.Insert(p.Doc)
 
+	case MethodDocInsertMedia:
+		dm := h.sdk.DocMemory()
+		if dm == nil {
+			return nil, errUnavailable("doc memory")
+		}
+		var p struct {
+			Doc         *pubsdk.Doc              `json:"doc,omitempty"`
+			Attachments []pubsdk.MediaAttachment `json:"attachments,omitempty"`
+			DocRef      SharedRef                `json:"doc_ref,omitempty"`
+			AttachRef   SharedRef                `json:"attachments_ref,omitempty"`
+		}
+		if err := unmarshal(params, &p); err != nil {
+			return nil, err
+		}
+		// 文档正文 + 附件（含媒体二进制/data URL）都优先走共享内存。
+		if err := h.resolveJSONRef(p.DocRef, &p.Doc); err != nil {
+			return nil, err
+		}
+		if err := h.resolveJSONRef(p.AttachRef, &p.Attachments); err != nil {
+			return nil, err
+		}
+		if p.Doc == nil {
+			return nil, fmt.Errorf("doc.insertWithMedia: 缺少 doc 字段")
+		}
+		if err := dm.InsertWithMedia(p.Doc, p.Attachments); err != nil {
+			return nil, err
+		}
+		// 回传内核补过的字段：ID 新建时才生成，Content 含内核补的媒体标记，
+		// MediaDigests 是附件落盘后的完整 digest——插件靠它们后续引用同一份媒体。
+		return map[string]interface{}{"doc": p.Doc}, nil
+
 	case MethodDocRemove:
 		dm := h.sdk.DocMemory()
 		if dm == nil {
@@ -342,12 +475,18 @@ func (h *coreHandler) Handle(method string, params json.RawMessage) (interface{}
 			return nil, errUnavailable("knowledge")
 		}
 		var p struct {
-			Name    string `json:"name"`
-			Content string `json:"content"`
+			Name       string    `json:"name"`
+			Content    string    `json:"content,omitempty"`
+			ContentRef SharedRef `json:"content_ref,omitempty"`
 		}
 		if err := unmarshal(params, &p); err != nil {
 			return nil, err
 		}
+		// 知识正文可达数十 KB，优先走共享内存。内容是 JSON 字符串，
+		// 所以从 ref 读出后需再解一层。
+		if err := h.resolveJSONRef(p.ContentRef, &p.Content); err != nil {
+			return nil, err
+		}
 		return nil, kn.Add(p.Name, p.Content)
 
 	case MethodKnowledgeList:
@@ -490,19 +629,141 @@ func (h *coreHandler) Handle(method string, params json.RawMessage) (interface{}
 		// 当前设计：子进程 Stop 时由内核统一清理其订阅。
 		return nil, nil
 
-	// ---- 多模态注入（C ABI 侧空实现）----
+	// ---- 共享槽池（内部传输层，见 protocol.go 注释）----
+	case MethodArenaAlloc:
+		var p ArenaAllocParams
+		if err := unmarshal(params, &p); err != nil {
+			return nil, err
+		}
+		ref, err := h.arenaAlloc(p.Size)
+		if err != nil {
+			return nil, err
+		}
+		return ArenaAllocResult{Ref: ref}, nil
+
+	case MethodArenaFree:
+		var p ArenaFreeParams
+		if err := unmarshal(params, &p); err != nil {
+			return nil, err
+		}
+		return nil, h.arenaFree(p.Ref)
+
+	// ---- 多模态注入 ----
+	//
+	// 之前这里是桩：返回“待共享段二进制通道落地”。后果是**子进程插件调
+	// SetToolBlocks 必然失败**（模板只 log 一行），只有内置插件能用。
+	// 现在媒体块经共享内存传递，该能力对两种插件形态等价。
 	case MethodIOSetToolBlocks:
-		// Part 4 扩展：二进制落 arena、Slice 描述符回传（§3.8）。
-		return nil, fmt.Errorf("%s: 多模态注入待共享段二进制通道落地", method)
+		var p injectMediaParams
+		if err := unmarshal(params, &p); err != nil {
+			return nil, err
+		}
+		blocks, err := h.resolveBlocks(p)
+		if err != nil {
+			return nil, err
+		}
+		if len(blocks) == 0 {
+			return nil, fmt.Errorf("%s: blocks 为空", method)
+		}
+		h.sdk.SetToolBlocks(blocks)
+		return nil, nil
 	}
 
 	return nil, fmt.Errorf("未知 method: %s", method)
 }
 
+// resolveText 从 injectParams 中提取 text：优先使用 TextRef（共享槽），
+// 否则使用内联 Text。兼容新旧两种协议。
+//
+// 子进程分配自己的槽并在收到应答后释放，因此这里读到的一定是 busy 槽。
+func (h *coreHandler) resolveText(p injectParams) string {
+	if !p.TextRef.IsZero() {
+		data, err := h.host.Arena().Read(p.TextRef, h.host.Generation())
+		if err != nil {
+			return ""
+		}
+		return string(data)
+	}
+	return p.Text
+}
+
 type injectParams struct {
-	Source  string `json:"source"`
-	Channel string `json:"channel"`
-	Text    string `json:"text"`
+	Source        string    `json:"source"`
+	Channel       string    `json:"channel"`
+	Text          string    `json:"text,omitempty"`
+	TextRef       SharedRef `json:"text_ref,omitempty"`
+	NoMemory      bool      `json:"no_memory,omitempty"`
+	ContextPolicy string    `json:"context_policy,omitempty"`
+	CleanerName   string    `json:"cleaner_name,omitempty"`
+}
+
+// injectMediaParams 是带媒体注入/工具块注入的参数。
+//
+// blocks 优先经共享内存传递（BlocksRef）。旧的注释说“data URL 已是 base64
+// 文本、再套一层二进制不会更小，所以走 JSON”——那只算了体积，漏了两件更重要
+// 的事：① 内联时整份 base64 要在 RPC 报文里再编码/再拷贝一遍（一张本地生图
+// 可达数 MB），② 内容本体不在共享段里，插件回调就无法就地改写，只能各自
+// 持一份拷贝。共享内存的意义是后者。
+//
+// 没有 BlocksRef 时（直连 RPC 测试、arena 不可用）回退内联 Blocks。
+type injectMediaParams struct {
+	Source        string                `json:"source"`
+	Channel       string                `json:"channel"`
+	Text          string                `json:"text,omitempty"`
+	Blocks        []pubsdk.ContentBlock `json:"blocks,omitempty"`
+	BlocksRef     SharedRef             `json:"blocks_ref,omitempty"`
+	NoMemory      bool                  `json:"no_memory,omitempty"`
+	ContextPolicy string                `json:"context_policy,omitempty"`
+	CleanerName   string                `json:"cleaner_name,omitempty"`
+}
+
+// pubSdkInjectOpts 把 RPC 报文里的三个字段转成公开 SDK 的 InjectOptions。
+//
+// 单独提一个转换函数是为了让「默认值」只有一个出处：零值即记入记忆 + 不裁剪，
+// 与旧三参数注入等价。
+func pubSdkInjectOpts(noMemory bool, policy, cleanerName string) pubsdk.InjectOptions {
+	return pubsdk.InjectOptions{NoMemory: noMemory, ContextPolicy: policy, CleanerName: cleanerName}
+}
+
+// validateContextPolicy 校验上下文策略取值，与 tool.register 同一套规则。
+//
+// 空串等价于 none（不裁剪）。非法值必须报错而不是当成 none：把拼写错误
+// 静默降级成「不裁剪」会让调用方以为自己声明的裁剪在生效。
+func validateContextPolicy(where, policy string) error {
+	if !pubsdk.ValidContextPolicy(policy) {
+		return fmt.Errorf("%s: context_policy 只允许 none/prune，实际 %q", where, policy)
+	}
+	return nil
+}
+
+// resolveJSONRef 若 ref 非零则从共享内存读取并 JSON 反序列化到 out；
+// ref 为零时不动 out（调用方已填的内联值生效）。
+//
+// 供「大 payload 优先走共享内存、否则内联」的字段对共用。
+func (h *coreHandler) resolveJSONRef(ref SharedRef, out interface{}) error {
+	if ref.IsZero() {
+		return nil
+	}
+	data, err := h.host.Arena().Read(ref, h.host.Generation())
+	if err != nil {
+		return fmt.Errorf("读取共享内容失败: %w", err)
+	}
+	if err := json.Unmarshal(data, out); err != nil {
+		return fmt.Errorf("解析共享内容失败: %w", err)
+	}
+	return nil
+}
+
+// resolveBlocks 取出媒体块：优先共享内存，否则内联。
+func (h *coreHandler) resolveBlocks(p injectMediaParams) ([]pubsdk.ContentBlock, error) {
+	if p.BlocksRef.IsZero() {
+		return p.Blocks, nil
+	}
+	var blocks []pubsdk.ContentBlock
+	if err := h.resolveJSONRef(p.BlocksRef, &blocks); err != nil {
+		return nil, err
+	}
+	return blocks, nil
 }
 
 func unmarshal(params json.RawMessage, out interface{}) error {
@@ -519,11 +780,96 @@ func errUnavailable(what string) error {
 	return fmt.Errorf("%s 能力在当前内核实例中不可用", what)
 }
 
+// cleanerProxy 把进程内函数式 Cleaner 恢复成内核侧透明代理。
+// RPC 失败时返回原文：清洗是计算层优化，不能因插件暂时离线而丢失内容。
+func (h *coreHandler) cleanerProxy(scope, name string, enabled bool) (func(string) string, error) {
+	if !enabled {
+		return nil, nil
+	}
+	if h.invokeCleaner == nil {
+		return nil, fmt.Errorf("%s %s 声明 Cleaner，但清洗回调通道未就绪", scope, name)
+	}
+	return func(text string) string {
+		out, err := h.invokeCleanerText(scope, name, text)
+		if err != nil {
+			return text
+		}
+		return out
+	}, nil
+}
+
+// invokeCleanerText 完成一次 Cleaner 往返，使用与工具调用相同的 funccall 帧模型。
+//
+// 内核（caller）标定帧：输入段 + 结果预算段，插件在帧内写结果；
+// 只有结果超出预算时插件才向内核申请扩容块（插件只申请，回收由内核做）。
+func (h *coreHandler) invokeCleanerText(scope, name, text string) (string, error) {
+	arena := h.host.Arena()
+	gen := h.host.Generation()
+
+	frame, err := arena.Alloc(OwnerHost, len(text)+cleanerResultBudget, gen)
+	if err != nil {
+		return "", fmt.Errorf("%s %s Cleaner 分配调用帧失败: %w", scope, name, err)
+	}
+	defer func() { _ = arena.Free(OwnerHost, frame) }()
+
+	area, err := arena.Read(frame, gen)
+	if err != nil {
+		return "", err
+	}
+	copy(area[:len(text)], text)
+
+	params := CleanerInvokeParams{
+		Scope:    scope,
+		Name:     name,
+		Frame:    frame,
+		InputLen: uint32(len(text)),
+	}
+
+	res, err := h.invokeCleaner(params)
+	if err != nil {
+		return "", err
+	}
+
+	// 插件申请了扩容块：内核负责归还（插件只会申请，回收由内核做）。
+	if res.TextRef.IsZero() {
+		return "", fmt.Errorf("%s %s Cleaner 未返回结果引用", scope, name)
+	}
+	if res.TextRef.Flags&sharedRefFlagExpand != 0 {
+		defer func() { _ = arena.Free(OwnerHost, res.TextRef) }()
+	}
+	data, err := arena.Read(res.TextRef, gen)
+	if err != nil {
+		return "", err
+	}
+	return string(data), nil
+}
+
+// ---- 共享内存的 syscall 风格接口（插件 RPC）----
+//
+// 共享内存是内部实现，不向插件开发者暴露；模板运行时在传输层调用它们，
+// 公开 SDK 仍是普通字符串/Map。
+
+// arenaAlloc 给本插件分配一块共享内存。
+//
+// 用途：结果超出内核标定帧的预算时，插件据此申请扩容块。
+func (h *coreHandler) arenaAlloc(size uint32) (SharedRef, error) {
+	return h.host.Arena().Alloc(h.owner, int(size), h.host.Generation())
+}
+
+// arenaFree 归还本插件申请的块。
+//
+// 内核会走块链校验 offset 确实是某个已分配块的数据起点、owner 匹配，
+// 伪造引用不能改动分配器状态。
+func (h *coreHandler) arenaFree(ref SharedRef) error {
+	return h.host.Arena().Free(h.owner, ref)
+}
+
 // toolRegister 注册插件工具，handler 反向调用插件执行（原 case 1）。
 func (h *coreHandler) toolRegister(params json.RawMessage) (interface{}, error) {
 	var p struct {
-		Name string         `json:"name"`
-		Def  pubsdk.ToolDef `json:"def"`
+		Name       string         `json:"name"`
+		Def        pubsdk.ToolDef `json:"def"`
+		HasCleaner bool           `json:"has_cleaner"`
 	}
 	if err := unmarshal(params, &p); err != nil {
 		return nil, err
@@ -531,9 +877,16 @@ func (h *coreHandler) toolRegister(params json.RawMessage) (interface{}, error)
 	if p.Name == "" {
 		return nil, fmt.Errorf("tool.register: 缺少 name")
 	}
+	if err := validateContextPolicy("tool.register", p.Def.ContextPolicy); err != nil {
+		return nil, err
+	}
 	p.Def.Plugin = h.name
-	// ToolDef.Cleaner 是函数，跨进程无法传递（§3.5）——与 C ABI 路径行为一致。
-	p.Def.Cleaner = nil
+	// 函数本身不进 JSON；has_cleaner 只声明其存在，实际执行回到插件进程。
+	cleaner, err := h.cleanerProxy(CleanerScopeTool, p.Name, p.HasCleaner)
+	if err != nil {
+		return nil, fmt.Errorf("tool.register: %w", err)
+	}
+	p.Def.Cleaner = cleaner
 
 	name := p.Name
 	return nil, h.sdk.RegisterTool(name, p.Def, func(args map[string]interface{}) (interface{}, error) {
@@ -576,10 +929,11 @@ func (h *coreHandler) stageRegister(params json.RawMessage) (interface{}, error)
 // 永远返回成功（§9.4，现网 2 次消息发不出而模型以为成功）。
 func (h *coreHandler) outputRegister(params json.RawMessage) (interface{}, error) {
 	var p struct {
-		Name string            `json:"name"`
-		Caps int               `json:"caps"`
-		Desc string            `json:"desc"`
-		Def  pubsdk.ChannelDef `json:"def"`
+		Name       string            `json:"name"`
+		Caps       int               `json:"caps"`
+		Desc       string            `json:"desc"`
+		Def        pubsdk.ChannelDef `json:"def"`
+		HasCleaner bool              `json:"has_cleaner"`
 	}
 	if err := unmarshal(params, &p); err != nil {
 		return nil, err
@@ -588,8 +942,12 @@ func (h *coreHandler) outputRegister(params json.RawMessage) (interface{}, error
 		return nil, fmt.Errorf("output.register: 缺少 name")
 	}
 	channel := p.Name
+	cleaner, err := h.cleanerProxy(CleanerScopeOutput, channel, p.HasCleaner)
+	if err != nil {
+		return nil, fmt.Errorf("output.register: %w", err)
+	}
 	return nil, h.sdk.RegisterOutputChannel(channel, p.Caps, p.Desc,
-		pubsdk.ChannelDef{NoMemory: p.Def.NoMemory},
+		pubsdk.ChannelDef{NoMemory: p.Def.NoMemory, Cleaner: cleaner},
 		func(args map[string]interface{}) (interface{}, error) {
 			return h.invokeOutput(channel, args)
 		})