dsh-form-fill-agent 0.2.22 → 0.2.24

package/README.md

@@ -1,17 +1,39 @@
 # AI填表智能体
 
+> 0.2.24 新增只读安装兼容预检。请根据实际 DSH 宿主选择匹配的侧栏版本。
+
 > 统一侧栏适配需要 Better Sidebar `>=0.17.1 <0.19.0`。五个流程入口打开同一 Session Tab；侧栏展开、收起和关闭由宿主管理。缺少依赖时会显示安装升级提示。
 
 ## 安装与三分钟上手
 
 AI填表智能体：支持自动填表、表格填充、表格补全、Excel填表与 Excel回填；使用企查查 MCP 填写 XLSX 空白字段，预览确认后导出新副本。
 
+先运行 `dsh --version` 确认宿主版本。当前推荐组合为 **DSH 0.1.2-rc.1 + Better Sidebar 0.18.1**：
+
 ```sh
-dsh plugin --profile web add dsh-better-sidebar@0.17.1
-dsh plugin --profile web add dsh-form-fill-agent@0.2.22
+dsh plugin --profile web add dsh-better-sidebar@0.18.1
+dsh plugin --profile web add dsh-form-fill-agent@0.2.24
 ```
 
-请先满足下文的 DSH、连接器及侧边栏依赖要求；安装后完整停止并重启对应 Profile。
+若仍使用 **DSH 0.1.1-rc.2**，请将上述侧栏安装命令改为 `dsh plugin --profile web add dsh-better-sidebar@0.17.1`。该旧宿主加载 0.18.1 会因缺少 `SessionLogOffset` 导出而失败；新宿主搭配旧侧栏 0.17.1 也会缺少 `settingsNamespace`，必须成套选择。
+
+不建议侧栏使用无上限的 `@latest`：本插件当前支持 `>=0.17.1 <0.19.0`，未来 latest 可能超出范围或要求更新的 DSH。依赖与主包必须安装在同一 profile；自定义 profile 请替换命令中的 `web`。安装后完整停止并重启对应 profile。
+
+### 升级前检查与回滚
+
+产品必需项是 Node.js、完整 DSH 及插件自身内核/Provider；工作台侧栏需要上述兼容的 Better Sidebar。**dsh-context 不是必装依赖**。如果已有 context：0.36.0 与新 DSH 的设置接口不兼容，须在升级计划中处理；当前共存验证使用 0.48.0，其他版本提示未验证。
+
+0.2.24 新增只读预检工具，在包安装目录运行：
+
+```sh
+node /path/to/dsh-form-fill-agent/lib/preflight.js --dsh-bin /path/to/dsh --profile-dir /path/to/profiles/web --sidebar-version 0.18.1
+```
+
+`--sidebar-version` 是计划安装版本；省略则检查该 profile 已安装版本。若计划同时更新已有 context，可加 `--context-version 0.48.0`。预检读取版本元数据，不加载插件树、不读凭据、不安装或重启；已知不兼容退出码为 2，未知组合明确显示未验证。通过只代表版本组合，不代表 MCP 权限、费用或业务结果。
+
+升级前记录 `dsh --version` 和该 profile 的精确依赖版本，停止该 profile 并备份其配置及 form-fill-tasks。由宿主管理者升级完整 DSH，不能仅替换某个 SDK 包；如用 npm 管理全局 DSH，新组合的明确命令为 `npm install -g @deepseek-ai/dsh@0.1.2-rc.1`。随后按上文选择侧栏版本；仅当原本安装 context 时才处理它，例如 `dsh plugin --profile web add dsh-context@0.48.0`。
+
+先在独立 profile 验证启动、原生会话、合成 XLSX 导入/预览/确认/导出，再重启目标 profile。失败时恢复升级前完整宿主、侧栏及已安装插件版本组合和备份的任务目录，不移动发布标签、不让旧版直接读取已迁移任务目录。本预检不会替你修改全局环境。
 
 打开“AI填表”并展开合成演示，选择客户台账模板，检查工作表、企业主体和空白字段。需要真实补全时确认数据来源及范围并手动发送指令；核对单元格预览后下载新 XLSX 副本。
 
@@ -33,7 +55,9 @@ AI填表是 DeepSeek Harness（DSH）的企业表格填写插件：识别已有
 
 ## 安装
 
