dsh-redteam-memory 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fasthei
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,219 @@
+# 红队记忆 · DSH 插件
+
+给模型一个**可检索的 AI 安全知识库**：把 AI 安全知识与进攻技巧（OWASP LLM Top 10、提示词注入、
+RAG 投毒、Agent / MCP 工具滥用、推理服务未授权与已知 CVE、证据与合规清单…）存进**本地库**，
+模型在需要时用 `memory_search` 检索，人可以在面板上导入 / 删除 / 浏览。
+
+**本地库是权威数据，Milvus 只是它的派生索引** —— 没配向量模型也能记录与检索（自动退回本地关键词匹配），
+网络故障、Key 过期都不会让「写不进去」。工作区对话里说到「写入记忆」这类触发词，内容会被**自动收进本地库**。
+
+它不是「记目标上下文」那种对话记忆（那是另一条路），而是**一本随取随查的作战手册**：
+判断某个手法能不能用、报告里该怎么写、某个风险点的标准做法是什么，让模型去查，而不是凭印象编。
+
+## 架构
+
+```
+   会话事件（session/event）─┐           面板（导入 / 删除 / 列表 / 检索 / 捕获）
+                            │                          │  RPC（宿主路由 /dsh-redteam-memory/rpc）
+                            ▼                          ▼
+        ┌──────────────────────────────────────────────────────┐
+        │  Host 半边（本插件）                                   │
+        │  · 对话捕获：命中触发词 → 收进本地库（不依赖任何外部服务） │
+        │  · 本地库 .redteam-memory.json（权威数据，含设置与条目） │
+        │  · 索引同步（尽力而为）→ Milvus REST v2：建集合/upsert/检索/删除/统计
+        │  · 向量模型适配器  → 阿里百炼 tongyi-embedding-vision-flash / 智谱 Embedding-3 / OpenAI 兼容
+        │  · 重排模型适配器  → jina / siliconflow / dashscope / cohere / bigmodel / 自定义
+        │  · S3 关联        → Milvus 用的存储桶（例如 mimo）：连通测试 / 列举 / 整库导出
+        │  · 对外服务 redteamMemory（其它插件把成稿导入记忆）      │
+        └──────────────────────────────────────────────────────┘
+                     │  shell → curl（只在需要索引/重排/S3 时才发出去）
+              Milvus / 向量服务 / 重排服务 / S3
+```
+
+**HTTP 为什么走 `shell` + `curl` 而不是 `fetch`**：动态半边屏蔽了 `fetch`（见
+[仓库开发约定](../../docs/DEVELOPMENT.md)），而本插件两种形态都要能跑；资产图谱调 Jina MCP
+用的是同一套。顺带一个好处：curl 自带 `--aws-sigv4`，S3 的签名不用手写。
+
+## 安装与报告集成
+
+```bash
+dsh plugin --profile web add dsh-redteam-memory
+# 需要报告功能时，再安装报告包：
+dsh plugin --profile web add dsh-redteam-report
+# 重启 dsh web 使静态插件组合生效。
+```
+
+记忆插件可独立使用。安装报告插件后，两者的配置统一显示在 **设置 → 红队设置**：
+上方为「记忆与向量存储」（按钮「保存记忆设置」），下方为报告插件提供的设置组件。
+未启用报告插件时显示可读提示，不影响记忆功能。
+
+客户端服务 `redteamSettingsUI` 提供以下协议，供报告插件接入：
+
+- `current()`：当前报告 React 组件，未注册时为 `null`。
+- `subscribe(fn)`：订阅变更，立即通知一次，返回幂等退订函数。
+- `register(Component)`：注册唯一报告组件，返回幂等注销函数；重复注册需先注销旧组件。
+
+报告客户端应声明 `inject: ['redteamSettingsUI']`，并通过
+`ctx.effect(() => ctx.redteamSettingsUI.register(Component))` 管理注册生命周期。
+记忆插件退出时服务、组件引用与订阅均随 fiber 清理，报告依赖方可在记忆重载后自动重新注册。
+
+## 配置（DSH 设置 → 红队设置）
+
+配置**不在记忆面板里**：它是 DSH 设置里的一页「红队设置」（注册在 `settings.section` 插槽），
+因为数据库地址、向量模型 Key 这些一年改两次，而「导入一份报告」「查一条技巧」每天都要用。
+记忆面板只管用（知识库 / 检索 / 日志），设置页只管配。
+
+四组，各自有独立的「测试」按钮，填错立刻能看到真实错误：
+
+| 组 | 必填 | 说明 |
+|---|---|---|
+| Milvus | 地址 | 自建 `http://127.0.0.1:19530`；Zilliz 云 `https://xxx.api.region.zillizcloud.com` + Token |
+| 向量模型 | 服务 / 模型 / Key / 维度 | 换模型必须换 collection 或删掉重建（维度不一致会明确报错，不会静默写坏） |
+| 重排模型 | 开关 / 服务 / 模型 / Key | 可选。默认列出 jina、硅基流动、百炼 gte-rerank、Cohere、智谱，也可以填自定义的 OpenAI 兼容 `/v1/rerank` |
+| MinIO | 端点 / 桶 / Region / AK / SK | 可选对象存储关联与备份；可填写 Milvus 使用的实际桶名。MinIO / 自建要开 path-style；兼容 S3 协议 |
+| 本地库 | 存储文件 / 默认返回条数 | 解析后的**绝对路径**会显示在这里。文件含 Key，已在 `.gitignore` 里 |
+
+**只有 Milvus / 向量模型是「想用向量检索才需要」的**：不填也能记、也能按关键词查，
+面板上的「同步索引」会在你填好之后再把这些条目补进索引。
+
+填写后先点击 **「保存记忆设置」** 再测试。`testMilvus` / `testEmbed` / `testRerank` /
+`testS3` 的缺配置或连接失败都会返回 `{ok:false,error}`，在面板内显示，不抛成 Handler 异常。
+自定义 OpenAI 兼容向量端点仍允许不填写 API Key。
+
+**MinIO 只是界面命名变化**：存储字段仍是 `s3`，RPC 仍使用 `testS3`、`s3List`、`s3Backup`，
+已有配置无需迁移。只使用向量检索时可不启用 MinIO；Milvus 自己连接哪个对象存储，应在 Milvus 部署中配置，
+这里不会更改 Milvus 的底层存储设置。
+
+设置与条目同在一个文件里（`storePath`，默认 `.redteam-memory.json`；相对名由宿主按**插件自己的工作区**解析，
+实测落点是 `/home/kali/桌面/`，见 [开发约定 §5.1](../../docs/DEVELOPMENT.md)）。
+写不进那个目录时面板会显示失败原因，把「存储文件」改成能写的绝对路径即可。
+
+## 用法
+
+**给模型用的三个工具**
+
+| 工具 | 用途 |
+|---|---|
+| `memory_search` | 按自然语言检索知识库。命中返回标题、类型、标签、正文与分数（启用重排时同时给出召回分与重排分） |
+| `memory_add` | 写一条知识进去（正文 / 标题 / 类型 / 标签 / 来源） |
+| `memory_delete` | 按 id 删除（id 从检索结果里拿） |
+
+**对话捕获（不用调工具）**：会话里出现触发词（默认「写入记忆 / 记到记忆 / 存到记忆 / 记住这个 /
+remember this…」，面板可改）时，那条用户消息会被自动收进本地库，来源标成 `对话捕获 · <会话标题>`。
+只认**用户消息**（模型回复里的「记忆」多半是在解释功能本身），同一个事件重放不会写第二条。
+
+**两个界面**
+
+```
+红队记忆（侧栏面板，只用不管配）
+┌ 顶栏：本地 N 条 · 索引 M 条（待同步 k）· 向量模型是否配好 + 指路「设置 → 红队设置」
+├ 知识库：同步索引（待同步 k）；不再展示查询框或内置知识包按钮
+│        导入文件：[绝对路径] [导入]           ← 支持 pdf / word(.docx) / md / txt
+│        对话捕获：默认折叠成一行（开关 · 触发词 N 个 · 最近捕获 N 条），展开才配置
+│        列表：勾选 / 标题（点开看全文）/ 类型 / 标签 / 索引（已索引 · 仅本地）/ 更新时间
+│        底部：删除选中 · 删除向量索引
+├ 检索：query + topK + 是否重排 → 命中（标注向量 / 本地关键词 / 混合，召回分与重排分并列）
+└ 日志：最近操作与错误
+
+红队设置（DSH 设置里的一页，只配不管用）
+├ 记忆与向量存储：Milvus / 向量模型 / 重排模型 / MinIO / 本地库 + 四个测试按钮
+│ + 保存记忆设置 · 同步索引 · 整库重建索引 · 删除向量索引 · 列举 MinIO 对象 · 导出到 MinIO
+└ 报告设置组件（报告插件提供；未启用时显示提示）
+```
+
+**导入方式**
+
+知识库界面只保留**文件导入**，不再提供「导入内置知识包」按钮，也不会自动灌入种子知识。
+后端 `seed` RPC 为兼容旧调用保留，但没有对应界面入口。
+
+**文件**：**只认四类** —— `pdf` / `word(.docx)` / `md` / `txt`。别的格式会被直接拒绝并说明原因
+   （不猜、也不静默失败）。解析都不引依赖：md 与 txt 直接读；word 用 `unzip -p … word/document.xml`
+   抽正文并反转义；pdf 用 `pdftotext -layout`（poppler）。md 按 `##` 分节，word / pdf 按段落
+   归拢成约 2000 字一条；长文入库时再自动切块（每块 1200 字符、重叠 120）。
+
+**删除**：面板勾选删除、删除整个 collection（本地库不动，下次同步自动重建 collection），
+或让模型用 `memory_delete`。删除**先删本地**，删索引是尽力而为 —— 连不上向量库不该让本地条目删不掉。
+
+**给别的插件用**：本插件对外提供 `redteamMemory` 服务（`add` / `search` / `stats`），
+报告插件就是靠它把成稿导入记忆的，不必各自去读写存储文件。
+
+## 已知限制
+
+- **同一条内容重复导入是同 id 覆盖**（条目 id 由 类型+标题+正文 哈希而来，索引行 id 由
+  条目 id+块号+内容指纹 而来），所以想更新一条知识，改完再导一次即可，不会堆重复。
+- **改过的条目会在索引里留下旧行的孤儿**：id 是内容哈希，改正文等于换了 id，旧行不会被自动删掉。
+  在意的话按「整库重建索引」前先「删除 collection」。
+- **本地关键词检索是兜底，不是替代**：中文按 2 字滑窗 + 英文按空白切词做打分（标题×3 / 标签×2 / 正文×1）。
+  同义词、跨语言、语义相近都指望不上，那些要靠向量检索。
+- **索引可能落后于本地库**：面板顶栏的「待同步 N」就是差距；检索会把本地库里索引没有的条目并进结果
+  （命中上标了「本地」），topK 用满时它们排在向量命中之后。
+- **检索质量取决于向量模型与维度**。默认维度取自模型预设；自己填错维度会在建集合时被拦住。
+- **重排失败不会拖垮检索**：会记一条警告并退回原始召回顺序（`reranked` 标记为 false）。
+- **pdf / word 导入依赖机器上的命令**：`pdftotext`（poppler-utils）与 `unzip`。缺了会明确报错
+  并说明装什么，而不是抽出一堆乱码。老式 `.doc` 不支持（请先另存为 `.docx`）。
+- S3 只做了**关联**层面的能力（测连通、列举、整库导出），不负责 Milvus 自身的备份调度。
+
+## 版本
+
+当前包版本以 `package.json` 为准。`src/` 是权威源码，`lib/` 由构建脚本生成；
+发布前必须运行构建和同步检查。当前源码已正式包含统一设置页、MinIO 展示名称、知识库操作栏精简、
+连接测试业务错误响应，以及静态 Host 的 `tools` 硬依赖声明。以下保留历史版本说明。
+
+`0.3.0` 把架构改成**本地优先**、加上对话捕获，并按「只用 / 只配」拆开了界面：
+
+- **本地库成为权威数据**，Milvus 降级为派生索引。原来「写入 = 先向量化再插 Milvus」，
+  没配 Key 时 `memory_add` 直接 401 失败、内容丢掉；现在**先落本地（一定成功）**，
+  索引同步失败只记一条日志，配好后点「同步索引」补齐。
+- **检索加了本地关键词兜底**：没配向量模型也能查，配了但索引落后时两条路的结果会合并，
+  命中上标注来源（向量 / 本地）。
+- **对话捕获**：监听 `session/event`，命中触发词就把那条用户消息收进本地库（含干跑与最近捕获列表）。
+- **删除改成先删本地**，索引删除尽力而为；列表、详情、S3 导出都改读本地库。
+- 版本号升级不再丢设置（按字段合并，只有条目结构变化时才需要重建）。
+- **对外提供 `redteamMemory` 服务**，供报告插件导入成稿。
+- **界面重做**：配置从记忆面板搬进 DSH 设置的一页「红队设置」（`settings.section`）；
+  记忆面板只剩三件事（知识库 / 检索 / 日志），对话捕获默认折叠成一行。
+  颜色全部改用主题 token（`--dsw-alias-bg-layer-1/2`、`--dsw-alias-label-secondary`…）——
+  之前几个变量名是猜的，猜错就掉回硬编码 rgba，深色主题下会脏。
+- **导入收窄成 pdf / word(.docx) / md / txt**（原来还有 `.json` 与粘贴导入两块界面）。
+
+`0.2.0` 是第一个可用版本：Milvus + 向量模型 + 重排 + S3 关联 + 导入/删除/列表/检索，
+三件套模型工具与内置知识包。`0.1.0` 是只有目录与构建链路的骨架。
+
+修复的骨架缺陷（都是从资产图谱复制骨架时带过来的）：
+
+- **客户端 RPC 路径被写死成 `/dsh-redteam-asset-graph/rpc`** —— 面板会去打资产图谱的路由，
+  请求全 404，两者同时安装还会读到对方的数据（与资产图谱 README 记的那次事故同一个根因）。
+  现在由生成器按包名填充，并把**实际请求的 url** 钉进渲染测试。
+- **静态 head 缺 JSON Schema → ParameterSchemaSpec 的转换**，三个工具会在 apply 时全部注册失败。
+- **列表加载的 `useEffect` 依赖漏了 Milvus 地址**：snapshot 是挂载之后才到的，依赖不变效果不重跑，
+  首屏列表永远是空的。
+- **模型下拉按「已保存的」服务商算候选项**：界面上切服务商后，模型列表要保存一次才跟着变。
+
+## 开发
+
+```bash
+npm run build:lib     # 生成 lib/
+npm run check:lib     # 校验与 src/ 是否漂移（prepack 会跑）
+npm test              # 主机侧 176 项 + 客户端/真实 Cordis 生命周期 120 项
+```
+
+主机侧测试不需要真 Milvus / 真向量服务：HTTP 全走 `shell`+`curl`，测试塞了一个假 shell
+按 URL 返回构造好的响应，并断言**我们发出去的请求长什么样**（端点、鉴权头、body 结构、
+维度、过滤器写法）—— 那是最容易写错、也最难在真实环境里定位的部分。
+
+其中三组用例专门盯这次改动的要害：**离线可用**（没配任何外部服务时必须一个 HTTP 请求都不发）、
+**对话捕获**（把监听器抓出来直接投一个 `user/message` 事件，验证真的落库、重放不写第二条、
+只认用户消息、关掉开关就不再写）、**对外服务**（`redteamMemory` 的 add/search/stats）。
+
+`test:flow` 需要解析 `@deepseek-ai/dsh-tools`；解析不到时会**红**并给出修复命令
+（刻意不静默跳过：绿但没跑比红更糟）。
+
+改之前请先读仓库的 [../../docs/DEVELOPMENT.md](../../docs/DEVELOPMENT.md)。
+
+| 文件 | 说明 |
+|---|---|
+| `src/host.js` | `applyHost` 的**函数体**（函数头/垫片/收尾在 `lib/parts/`，不要重复写） |
+| `src/client.js` | 客户端半边，以 `return { name, inject, apply }` 结尾 |
+| `lib/parts/` | 生成器模板：垫片与包装都在这里 |
+| `tools/build-lib.mjs` | 生成器 |
+| `cordis.patch.yml` | bundle patch，`dsh plugin add` 靠它自动挂载 |

package/cordis.patch.yml

@@ -0,0 +1,10 @@
+# dsh-redteam-memory 的 bundle patch。
+#
+# `dsh plugin --profile <name> add dsh-redteam-memory` 装完，reconcilePlugins 发现本包声明了
+# dsh.bundle.patch，就把包名并入 dsh.profile.bundles —— 插行由此生效，无需手工编辑配置。
+#
+# 语义提醒：patch 条目是 PatchOptions。带 id 的是「改某行配置」，
+# 只有 insert 且不带 id 才是往根列表追加新行（下面就是）。
+- insert:
+    - id: redteam-memory
+      name: 'dsh-redteam-memory'