@yanglaofish/fishtools 0.4.0 → 0.5.1

package/manual/packages/core/src/development.js

@@ -0,0 +1,146 @@
+import {fork} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+import path from 'node:path';
+
+const worker=fileURLToPath(new URL('./development-watch-worker.js',import.meta.url));
+const positive=(value,fallback,name)=>{const number=value??fallback;if(!Number.isInteger(number)||number<1)throw new TypeError(`${name} 必须是正整数`);return number;};
+const send=(child,message)=>{if(child?.connected)child.send(message,()=>{});};
+
+/** 监督进程只传递配置和 IPC；每一代应用拥有独立的完整 ESM 模块图。 */
+export async function createDevelopmentSupervisor(options={}){
+  const projectDir=path.resolve(options.projectDir??process.cwd());
+  if(!options.entry)throw new TypeError('开发模式需要应用子进程入口');
+  const debounce=positive(options.debounce,180,'debounce'),closeTimeout=positive(options.closeTimeout,5000,'closeTimeout');
+  const killTimeout=positive(options.killTimeout,2000,'killTimeout'),startupTimeout=positive(options.startupTimeout,15000,'startupTimeout');
+  const watchTimeout=positive(options.watchTimeout,5000,'watchTimeout');
+  let phase='starting',child=null,watcher=null,generation=0,pending=false,draining=false,stopping=false,failed=false,closing;
+  let debounceTimer,startTimer,closeTimer,scanTimer;
+  const environment={...process.env,...options.env,FISHTOOLS_DEV_CHILD:'1'};
+  const emit=(type,details={})=>options.onEvent?.({generation,...details,type});
+  const active=()=>child&&child.exitCode===null&&child.signalCode===null;
+  const clearChildTimers=()=>{clearTimeout(startTimer);clearTimeout(closeTimer);};
+  async function terminate(target,kind){
+    if(!target||target.exitCode!==null||target.signalCode!==null)return true;
+    emit('forced',{pid:target.pid,kind,message:`${kind==='application'?'应用关闭':'文件监听'}超时，正在强制回收`});
+    target.kill('SIGKILL');
+    return new Promise(resolve=>{
+      const timer=setTimeout(()=>{target.removeListener('exit',exited);emit('blocked',{pid:target.pid,kind,message:'子进程尚未回收，保留占用预算并停止启动新宿主'});phase='blocked';resolve(false);},killTimeout);
+      const exited=()=>{clearTimeout(timer);resolve(true);};target.once('exit',exited);
+      if(target.exitCode!==null||target.signalCode!==null)exited();
+    });
+  }
+  function launch(){
+    if(stopping||active()||phase==='blocked')return;
+    clearTimeout(debounceTimer);debounceTimer=null;pending=false;draining=false;phase='starting';generation++;
+    const next=fork(path.resolve(options.entry),options.args??[],{cwd:options.cwd??process.cwd(),env:environment,execArgv:[],windowsHide:true,stdio:options.stdio??['inherit','inherit','inherit','ipc']});
+    child=next;let ready=false,reported=false;
+    startTimer=setTimeout(()=>{reported=true;failed=true;emit('failed',{pid:next.pid,message:'开发应用启动超时，继续等待源码修复'});void terminate(next,'application');},startupTimeout);
+    next.on('message',message=>{
+      if(next!==child)return;
+      if(message?.type==='development:ready'){
+        clearTimeout(startTimer);ready=true;phase='running';
+        if(message.details?.port!==undefined)environment.FISHTOOLS_DEV_PORT=String(message.details.port);
+        emit('ready',{pid:next.pid,details:message.details??{},recovered:failed});failed=false;
+        if(stopping||pending)drain();
+      }else if(message?.type==='development:waiting')emit('waiting',{pid:next.pid,status:message.status});
+      else if(message?.type==='development:closing'){
+        clearTimeout(startTimer);phase='closing';
+        closeTimer=setTimeout(()=>{void terminate(next,'application');},closeTimeout);
+      }else if(message?.type==='development:failed'){
+        reported=true;failed=true;emit('failed',{pid:next.pid,message:message.message});
+      }else if(message?.type==='development:closed')emit('applicationClosed',{pid:next.pid});
+    });
+    next.on('error',error=>{reported=true;failed=true;emit('failed',{pid:next.pid,message:error.message});});
+    next.once('exit',(code,signal)=>{
+      clearChildTimers();emit('exited',{pid:next.pid,code,signal});if(child===next)child=null;
+      if(stopping)return;
+      if(draining){draining=false;phase='waiting';if(!debounceTimer)launch();}
+      else if(pending){phase='waiting';if(!debounceTimer)launch();}
+      else if(ready&&!reported){void supervisor.close();}
+      else{phase='failed';failed=true;if(!reported)emit('failed',{pid:next.pid,message:`开发应用启动失败（${code??signal}），修复源码后自动重试`});}
+    });
+  }
+  function drain(){
+    if(draining||!active())return;
+    draining=true;phase='waiting';emit('restarting',{pid:child.pid});send(child,{type:'development:drain'});
+  }
+  function changed(message){
+    if(stopping)return;pending=true;emit('changed',{file:message.file});clearTimeout(debounceTimer);
+    debounceTimer=setTimeout(()=>{debounceTimer=null;if(active()){if(phase!=='starting')drain();}else launch();},debounce);
+  }
+  const supervisor={
+    status:()=>({phase,generation,pending,pid:active()?child.pid:null,watcherPid:watcher?.exitCode===null&&watcher.signalCode===null?watcher.pid:null}),
+    close(){
+      if(closing)return closing;stopping=true;clearTimeout(debounceTimer);debounceTimer=null;clearTimeout(scanTimer);
+      closing=(async()=>{
+        const watched=watcher;
+        const stopWatch=watched&&watched.exitCode===null&&watched.signalCode===null?new Promise(resolve=>{
+          const timer=setTimeout(async()=>resolve(await terminate(watched,'watcher')),closeTimeout);
+          watched.once('exit',()=>{clearTimeout(timer);resolve(true);});send(watched,{type:'close'});
+        }):Promise.resolve(true);
+        const running=child;
+        const stopApp=active()?new Promise(resolve=>{
+          // 活跃业务无强制截止时间；收到 idle/closing 才开始关闭超时预算。
+          running.once('exit',()=>resolve(true));drain();
+          const blocked=()=>{if(phase==='blocked'){clearInterval(check);resolve(false);}};
+          const check=setInterval(blocked,Math.min(killTimeout,100));running.once('exit',()=>clearInterval(check));
+        }):Promise.resolve(true);
+        const results=await Promise.all([stopWatch,stopApp]);clearChildTimers();
+        if(results.some(result=>!result)){phase='blocked';throw new Error('开发子进程未回收，不能启动重叠宿主');}
+        phase='closed';emit('closed');
+      })();return closing;
+    },
+  };
+  const watchOptions={projectDir,configFile:options.configFile?path.resolve(options.configFile):undefined,
+    maxDirectories:positive(options.maxDirectories,512,'maxDirectories'),maxEntries:positive(options.maxEntries,20000,'maxEntries'),maxDepth:positive(options.maxDepth,24,'maxDepth')};
+  try{
+    await new Promise((resolve,reject)=>{
+      let initialized=false;
+      watcher=fork(worker,[],{env:{...process.env,FISHTOOLS_WATCH_OPTIONS:JSON.stringify(watchOptions)},execArgv:[],windowsHide:true,stdio:['ignore','ignore','pipe','ipc']});
+      const deadline=()=>{clearTimeout(scanTimer);scanTimer=setTimeout(async()=>{
+        emit('watchError',{message:'开发目录扫描超时，停止监听并回收隔离进程'});
+        await terminate(watcher,'watcher');if(!initialized)reject(new Error('开发目录扫描超时'));
+      },watchTimeout);};deadline();
+      watcher.on('message',message=>{
+        if(message?.type==='scanning')deadline();
+        else if(message?.type==='ready'||message?.type==='snapshot'){
+          clearTimeout(scanTimer);emit('watching',message);
+          if(message.readOnly){if(!initialized)reject(new Error('只读运行包不能启用开发源码监听'));else{emit('watchError',{message:'项目已变为只读，开发监听正在关闭'});void supervisor.close();}return;}
+          if(!initialized){initialized=true;resolve();}
+        }else if(message?.type==='changed')changed(message);
+        else if(message?.type==='warning')emit('watchError',{message:message.message});
+        else if(message?.type==='fatal'){clearTimeout(scanTimer);if(!initialized)reject(new Error(message.message));else emit('watchError',{message:message.message});}
+      });
+      watcher.on('error',error=>{if(!initialized)reject(error);else emit('watchError',{message:error.message});});
+      watcher.once('exit',()=>{clearTimeout(scanTimer);if(!initialized)reject(new Error('开发文件监听进程提前退出'));else if(!stopping)emit('watchError',{message:'开发文件监听进程已停止'});});
+      watcher.stderr.on('data',data=>emit('watchError',{message:String(data).trim()}));
+    });launch();return supervisor;
+  }catch(error){await supervisor.close();throw error;}
+}
+
+/** 子进程必须把应用空闲状态与关闭动作放在同一事件循环中判断。 */
+export function bindDevelopmentChild(app,{details={},closePresentation,pollInterval=100}={}){
+  let requested=false,checking=false,closed=false,waiting=false;
+  let finish;const done=new Promise(resolve=>{finish=resolve;});
+  const sendMessage=message=>{if(process.connected)process.send(message);};
+  async function check(){
+    if(!requested||checking||closed)return;
+    const status=app.developmentStatus();
+    if(status.running||status.busy||status.closing){if(!waiting){waiting=true;sendMessage({type:'development:waiting',status});}return;}
+    checking=true;sendMessage({type:'development:closing'});
+    try{
+      const errors=[];
+      try{await app.close();}catch(error){errors.push(error);}
+      try{await closePresentation?.();}catch(error){errors.push(error);}
+      if(errors.length)throw new AggregateError(errors,errors.map(error=>error.message).join('；'));
+      sendMessage({type:'development:closed'});
+    }
+    catch(error){sendMessage({type:'development:failed',message:`开发应用关闭失败：${error.message}`});process.exitCode=1;}
+    finally{closed=true;clearInterval(timer);process.removeListener('message',message);process.removeListener('disconnect',disconnected);process.disconnect?.();finish();}
+  }
+  const message=message=>{if(message?.type==='development:drain'){requested=true;void check();}};
+  const disconnected=()=>{requested=true;void check();};
+  const timer=setInterval(()=>{void check();},positive(pollInterval,100,'pollInterval'));
+  process.on('message',message);process.on('disconnect',disconnected);sendMessage({type:'development:ready',details});
+  return {close:()=>{requested=true;void check();return done;}};
+}

