dsh-form-fill-agent 0.2.30 → 0.2.31

package/README.md

@@ -1,6 +1,6 @@
 # AI填表智能体
 
-> 0.2.30：统一简洁首页、稳定菜单与可恢复品牌标题，明确任务状态；侧栏仍为可选依赖。
+> 0.2.31：新业务会话首次预填可编辑引导，保护已有文字、附件与主动清空；不自动发送或查询。
 
 > 统一侧栏适配需要 Better Sidebar `>=0.17.1 <0.19.0`。五个流程入口打开同一 Session Tab；侧栏展开、收起和关闭由宿主管理。缺少依赖时会显示安装升级提示。
 
@@ -11,7 +11,7 @@ AI填表智能体：支持自动填表、表格填充、表格补全、Excel填
 ### 基础安装（不需要侧栏）
 
 ```sh
-dsh plugin --profile web add dsh-form-fill-agent@0.2.30
+dsh plugin --profile web add dsh-form-fill-agent@0.2.31
 ```
 
 只需 Node.js >=22、完整 DSH 与主包自动安装的内核/Provider。Better Sidebar 和 dsh-context 都是可选项，不会由基础安装强装。
@@ -102,7 +102,7 @@ dsh plugin --profile web add dsh-form-fill-agent@latest
 
 ## 使用边界与数据保存
 
-补充要求为模型可读文本；字段或工作表范围请通过向导/工作台修改，不能仅改文字后假定执行范围已同步。任务 schema 5 可读取 schema 1–5；回退旧版本请使用升级前目录副本或独立任务目录。主包为 0.2.30，共享内核为 0.2.10，Provider 为 0.2.2，共享字段契约为 0.1.0。
+补充要求为模型可读文本；字段或工作表范围请通过向导/工作台修改，不能仅改文字后假定执行范围已同步。任务 schema 5 可读取 schema 1–5；回退旧版本请使用升级前目录副本或独立任务目录。主包为 0.2.31，共享内核为 0.2.10，Provider 为 0.2.2，共享字段契约为 0.1.0。
 
 支持企业完整登记名称或 18 位信用代码；简称、主体不一致或多候选不会自动猜选。仅有信用代码的表格也可作为查询锚点。连接候选检索工具时可检索简称，仍需人工确认；缺少工具时降级人工输入。字段映射采用确定性规则及人工确认，不让模型编造事实。支持普通内部公式、固定区域下拉、基础条件格式和普通表格对象；复杂 Excel 结构和 Word 暂不支持，保真边界见下方安全说明。
 

package/lib/client.js

