dsh-form-fill-agent 0.2.24 → 0.2.25

package/README.md

@@ -1,6 +1,6 @@
 # AI填表智能体
 
-> 0.2.24 新增只读安装兼容预检。请根据实际 DSH 宿主选择匹配的侧栏版本。
+> 0.2.25：侧栏为可选依赖，基础安装无需侧栏；内嵌工作台需匹配宿主版本。
 
 > 统一侧栏适配需要 Better Sidebar `>=0.17.1 <0.19.0`。五个流程入口打开同一 Session Tab；侧栏展开、收起和关闭由宿主管理。缺少依赖时会显示安装升级提示。
 
@@ -8,16 +8,27 @@
 
 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.18.1
-dsh plugin --profile web add dsh-form-fill-agent@0.2.24
+dsh plugin --profile web add dsh-form-fill-agent@0.2.25
 ```
 
-若仍使用 **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`，必须成套选择。
+只需 Node.js >=22、完整 DSH 与主包自动安装的内核/Provider。Better Sidebar 和 dsh-context 都是可选项，不会由基础安装强装。
+
+无侧栏可使用原生会话和独立 `/form-fill/` 页面：上传 XLSX、确认映射、查看预览、确认并导出副本。点击会话中的工作台按钮会显示提示及“打开独立填表页面”链接，保留原生草稿和已保存任务。独立页面无法自动回填原生草稿，需复制指令到对话框发送。企查查查询仍需用户授权的 MCP 和模型；无侧栏不会授予额外权限。
+
+### 可选：启用内嵌工作台
+
+先运行 `dsh --version`，按实际宿主在同一 profile 加装：
+
+```sh
+# DSH 0.1.2-rc.1
+dsh plugin --profile web add dsh-better-sidebar@0.18.1
+# 仅旧 DSH 0.1.1-rc.2 使用 0.17.1
+```
 
-不建议侧栏使用无上限的 `@latest`：本插件当前支持 `>=0.17.1 <0.19.0`，未来 latest 可能超出范围或要求更新的 DSH。依赖与主包必须安装在同一 profile；自定义 profile 请替换命令中的 `web`。安装后完整停止并重启对应 profile。
+旧宿主配 0.18.1 会缺少 `SessionLogOffset`，新宿主配 0.17.1 会缺少 `settingsNamespace`。侧栏是可选的，但已经安装的错误组合仍会阻断宿主，必须处理。不建议使用无上限的 `@latest`；可接受范围 `>=0.17.1 <0.19.0` 不等于每个版本均已验证。自定义 profile 请替换 `web`，安装后重启对应 profile。
 
 ### 升级前检查与回滚
 
@@ -26,10 +37,10 @@ dsh plugin --profile web add dsh-form-fill-agent@0.2.24
 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