package/manual/packages/core/src/environments.js

@@ -0,0 +1,2 @@
+// 兼容既有 core 公开入口，实际能力由 platform 模块维护。
+export * from '@mytools/fst-platform/environments';

package/manual/packages/core/src/export-snapshot.js

@@ -0,0 +1,42 @@
+import {fileURLToPath} from 'node:url';
+import {FlowError} from '@mytools/sdk';
+
+function selectedNetwork(network,ids){
+  if(!network)return undefined;
+  const plugins=Object.fromEntries(Object.entries(network.plugins??{}).filter(([id])=>ids.has(id)));
+  const used=new Set();
+  const add=rule=>{if(rule?.mode==='profile')used.add(rule.profile);};
+  add(network.default);
+  for(const policy of Object.values(plugins)){
+    add(policy.default);
+    for(const rule of Object.values(policy.actions??{}))add(rule);
+  }
+  return {
+    ...(network.default?{default:network.default}:{}),
+    profiles:Object.fromEntries(Object.entries(network.profiles??{}).filter(([name])=>used.has(name))),
+    plugins,
+  };
+}
+
+// 只向打包器交付声明快照和发行入口位置，避免其直接访问活跃宿主。
+export async function createExportSnapshot({store,host,project},{entries,portable=false,includeWeb=false}={}){
+  if(portable)entries=(await store.list()).map(w=>w.id);
+  if(!portable&&!entries?.length)throw new FlowError('请至少选择一个工作流');
+  const closure=await store.resolve(entries,host);
+  const web=[...host.definitions.values()].find(p=>typeof p.services?.web==='function');
+  const ids=new Set(portable?[...host.definitions.keys()].filter(id=>id!==web?.id||includeWeb):closure.plugins);
+  for(const id of closure.plugins)ids.add(id);
+  if(includeWeb){if(!web)throw new FlowError('未安装提供 Web 服务的插件');ids.add(web.id);}
+  for(const id of ids)for(const dependency of Object.keys(host.definitions.get(id)?.dependencies??{}))ids.add(dependency);
+  const plugins=[...ids].map(id=>{
+    const p=host.definitions.get(id);
+    if(!p?.root)throw new FlowError('内存中临时定义的插件不能打包，请先安装为标准包');
+    return Object.fromEntries([
+      ...['id','version','root','platforms','architectures','environments','dependencies','defaultConfig'].map(key=>[key,p[key]]),
+      ['requirements',p.requirements],
+      ['actions',Object.fromEntries(Object.entries(p.actions??{}).map(([name,action])=>[name,{environments:action.environments,requirements:action.requirements}]))],
+    ]);
+  });
+  return structuredClone({entries,closure,plugins,project:{environments:project.environments,network:selectedNetwork(project.network,ids),logs:project.logs,baseBundle:project.baseBundle},
+    toolRoot:fileURLToPath(new URL('../../fst-cli',import.meta.url))});
+}

