From 5f258e830856fafb8f5a47768febbc5f432ae7fa Mon Sep 17 00:00:00 2001
From: jiangchen <1703935164@qq.com>
Date: Sun, 27 Sep 2026 16:09:30 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=2015-17=20=E5=8F=B7=E8=B8=A9?=
 =?UTF-8?q?=E5=9D=91=EF=BC=88defineTool=20=E5=BF=85=E9=A1=BB=E8=BD=AC?=
 =?UTF-8?q?=E6=8D=A2=E5=8F=82=E6=95=B0=20schema=E3=80=81=E5=85=B7=E5=90=8D?=
 =?UTF-8?q?=E5=AF=BC=E5=87=BA=E8=A2=AB=20default=20=E5=90=9E=E3=80=81?=
 =?UTF-8?q?=E4=B8=8A=E4=B8=8B=E6=96=87=E7=AA=97=E5=8F=A3=E6=9D=A5=E8=87=AA?=
 =?UTF-8?q?=20request/context=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/README.md b/README.md
index 7cac562..cd8c6c0 100644
--- a/README.md
+++ b/README.md
@@ -113,6 +113,11 @@ shell\run-float.cmd -Action pin                      # 给正在运行的实例
 12. **会话事件载荷在 `event.data` 下**，不在顶层：`user/message` → `data.content[{type:'text',text}]`、`assistant/chunk` → `data.chunk{type,text,reason}`、`session/title` → `data.title`、`tool/call` → `data.name/args`。另外要过滤 `data.source.kind === 'plugin'` 的消息（系统提示快照），否则镜像里会混入一大段内部注入文本。
 13. **宿主 RPC 的信封是 `{ rpcId, payload }`**（0.1.0 的 `ctx.apiProxy.sessions.*`）：把字段平铺在顶层会得到 `Cannot read properties of undefined (reading 'sessionId')`。
 14. **0.1.7 起宿主面换成了 `ctx.sessionController`**（`ctx.apiProxy` 不再存在），并且 Remote 签名是 `(request, signal)`——**漏了 signal 会报 `Cannot read properties of undefined (reading 'throwIfAborted')`**；`create` 还必须带一个合法的 `agentPreset`（否则 `Unknown agent preset: xxx`）。插件对两套 API 都自动适配（见 `hostCall`）。
+15. **手工拼工具定义会打断每一轮对话**（真机事故）：0.1.7 的 `ctx.tools.register()` 要求模型侧看到的就是 JSON Schema，参数必须经 `defineTool()`（内部 `parameterSchemaSpecToJsonSchema`）转换。直接塞 DSL 对象会让 provider 收到 `parameters.type = null`，于是**每次请求都被拒**：
+    `Invalid schema for function 'float_window': schema must be a JSON Schema of 'type: "object"', got 'type: null'`。
+    现在的三层防护：解析不到 `defineTool` 就**根本不注册**；注册前自检 `parameters.type === 'object'`；配置项 `tool: false` 可一键关掉。
+16. **link: 安装时优先返回 `default` 会吞掉具名导出**：`@deepseek-ai/dsh-tools` 的 `default` 是 `ToolRuntime` 类，`defineTool` 是具名导出——宿主模块加载器必须返回模块命名空间本身。
+17. **上下文窗口不在 model 配置里**，而在会话事件 **`request/context.contextWindow`**（实测 `deepseek-flash` = 1000000），用它算上下文用量百分比最可靠；状态文件里的 `toolSchemas` 是从真实 `request/header` 抓下来的"模型视角工具 schema"，用来一眼确认 schema 合法。
 
 ## 版本支持