@@ -57,6 +57,57 @@ window.__ModuleLoader__.load({
    connect();const unsubscribe=sessions?.list?.subscribe?.(connect);
    return()=>{disposed=true;stop();unsubscribe?.();seen.clear()};
   }
+  const INITIAL_TEMPLATE_ID='dsh-initial-draft/form-fill/1';
+  const INITIAL_TEMPLATE_TEXT='请帮我填写企业信息表。请上传 Excel 模板，说明主体定位列和需要填写的字段；也可点击左上角「提示词生成」设置填写规则。例如：按“企业名称”定位，只填空白单元格，补充统一社会信用代码、法定代表人和注册地址，并生成新文件。';
+  // Full text equality is the collision-free fingerprint; never trim/normalize user edits.
+  function createInitialDraftController({current,shell,storage,subscribeCurrent,defer=fn=>Promise.resolve().then(fn)}){
+   const entries=new Map();let disposed=false;
+   const key=id=>INITIAL_TEMPLATE_ID+':'+id;
+   const persist=(id,entry)=>{try{storage.setItem(key(id),JSON.stringify({state:entry.state,templateId:INITIAL_TEMPLATE_ID,fingerprint:INITIAL_TEMPLATE_TEXT,untouched:entry.untouched}));return true}catch{return false}};
+   const snapshot=face=>{
+    const state=face?.state?.getSnapshot?.(),editor=face?.editor;
+    if(!state||typeof state.draft!=='string'||!Array.isArray(state.imageIds)||!Number.isSafeInteger(state.draftRev)||typeof editor?.isComposing!=='function'||typeof editor?.getRootElement!=='function'||typeof editor?.update!=='function')return null;
+    return {draft:state.draft,rev:state.draftRev,empty:state.draft===''&&state.imageIds.length===0&&state.phase==='plain'&&Array.isArray(state.occurrences)&&state.occurrences.length===0,ready:!!editor.getRootElement(),composing:editor.isComposing()};
+   };
+   const skip=(id,e)=>{e.state='skipped';e.untouched=false;persist(id,e)};
+   return {
+    // Called only after this entry's create succeeds, before the asynchronous open.
+    arm(id){
+     if(disposed||!id?.startsWith('session-dsh-form-fill-agent-')||entries.has(id))return;
+     try{if(storage.getItem(key(id)))return}catch{return}
+     let face;try{face=shell(id)}catch{return}
+     const first=snapshot(face),e={state:'unseen',face,first,untouched:false};entries.set(id,e);
+     if(!first||!first.empty||first.composing||typeof face?.setDraft!=='function'||typeof face.state.subscribe!=='function'||!persist(id,e)){skip(id,e);return}
+     let visited=current()===id;
+     e.sessionOff=subscribeCurrent?.(()=>{if(current()===id)visited=true;else if(visited&&e.state==='unseen')skip(id,e)});
+     e.off=face.state.subscribe(()=>{
+      const next=snapshot(face);
+      if(e.writing)return;
+      if(e.state==='unseen'&&(!next||next.rev!==first.rev||!next.empty||next.composing))skip(id,e);
+      if(e.state==='initialized'&&next?.rev!==e.seedRev){e.untouched=false;persist(id,e)}
+     });
+    },
+    async attempt(id){
+     const e=entries.get(id);if(disposed||e?.state!=='unseen')return false;
+     const before=snapshot(e.face);
+     if(current()!==id||!before||!before.empty||before.composing||before.rev!==e.first.rev){skip(id,e);return false}
+     if(!before.ready)return false;
+     // All asynchronous work precedes this second snapshot and synchronous public write.
+     return defer(()=>{
+      const after=snapshot(e.face);
+      if(disposed||e.state!=='unseen')return false;
+      if(current()!==id||!after?.ready||!after.empty||after.composing||after.rev!==before.rev){skip(id,e);return false}
+      e.state='initialized';e.untouched=true;
+      if(!persist(id,e)){skip(id,e);return false}
+      try{e.writing=true;e.face.editor.update(()=>e.face.setDraft(INITIAL_TEMPLATE_TEXT),{discrete:true,tag:'skip-dom-selection'});e.seedRev=snapshot(e.face)?.rev;if(snapshot(e.face)?.draft!==INITIAL_TEMPLATE_TEXT){skip(id,e);return false}return true}
+      catch{skip(id,e);return false}finally{e.writing=false}
+     });
+    },
+    expire(id){const e=entries.get(id);if(e?.state==='unseen')skip(id,e)},
+    isTemplate(id,text){const e=entries.get(id);return e?.state==='initialized'&&e.untouched&&text===INITIAL_TEMPLATE_TEXT&&snapshot(e.face)?.rev===e.seedRev},
+    dispose(){disposed=true;for(const [id,e] of entries){if(e.state==='unseen')skip(id,e);e.off?.();e.sessionOff?.()}entries.clear()}
+   };
+  }
   function apply(ctx) {
    let React, portal;
    try { React=require('react');portal=require('react-dom').createPortal; } catch {}
@@ -70,6 +121,9 @@ window.__ModuleLoader__.load({
    const theme=()=>document.documentElement.hasAttribute('data-ds-dark-theme')?'dark':getComputedStyle(document.documentElement).colorScheme==='light'?'light':matchMedia('(prefers-color-scheme:dark)').matches?'dark':'light';
    if(typeof document!=='undefined'&&document.head?.append){const css=document.createElement('link');css.rel='stylesheet';css.href='/form-fill/brand.css';css.dataset.formFillStyle='true';document.head.append(css);disposers.push(()=>css.remove())}
    const current=()=>ctx.sessions?.list?.getSnapshot?.().current;
+   let draftStorage;try{draftStorage=window.sessionStorage}catch{}
+   const initialDraft=createInitialDraftController({current,subscribeCurrent:fn=>ctx.sessions?.list?.subscribe?.(fn),shell:id=>ctx.conversation?.input?.shell?.(id),storage:draftStorage});
+   disposers.push(()=>initialDraft.dispose());
    function register(name,component){ctx.slots.inject(name,()=>ctx.slots.register({name,id:'form-fill-agent',order:120},component))}
    function openPanel(id,step='import'){
     if(!activePlugin||!owned(id))return;
@@ -91,7 +145,15 @@ window.__ModuleLoader__.load({
     const id=prefix+crypto.randomUUID();
     const result=await ctx.sessions.create({workspaceId:workspace.workspaceId,sessionId:id});
     if(result!==id)throw Error('宿主不支持独立业务会话');
+    initialDraft.arm(id);
     await ctx.sessions.open(id);
+    // Input mounting is bounded; any user edit or Session switch consumes eligibility.
+    if(ctx.conversation?.input?.shell)for(let i=0;i<20&&activePlugin;i++){
+     if(await initialDraft.attempt(id))break;
+     if(current()!==id)break;
+     await new Promise(resolve=>setTimeout(resolve,50));
+    }
+    initialDraft.expire(id);
    }
    const launcher=()=>h('a',{className:'ff-launcher',href:'/form-fill/',target:'_blank',rel:'noopener noreferrer','aria-label':'AI 填表',onClick:async e=>{
     if(!ctx.sessions?.create)return;e.preventDefault();try{await start()}catch{window.open('/form-fill/','_blank','noopener')}
@@ -211,6 +273,7 @@ window.__ModuleLoader__.load({
        let draft=readDraft();if(typeof draft!=='string')throw Error('cannot read draft');
        const mode=event.data.mode;
        const prior=lastDrafts.get(view.id),unchanged=draft===prior?.value;
+       if(initialDraft.isTemplate(view.id,draft))draft='';
        if(draft.trim()&&!unchanged&&(!['replace','append'].includes(mode)||event.data.expectedDraft!==draft)){
         frame.current.contentWindow.postMessage({type:'ff-draft-conflict',draft},location.origin);return;
        }
@@ -239,6 +302,6 @@ window.__ModuleLoader__.load({
    register('conversation.input.overlay',props=>owned(props.sessionId)?h('div',{className:'ff-ui','data-ff-theme':theme()},h('button',{className:'ff-prompt',type:'button',onClick:()=>openPanel(props.sessionId,'wizard')},icon('spark'),'提示词生成')):null);
    ctx.effect?.(()=>()=>{activePlugin=false;for(const dispose of disposers)dispose();viewListeners.clear();views.clear();sessionTasks.clear();lastDrafts.clear()});
   }
-  return {createSidebarAdapter,installSubmittedWorkbenchBridge,name:'form-fill-agent',inject:['slots','sessions','workspaces','conversation'],apply};
+  return {createSidebarAdapter,installSubmittedWorkbenchBridge,createInitialDraftController,INITIAL_TEMPLATE_ID,INITIAL_TEMPLATE_TEXT,name:'form-fill-agent',inject:['slots','sessions','workspaces','conversation'],apply};
  }
 });

package/lib/index.js

@@ -7,7 +7,16 @@ import { renderEnrichmentResult } from './diagnostics.js';
 export { previewBytes, previewFile, writeCopy } from './workflow.js';
 export const name = 'form-fill-agent';
 export const inject = [];
+export const INITIAL_GUIDANCE_POLICY = 'AI填表业务边界：仅支持上传的 Excel 模板，按用户明确的主体定位列补充已确认字段；只填空白，保留公式和格式，生成新文件。首页初始引导是示例，不是已上传文件、已识别列或查询授权。若用户直接发送引导、仍含未补全的【】占位符、未上传 Excel 或未说明主体定位列，请用中文先询问缺失信息，不创建任务，不调用 form_fill_enrich、Provider、MCP、OCR 或其他业务工具。已有真实任务与已保存定位映射时可沿用任务信息，不重复询问。不得宣传 Word、覆盖源模板或外部写回。';
+export function initialGuidanceSection(context) {
+  return context?.agent?.session?.id?.startsWith('session-dsh-form-fill-agent-') ? INITIAL_GUIDANCE_POLICY : '';
+}
 export function apply(ctx, config = {}) {
+  ctx.inject(['systemPrompt'], scope => {
+    if(typeof scope.systemPrompt?.section!=='function')return;
+    const dispose = scope.systemPrompt.section({name:'dsh-form-fill-agent/initial-guidance',order:120,text:initialGuidanceSection});
+    scope.effect?.(() => () => dispose?.());
+  });
   ctx.inject(['webServer'], scope => {
     let toolService;
     const taskDirectory = config.taskDirectory ?? profileTaskDirectory(import.meta.url);
@@ -17,7 +26,7 @@ export function apply(ctx, config = {}) {
       toolService = tools;
       const disposeTool = tools.register({
         name: 'form_fill_enrich',
-        description: 'Use QCC to fill an uploaded AI填表 task. Invoke only when the user requests QCC enrichment. Returns counts and a preview link; the user confirms cell changes in the workbench.',
+        description: 'Use QCC to fill an uploaded AI填表 task. Invoke only for a real uploaded Excel task with a saved entity locating column and explicit user enrichment request. If these are missing or the message is an unfilled guidance/example, ask for the Excel template and locating column without calling tools. Returns counts and a preview link; the user confirms cell changes in the workbench.',
         parameters: { type: 'object', additionalProperties: false, properties: { taskId: { type: 'string' }, expectedRevision: { type: 'integer' }, mode:{type:'string',enum:['all','retry']} }, required: ['taskId'] },
         output: {
           schema: { type: 'object', properties: { taskId: { type: 'string' }, filled: { type: 'integer' }, incomplete: { type: 'integer' }, diagnostics:{type:'object'}, previewPath: { type: 'string' } }, required: ['taskId','filled','incomplete','previewPath'] },

package/package.json

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