package/manual/packages/core/src/plugin-update.js

@@ -0,0 +1,108 @@
+import {isDeepStrictEqual} from 'node:util';
+import {createHash} from 'node:crypto';
+import {createReadStream} from 'node:fs';
+import {readFile,readdir,readlink} from 'node:fs/promises';
+import path from 'node:path';
+
+function comparable(value){
+  if(typeof value==='function')return {functionSource:Function.prototype.toString.call(value)};
+  if(Array.isArray(value))return value.map(comparable);
+  if(value&&typeof value==='object')return Object.fromEntries(Object.entries(value).filter(([key])=>key!=='root').map(([key,item])=>[key,comparable(item)]));
+  return value;
+}
+
+function dependencies(definitions){
+  const consumers=new Map(),providers=new Map();
+  for(const [id,p] of definitions)for(const name of p.runtime?.provides??[])providers.set(name,id);
+  for(const [id,p] of definitions){
+    const used=new Set(Object.keys(p.dependencies??{}));
+    for(const name of p.runtime?.inject??[])if(providers.has(name))used.add(providers.get(name));
+    for(const owner of used){
+      if(!consumers.has(owner))consumers.set(owner,new Set());
+      consumers.get(owner).add(id);
+    }
+  }
+  return consumers;
+}
+
+export function planPluginUpdate(current,next,currentConfig={},nextConfig={},sourceChanged=new Set()){
+  const all=[...new Set([...current.keys(),...next.keys()])],changed=[];
+  for(const id of all){
+    const before=current.get(id),after=next.get(id);
+    if(!before||!after||sourceChanged.has(id)||!isDeepStrictEqual(comparable(before),comparable(after))||!isDeepStrictEqual(currentConfig[id]??{},nextConfig[id]??{}))changed.push(id);
+  }
+  const oldConsumers=dependencies(current),newConsumers=dependencies(next),affected=new Set(changed),queue=[...changed];
+  while(queue.length){
+    const owner=queue.shift();
+    for(const id of new Set([...(oldConsumers.get(owner)??[]),...(newConsumers.get(owner)??[])]))if(!affected.has(id)){
+      affected.add(id);queue.push(id);
+    }
+  }
+  const maintenance=[...affected].filter(id=>[current.get(id),next.get(id)].some(p=>p?.runtime&&p.runtime.updatePolicy!=='automatic'));
+  return {changed,affected:[...affected],maintenance};
+}
+
+async function directoryDigest(root){
+  const hash=createHash('sha256');
+  const visit=async(directory,relative='')=>{
+    const entries=(await readdir(directory,{withFileTypes:true})).sort((a,b)=>a.name.localeCompare(b.name));
+    for(const entry of entries){
+      if(entry.name==='node_modules'||entry.name==='.git')continue;
+      const name=path.posix.join(relative,entry.name),file=path.join(directory,entry.name);
+      hash.update(name);hash.update('\0');
+      if(entry.isDirectory())await visit(file,name);
+      else if(entry.isFile())for await(const chunk of createReadStream(file))hash.update(chunk);
+      else if(entry.isSymbolicLink())hash.update(await readlink(file));
+      else hash.update(entry.name);
+      hash.update('\0');
+    }
+  };
+  await visit(root);return hash.digest('hex');
+}
+
+async function resolutionDigest(installationRoot,pluginRoot){
+  if(!installationRoot)return null;
+  let lock;
+  try{lock=JSON.parse(await readFile(path.join(installationRoot,'package-lock.json'),'utf8'));}
+  catch(error){if(error.code==='ENOENT')return null;throw error;}
+  const packages=lock.packages??{},start=path.relative(installationRoot,pluginRoot).split(path.sep).join('/');
+  if(!Object.hasOwn(packages,start))return null;
+  const visited=new Set(),items=[];
+  const resolve=(from,name)=>{
+    let prefix=from;
+    while(true){
+      const key=`${prefix?`${prefix}/`:''}node_modules/${name}`;
+      if(Object.hasOwn(packages,key))return key;
+      if(!prefix)return null;
+      const index=prefix.lastIndexOf('/node_modules/');
+      prefix=index<0?'':prefix.slice(0,index);
+    }
+  };
+  const visit=key=>{
+    if(visited.has(key))return;visited.add(key);
+    const entry=packages[key];items.push([key,entry]);
+    for(const name of Object.keys({...entry.dependencies,...entry.optionalDependencies,...entry.peerDependencies}).sort()){
+      const dependency=resolve(key,name);
+      if(dependency)visit(dependency);
+      else items.push([`${key} -> ${name}`,null]);
+    }
+  };
+  visit(start);
+  items.sort(([a],[b])=>a.localeCompare(b));
+  return createHash('sha256').update(JSON.stringify(items)).digest('hex');
+}
+
+export async function changedPluginSources(current,next,{oldInstallationRoot,newInstallationRoot}={}){
+  const changed=new Set();
+  for(const [id,before] of current){
+    const after=next.get(id);
+    if(!after||before.root===after.root)continue;
+    if(!before.root||!after.root){changed.add(id);continue;}
+    const [beforeFiles,afterFiles,beforeLock,afterLock]=await Promise.all([
+      directoryDigest(before.root),directoryDigest(after.root),
+      resolutionDigest(oldInstallationRoot,before.root),resolutionDigest(newInstallationRoot,after.root),
+    ]);
+    if(beforeFiles!==afterFiles||beforeLock!==afterLock)changed.add(id);
+  }
+  return changed;
+}

