@dsh-fly/dsh-plugin-fly-engagement 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DSH Fly contributors
+
+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

@@ -1,3 +1,28 @@
-# Temporary Holding Version
+# @dsh-fly/dsh-plugin-fly-engagement
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+DSH Fly 的 **engagement 记录面**（Security / CTF 作战室的"把发现沉淀下来"那一半）：
+
+- **agent 平面**（`tools/index.js`，由 Fly preset 按会话挂载）：`eng_record`（goal/facts/findings/assets/edges，
+  漏洞**必须带复现步骤**）、`eng_state`（投影 + `counts`/`dropped`/`refused`/`truncated`）、
+  `eng_report`（全量 Markdown 报告）。
+- **宿主平面**（根 `index.js`，`inject: ['webServer','shell']`）：`GET /fly/engagement/state|report`，
+  给抽屉面板取数；两半共用 `lib/fold.mjs` 的投影口径 ⇒ 面板读数与 `eng_state` 永远同口径。
+
+存储：`<workspace>/.fly-engagement/events.jsonl`（append-only，投影 = fold）。
+**不写任何自定义会话事件**（DSH 毒药条）；文件读写全走 `ctx.shell` 接缝。
+
+借鉴 `@howmp/dsh-pentest`（MIT）的数据形状（六表 + 带词汇的边 + 必填步骤 + 双计数 + 确定性 id），
+承载面用 DSH Fly 自己的抽屉面板。设计与验收见 dsh-fly 仓 `docs/security-mode-review-and-plan.md` §11。
+
+## 形状（与 fly-smart 同一条：一个包、两种挂载）
+
+| 挂载点 | 文件 | 干什么 |
+| --- | --- | --- |
+| 宿主行（bundle patch，**裸包名**） | `index.js` | 端点 + 客户端半边（客户端半边要求行名是裸包名，带 `/` 不会被登记） |
+| agent 行（preset 指向子路径） | `tools/index.js` | 三个 `eng_*` 工具 |
+
+## 门禁
+
+```bash
+node scripts/verify.mjs      # 包内测试 + 静态钉子（毒药条 / shell 接缝 / 裸包名 / dsh.client）
+```

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# dsh-plugin-fly-engagement 的**宿主层**声明：只有工作台那一页（路径规划 §11.3b）。
+#
+# **行名必须是裸包名**：`dsh-client-modules` 的 `exactPackageSpecifier()` 对带 `/` 的行名
+# 一律返回 undefined ⇒ 客户端半边不会被登记、面板在浏览器里根本不出现（fly-smart 的 patch
+# 注释记着同一条实测）。所以本包的裸名 = 宿主平面的面板行，agent 平面的工具挪到包内子路径
+# `tools/index.js`，由 preset 按会话挂载 —— 两条纪律同时满足：
+#   ① 本 patch 里**没有** `inject: ['tools']` 的行（宿主不会在开机激活工具插件）；
+#   ② 面板这一行是裸名 ⇒ 它的客户端半边登记得上。
+- insert:
+    - id: fly-engagement-panel
+      name: @dsh-fly/dsh-plugin-fly-engagement

package/index.js