+node /path/to/dsh-form-fill-agent/lib/preflight.js --dsh-bin /path/to/dsh --profile-dir /path/to/profiles/web --mode basic
 ```
 
-`--sidebar-version` 是计划安装版本；省略则检查该 profile 已安装版本。若计划同时更新已有 context，可加 `--context-version 0.48.0`。预检读取版本元数据，不加载插件树、不读凭据、不安装或重启；已知不兼容退出码为 2，未知组合明确显示未验证。通过只代表版本组合，不代表 MCP 权限、费用或业务结果。
+默认 `--mode basic` 允许缺少侧栏；启用内嵌工作台用 `--mode workbench --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`。
 
@@ -91,7 +102,7 @@ dsh plugin --profile web add dsh-form-fill-agent@latest
 
 ## 使用边界与数据保存
 
-补充要求为模型可读文本；字段或工作表范围请通过向导/工作台修改，不能仅改文字后假定执行范围已同步。任务 schema 5 可读取 schema 1–5；回退旧版本请使用升级前目录副本或独立任务目录。主包为 0.2.23，共享内核为 0.2.10，Provider 为 0.2.2，共享字段契约为 0.1.0。
+补充要求为模型可读文本；字段或工作表范围请通过向导/工作台修改，不能仅改文字后假定执行范围已同步。任务 schema 5 可读取 schema 1–5；回退旧版本请使用升级前目录副本或独立任务目录。主包为 0.2.25，共享内核为 0.2.10，Provider 为 0.2.2，共享字段契约为 0.1.0。
 
 支持企业完整登记名称或 18 位信用代码；简称、主体不一致或多候选不会自动猜选。仅有信用代码的表格也可作为查询锚点。连接候选检索工具时可检索简称，仍需人工确认；缺少工具时降级人工输入。字段映射采用确定性规则及人工确认，不让模型编造事实。支持普通内部公式、固定区域下拉、基础条件格式和普通表格对象；复杂 Excel 结构和 Word 暂不支持，保真边界见下方安全说明。
 

package/lib/client.js

@@ -2,7 +2,7 @@ window.__ModuleLoader__.load({
  id: 'dsh-form-fill-agent',
  factory(require) {
   const SIDEBAR_TAB='dsh-form-fill-agent:workbench';
-  const SIDEBAR_HELP='工作台需要 Better Sidebar >=0.17.1 <0.19.0。请在当前 DSH profile 安装或升级 dsh-better-sidebar，重启后重试；原生对话仍可使用。';
+  const SIDEBAR_HELP='内嵌工作台暂不可用。原生对话与独立填表页面仍可使用，输入和已保存任务不会清除。启用内嵌工作台需与宿主匹配的 Better Sidebar（>=0.17.1 <0.19.0），请按安装说明选择版本。';
   // The only adapter allowed to reveal host panels. No geometry or business writes.
   function createSidebarAdapter(service,component,icon){
    const version=/^0\.(17|18)\.(\d+)$/.exec(service?.version||'');
@@ -128,7 +128,7 @@ window.__ModuleLoader__.load({
     if(!owned(sessionId))return null;
     const content=h('div',{className:'ff-ui','data-ff-theme':theme()},h('nav',{className:'ff-shortcuts','aria-label':'AI填表快捷菜单'},...[
      ['导入表格','import','upload'],['字段设置','rules','check'],['主体核验','identity','search'],['填写预览','preview','table'],['任务历史','history','history']
-    ].map(([label,step,symbol])=>h('button',{key:step,type:'button',onClick:()=>openPanel(sessionId,step)},icon(symbol),h('span',{className:'ff-shortcut-label'},label)))),error?h('p',{className:'ff-sidebar-help',role:'alert'},error):null);
+    ].map(([label,step,symbol])=>h('button',{key:step,type:'button',onClick:()=>openPanel(sessionId,step)},icon(symbol),h('span',{className:'ff-shortcut-label'},label)))),error?h('div',{className:'ff-sidebar-help',role:'alert'},h('p',null,error),h('a',{href:'/form-fill/?session='+encodeURIComponent(sessionId)+(sessionTasks.has(sessionId)?'#task='+sessionTasks.get(sessionId):''),target:'_blank',rel:'noopener noreferrer'},'打开独立填表页面'),h('p',null,'独立页面生成的指令请复制到对话框后发送。')):null);
     return h('div',{ref,'data-form-fill-session':sessionId},h(Hero,{sessionId}),mount?portal(content,mount):content);
    }
    function WorkbenchTab({scope,store,tab,visible}){

package/lib/preflight.js

@@ -6,24 +6,25 @@ import {join, resolve} from 'node:path';
 import {fileURLToPath} from 'node:url';
 import {execFileSync} from 'node:child_process';
 
-export function assessCompatibility({nodeVersion,hostVersion,sidebarVersion,contextVersion}) {
+export function assessCompatibility({nodeVersion,hostVersion,sidebarVersion,contextVersion,mode='basic'}) {
+ if(!['basic','workbench'].includes(mode))throw Error('mode 仅支持 basic 或 workbench');
  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)add(mode==='workbench'?'blocked':'info','SIDEBAR_MISSING','未安装侧栏：基础会话与独立 /form-fill/ 页面可用；内嵌工作台及自动草稿回填需安装与宿主匹配的 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';
+ const known=(!sidebarVersion&&['0.1.1-rc.2','0.1.2-rc.1'].includes(hostVersion))||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 权限或全部业务验收通过。不会自动安装、升级、重启。'};
+ return {status:blocked?'blocked':issues.some(i=>i.severity==='warning')?'unverified':'verified-combination',mode,nodeVersion,hostVersion,sidebarVersion:sidebarVersion||null,contextVersion:contextVersion||null,issues,scope:'版本预检；不代表模型、MCP 权限或全部业务验收通过。不会自动安装、升级、重启。'};
 }
 
-export async function inspectInstallation({dshBin,profileDir,sidebarVersion,contextVersion}) {
+export async function inspectInstallation({dshBin,profileDir,sidebarVersion,contextVersion,mode='basic'}) {
  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');
@@ -31,15 +32,15 @@ export async function inspectInstallation({dshBin,profileDir,sidebarVersion,cont
  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}};
+ return {...assessCompatibility({nodeVersion:process.version,hostVersion,sidebarVersion:sidebarVersion||installedSidebar,contextVersion:contextVersion||installedContext,mode}),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，未验证组合会显式提示。');}
+  if(args.includes('--help')){console.log('form-fill-preflight --dsh-bin /absolute/path/to/dsh --profile-dir /path/to/profiles/web [--mode basic|workbench] [--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'};
+   const keys={'--mode':'mode','--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;

package/lib/ui.html

@@ -330,5 +330,6 @@ window.addEventListener('pagehide',saveMappingDraft);
 for(const event of ['change','click'])$('mapping').addEventListener(event,saveMappingDraft);
 $('mapping').addEventListener('change',()=>{wizardMappingApplied=false;$('mapping-next').hidden=true;highlightMappingConflicts()});
 window.addEventListener('hashchange',()=>{if(new URLSearchParams(location.hash.slice(1)).get('task')!==current?.id)restore()});
-navigate('import');restore();setInterval(()=>{if(!document.hidden&&current&&!busy&&!$('wizard').open)restore(true)},2000);
+async function restoreSessionTask(){if(location.hash||!sessionId){restore();return}try{const list=await api('/tasks');if(current||location.hash)return;const task=list.filter(item=>item.sessionId===sessionId).sort((a,b)=>(b.updatedAt||b.created)-(a.updatedAt||a.created))[0];if(task){location.hash='task='+task.id;await restore()}}catch(e){$('status').textContent='恢复任务失败，可在任务历史中重试：'+e.message}}
+navigate('import');restoreSessionTask();setInterval(()=>{if(!document.hidden&&current&&!busy&&!$('wizard').open)restore(true)},2000);
 </script></html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-form-fill-agent",
-  "version": "0.2.24",
+  "version": "0.2.25",
   "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": {