package/manual/packages/core/src/process.js

@@ -0,0 +1,2 @@
+// 兼容既有 core 公开入口，实际能力由 platform 模块维护。
+export * from '@mytools/fst-platform';

package/manual/packages/core/src/resources.js

@@ -0,0 +1,31 @@
+import {FlowError} from '@mytools/sdk';
+
+// 应用持有长驻资源；业务插件宿主替换时，这些句柄仍属于同一个应用。
+export function createResources(){
+  const pending=new Map(),handles=new Map();let closing;
+  return {
+    active:owner=>[...pending.values(),...handles.values()].includes(owner),
+    async own(factory,owner){
+      if(closing)throw new FlowError('应用已关闭');
+      const task=Promise.resolve().then(factory).then(raw=>{
+        if(typeof raw?.close!=='function')throw new FlowError('长期资源必须提供 close()');
+        let closed;
+        const handle={...raw,close(){
+          closed??=Promise.resolve().then(()=>raw.close()).then(()=>{handles.delete(handle);});
+          return closed;
+        }};
+        handles.set(handle,owner);return handle;
+      });
+      pending.set(task,owner);
+      try{return await task;}finally{pending.delete(task);}
+    },
+    close(){
+      closing??=(async()=>{
+        await Promise.allSettled([...pending.keys()]);
+        const results=await Promise.allSettled([...handles.keys()].map(h=>h.close()));
+        const errors=results.filter(r=>r.status==='rejected').map(r=>r.reason);
+        if(errors.length)throw new AggregateError(errors,`资源关闭失败：${errors.map(e=>e.message).join('；')}`);
+      })();return closing;
+    },
+  };
+}

package/manual/packages/core/src/version.js

@@ -0,0 +1,2 @@
+// 由 npm version 的生命周期脚本同步，内部插件 API 版本独立维护。
+export const VERSION="0.5.1";

package/manual/packages/fst-cli/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mytools 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/manual/packages/fst-cli/README.md