@@ -0,0 +1,101 @@
+import { foldEvents, ledgerPath, renderReport, windowView } from './lib/fold.mjs'
+
+/**
+ * fly-engagement —— **宿主平面的面板行**（根文件 = 裸包名，客户端半边才登记得上）。
+ *
+ * 形状照 `dsh-plugin-fly-smart`（一个包、两种挂载）：
+ *   · 根 `index.js`（本文件）= 宿主行：`inject: ['webServer', 'shell']`，只做
+ *     `GET /fly/engagement/state|report`；**不注册工具**（bundle patch 里没有 `inject:['tools']` 的行）；
+ *   · `tools/index.js` = agent 平面的三个 `eng_*`，由 preset 按会话挂；
+ *   · 两半共用 `lib/fold.mjs` 的投影口径 ⇒ 面板读数与 `eng_state` 永远同口径。
+ *
+ * 数据来源：`<workspace>/.fly-engagement/events.jsonl`（append-only，投影=fold），
+ * 读文件走沙箱化的 `ctx.shell` 接缝（本包不 import `node:fs`）。
+ */
+
+export const name = 'fly-engagement-panel'
+export const inject = ['webServer', 'shell']
+
+const BASE = '/fly/engagement'
+
+function shq(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`
+}
+
+async function readText(shell, file) {
+  const handle = await shell.execute(shell.resolve({ command: 'cat ' + shq(file) + ' 2>/dev/null || true' }))
+  const result = await handle.result()
+  if (result.sandbox?.denied) {
+    const error = new Error(`[sandbox: file access denied under ${result.sandbox.mode} mode]`)
+    error.name = 'SandboxError'
+    throw error
+  }
+  return result.stdout.text
+}
+
+function json(res, status, payload) {
+  const body = JSON.stringify(payload, null, 2)
+  res.writeHead(status, { 'content-type': 'application/json; charset=utf-8', 'content-length': Buffer.byteLength(body) })
+  res.end(body)
+}
+
+/** 每条路由都自述（面板的"这个面板能问什么"表，与 netops 同一条纪律）。 */
+export const endpoints = [
+  { path: `${BASE}/state`, summary: 'engagement 投影（与 eng_state 同口径）：goal/节点/边/counts/dropped/refused/truncated' },
+  { path: `${BASE}/report`, summary: '全量 Markdown 报告（与 eng_report 同一份渲染）' },
+]
+
+/**
+ * 处理一条请求。`?workspace=<绝对路径>` 必填（取不到会话 cwd 时由面板填 + 记忆）。
+ * 返回 `{ status, payload }`，由 transport 层写回 —— 纯函数，好测。
+ */
+export async function answer(shell, url) {
+  const path = String(url ?? '/')
+  if (!path.startsWith(BASE)) return { status: 404, payload: { error: 'not found', endpoints } }
+  const query = new URLSearchParams(path.slice(path.indexOf('?') + 1))
+  const workspace = query.get('workspace')
+  if (workspace === null || workspace.trim() === '') {
+    return { status: 400, payload: { error: 'missing ?workspace=<absolute path>', endpoints } }
+  }
+  if (!workspace.startsWith('/')) {
+    return { status: 400, payload: { error: 'workspace 必须是绝对路径（收到 ' + workspace + '）', endpoints } }
+  }
+  const windowSize = Math.min(2000, Math.max(1, Math.round(Number(query.get('window') ?? 200) || 200)))
+  const file = ledgerPath(workspace)
+  const state = foldEvents((await readText(shell, file)).split('\n'))
+  if (path.startsWith(BASE + '/report')) {
+    return { status: 200, payload: { workspace, ledger: file, markdown: renderReport(workspace, state) } }
+  }
+  if (path.startsWith(BASE + '/state')) {
+    return {
+      status: 200,
+      payload: {
+        workspace,
+        ledger: file,
+        window: windowSize,
+        projection: windowView(state, windowSize),
+        endpoints,
+      },
+    }
+  }
+  return { status: 404, payload: { error: 'not found', endpoints } }
+}
+
+export function apply(ctx) {
+  const shell = ctx.shell
+  ctx.effect(
+    () => ctx.webServer.register({
+      kind: 'prefix',
+      path: BASE,
+      handler: async (req, res) => {
+        try {
+          const { status, payload } = await answer(shell, req.url ?? '/')
+          json(res, status, payload)
+        } catch (error) {
+          json(res, 500, { error: String(error?.message ?? error), endpoints })
+        }
+      },
+    }),
+    'fly-engagement: ' + BASE + '/*',
+  )
+}

package/lib/client.js

@@ -0,0 +1,400 @@
+/* @dsh-fly/dsh-plugin-fly-engagement — browser half, built by scripts/build-plugin-client.mjs.
+ * src-hash: dfc489bb58d29d86b67f417b96d83c86f598b665a6426ab841f69745bd106120
+ * Factory-form CJS: the loader calls the factory with its platform `require`
+ * and memoizes the returned exports. Keep the banner so the loader id and the
+ * package that produced the bundle stay greppable in a live page. */
+window.__ModuleLoader__.load({
+  id: "@dsh-fly/dsh-plugin-fly-engagement",
+  factory: (require) => {
+    var module = { exports: {} };
+    var exports = module.exports;
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const jsxRuntime = require("react/jsx-runtime");
+const react = require("react");
+const name = "fly-engagement-panel";
+const inject = ["slots", "sidebarRightTabs"];
+const PACKAGE = "@dsh-fly/dsh-plugin-fly-engagement";
+const KIND = "fly.engagement";
+const TAB_TITLE = "Engagement";
+const TAB_DESCRIPTION = "目标 / 资产 / 漏洞 / 证据图";
+const GUIDE_ORDER = 12;
+const BASE = "/fly/engagement";
+const STORE_KEY = "fly.engagement.workspace";
+const PANEL_CSS = `/*
+ * fly-engagement 抽屉面板 —— **目标效果图的样式表**（2026-10-18，等用户判方向）
+ *
+ * 这张表就是实现时的对照物：类名 / token / 尺寸都按真面板的约定写（'.fly-eg-*' 前缀，
+ * 与 shell 的 '.fly-*' 一族同形），所以"照图实现"不会漂移成另一套。
+ *
+ * token 纪律：这里因为要**独立渲染**（没有宿主 skin），把深色底值写进 ':root' 兜底；
+ * 实现时一律 'var(--dsw-alias-*, 兜底)' —— 真宿主会给出 token，兜底只在 mock/降级时生效。
+ * 面板框（rail 8px / desk 12px / 3px 亮缘）照 '.fly-panel' 的结构，不再发明第二套。
+ */
+:root {
+  --dsw-alias-bg-base: #070b12;
+  --dsw-alias-bg-layer-1: rgba(255, 255, 255, 0.045);
+  --dsw-alias-bg-layer-2: rgba(255, 255, 255, 0.07);
+  --dsw-alias-fg-primary: #e8eef8;
+  --dsw-alias-fg-secondary: #9fb0c6;
+  --dsw-alias-fg-muted: #6b7d95;
+  --dsw-alias-border-l1: rgba(255, 255, 255, 0.10);
+  --fly-accent: #f0a55a;
+  --fly-accent-dim: rgba(240, 165, 90, 0.16);
+  --fly-critical: #ff5f6d;
+  --fly-high: #ff9b52;
+  --fly-medium: #e8c54a;
+  --fly-low: #6fc2ff;
+  --fly-info: #8fa3bd;
+}
+
+* { box-sizing: border-box; }
+body {
+  margin: 0;
+  padding: var(--fly-desk, 12px);
+  background: #05080d;
+  font: 13px/1.5 -apple-system, "SF Pro Text", "PingFang SC", system-ui, sans-serif;
+  color: var(--dsw-alias-fg-primary);
+}
+
+/* ── 面板框：照 .fly-panel 的结构（rail 8px / 3px 亮缘 / 底部关系型亮缘） ── */
+.fly-eg-panel {
+  --fly-rail: 8px;
+  width: 760px;
+  border-radius: 12px;
+  border: 1px solid var(--dsw-alias-border-l1);
+  background:
+    radial-gradient(900px 320px at 12% -12%, rgba(240, 165, 90, 0.10), transparent 70%),
+    linear-gradient(180deg, rgba(255, 255, 255, 0.05), rgba(255, 255, 255, 0) 42%),
+    var(--dsw-alias-bg-base);
+  padding: var(--fly-rail) calc(var(--fly-rail) + 6px) calc(var(--fly-rail) + 8px);
+  box-shadow: 0 18px 48px rgba(0, 0, 0, 0.55), inset 0 1px 0 rgba(255, 255, 255, 0.06);
+}
+
+/* ── 头部：工作区 + goal + authorization ── */
+.fly-eg-head { display: flex; flex-direction: column; gap: 6px; padding-bottom: 10px; border-bottom: 1px solid var(--dsw-alias-border-l1); }
+.fly-eg-title { display: flex; align-items: baseline; gap: 8px; }
+.fly-eg-title h1 { margin: 0; font-size: 15px; font-weight: 600; letter-spacing: 0.2px; }
+.fly-eg-badge { font-size: 11px; padding: 1px 7px; border-radius: 999px; background: var(--fly-accent-dim); color: var(--fly-accent); border: 1px solid rgba(240, 165, 90, 0.35); }
+.fly-eg-meta { font-size: 11.5px; color: var(--dsw-alias-fg-secondary); display: flex; flex-wrap: wrap; gap: 10px; }
+.fly-eg-mono { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 11.5px; color: var(--dsw-alias-fg-primary); }
+.fly-eg-auth { font-size: 11.5px; color: var(--dsw-alias-fg-muted); }
+.fly-eg-auth b { color: var(--fly-accent); font-weight: 600; }
+
+/* ── 计数读数：counts + dropped/refused/truncated（截断显眼） ── */
+.fly-eg-counters { display: flex; gap: 4px; margin: 8px 0; flex-wrap: wrap; align-items: center; }
+.fly-eg-counter { border: 1px solid var(--dsw-alias-border-l1); background: var(--dsw-alias-bg-layer-1); border-radius: 6px; padding: 2px 6px; font-size: 10.5px; line-height: 1.5; color: var(--dsw-alias-fg-muted); }
+.fly-eg-counter b { margin-left: 3px; font-size: 11px; }
+.fly-eg-counter b { color: var(--dsw-alias-fg-primary); font-weight: 600; margin-left: 5px; }
+.fly-eg-counter.is-warn { border-color: rgba(255, 95, 109, 0.45); background: rgba(255, 95, 109, 0.10); color: #ffb8be; }
+.fly-eg-counter.is-warn b { color: #ffd7da; }
+
+/* ── 表/图 切换（借 dsh-pentest AssetsView 的两模式） ── */
+.fly-eg-tabs { display: inline-flex; gap: 2px; padding: 2px; border: 1px solid var(--dsw-alias-border-l1); border-radius: 8px; background: var(--dsw-alias-bg-layer-1); margin-bottom: 10px; }
+.fly-eg-tab { font-size: 11.5px; padding: 3px 10px; border-radius: 6px; color: var(--dsw-alias-fg-secondary); }
+.fly-eg-tab.is-active { background: rgba(240, 165, 90, 0.18); color: var(--fly-accent); }
+
+/* ── 分区标题 ── */
+.fly-eg-section { margin-top: 12px; }
+.fly-eg-section > h2 { margin: 0 0 6px; font-size: 12px; font-weight: 600; color: var(--dsw-alias-fg-secondary); letter-spacing: 0.4px; text-transform: uppercase; }
+
+/* ── 表 ── */
+.fly-eg-table { width: 100%; border-collapse: collapse; font-size: 12px; }
+.fly-eg-table th { text-align: left; font-weight: 500; color: var(--dsw-alias-fg-muted); font-size: 11px; padding: 4px 6px; border-bottom: 1px solid var(--dsw-alias-border-l1); }
+.fly-eg-table td { padding: 5px 6px; border-bottom: 1px solid rgba(255, 255, 255, 0.05); vertical-align: top; }
+.fly-eg-id { font-family: ui-monospace, Menlo, monospace; font-size: 11px; color: var(--dsw-alias-fg-muted); }
+.fly-eg-src { font-size: 11px; color: var(--dsw-alias-fg-muted); }
+.fly-eg-src b { color: var(--dsw-alias-fg-secondary); font-weight: 500; }
+.fly-eg-sev { font-size: 11px; font-weight: 600; padding: 1px 7px; border-radius: 999px; display: inline-block; }
+.fly-eg-sev.critical { color: #fff; background: var(--fly-critical); }
+.fly-eg-sev.high { color: #1a0f06; background: var(--fly-high); }
+.fly-eg-sev.medium { color: #1a1506; background: var(--fly-medium); }
+.fly-eg-sev.low { color: #061019; background: var(--fly-low); }
+.fly-eg-sev.info { color: #0b1017; background: var(--fly-info); }
+.fly-eg-steps { margin: 4px 0 0 0; padding-left: 18px; color: var(--dsw-alias-fg-secondary); font-size: 11.5px; }
+.fly-eg-steps code, .fly-eg-cmd { font-family: ui-monospace, Menlo, monospace; font-size: 11px; background: rgba(255, 255, 255, 0.06); padding: 0 4px; border-radius: 4px; }
+
+/* ── 图区：静态分层 + 边胶囊 + 只读（借 xyflow 的形状，不引入拖拽） ── */
+.fly-eg-graph { position: relative; height: 300px; border: 1px solid var(--dsw-alias-border-l1); border-radius: 10px; background: radial-gradient(600px 240px at 50% 0%, rgba(255,255,255,0.035), transparent 70%), var(--dsw-alias-bg-layer-1); overflow: hidden; }
+.fly-eg-graph-hint { position: absolute; left: 8px; bottom: 6px; font-size: 10.5px; color: var(--dsw-alias-fg-muted); }
+.fly-eg-graph-badge { position: absolute; right: 8px; top: 8px; font-size: 10.5px; padding: 2px 7px; border-radius: 999px; border: 1px solid rgba(255, 95, 109, 0.45); background: rgba(255, 95, 109, 0.12); color: #ffb8be; }
+.fly-eg-node { position: absolute; transform: translate(-50%, -50%); border-radius: 8px; border: 1px solid var(--dsw-alias-border-l1); background: var(--dsw-alias-bg-layer-2); padding: 5px 9px; font-size: 11.5px; white-space: nowrap; }
+.fly-eg-node.is-finding { border-color: rgba(255, 155, 82, 0.55); background: rgba(255, 155, 82, 0.14); color: #ffd7b0; }
+.fly-eg-node.is-asset { border-color: rgba(111, 194, 255, 0.45); background: rgba(111, 194, 255, 0.12); color: #cbe8ff; }
+.fly-eg-edge { position: absolute; height: 1.5px; background: rgba(240, 165, 90, 0.55); transform-origin: 0 50%; }
+.fly-eg-edge-cap { position: absolute; font-size: 10px; color: var(--fly-accent); background: rgba(7, 11, 18, 0.85); padding: 0 4px; border-radius: 4px; border: 1px solid rgba(240, 165, 90, 0.3); }
+
+/* ── 报告区 ── */
+.fly-eg-report { border: 1px solid var(--dsw-alias-border-l1); border-radius: 10px; background: var(--dsw-alias-bg-layer-1); padding: 8px 10px; font-size: 11.5px; color: var(--dsw-alias-fg-secondary); }
+.fly-eg-report-actions { display: flex; gap: 6px; margin-top: 8px; }
+.fly-eg-btn { font-size: 11.5px; padding: 3px 10px; border-radius: 7px; border: 1px solid var(--dsw-alias-border-l1); background: var(--dsw-alias-bg-layer-2); color: var(--dsw-alias-fg-primary); }
+
+/* 图区的线走 SVG（按节点实测中心算），不用手摆坐标 —— 实现时同样按数据算 */
+.fly-eg-wires { position: absolute; inset: 0; pointer-events: none; }
+
+/* 连线走**折线**（elbow）：横向只占层间那一段，纵向在间隙里走 —— 比直线省横向空间。
+   实现时同样用 SVG path（M/H/V 折角 + stroke-linejoin:round）。 */
+.fly-eg-wire { fill: none; stroke: rgba(240, 165, 90, 0.55); stroke-width: 1.5; stroke-linejoin: round; stroke-linecap: round; }
+
+/* ── 事实按来源工具折叠（<details>，缺省收起：长会话省地方） ── */
+.fly-eg-group { border: 1px solid var(--dsw-alias-border-l1); border-radius: 8px; background: var(--dsw-alias-bg-layer-1); margin-bottom: 4px; }
+.fly-eg-group > summary { cursor: default; list-style: none; padding: 4px 8px; font-size: 11.5px; color: var(--dsw-alias-fg-secondary); display: flex; align-items: center; gap: 6px; }
+.fly-eg-group > summary::-webkit-details-marker { display: none; }
+.fly-eg-group > summary::before { content: '▸'; color: var(--dsw-alias-fg-muted); font-size: 10px; }
+.fly-eg-group[open] > summary::before { content: '▾'; }
+.fly-eg-group > summary b { color: var(--dsw-alias-fg-primary); font-weight: 600; }
+.fly-eg-group > summary .fly-eg-count { margin-left: auto; font-size: 10.5px; color: var(--dsw-alias-fg-muted); }
+.fly-eg-group table { margin: 0 0 2px; }
+
+.fly-eg-input { width: 100%; font: inherit; font-size: 11.5px; padding: 3px 8px; border-radius: 7px; border: 1px solid var(--dsw-alias-border-l1); background: var(--dsw-alias-bg-layer-1); color: var(--dsw-alias-fg-primary); }
+.fly-eg-error { margin: 8px 0; padding: 6px 9px; border-radius: 8px; border: 1px solid rgba(255,95,109,0.45); background: rgba(255,95,109,0.10); color: #ffb8be; font-size: 11.5px; }
+.fly-eg-empty { margin: 14px 0; color: var(--dsw-alias-fg-muted); font-size: 11.5px; }
+`;
+async function getJson(path) {
+  const response = await fetch(path, { headers: { accept: "application/json" } });
+  if (!response.ok) throw new Error(path + " → HTTP " + response.status);
+  return await response.json();
+}
+function Graph({ nodes, edges, kind }) {
+  const byLayer = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    const list = byLayer.get(node.layer) ?? [];
+    list.push(node);
+    byLayer.set(node.layer, list);
+  }
+  const layers = [...byLayer.keys()].sort((a, b) => a - b);
+  const widest = Math.max(120, ...nodes.map((node) => node.label.length * 6.6 + 20));
+  const gap = 78;
+  const xOf = /* @__PURE__ */ new Map();
+  let cursor = 60;
+  for (const layer of layers) {
+    for (const node of byLayer.get(layer) ?? []) xOf.set(node.id, cursor + widest / 2);
+    cursor += widest + gap;
+  }
+  const height = Math.max(180, ...layers.map((layer) => (byLayer.get(layer) ?? []).length * 54));
+  const yOf = /* @__PURE__ */ new Map();
+  for (const layer of layers) {
+    const list = byLayer.get(layer) ?? [];
+    list.forEach((node, index) => yOf.set(node.id, height / (list.length + 1) * (index + 1)));
+  }
+  return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "fly-eg-graph", style: { height: height + 60 }, children: [
+    /* @__PURE__ */ jsxRuntime.jsx("svg", { className: "fly-eg-wires", width: "100%", height: "100%", children: edges.filter((edge) => xOf.has(edge.from) && xOf.has(edge.to)).map((edge) => {
+      const x1 = (xOf.get(edge.from) ?? 0) + widest / 2;
+      const x2 = (xOf.get(edge.to) ?? 0) - widest / 2;
+      const midX = (x1 + x2) / 2;
+      return /* @__PURE__ */ jsxRuntime.jsx("path", { className: "fly-eg-wire", d: "M " + x1 + " " + yOf.get(edge.from) + " H " + midX + " V " + yOf.get(edge.to) + " H " + x2 }, kind + edge.from + edge.to);
+    }) }),
+    nodes.map((node) => /* @__PURE__ */ jsxRuntime.jsx(
+      "div",
+      {
+        className: "fly-eg-node" + (node.tone === "finding" ? " is-finding" : node.tone === "asset" ? " is-asset" : ""),
+        style: { left: xOf.get(node.id), top: yOf.get(node.id) },
+        children: node.label
+      },
+      node.id
+    )),
+    /* @__PURE__ */ jsxRuntime.jsx("div", { className: "fly-eg-graph-hint", children: "折线走层间间隙 · 静态分层 · 只读" })
+  ] });
+}
+function Panel() {
+  const [workspace, setWorkspace] = react.useState(() => localStorage.getItem(STORE_KEY) ?? "");
+  const [state, setState] = react.useState(null);
+  const [error, setError] = react.useState("");
+  const [view, setView] = react.useState("table");
+  const [report, setReport] = react.useState("");
+  const load = react.useCallback(async (target) => {
+    if (target.trim() === "") return;
+    setError("");
+    try {
+      const [next, rendered] = await Promise.all([
+        getJson(BASE + "/state?workspace=" + encodeURIComponent(target)),
+        getJson(BASE + "/report?workspace=" + encodeURIComponent(target)).catch(() => ({ markdown: "" }))
+      ]);
+      setState(next);
+      setReport(rendered.markdown);
+      localStorage.setItem(STORE_KEY, target);
+    } catch (failure) {
+      setError(String(failure.message ?? failure));
+      setState(null);
+    }
+  }, []);
+  react.useEffect(() => {
+    void load(workspace);
+  }, [load, workspace]);
+  const projection = state?.projection;
+  const groups = react.useMemo(() => {
+    const map = /* @__PURE__ */ new Map();
+    for (const fact of projection?.facts ?? []) {
+      const tool = fact.source?.tool ?? "(unknown tool)";
+      map.set(tool, [...map.get(tool) ?? [], fact]);
+    }
+    return [...map.entries()].sort((a, b) => b[1].length - a[1].length);
+  }, [projection]);
+  return /* @__PURE__ */ jsxRuntime.jsxs("section", { className: "fly-eg-panel", children: [
+    /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "fly-eg-head", children: [
+      /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "fly-eg-title", children: [
+        /* @__PURE__ */ jsxRuntime.jsx("h1", { children: "Engagement" }),
+        projection?.goal === null || projection === void 0 ? null : /* @__PURE__ */ jsxRuntime.jsx("span", { className: "fly-eg-badge", children: projection.goal.target })
+      ] }),
+      /* @__PURE__ */ jsxRuntime.jsx("div", { className: "fly-eg-meta", children: /* @__PURE__ */ jsxRuntime.jsx(
+        "input",
+        {
+          className: "fly-eg-input",
+          value: workspace,
+          placeholder: "工作区绝对路径（记录在 <workspace>/.fly-engagement/events.jsonl）",
+          onChange: (event) => setWorkspace(event.target.value),
+          onKeyDown: (event) => {
+            if (event.key === "Enter") void load(workspace);
+          }
+        }
+      ) }),
+      projection?.goal === null || projection === void 0 ? null : /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+        /* @__PURE__ */ jsxRuntime.jsx("div", { className: "fly-eg-meta", children: /* @__PURE__ */ jsxRuntime.jsxs("span", { children: [
+          "objective: ",
+          projection.goal.objective
+        ] }) }),
+        /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "fly-eg-auth", children: [
+          "authorization: ",
+          /* @__PURE__ */ jsxRuntime.jsx("b", { children: projection.goal.authorization === void 0 || projection.goal.authorization === "" ? "（未记录）" : projection.goal.authorization }),
+          " · 审计事实，不是门禁"
+        ] })
+      ] })
+    ] }),
+    error !== "" ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: "fly-eg-error", children: error }) : null,
+    projection === void 0 ? /* @__PURE__ */ jsxRuntime.jsx("div", { className: "fly-eg-empty", children: "还没读取记录（填工作区后回车）" }) : /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+      /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "fly-eg-counters", children: [
+        /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "fly-eg-counter", children: [
+          "facts",
+          /* @__PURE__ */ jsxRuntime.jsx("b", { children: projection.counts.facts })
+        ] }),
+        /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "fly-eg-counter", children: [
+          "findings",
+          /* @__PURE__ */ jsxRuntime.jsx("b", { children: projection.counts.findings })
+        ] }),
+        /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "fly-eg-counter", children: [
+          "assets",
+          /* @__PURE__ */ jsxRuntime.jsx("b", { children: projection.counts.assets })
+        ] }),
+        /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "fly-eg-counter", children: [
+          "edges",
+          /* @__PURE__ */ jsxRuntime.jsx("b", { children: projection.counts.edges })
+        ] }),
+        /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "fly-eg-counter" + (projection.dropped > 0 ? " is-warn" : ""), children: [
+          "dropped",
+          /* @__PURE__ */ jsxRuntime.jsx("b", { children: projection.dropped })
+        ] }),
+        /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "fly-eg-counter" + (projection.refused > 0 ? " is-warn" : ""), children: [
+          "refused",
+          /* @__PURE__ */ jsxRuntime.jsx("b", { children: projection.refused })
+        ] })
+      ] }),
+      /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "fly-eg-tabs", children: [
+        /* @__PURE__ */ jsxRuntime.jsx("span", { className: "fly-eg-tab" + (view === "table" ? " is-active" : ""), onClick: () => setView("table"), children: "表" }),
+        /* @__PURE__ */ jsxRuntime.jsx("span", { className: "fly-eg-tab" + (view === "graph" ? " is-active" : ""), onClick: () => setView("graph"), children: "图" })
+      ] }),
+      view === "table" ? /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+        /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "fly-eg-section", children: [
+          /* @__PURE__ */ jsxRuntime.jsx("h2", { children: "Assets" }),
+          /* @__PURE__ */ jsxRuntime.jsx("table", { className: "fly-eg-table", children: /* @__PURE__ */ jsxRuntime.jsx("tbody", { children: projection.assets.map((asset) => /* @__PURE__ */ jsxRuntime.jsxs("tr", { children: [
+            /* @__PURE__ */ jsxRuntime.jsx("td", { className: "fly-eg-id", children: asset.id }),
+            /* @__PURE__ */ jsxRuntime.jsx("td", { children: asset.type }),
+            /* @__PURE__ */ jsxRuntime.jsx("td", { children: asset.value }),
+            /* @__PURE__ */ jsxRuntime.jsx("td", { className: "fly-eg-src", children: asset.parentId ?? "—" })
+          ] }, asset.id)) }) })
+        ] }),
+        /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "fly-eg-section", children: [
+          /* @__PURE__ */ jsxRuntime.jsx("h2", { children: "Findings" }),
+          /* @__PURE__ */ jsxRuntime.jsx("table", { className: "fly-eg-table", children: /* @__PURE__ */ jsxRuntime.jsx("tbody", { children: projection.findings.map((finding) => /* @__PURE__ */ jsxRuntime.jsxs("tr", { children: [
+            /* @__PURE__ */ jsxRuntime.jsx("td", { className: "fly-eg-id", children: finding.id }),
+            /* @__PURE__ */ jsxRuntime.jsx("td", { children: /* @__PURE__ */ jsxRuntime.jsx("span", { className: "fly-eg-sev " + (finding.severity ?? "info"), children: finding.severity ?? "info" }) }),
+            /* @__PURE__ */ jsxRuntime.jsx("td", { children: finding.title }),
+            /* @__PURE__ */ jsxRuntime.jsx("td", { children: /* @__PURE__ */ jsxRuntime.jsx("ol", { className: "fly-eg-steps", children: finding.reproducibleSteps.map((step, index) => /* @__PURE__ */ jsxRuntime.jsx("li", { children: /* @__PURE__ */ jsxRuntime.jsx("code", { children: step }) }, index)) }) })
+          ] }, finding.id)) }) })
+        ] }),
+        /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "fly-eg-section", children: [
+          /* @__PURE__ */ jsxRuntime.jsx("h2", { children: "Facts · by source tool" }),
+          groups.map(([tool, facts], index) => /* @__PURE__ */ jsxRuntime.jsxs("details", { className: "fly-eg-group", open: index === 0, children: [
+            /* @__PURE__ */ jsxRuntime.jsxs("summary", { children: [
+              /* @__PURE__ */ jsxRuntime.jsx("b", { children: tool }),
+              /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "fly-eg-count", children: [
+                facts.length,
+                " 条"
+              ] })
+            ] }),
+            /* @__PURE__ */ jsxRuntime.jsx("table", { className: "fly-eg-table", children: /* @__PURE__ */ jsxRuntime.jsx("tbody", { children: facts.map((fact) => /* @__PURE__ */ jsxRuntime.jsxs("tr", { children: [
+              /* @__PURE__ */ jsxRuntime.jsx("td", { className: "fly-eg-id", children: fact.id }),
+              /* @__PURE__ */ jsxRuntime.jsx("td", { children: fact.detail })
+            ] }, fact.id)) }) })
+          ] }, tool))
+        ] }),
+        /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "fly-eg-section", children: [
+          /* @__PURE__ */ jsxRuntime.jsx("h2", { children: "Report" }),
+          /* @__PURE__ */ jsxRuntime.jsx("div", { className: "fly-eg-report", children: report === "" ? "（还没有可渲染的报告）" : report.slice(0, 2e3) })
+        ] })
+      ] }) : /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+        /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "fly-eg-section", children: [
+          /* @__PURE__ */ jsxRuntime.jsx("h2", { children: "Evidence graph" }),
+          /* @__PURE__ */ jsxRuntime.jsx(
+            Graph,
+            {
+              kind: "proves",
+              nodes: [
+                ...projection.facts.map((fact, index) => ({ id: fact.id, label: fact.id + " " + (fact.kind ?? "info"), layer: 0, tone: void 0 })),
+                ...projection.findings.map((finding) => ({ id: finding.id, label: finding.id + " " + finding.title, layer: 1, tone: "finding" }))
+              ],
+              edges: projection.edges.filter((edge) => edge.kind === "proves" || edge.kind === "derived_from")
+            }
+          )
+        ] }),
+        /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "fly-eg-section", children: [
+          /* @__PURE__ */ jsxRuntime.jsx("h2", { children: "Asset tree" }),
+          /* @__PURE__ */ jsxRuntime.jsx(
+            Graph,
+            {
+              kind: "parent",
+              nodes: projection.assets.map((asset) => ({ id: asset.id, label: asset.value + " (" + asset.type + ")", layer: asset.parentId === void 0 ? 0 : 1, tone: "asset" })),
+              edges: projection.edges.filter((edge) => edge.kind === "parent")
+            }
+          )
+        ] })
+      ] })
+    ] })
+  ] });
+}
+function EngagementMark({ size = 18, active = false }) {
+  return /* @__PURE__ */ jsxRuntime.jsxs("svg", { className: "fly-mark", "data-active": active ? "true" : "false", width: size, height: size, viewBox: "0 0 24 24", fill: "none", "aria-hidden": "true", children: [
+    /* @__PURE__ */ jsxRuntime.jsx("circle", { cx: "6", cy: "6", r: "2.2", stroke: "currentColor", strokeWidth: "1.6" }),
+    /* @__PURE__ */ jsxRuntime.jsx("circle", { cx: "18", cy: "12", r: "2.2", stroke: "currentColor", strokeWidth: "1.6" }),
+    /* @__PURE__ */ jsxRuntime.jsx("circle", { cx: "6", cy: "18", r: "2.2", stroke: "currentColor", strokeWidth: "1.6" }),
+    /* @__PURE__ */ jsxRuntime.jsx("path", { d: "M8 7l8 4M8 17l8-4", stroke: "currentColor", strokeWidth: "1.4", strokeLinecap: "round" })
+  ] });
+}
+function apply(ctx) {
+  ctx.effect(() => ctx.sidebarRightTabs.register({
+    id: PACKAGE,
+    kind: KIND,
+    title: () => TAB_TITLE,
+    guide: [{ id: "open", order: GUIDE_ORDER, title: () => TAB_TITLE, description: () => TAB_DESCRIPTION, icon: EngagementMark }]
+  }), "fly-engagement-panel: drawer type");
+  ctx.effect(() => {
+    const tag = document.createElement("style");
+    tag.setAttribute("data-plugin", PACKAGE);
+    tag.textContent = PANEL_CSS;
+    document.head.appendChild(tag);
+    return () => {
+      tag.remove();
+    };
+  }, "fly-engagement-panel: panel stylesheet");
+  ctx.effect(() => ctx.slots.inject("sidebar.right.pane.tab", () => ctx.slots.register(
+    { name: "sidebar.right.pane.tab", key: PACKAGE, inject: () => ({}) },
+    Panel
+  )), "fly-engagement-panel: drawer body");
+}
+exports.EngagementMark = EngagementMark;
+exports.apply = apply;
+exports.inject = inject;
+exports.name = name;
+
+    return module.exports;
+  },
+});

package/lib/fold.mjs

@@ -0,0 +1,146 @@
+/**
+ * engagement 记录的**纯函数层** —— 工具半边（agent 平面）与面板半边（宿主行）共用一份。
+ *
+ * 为什么单独成文件：这两半是两个挂载点（`tools/index.js` 由 preset 按会话挂；根 `index.js`
+ * 是宿主平面的面板行），**投影口径必须逐字一致**，否则面板上的计数和 `eng_state` 会讲两个故事。
+ * 同包内 import ⇒ 不需要"两份逐字节相同"的钉子（那是跨包才付的代价）。
+ */
+
+export const FACT_KINDS = ['net', 'service', 'http', 'binary', 'code', 'vuln', 'info']
+export const SEVERITIES = ['critical', 'high', 'medium', 'low', 'info']
+export const ASSET_TYPES = ['host', 'ip', 'port', 'service', 'url', 'file', 'binary', 'process']
+export const EDGE_KINDS = ['parent', 'proves', 'derived_from']
+
+export const LEDGER_DIR = '.fly-engagement'
+export const LEDGER_FILE = 'events.jsonl'
+
+/** `<workspace>/.fly-engagement/events.jsonl`（工作区路径尾斜杠无所谓）。 */
+export function ledgerPath(workspace) {
+  return String(workspace).replace(/\/+$/u, '') + '/' + LEDGER_DIR + '/' + LEDGER_FILE
+}
+
+/**
+ * 折叠事件流 ⇒ 完整状态（**确定性**：同一个文件永远折出同一张图）。
+ * 坏引用计入 `refused`（不是静默丢弃）。
+ */
+export function foldEvents(lines) {
+  const state = { goal: null, facts: [], findings: [], assets: [], edges: [], refused: 0 }
+  const known = () => new Set([...state.facts.map(row => row.id), ...state.findings.map(row => row.id), ...state.assets.map(row => row.id)])
+  for (const line of lines) {
+    if (line.trim() === '') continue
+    let event
+    try {
+      event = JSON.parse(line)
+    } catch {
+      state.refused += 1
+      continue
+    }
+    if (event.op === 'goal') {
+      if (state.goal !== null) { state.refused += 1; continue }
+      state.goal = event.goal
+      continue
+    }
+    if (event.op !== 'record') continue
+    const ids = known()
+    for (const asset of event.assets ?? []) {
+      if (asset.parentId !== undefined && asset.parentId !== '' && !ids.has(asset.parentId)) { state.refused += 1; continue }
+      state.assets.push(asset)
+      ids.add(asset.id)
+    }
+    for (const fact of event.facts ?? []) {
+      state.facts.push(fact)
+      ids.add(fact.id)
+    }
+    for (const finding of event.findings ?? []) {
+      if (finding.affectedAssetId !== undefined && finding.affectedAssetId !== '' && !ids.has(finding.affectedAssetId)) { state.refused += 1; continue }
+      state.findings.push(finding)
+      ids.add(finding.id)
+    }
+    for (const edge of event.edges ?? []) {
+      if (!ids.has(edge.from) || !ids.has(edge.to)) { state.refused += 1; continue }
+      state.edges.push(edge)
+    }
+  }
+  return state
+}
+
+/**
+ * 窗口视图：每张表留最新 `windowSize` 条；`dropped` 是被逐出的条数。
+ * `counts` 报**全量**、窗口只影响 rows —— 两个读数都要在（面板与 `eng_state` 同口径）。
+ */
+export function windowView(state, windowSize) {
+  const cut = rows => rows.length <= windowSize
+    ? { rows, dropped: 0 }
+    : { rows: rows.slice(rows.length - windowSize), dropped: rows.length - windowSize }
+  const facts = cut(state.facts)
+  const findings = cut(state.findings)
+  const assets = cut(state.assets)
+  const kept = new Set([...facts.rows, ...findings.rows, ...assets.rows].map(row => row.id))
+  const dropped = facts.dropped + findings.dropped + assets.dropped
+  return {
+    goal: state.goal,
+    facts: facts.rows,
+    findings: findings.rows,
+    assets: assets.rows,
+    edges: state.edges.filter(edge => kept.has(edge.from) && kept.has(edge.to)),
+    counts: { facts: state.facts.length, findings: state.findings.length, assets: state.assets.length, edges: state.edges.length },
+    dropped,
+    refused: state.refused,
+    truncated: dropped > 0,
+  }
+}
+
+/** 下一个确定性 id `<kind>-<n>`。 */
+export function nextId(prefix, rows) {
+  let max = 0
+  for (const row of rows) {
+    const match = new RegExp('^' + prefix + '-(\\d+)$', 'u').exec(row.id)
+    if (match !== null) max = Math.max(max, Number(match[1]))
+  }
+  return prefix + '-' + (max + 1)
+}
+
+/** 从全量状态渲染 Markdown 报告（`eng_report` 与 `/fly/engagement/report` 同一份）。 */
+export function renderReport(workspace, state) {
+  const lines = []
+  lines.push('# Engagement report')
+  lines.push('')
+  lines.push('- workspace: `' + workspace + '`')
+  lines.push('- ledger: `' + ledgerPath(workspace) + '`')
+  lines.push('- counts: facts=' + state.facts.length + ' findings=' + state.findings.length + ' assets=' + state.assets.length + ' edges=' + state.edges.length)
+  if (state.refused > 0) lines.push('- refused writes: ' + state.refused + '（引用不存在的 id，已拒绝）')
+  lines.push('', '## Goal', '')
+  if (state.goal === null) {
+    lines.push('_未设置（还没有 eng_record 带 goal）_')
+  } else {
+    lines.push('- target: ' + state.goal.target)
+    lines.push('- objective: ' + state.goal.objective)
+    lines.push('- authorization: ' + (state.goal.authorization === undefined || state.goal.authorization === '' ? '_未记录_（这是审计事实，不是门禁）' : state.goal.authorization))
+  }
+  lines.push('', '## Assets')
+  if (state.assets.length === 0) lines.push('', '_none_')
+  for (const asset of state.assets) {
+    const parent = asset.parentId === undefined || asset.parentId === '' ? '' : '  ← parent `' + asset.parentId + '`'
+    lines.push('- `' + asset.id + '` [' + asset.type + '] ' + asset.value + parent)
+  }
+  lines.push('', '## Findings')
+  if (state.findings.length === 0) lines.push('', '_none_')
+  for (const finding of state.findings) {
+    lines.push('', '### `' + finding.id + '` ' + finding.title + ' — **' + (finding.severity ?? 'info') + '**')
+    if (finding.description !== undefined && finding.description !== '') lines.push('', finding.description)
+    if (finding.affectedAssetId !== undefined && finding.affectedAssetId !== '') lines.push('', 'affected asset: `' + finding.affectedAssetId + '`')
+    lines.push('', 'reproducible steps (' + finding.reproducibleSteps.length + '):')
+    for (const [index, step] of finding.reproducibleSteps.entries()) lines.push((index + 1) + '. ' + step)
+  }
+  lines.push('', '## Facts')
+  if (state.facts.length === 0) lines.push('', '_none_')
+  for (const fact of state.facts) {
+    const source = fact.source === undefined ? '' : '  _(source: ' + [fact.source.tool, fact.source.operation].filter(Boolean).join(' · ') + ')_'
+    lines.push('- `' + fact.id + '` [' + (fact.kind ?? 'info') + ']' + (fact.target === undefined ? '' : ' ' + fact.target) + ' — ' + fact.detail + source)
+  }
+  lines.push('', '## Edges')
+  if (state.edges.length === 0) lines.push('', '_none_')
+  for (const edge of state.edges) lines.push('- `' + edge.from + '` -[' + edge.kind + ']→ `' + edge.to + '`')
+  lines.push('')
+  return lines.join('\n')
+}

package/package.json

@@ -1,6 +1,58 @@
 {
   "name": "@dsh-fly/dsh-plugin-fly-engagement",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "tools/index.js",
+    "lib/fold.mjs",
+    "lib/client.js",
+    "cordis.patch.yml"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-shell": "^0.2.1-rc.2",
+    "@deepseek-ai/dsh-tools": "^0.2.1-rc.2"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ethanchen669/dsh-plugin-fly-engagement.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./tools/index.js": "./tools/index.js",
+    "./lib/fold.mjs": "./lib/fold.mjs",
+    "./client": "./lib/client.js",
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-sidebar-right"
+      ]
+    }
+  },
+  "scripts": {
+    "verify": "node scripts/verify.mjs",
+    "test": "node --test tests/*.spec.mjs",
+    "build:client": "node scripts/build-client.mjs"
+  },
+  "description": "DSH Fly engagement 记录面：eng_record/eng_state/eng_report + 抽屉面板（工作区 JSONL + 投影）",
+  "homepage": "https://github.com/ethanchen669/dsh-plugin-fly-engagement#readme",
+  "bugs": {
+    "url": "https://github.com/ethanchen669/dsh-plugin-fly-engagement/issues"
+  },
+  "devDependencies": {
+    "vite": "^5.4.21"
+  }
+}

package/tools/index.js

@@ -0,0 +1,230 @@
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import {
+  ASSET_TYPES, EDGE_KINDS, FACT_KINDS, SEVERITIES,
+  foldEvents, ledgerPath, nextId, renderReport, windowView,
+} from '../lib/fold.mjs'
+
+/**
+ * fly-engagement —— **agent 平面**的工具半边（preset 行：`dsh-plugin-fly-engagement/tools/index.js`）。
+ *
+ * 记录写进工作区：`<workspace>/.fly-engagement/events.jsonl`（append-only，投影=fold）。
+ * 面板半边是**同一个包的根 `index.js`**（宿主行，`inject:['webServer','shell']`）——
+ * 两个挂载点共用 `lib/fold.mjs` 的投影口径，所以面板读数与 `eng_state` 永远同口径。
+ *
+ * **不写任何自定义会话事件**（AGENTS.md 毒药条）；文件读写全走 `ctx.shell` 接缝。
+ */
+
+export const name = 'fly-engagement-tools'
+export const inject = ['tools', 'shell']
+
+function argumentError(message) {
+  const error = new Error(message)
+  error.name = 'ArgumentError'
+  return error
+}
+
+function shq(value) {
+  return `'${String(value).replace(/'/g, "'\\''")}'`
+}
+
+/** 与五个安全包同一形状：`resolve()` + `execute()`，handle 上 `result` 是方法。 */
+async function runCmd(shell, argv, exec, opts = {}) {
+  const result = await (await shell.execute(shell.resolve({
+    command: argv.map(shq).join(' '),
+    ...opts.timeoutMs !== undefined ? { timeoutMs: opts.timeoutMs } : {},
+    signal: exec.signal,
+  }))).result()
+  if (result.aborted) {
+    const error = new Error('tool call aborted')
+    error.name = 'AbortError'
+    throw error
+  }
+  if (result.sandbox?.denied) {
+    const error = new Error(`[sandbox: file access denied under ${result.sandbox.mode} mode]`)
+    error.name = 'SandboxError'
+    throw error
+  }
+  return { stdout: result.stdout.text, stderr: result.stderr.text, exitCode: result.exitCode }
+}
+
+async function appendText(shell, file, text, exec) {
+  const encoded = Buffer.from(text, 'utf8').toString('base64')
+  return await runCmd(shell, ['sh', '-c', 'printf %s ' + shq(encoded) + ' | base64 -d >> ' + shq(file)], exec)
+}
+
+async function readText(shell, file, exec) {
+  const run = await runCmd(shell, ['sh', '-c', 'cat ' + shq(file) + ' 2>/dev/null || true'], exec)
+  return run.stdout
+}
+
+function normalizeRecord(args) {
+  const goal = args.goal === undefined ? null : args.goal
+  if (goal !== null) {
+    if (typeof goal !== 'object') throw argumentError('goal 必须是一个对象')
+    if (typeof goal.target !== 'string' || goal.target.trim() === '') throw argumentError('goal.target 必填（目标）')
+    if (typeof goal.objective !== 'string' || goal.objective.trim() === '') throw argumentError('goal.objective 必填（目标/完成标准）')
+  }
+  const facts = Array.isArray(args.facts) ? args.facts : []
+  const findings = Array.isArray(args.findings) ? args.findings : []
+  const assets = Array.isArray(args.assets) ? args.assets : []
+  const edges = Array.isArray(args.edges) ? args.edges : []
+  for (const [index, fact] of facts.entries()) {
+    if (typeof fact?.detail !== 'string' || fact.detail.trim() === '') throw argumentError('facts[' + index + '].detail 必填（确认到的证据）')
+    if (fact.kind !== undefined && !FACT_KINDS.includes(fact.kind)) throw argumentError('facts[' + index + '].kind 只能是 ' + FACT_KINDS.join('/'))
+  }
+  for (const [index, finding] of findings.entries()) {
+    if (typeof finding?.title !== 'string' || finding.title.trim() === '') throw argumentError('findings[' + index + '].title 必填')
+    if (finding.severity !== undefined && !SEVERITIES.includes(finding.severity)) throw argumentError('findings[' + index + '].severity 只能是 ' + SEVERITIES.join('/'))
+    if (!Array.isArray(finding.reproducibleSteps) || finding.reproducibleSteps.length === 0) {
+      throw argumentError('findings[' + index + '].reproducibleSteps 必填且至少 1 条（没有复现步骤的漏洞不算记录）')
+    }
+    if (finding.reproducibleSteps.some(step => typeof step !== 'string' || step.trim() === '')) {
+      throw argumentError('findings[' + index + '].reproducibleSteps 里每条都必须是非空字符串')
+    }
+  }
+  for (const [index, asset] of assets.entries()) {
+    if (!ASSET_TYPES.includes(asset?.type)) throw argumentError('assets[' + index + '].type 只能是 ' + ASSET_TYPES.join('/'))
+    if (typeof asset.value !== 'string' || asset.value.trim() === '') throw argumentError('assets[' + index + '].value 必填')
+  }
+  for (const [index, edge] of edges.entries()) {
+    if (!EDGE_KINDS.includes(edge?.kind)) throw argumentError('edges[' + index + '].kind 只能是 ' + EDGE_KINDS.join('/'))
+    if (typeof edge.from !== 'string' || edge.from.trim() === '') throw argumentError('edges[' + index + '].from 必填')
+    if (typeof edge.to !== 'string' || edge.to.trim() === '') throw argumentError('edges[' + index + '].to 必填')
+  }
+  return { goal, facts, findings, assets, edges }
+}
+
+const workspaceParam = { type: 'string', required: true, description: 'Absolute workspace path; the ledger lives in <workspace>/.fly-engagement/events.jsonl' }
+
+export function apply(ctx) {
+  const shell = ctx.shell
+
+  ctx.tools.register(defineTool({
+    name: 'eng_record',
+    description: 'Record engagement evidence into the workspace ledger: goal (once), facts, findings (reproducible steps required), assets and edges. Returns deterministic ids for later reference.',
+    parameters: {
+      workspace: workspaceParam,
+      goal: { type: 'object', additionalProperties: true, description: 'Once per engagement: { target, objective, authorization? }' },
+      facts: { type: 'array', items: { type: 'object', additionalProperties: true }, description: 'Facts: { kind?, target?, detail (required), confidence?, source? }' },
+      findings: { type: 'array', items: { type: 'object', additionalProperties: true }, description: 'Findings: { title, severity?, description?, reproducibleSteps (required), affectedAssetId? }' },
+      assets: { type: 'array', items: { type: 'object', additionalProperties: true }, description: 'Assets: { type, value, parentId?, meta? }' },
+      edges: { type: 'array', items: { type: 'object', additionalProperties: true }, description: 'Edges: { kind: parent|proves|derived_from, from, to }' },
+    },
+    output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
+    async execute(args, exec) {
+      if (typeof args.workspace !== 'string' || args.workspace.trim() === '') throw argumentError('eng_record 需要 workspace（绝对路径）')
+      const normalized = normalizeRecord(args)
+      if (normalized.goal === null && normalized.facts.length === 0 && normalized.findings.length === 0 && normalized.assets.length === 0 && normalized.edges.length === 0) {
+        throw argumentError('eng_record 一次要写至少一样东西（goal / facts / findings / assets / edges 全空）')
+      }
+      const file = ledgerPath(args.workspace)
+      const dir = file.slice(0, file.lastIndexOf('/'))
+      await runCmd(shell, ['sh', '-c', 'mkdir -p ' + shq(dir)], exec)
+      const existing = foldEvents((await readText(shell, file, exec)).split('\n'))
+      if (normalized.goal !== null && existing.goal !== null) {
+        throw argumentError('这个 engagement 已经有 goal 了（target=' + existing.goal.target + '）—— 一个 engagement 只有一个 goal；要重新开始请换一个工作区')
+      }
+      const ids = new Set([...existing.facts.map(row => row.id), ...existing.findings.map(row => row.id), ...existing.assets.map(row => row.id)])
+      const created = { facts: [], findings: [], assets: [], edges: [] }
+      for (const asset of normalized.assets) {
+        if (asset.parentId !== undefined && asset.parentId !== '' && !ids.has(asset.parentId)) {
+          throw argumentError('assets.parentId=' + asset.parentId + ' 不存在（只能引用已记录的资产；同一次调用里请先写父资产）')
+        }
+        const row = { id: nextId('asset', [...existing.assets, ...created.assets]), ...asset }
+        created.assets.push(row)
+        ids.add(row.id)
+      }
+      for (const fact of normalized.facts) {
+        const row = { id: nextId('fact', [...existing.facts, ...created.facts]), ...fact }
+        created.facts.push(row)
+        ids.add(row.id)
+      }
+      for (const finding of normalized.findings) {
+        if (finding.affectedAssetId !== undefined && finding.affectedAssetId !== '' && !ids.has(finding.affectedAssetId)) {
+          throw argumentError('findings.affectedAssetId=' + finding.affectedAssetId + ' 不存在（只能引用已记录的资产）')
+        }
+        const row = { id: nextId('finding', [...existing.findings, ...created.findings]), ...finding }
+        created.findings.push(row)
+        ids.add(row.id)
+      }
+      for (const edge of normalized.edges) {
+        if (!ids.has(edge.from) || !ids.has(edge.to)) {
+          throw argumentError('edges 的端点必须已记录（' + edge.from + ' → ' + edge.to + '）；未知 id 一律拒绝，不静默丢弃')
+        }
+        created.edges.push({ ...edge })
+      }
+      const events = []
+      if (normalized.goal !== null) events.push({ op: 'goal', at: new Date().toISOString(), goal: normalized.goal })
+      events.push({ op: 'record', at: new Date().toISOString(), facts: created.facts, findings: created.findings, assets: created.assets, edges: created.edges })
+      await appendText(shell, file, events.map(event => JSON.stringify(event)).join('\n') + '\n', exec)
+      return JSON.stringify({
+        tool: 'eng_record',
+        target: file,
+        operation: 'append to the workspace ledger (goal/facts/findings/assets/edges)',
+        observed: {
+          created: { facts: created.facts.length, findings: created.findings.length, assets: created.assets.length, edges: created.edges.length },
+          ids: { facts: created.facts.map(row => row.id), findings: created.findings.map(row => row.id), assets: created.assets.map(row => row.id) },
+          goal: normalized.goal === null ? null : normalized.goal.target,
+        },
+        confidence: 'observed',
+        limitations: [
+          '记录是 append-only 的：写错要改请换工作区重来（v1 不做改写/删除）',
+          'id 是确定性 <kind>-<n>（按会话内的记录次序），跨调用可引用；同一次调用内不能互相引用（先父后子）',
+          'ledger 在 <workspace>/.fly-engagement/events.jsonl —— 工作区换一个就是另一个 engagement',
+        ],
+      }, null, 2)
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'eng_state',
+    description: 'Read the engagement projection: goal, nodes, edges, counts, and the window bookkeeping (dropped/refused/truncated).',
+    parameters: {
+      workspace: workspaceParam,
+      window: { type: 'number', description: 'Node window per table (default 200)' },
+    },
+    output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
+    async execute(args, exec) {
+      if (typeof args.workspace !== 'string' || args.workspace.trim() === '') throw argumentError('eng_state 需要 workspace（绝对路径）')
+      const windowSize = Math.min(2000, Math.max(1, Math.round(Number(args.window ?? 200) || 200)))
+      const file = ledgerPath(args.workspace)
+      const view = windowView(foldEvents((await readText(shell, file, exec)).split('\n')), windowSize)
+      return JSON.stringify({
+        tool: 'eng_state',
+        target: file,
+        operation: 'fold the workspace ledger into the engagement projection (window=' + windowSize + ')',
+        observed: view,
+        confidence: 'observed',
+        limitations: [
+          '投影是**窗口视图**：每张表只留最新 ' + windowSize + ' 条；dropped=' + view.dropped + '（被逐出）refused=' + view.refused + '（引用不存在的 id 被拒，累计）',
+          view.truncated ? '⚠️ truncated=true：被逐出的记录不在这个视图里 —— 完整记录以 eng_report（读全量）为准' : '这次没有截断（每张表都在窗口内）',
+          'ledger 不存在 ⇒ 空 projection（还没开始记录，不是错误）',
+        ],
+      }, null, 2)
+    },
+  }))
+
+  ctx.tools.register(defineTool({
+    name: 'eng_report',
+    description: 'Render the engagement report as Markdown (goal + authorization, assets, facts with source tools, findings with reproducible steps, counts).',
+    parameters: { workspace: workspaceParam },
+    output: { schema: { type: 'string' }, render: (_args, value) => [{ type: 'text', text: value }] },
+    async execute(args, exec) {
+      if (typeof args.workspace !== 'string' || args.workspace.trim() === '') throw argumentError('eng_report 需要 workspace（绝对路径）')
+      const file = ledgerPath(args.workspace)
+      const state = foldEvents((await readText(shell, file, exec)).split('\n'))
+      return JSON.stringify({
+        tool: 'eng_report',
+        target: file,
+        operation: 'render the full engagement ledger as Markdown (no window)',
+        observed: { markdown: renderReport(args.workspace, state), counts: { facts: state.facts.length, findings: state.findings.length, assets: state.assets.length, edges: state.edges.length }, refused: state.refused },
+        confidence: 'observed',
+        limitations: [
+          '这份报告读的是**全量** ledger（不经窗口）—— 面板上的图是窗口视图，两者条数可能不同',
+          'findings 的复现步骤原样列出（不重新编号内容、不排序）',
+          'ledger 写在 <workspace>/.fly-engagement/events.jsonl；报告可以复制走，记录仍在工作区里',
+        ],
+      }, null, 2)
+    },
+  }))
+}