-需要 Node.js 22 或以上，以及 DSH。已验证的 DSH 基线为 0.1.1-rc.2 和 0.1.2-alpha.2。
+需要 Node.js 22 或以上和完整 DSH。当前验证组合为 DSH 0.1.2-rc.1 + Better Sidebar 0.18.1，旧组合为 DSH 0.1.1-rc.2 + Better Sidebar 0.17.1。历史 alpha 测试不作为当前兼容承诺。
+
+请先按文首的宿主版本选择并安装 Better Sidebar，再安装主包：
 
 ```sh
 dsh plugin --profile web add dsh-form-fill-agent@latest
@@ -67,7 +91,7 @@ dsh plugin --profile web add dsh-form-fill-agent@latest
 
 ## 使用边界与数据保存
 
-补充要求为模型可读文本；字段或工作表范围请通过向导/工作台修改，不能仅改文字后假定执行范围已同步。任务 schema 5 可读取 schema 1–5；回退旧版本请使用升级前目录副本或独立任务目录。主包为 0.2.22，共享内核为 0.2.10，Provider 为 0.2.2，共享字段契约为 0.1.0。
+补充要求为模型可读文本；字段或工作表范围请通过向导/工作台修改，不能仅改文字后假定执行范围已同步。任务 schema 5 可读取 schema 1–5；回退旧版本请使用升级前目录副本或独立任务目录。主包为 0.2.23，共享内核为 0.2.10，Provider 为 0.2.2，共享字段契约为 0.1.0。
 
 支持企业完整登记名称或 18 位信用代码；简称、主体不一致或多候选不会自动猜选。仅有信用代码的表格也可作为查询锚点。连接候选检索工具时可检索简称，仍需人工确认；缺少工具时降级人工输入。字段映射采用确定性规则及人工确认，不让模型编造事实。支持普通内部公式、固定区域下拉、基础条件格式和普通表格对象；复杂 Excel 结构和 Word 暂不支持，保真边界见下方安全说明。
 
@@ -75,7 +99,7 @@ dsh plugin --profile web add dsh-form-fill-agent@latest
 
 显式设置 DSH_HOME 时，任务保存至其 form-fill-tasks 目录，默认 24 小时过期；未设置时使用内存。任务保存输入表格和归一化预览，不持久化原始 MCP 响应，可主动删除任务。模型及 MCP 凭据由宿主管理。
 
-0.2.22 保存任务 schema 5，兼容读取旧 schema 1–4；回退旧版本须使用升级前任务目录副本或新目录，防止丢失已确认的字段/主体设置。
+0.2.23 保存任务 schema 5，兼容读取旧 schema 1–4；回退旧版本须使用升级前任务目录副本或新目录，防止丢失已确认的字段/主体设置。
 
 ## 文档与反馈
 

package/lib/preflight.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+// Read-only installation planning. Never imports plugins, reads credentials or mutates a profile.
+import {readFile, realpath, mkdtemp, rm, stat} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join, resolve} from 'node:path';
+import {fileURLToPath} from 'node:url';
+import {execFileSync} from 'node:child_process';
+
+export function assessCompatibility({nodeVersion,hostVersion,sidebarVersion,contextVersion}) {
+ const issues=[];
+ const add=(severity,code,message)=>issues.push({severity,code,message});
+ if(Number(String(nodeVersion).replace(/^v/,'').split('.')[0])<22)add('blocked','NODE_TOO_OLD','AI 填表需要 Node.js >=22；请先更新运行该 DSH 的 Node.js。');
+ if(!hostVersion)add('blocked','HOST_UNKNOWN','无法读取实际 DSH 版本；请用 --dsh-bin 指定实际 dsh 可执行文件。');
+ if(!sidebarVersion)add('blocked','SIDEBAR_MISSING','侧栏未安装；请选择与宿主对应的版本，通过 dsh plugin --profile <名称> add dsh-better-sidebar@<版本> 安装。');
+ if(sidebarVersion&&!/^0\.(?:17|18)\.\d+$/.test(sidebarVersion)||sidebarVersion==='0.17.0')add('blocked','SIDEBAR_RANGE','侧栏必须满足 >=0.17.1 <0.19.0；请使用已验证的固定版本，不要直接使用 latest。');
+ if(hostVersion==='0.1.1-rc.2'&&/^0\.18\./.test(sidebarVersion||''))add('blocked','HOST_SIDEBAR','旧 DSH 缺少 SessionLogOffset，不能加载该侧栏。保留 dsh-better-sidebar@0.17.1，或由宿主管理者升级完整 DSH 到 0.1.2-rc.1 后安装 0.18.1；不要只升级单个 SDK 包。');
+ if(hostVersion==='0.1.2-rc.1'&&sidebarVersion==='0.17.1')add('blocked','SIDEBAR_LEGACY','Better Sidebar 0.17.1 使用旧 settingsNamespace，不能加载到 DSH 0.1.2-rc.1。请在同一 profile 安装 dsh-better-sidebar@0.18.1。');
+ if(hostVersion==='0.1.2-rc.1'&&contextVersion==='0.36.0')add('blocked','CONTEXT_LEGACY','已安装 dsh-context@0.36.0 使用旧 settingsNamespace，会阻断新宿主。升级前备份 profile，将已安装的 context 升级到 0.48.0；例如 dsh plugin --profile <名称> add dsh-context@0.48.0。context 不是 AI 填表必装项。');
+ if(contextVersion&&!(hostVersion==='0.1.2-rc.1'&&['0.48.0','0.36.0'].includes(contextVersion)))add('warning','CONTEXT_UNVERIFIED','此宿主与 context 组合未纳入当前共存验证；不要据此推断兼容。');
+ const known=hostVersion==='0.1.1-rc.2'&&sidebarVersion==='0.17.1'||hostVersion==='0.1.2-rc.1'&&sidebarVersion==='0.18.1';
+ if(!known)add('warning','COMBINATION_UNVERIFIED','此宿主与侧栏组合未验证；版本范围可接受不等于已通过业务验收。');
+ const blocked=issues.some(i=>i.severity==='blocked');
+ return {status:blocked?'blocked':issues.length?'unverified':'verified-combination',nodeVersion,hostVersion,sidebarVersion,contextVersion:contextVersion||null,issues,scope:'版本预检；不代表模型、MCP 权限或全部业务验收通过。不会自动安装、升级、重启。'};
+}
+
+export async function inspectInstallation({dshBin,profileDir,sidebarVersion,contextVersion}) {
+ if(!(await stat(profileDir)).isDirectory())throw Error('指定 profile 路径不是目录，无法核对已安装插件。');
+ const installed=async name=>{try{return JSON.parse(await readFile(join(profileDir,'node_modules',name,'package.json'),'utf8')).version}catch(e){if(e.code==='ENOENT')return undefined;throw e}};
+ const installedSidebar=await installed('dsh-better-sidebar'),installedContext=await installed('dsh-context');
+ // Run version command with an empty environment profile to avoid activating the actual plugin tree.
+ const isolatedHome=await mkdtemp(join(tmpdir(),'form-fill-preflight-'));let raw;
+ try{raw=execFileSync(dshBin.endsWith('.js')?process.execPath:dshBin,[...(dshBin.endsWith('.js')?[dshBin]:[]),'--version'],{cwd:isolatedHome,encoding:'utf8',timeout:15000,env:{PATH:process.env.PATH,HOME:isolatedHome,DSH_HOME:isolatedHome,NO_COLOR:'1'}}).trim()}finally{await rm(isolatedHome,{recursive:true,force:true})}
+ const hostVersion=raw.match(/\b\d+\.\d+\.\d+(?:-[\w.]+)?\b/)?.[0];
+ return {...assessCompatibility({nodeVersion:process.version,hostVersion,sidebarVersion:sidebarVersion||installedSidebar,contextVersion:contextVersion||installedContext}),installed:{sidebar:installedSidebar||null,context:installedContext||null},proposed:{sidebar:sidebarVersion||null,context:contextVersion||null}};
+}
+
+if(process.argv[1]&&await realpath(process.argv[1]).catch(()=>resolve(process.argv[1]))===fileURLToPath(import.meta.url)) {
+ try {
+  const args=process.argv.slice(2),options={};
+  if(args.includes('--help')){console.log('form-fill-preflight --dsh-bin /absolute/path/to/dsh --profile-dir /path/to/profiles/web [--sidebar-version 0.18.1] [--context-version 0.48.0]\n只读当前版本；可预检计划安装版本。阻断退出码 2，未验证组合会显式提示。');}
+  else {
+   const keys={'--dsh-bin':'dshBin','--profile-dir':'profileDir','--sidebar-version':'sidebarVersion','--context-version':'contextVersion'};
+   for(let i=0;i<args.length;i+=2){if(!keys[args[i]]||!args[i+1]||args[i+1].startsWith('--'))throw Error('无效参数；使用 --help 查看用法');options[keys[args[i]]]=args[i+1]}
+   if(!options.dshBin||!options.profileDir)throw Error('必须指定 --dsh-bin 和 --profile-dir；不默认读取生产 profile。');
+   const result=await inspectInstallation(options);console.log(JSON.stringify(result,null,2));if(result.status==='blocked')process.exitCode=2;
+  }
+ } catch(error){console.error('预检未完成：'+error.message);process.exitCode=2}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-form-fill-agent",
-  "version": "0.2.22",
+  "version": "0.2.24",
   "private": false,
   "description": "AI form filling and spreadsheet autofill for XLSX in DeepSeek Harness, using authorized Qichacha MCP facts with cell previews, user confirmation and export to a new copy.",
   "repository": {
@@ -19,7 +19,8 @@
     ".": "./lib/index.js",
     "./http": "./lib/http.js",
     "./client": "./lib/client.js",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./preflight": "./lib/preflight.js"
   },
   "files": [
     "lib",
@@ -71,5 +72,8 @@
     "spreadsheet-autofill",
     "xlsx",
     "enterprise-data"
-  ]
+  ],
+  "bin": {
+    "form-fill-preflight": "lib/preflight.js"
+  }
 }