@@ -0,0 +1,59 @@
+# 命令行与终端模块
+
+包名：`@mytools/fst-cli`。内部 workspace 包，随 `@yanglaofish/fishtools` 统一交付。
+
+## 职责与边界
+
+fst 命令入口、交互终端、输入呈现和运行观察。通过公开应用和模块接口工作，业务执行不在界面中重复实现。
+
+内部依赖：`@mytools/sdk`、`@mytools/core`、`@mytools/fst-workspace`、`@mytools/fst-platform`、`@mytools/fst-plugin`、`@mytools/fst-devtools`、`@mytools/fst-logs`。
+## 公开入口
+
+| 导入路径 | 实现位置 |
+| --- | --- |
+| `@mytools/fst-cli` | `./src/terminal/session.js` |
+| `@mytools/fst-cli/entry` | `./bin/fst.js` |
+| `@mytools/fst-cli/run` | `./src/cli-run.js` |
+| `@mytools/fst-cli/terminal/conditions` | `./src/terminal/conditions.js` |
+| `@mytools/fst-cli/terminal/log-viewer` | `./src/terminal/log-viewer.js` |
+| `@mytools/fst-cli/terminal/model` | `./src/terminal/model.js` |
+| `@mytools/fst-cli/terminal/navigation` | `./src/terminal/navigation.js` |
+| `@mytools/fst-cli/terminal/presentation` | `./src/terminal/presentation.js` |
+| `@mytools/fst-cli/terminal/run-feed` | `./src/terminal/run-feed.js` |
+| `@mytools/fst-cli/terminal/run-presentation` | `./src/terminal/run-presentation.js` |
+| `@mytools/fst-cli/terminal/run-viewer` | `./src/terminal/run-viewer.js` |
+| `@mytools/fst-cli/terminal/schema` | `./src/terminal/schema.js` |
+| `@mytools/fst-cli/terminal/session` | `./src/terminal/session.js` |
+| `@mytools/fst-cli/terminal/theme` | `./src/terminal/theme.js` |
+| `@mytools/fst-cli/terminal/view` | `./src/terminal/view.js` |
+| `@mytools/fst-cli/terminal/workflow-menu` | `./src/terminal/workflow-menu.js` |
+| `@mytools/fst-cli/package.json` | `./package.json` |
+
+仅依赖 exports 声明的入口，禁止消费者跨包读取 src/bin 私有文件。入口路径由本模块维护，修改协议时同步消费方回归。
+
+## 维护与验证
+
+本模块负责上述职责的实现、文档与回归；跨模块接口调整需要同时检查生产者与消费者。具体维护人员尚未指定。
+
+在仓库根目录执行：
+
+```sh
+node --test tests/modules.test.js tests/cli.test.js tests/terminal.test.js
+```
+
+## 开发源码自动重载
+
+`fst --watch` 只在交互终端启动开发 TUI；`fst --watch web` 启动开发 Web。先使用 `fst plugin link <目录>` 引用开发源码，修改源码后监督进程等待当前业务运行和管理操作结束，再关闭旧应用并启动新进程。`run`、`plugin`、`pack` 等一次性命令不能使用 `--watch`；只读运行包也不启用源码监听。
+
+连续保存会合并为一次重启，静态导入的子模块随整个进程更新。启动错误在终端明确显示，源码修复后自动恢复。开发 Web 保持同一端口和令牌，`--port 0` 首次分配后的实际端口也会保留。终端重启会恢复旧终端并启动新会话，未保存的编辑草稿不保证保留。关闭卡住时会报告强制回收，确认旧进程退出前不启动下一代。
+
+启动监督器的进程只解析参数及监听源码，不创建插件宿主。实际应用子进程由 `src/development.js` 绑定核心开发生命周期。验证：`node --test tests/development-watch.test.js tests/cli.test.js tests/terminal.test.js`。
+
+## 完整日志分页
+
+`fst logs` 列出历史，`fst logs <id> --cursor 0 --limit 65536 --json` 返回正文和下一页字节游标。TUI 运行详情按 `p` 打开完整日志，每页读取后可前后翻页或刷新。主面板保留有界近期摘要；日志清理失败显示维护警告。细节见 `fst docs generation`。
+
+主面板通过 `fst-logs/steps` 共用步骤摘要缓存，按最近更新顺序淘汰，同时限制条数和字节量。
+摘要不保存业务 input/output；缺失的状态显示“摘要已省略”，已有错误仍可查看。
+运行输入、最终结果与错误通过 `fst-logs/preview` 保存有界预览，避免业务完成后又缓存完整大结果。
+展开时明确提示结果为摘要，完整结果仍在日志中；不会替换业务调用方取得的完整输出。

package/{node_modules/@mytools/core → manual/packages/fst-cli}/bin/fst.js

@@ -2,20 +2,34 @@
 import { Command } from 'commander';
 import { readFile, access } from 'node:fs/promises';
 import path from 'node:path';
-import { createApplication } from '../src/application.js';
-import { verifyBundle } from '../src/bundle.js';
-import { resolveProject, initializeProject } from '../src/project.js';
+import {fileURLToPath} from 'node:url';
+import { createApplication } from '@mytools/core';
+import { verifyBundle } from '@mytools/fst-platform/bundle';
+import { resolveProject, initializeProject } from '@mytools/fst-workspace/project';
 import {waitForCliRun,cliRunResult} from '../src/cli-run.js';
-import {VERSION} from '../src/version.js';
-import {listDocumentation,readDocumentation,findDocumentationRoot,exportDocumentation} from '../src/documentation.js';
-import {collectInstallations} from '../src/plugin-installations.js';
-import {prepareBundleWorkspace} from '../src/bundle-workspace.js';
-import {readJson} from '../src/plugins.js';
+import {VERSION} from '@mytools/core/version';
+import {listDocumentation,readDocumentation,findDocumentationRoot,exportDocumentation} from '@mytools/fst-devtools/documentation';
+import {collectInstallations} from '@mytools/fst-workspace/installations';
+import {prepareBundleWorkspace} from '@mytools/fst-workspace/bundles';
+import {readJson} from '@mytools/fst-platform/json';
 
 const program=new Command().name('fst').description('Fishtools · 插件式工作流工作台').version(VERSION);
 program.option('--maintenance','维护模式：不启动有状态服务插件');
+program.option('--allow-unverified-privileges','本次允许权限预检结果无法确认的服务启动');
+program.option('--watch','开发模式：监听本地 link 源码，等待业务空闲后重启');
 program.option('--project <directory>','项目目录（默认当前项目或用户工作区）').option('--workspace <directory>','便携包的可写工作区').option('--output <directory>','日志与结果目录').option('--config <file>','插件配置覆盖文件').option('--host <host>','Web 监听地址','127.0.0.1').option('--port <port>','Web 监听端口','8765');
-async function app({management=false,removeInstalled}={}){const o=program.opts();return createApplication({projectDir:await resolveProject(o.project,o.workspace),outputDir:o.output,maintenance:management||!!o.maintenance,omitInstalledPlugin:removeInstalled,config:o.config?JSON.parse(await readFile(o.config,'utf8')):{}});}
+async function app({management=false,removeInstalled,allowUnknownPrivileges=false}={}){const o=program.opts();return createApplication({projectDir:process.env.FISHTOOLS_DEV_PROJECT??await resolveProject(o.project,o.workspace),outputDir:o.output,maintenance:management||!!o.maintenance,omitInstalledPlugin:removeInstalled,allowUnknownPrivileges:allowUnknownPrivileges||!!o.allowUnverifiedPrivileges,config:o.config?JSON.parse(await readFile(o.config,'utf8')):{}});}
+const developmentChild=process.env.FISHTOOLS_DEV_CHILD==='1';
+program.hook('preAction',(_program,command)=>{
+  if(!program.opts().watch||developmentChild)return;
+  if(![program,program.commands.find(item=>item.name()==='web')].includes(command))throw new Error('--watch 开发模式只支持交互 TUI 和 fst --watch web，不能用于一次性命令');
+  if(command===program&&(!process.stdin.isTTY||!process.stdout.isTTY))throw new Error('fst --watch 需要交互终端；Web 开发请使用 fst --watch web');
+});
+async function watchDevelopment(mode,settings=program.opts()){
+  const {startDevelopment}=await import('../src/development.js');
+  return startDevelopment({projectDir:await resolveProject(settings.project,settings.workspace),entry:fileURLToPath(import.meta.url),
+    args:process.argv.slice(2).filter(argument=>argument!=='--watch'),configFile:settings.config,mode,port:Number(settings.port)});
+}
 async function use(fn,options){const a=await app(options);try{for(const warning of a.host.warnings)console.error(`警告：${warning.message}`);return await fn(a);}finally{await a.close();}}
 program.command('init [directory]').description('创建项目，保留已有配置与工作流').action(async directory=>console.log(`Fishtools 项目：${await initializeProject(path.resolve(directory??process.cwd()))}`));
 program.command('docs [topic]').description('阅读或导出随安装提供的离线文档').option('--path','只打印文档路径').option('--export <directory>','导出完整资料到新目录').action(async(topic,options)=>{
@@ -25,29 +39,43 @@ program.command('docs [topic]').description('阅读或导出随安装提供的
   console.log((await listDocumentation()).map(document=>`${document.id}\t${document.title}`).join('\n'));
   console.log('\nfst docs <主题> 阅读正文；fst docs <主题> --path 查看路径；fst docs --export <新目录> 导出全部资料');
 });
-const workflow=program.command('workflow').description('查看和检查工作流');
+const workflow=program.command('workflow').description('查看、检查和复制工作流');
+program.command('logs [id]').description('列出运行历史或分页读取完整日志').option('--cursor <bytes>','正文 UTF-8 字节游标','0').option('--limit <bytes>','每页字节数（4 到 262144）','65536').option('--json','输出正文与下一页游标').action((id,options)=>use(async a=>{
+  if(!id){console.log(JSON.stringify(await a.listRunHistory(),null,2));return;}
+  const page=await a.readLogPage(id,{cursor:Number(options.cursor),limit:Number(options.limit)});
+  if(options.json)console.log(JSON.stringify(page,null,2));else{process.stdout.write(page.text);if(page.hasMore)console.error(`\n下一页：fst logs ${id} --cursor ${page.nextCursor} --limit ${options.limit}`);}
+},{management:true}));
 workflow.command('list').action(()=>use(async a=>console.log(JSON.stringify(await a.listWorkflows(),null,2))));
-workflow.command('check <id>').action(id=>use(async a=>{await a.checkWorkflow(id);console.log('工作流校验通过');}));
-program.command('run <id>').option('--input <file>','JSON 输入文件').action((id,o)=>use(async a=>{
-  const run=await a.startRun(id,o.input?JSON.parse(await readFile(o.input,'utf8')):{});
+workflow.command('check <id>').option('--json','输出包含权限要求的检查结果').action((id,options)=>use(async a=>{const report=await a.checkWorkflow(id);console.log(options.json?JSON.stringify(report,null,2):`工作流校验通过；涉及 ${report.privileges.length} 个动作的权限声明`);}));
+workflow.command('duplicate <source>').description('复制已保存工作流，不修改原版').requiredOption('--title <name>','新工作流名称').option('--id <id>','新工作流 ID（默认自动生成）').action((source,options)=>use(async a=>{
+  const definition=await a.store.get(source);
+  const result=await a.duplicateWorkflow(definition,{id:options.id,title:options.title.trim()});
+  console.log(JSON.stringify(result,null,2));
+}));
+program.command('run <id>').option('--input <file>','JSON 输入文件').option('--allow-unverified-privileges','本次允许权限预检结果为待确认的动作继续运行').action((id,o)=>use(async a=>{
+  const run=await a.startRun(id,o.input?JSON.parse(await readFile(o.input,'utf8')):{},{allowUnknownPrivileges:!!o.allowUnverifiedPrivileges});
   const result=cliRunResult(await waitForCliRun(a,run));console.log(JSON.stringify(result.value,null,2));
   process.exitCode=result.exitCode;
-}));
+},{allowUnknownPrivileges:!!o.allowUnverifiedPrivileges}));
 const plugin=program.command('plugin').description('管理插件');
 plugin.command('list').action(()=>use(a=>console.log(JSON.stringify(a.listPlugins(),null,2))));
 plugin.command('add <source>').action(source=>use(async a=>console.log(JSON.stringify(await a.installPlugin(source),null,2)),{management:true}));
 plugin.command('link <directory>').description('引用本地开发源码，修改后重启 fst 生效').action(directory=>use(async a=>console.log(JSON.stringify(await a.linkPlugin(path.resolve(directory)),null,2)),{management:true}));
-plugin.command('remove <name>').action(name=>use(async a=>console.log(JSON.stringify(await a.removePlugin(name),null,2)),{management:true,removeInstalled:name}));
-plugin.command('validate <directory>').description('检查可信插件声明，不执行动作或运行时服务').option('--json','输出结构化报告').action(async(directory,options)=>{
-  const {validatePluginDirectory}=await import('../src/plugin-tools.js');const report=await validatePluginDirectory(path.resolve(directory));
+plugin.command('remove <name>').option('--force','即使工作流仍引用此插件也继续卸载；不会越过插件依赖与活动 Web 检查').action((name,o)=>use(async a=>console.log(JSON.stringify(await a.removePlugin(name,{force:!!o.force}),null,2)),{management:true,removeInstalled:name}));
+const network=program.command('network').description('查看或保存工作区、插件和动作级代理规则');
+network.command('show').action(()=>use(a=>console.log(JSON.stringify(a.networkPolicy(),null,2))));
+network.command('set <file>').description('从 JSON 保存代理规则').action(file=>use(async a=>{const saved=await a.configureNetworkPolicy(JSON.parse(await readFile(file,'utf8')));console.log(`代理规则已保存；原项目配置备份：${saved.backup}`);}));
+for(const command of ['validate','lint'])plugin.command(`${command} <directory>`).description(command==='lint'?'检查可信插件声明与质量建议，不自动修改文件':'检查可信插件声明，不执行动作或运行时服务').option('--json','输出结构化报告').action(async(directory,options)=>{
+  const tools=await import('@mytools/fst-devtools');const report=await tools[command==='lint'?'lintPluginDirectory':'validatePluginDirectory'](path.resolve(directory));
   if(options.json)console.log(JSON.stringify(report,null,2));else{
     console.log(`${report.valid?'检查通过':'检查未通过'}：${report.plugin?.id??directory}`);
     for(const item of report.diagnostics)console.log(`${item.severity==='error'?'错误':'警告'} [${item.code}] ${item.path??''} ${item.message}`);
+    for(const item of report.notes)console.log(`说明 [${item.code}] ${item.message}`);
   }
   if(!report.valid)process.exitCode=1;
 });
 plugin.command('create <name> [directory]').description('创建可独立安装的插件骨架').action(async(name,directory)=>{
-  const {createPlugin}=await import('../src/plugin-tools.js');const result=await createPlugin(name,path.resolve(directory??name));
+  const {createPlugin}=await import('@mytools/fst-devtools');const result=await createPlugin(name,path.resolve(directory??name));
   console.log(`插件已创建：${result.directory}\n运行 fst plugin validate "${result.directory}" 检查；使用 fst plugin link "${result.directory}" 开发`);
 });
 plugin.command('gc').description('预览未引用安装批次；--apply 先备份再清理').option('--apply','压缩备份后清理安全批次').action(async options=>{
@@ -63,20 +91,24 @@ async function pack(a,entries,o,portable=false){
 }
 packOptions(program.command('pack <entries...>')).option('--web','包含 Web 界面').action((entries,o)=>use(a=>pack(a,entries,o)));
 packOptions(program.command('portable').description('导出完整便携工具、当前全部流程和插件')).option('--no-web','不额外携带 Web').action(o=>use(a=>pack(a,[],o,true)));
-program.command('command [name]').description('列出插件命令或执行动作命令').option('--input <file>','JSON 输入').action((name,o)=>use(async a=>{
+program.command('command [name]').description('列出插件命令或执行动作命令').option('--input <file>','JSON 输入').option('--allow-unverified-privileges','本次允许权限预检结果为待确认的命令继续运行').action((name,o)=>use(async a=>{
   if(!name){console.log(JSON.stringify(a.listCommands(),null,2));return;}
-  const run=await a.startCommand(name,o.input?JSON.parse(await readFile(o.input,'utf8')):{});
+  const run=await a.startCommand(name,o.input?JSON.parse(await readFile(o.input,'utf8')):{},{allowUnknownPrivileges:!!o.allowUnverifiedPrivileges});
   const result=cliRunResult(await waitForCliRun(a,run));console.log(JSON.stringify(result.value,null,2));process.exitCode=result.exitCode;
-}));
-program.command('configure <plugin> <file>').description('从 JSON 保存插件配置').action((id,file)=>use(async a=>{await a.configurePlugin(id,JSON.parse(await readFile(file,'utf8')));console.log('插件配置已保存');},{management:true}));
+},{allowUnknownPrivileges:!!o.allowUnverifiedPrivileges}));
+program.command('configure <plugin> <file>').description('从 JSON 保存插件配置').action((id,file)=>use(async a=>{const saved=await a.configurePlugin(id,JSON.parse(await readFile(file,'utf8')));console.log(`插件配置已保存。原项目配置备份：${saved.backup}`);},{management:true}));
 async function web(o){
+  if(program.opts().watch&&!developmentChild)return watchDevelopment('web',o);
+  if(developmentChild){const {runDevelopmentChild}=await import('../src/development.js');const a=await app();try{return await runDevelopmentChild(a,{mode:'web',webOptions:{host:o.host,port:Number(o.port)}});}catch(error){await a.close();throw error;}}
   const a=await app();let server;
   try{server=await a.startWeb({host:o.host,port:Number(o.port)});}catch(error){await a.close();throw error;}
   console.log(`Fishtools：${server.url}`);
   const stop=async()=>{await server.close();await a.close();};process.once('SIGINT',stop);process.once('SIGTERM',stop);
 }
 program.action(async()=>{
+  if(program.opts().watch&&!developmentChild)return watchDevelopment('terminal');
   if(!process.stdin.isTTY||!process.stdout.isTTY){program.outputHelp();return;}
+  if(developmentChild){const {runDevelopmentChild}=await import('../src/development.js');const a=await app();try{return await runDevelopmentChild(a,{mode:'terminal',webOptions:{host:program.opts().host,port:Number(program.opts().port)}});}catch(error){await a.close();throw error;}}
   const {startTerminal}=await import('../src/terminal/session.js');
   await use(a=>startTerminal(a,{webOptions:{host:program.opts().host,port:Number(program.opts().port)}}));
 });
@@ -89,4 +121,4 @@ program.command('doctor').action(()=>use(async a=>{
   console.log(JSON.stringify({node:process.version,platform:process.platform,arch:process.arch,plugins:a.listPlugins(),integrity},null,2));
   if(integrity&&!integrity.ok)process.exitCode=1;
 }));
-try {await program.parseAsync();}catch(error){console.error(error.message);process.exitCode=error.code==='CANCELLED'?130:2;}
+try {await program.parseAsync();}catch(error){console.error(error.message);process.exitCode=error.code==='CANCELLED'?130:2;if(developmentChild){process.send?.({type:'development:failed',message:error.message});process.disconnect?.();}}

package/manual/packages/fst-cli/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@mytools/fst-cli",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "src/terminal/session.js",
+  "exports": {
+    ".": "./src/terminal/session.js",
+    "./entry": "./bin/fst.js",
+    "./run": "./src/cli-run.js",
+    "./terminal/conditions": "./src/terminal/conditions.js",
+    "./terminal/log-viewer": "./src/terminal/log-viewer.js",
+    "./terminal/model": "./src/terminal/model.js",
+    "./terminal/navigation": "./src/terminal/navigation.js",
+    "./terminal/presentation": "./src/terminal/presentation.js",
+    "./terminal/run-feed": "./src/terminal/run-feed.js",
+    "./terminal/run-presentation": "./src/terminal/run-presentation.js",
+    "./terminal/run-viewer": "./src/terminal/run-viewer.js",
+    "./terminal/schema": "./src/terminal/schema.js",
+    "./terminal/session": "./src/terminal/session.js",
+    "./terminal/theme": "./src/terminal/theme.js",
+    "./terminal/view": "./src/terminal/view.js",
+    "./terminal/workflow-menu": "./src/terminal/workflow-menu.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "bin",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.15.0"
+  },
+  "dependencies": {
+    "@mytools/sdk": "0.1.0",
+    "@mytools/core": "0.1.0",
+    "@mytools/fst-logs": "0.1.0",
+    "@mytools/fst-workspace": "0.1.0",
+    "@mytools/fst-platform": "0.1.0",
+    "@mytools/fst-plugin": "0.1.0",
+    "@mytools/fst-devtools": "0.1.0",
+    "@mariozechner/pi-tui": "0.50.0",
+    "commander": "14.0.3"
+  },
+  "bin": {
+    "fst": "bin/fst.js"
+  }
+}