@yanglaofish/fishtools 0.1.4 → 0.3.0

package/manual/packages/core/src/terminal/view.js

@@ -0,0 +1,283 @@
+import { readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { homedir } from 'node:os';
+import { TUI, Text, Container, Editor, SelectList, ProcessTerminal, CombinedAutocompleteProvider, matchesKey, truncateToWidth, visibleWidth } from '@mariozechner/pi-tui';
+import { MarkdownLogViewer } from './log-viewer.js';
+import { RunViewer, mouseOn, mouseOff, mouseWheel } from './run-viewer.js';
+import {RunFeed} from './run-feed.js';
+import { logo } from './presentation.js';
+import { VERSION } from '../version.js';
+import {cleanText as safe,palette,menuTheme as theme,fitLine,shortenPath} from './theme.js';
+
+export const cancelled=()=>Object.assign(new Error('已返回主菜单'),{code:'PROMPT_CANCELLED'});
+// 上游菜单按字符数分配描述宽度，中文双宽字符需要再按终端列宽收口。
+function fit(component){const render=component.render.bind(component);component.render=width=>render(width).map(line=>truncateToWidth(line,width));return component;}
+
+// Pi 的 @ 模糊搜索依赖额外的 fd 程序。这里按目录补全，离线目标机无需安装 fd。
+export class FileAutocomplete extends CombinedAutocompleteProvider{
+  constructor(commands,baseDir,workflows=[]){super(commands,baseDir);this.baseDir=baseDir;this.workflows=workflows;}
+  getSuggestions(lines,line,col){
+    const run=lines[line].slice(0,col).match(/^\/run\s+([^@"\s]*)$/);
+    if(run){
+      const query=run[1].toLowerCase(),items=this.workflows.filter(flow=>`${flow.id} ${flow.title??''}`.toLowerCase().includes(query)).map(flow=>({value:flow.id,label:flow.title??flow.id,description:flow.id,workflow:true}));
+      return items.length?{prefix:run[1],items}:null;
+    }
+    const prefix=lines[line].slice(0,col).match(/(?:^|\s)(@"[^"\n]*|@[^\s]*)$/)?.[1];
+    if(!prefix)return super.getSuggestions(lines,line,col);
+    const raw=prefix.slice(1).replace(/^"/,'').replaceAll('\\','/');
+    const expanded=raw.startsWith('~/')?path.join(homedir(),raw.slice(2)):raw;
+    const absolute=path.resolve(this.baseDir,expanded||'.');
+    const directory=!raw||raw.endsWith('/')?absolute:path.dirname(absolute);
+    const query=!raw||raw.endsWith('/')?'':path.basename(absolute).toLowerCase();
+    try{
+      const items=readdirSync(directory,{withFileTypes:true}).filter(e=>e.name.toLowerCase().startsWith(query)).map(e=>{
+        let dir=e.isDirectory();if(e.isSymbolicLink()){try{dir=statSync(path.join(directory,e.name)).isDirectory();}catch{}}
+        const head=raw.slice(0,raw.lastIndexOf('/')+1),file=head+e.name+(dir?'/':'');
+        return {value:`@${/[\s"]/.test(file)?JSON.stringify(file):file}`,label:safe(e.name)+(dir?'/':''),description:dir?'目录':'文件',directory:dir};
+      }).sort((a,b)=>(b.description==='目录')-(a.description==='目录')||a.label.localeCompare(b.label)).slice(0,100);
+      return items.length?{prefix,items}:null;
+    }catch{return null;}
+  }
+  getForceFileSuggestions(lines,line,col){return this.getSuggestions(lines,line,col);}
+  applyCompletion(lines,line,col,item,prefix){
+    if(item.workflow){const next=[...lines],before=lines[line].slice(0,col-prefix.length),text=item.value+' ';next[line]=before+text+lines[line].slice(col);return {lines:next,cursorLine:line,cursorCol:before.length+text.length};}
+    if(!prefix.startsWith('@'))return super.applyCompletion(lines,line,col,item,prefix);
+    const before=lines[line].slice(0,col-prefix.length);
+    let after=lines[line].slice(col);if(after.startsWith('"'))after=after.slice(1);
+    const completed=item.value+(item.directory?'':' '),next=[...lines];next[line]=before+completed+after;
+    return {lines:next,cursorLine:line,cursorCol:before.length+completed.length-(item.directory&&item.value.endsWith('"')?1:0)};
+  }
+}
+
+export class TerminalView{
+  constructor({baseDir,previewLabel,terminal=new ProcessTerminal()}={}){
+    this.baseDir=baseDir;this.terminal=terminal;this.tui=new TUI(terminal);this.logs=[];this.runViews=new Map();
+    this.historyOffset=0;this.commandHistory=[];this.commandHistoryIndex=null;this.feed=new RunFeed(()=>this.refreshTranscript());
+    const originalStart=terminal.start.bind(terminal);
+    terminal.start=(input,resize)=>originalStart(data=>{
+      if(this.homeInput&&!this.runViewer&&!this.logViewer){
+        if(this.browseCommands(data))return;
+        if(matchesKey(data,'ctrl+o')){this.feed.expanded=!this.feed.expanded;this.historyOffset=0;this.refreshTranscript();return;}
+        const wheel=mouseWheel(data),page=Math.max(1,Math.floor(this.terminal.rows/2));
+        if(wheel||matchesKey(data,'pageUp')||matchesKey(data,'pageDown')){
+          this.historyOffset=Math.max(0,this.historyOffset+(wheel?-wheel*3:matchesKey(data,'pageUp')?page:-page));this.tui.requestRender();return;
+        }
+      }
+      if(matchesKey(data,'f4')&&this.homeInput&&this.pending&&!this.runViewer&&!this.logViewer){
+        // 快捷入口不提交或丢弃当前草稿，返回首页时继续编辑。
+        this.homeDraft=this.editor.getText();this.pending.resolve('/logs');return;
+      }
+      if(matchesKey(data,'ctrl+c')){if(this.runViewer){this.runViewer.onClose();return;}if(this.cancelRun)this.cancelRun();this.pending?.reject(cancelled());return;}
+      if(matchesKey(data,'escape')&&this.pending&&!this.logViewer&&!this.runViewer){
+        // 编辑器自己处理补全菜单 Escape，第二次 Escape 返回上一级。
+        if(this.editor?.isShowingAutocomplete?.()){input(data);return;}
+        this.pending.reject(cancelled());return;
+      }
+      input(data);
+    },resize);
+    this.header=new Text('',1,0);this.transcript=new Text('',1,0);this.prompt=new Container();this.hint=new Text('',1,0);
+    this.hint.render=width=>['',fitLine(' '+palette.muted(this.homeInput?(width<45?`/ 操作 · Ctrl+O ${this.feed.expanded?'收起':'展开'}`:`/ 操作 · Ctrl+O ${this.feed.expanded?'收起':'展开'}详情 · /logs 回看 · Ctrl+C 退出`):(width<45?'↑↓ 选择  Enter 确认  Esc 返回':'↑↓ 选择   Enter 确认   Tab 补全   Esc 返回   Ctrl+C 退出')),width)];
+    const renderTranscript=this.transcript.render.bind(this.transcript);
+    this.headingLines=(width,mark='FISHtools')=>{
+      const room=Math.max(1,width-2),lines=[''];
+      const summary=(this.summaryText??'').split('\n');
+      const workspace=summary.find(line=>line.startsWith('当前工作区：'));
+      const details=summary.filter(line=>line!==workspace&&!line.startsWith('[F4')&&!line.startsWith('欢迎使用'));
+      if(mark===logo){
+        const side=[palette.text('FISHtools')+'  '+palette.muted(`v${VERSION}`),palette.text('欢迎使用 · 插件编排工作台'),palette.muted(details[0]??'')];
+        lines.push(...logo.split('\n').map((line,i)=>' '+palette.brand(line)+'   '+side[i]));
+      }else lines.push(' '+palette.brand('FISH')+palette.text('tools')+'  '+palette.muted(`v${VERSION}`));
+      if(previewLabel)lines.push(' '+palette.brand(safe(previewLabel)));
+      if(workspace){
+        const label='当前工作区：',folder=shortenPath(workspace.slice(label.length),Math.max(1,room-visibleWidth(label)));
+        lines.push(' '+palette.muted(label)+palette.text(folder));
+      }
+      lines.push(' '+palette.muted('位置：')+palette.brand('主面板')+(this.commandLocation?palette.muted(' › ')+palette.text(this.commandLocation):''));
+      if(this.activeRuns?.())lines.push(' '+palette.muted(`${this.activeRuns()} 个运行中 · /logs 查看详情`));
+      lines.push('');return lines.map(line=>fitLine(line,width));
+    };
+    // 先保证输入与菜单可见，空间充足才展示三行字标。
+    this.header.render=width=>{
+      const full=this.headingLines(width,logo),other=renderTranscript(width).length+this.prompt.render(width).length+this.hint.render(width).length;
+      let lines=width>=55&&this.terminal.rows>=18&&full.length+other<=this.terminal.rows&&!this.feed.entries.length?full:this.headingLines(width);
+      const budget=Math.max(0,this.terminal.rows-this.prompt.render(width).length-this.hint.render(width).length-1);
+      if(lines.length>budget)lines=lines.filter(line=>safe(line).trim());
+      if(lines.length>budget)lines=lines.slice(0,budget);
+      return lines;
+    };
+    this.transcript.render=width=>{
+      const lines=renderTranscript(width),budget=Math.max(0,this.terminal.rows-this.header.render(width).length-this.prompt.render(width).length-this.hint.render(width).length);
+      if(lines.length<=budget){this.historyOffset=0;return lines;}
+      if(!budget)return [];
+      if(this.feed.entries.length){
+        const count=Math.max(0,budget-1),max=Math.max(0,lines.length-count);this.historyOffset=Math.min(this.historyOffset,max);
+        const end=lines.length-this.historyOffset,start=Math.max(0,end-count);
+        return [...lines.slice(start,end),fitLine(' '+palette.muted(`PgUp/PgDn/滚轮 查看过程 · ${this.historyOffset?'历史位置':'跟随最新'}`),width)];
+      }
+      const excerpt=this.logs.length<=1?lines.slice(0,budget-1):lines.slice(-(budget-1)||lines.length);
+      return [...excerpt,fitLine(' '+palette.muted('… /help 完整帮助 · /logs 运行日志'),width)];
+    };
+    this.tui.addChild(this.header);this.tui.addChild(this.transcript);this.tui.addChild(this.prompt);this.tui.addChild(this.hint);
+  }
+  start(){
+    if(this.started)return;this.started=true;
+    // 独立屏幕避免全屏阅读与主终端的滚动历史混在一起。
+    this.terminal.write('\x1b[?1049h\x1b[2J\x1b[H');this.tui.start();
+  }
+  browseCommands(data){
+    const direction=matchesKey(data,'up')?-1:matchesKey(data,'down')?1:0;
+    // 补全菜单保留方向键；多行编辑保留光标移动，不把配置值放进命令历史。
+    if(!direction||!this.editor||this.editor.isShowingAutocomplete()||this.editor.getText().includes('\n')||!this.commandHistory.length)return false;
+    const current=this.commandHistoryIndex??this.commandHistory.length;
+    const next=Math.max(0,Math.min(this.commandHistory.length,current+direction));
+    if(next===current)return true;
+    if(this.commandHistoryIndex===null)this.commandHistoryDraft=this.editor.getText();
+    this.commandHistoryIndex=next;
+    this.editor.setText(next===this.commandHistory.length?this.commandHistoryDraft:this.commandHistory[next]);
+    if(next===this.commandHistory.length)this.commandHistoryIndex=null;
+    this.tui.requestRender();return true;
+  }
+  async close(){
+    if(this.closed)return;this.closed=true;
+    this.feed.close();
+    // Pi 的渲染排在 nextTick；先排空最后一帧，再恢复终端，避免退出后隐藏光标。
+    await new Promise(resolve=>process.nextTick(resolve));this.tui.stop();
+    if(this.started)this.terminal.write(mouseOff+'\x1b[?1049l');
+    if(this.terminal instanceof ProcessTerminal)process.stdin.pause();
+  }
+  summary(text){this.summaryText=safe(text);this.tui.requestRender();}
+  beginCommand(text){
+    const name=text.trim().split(/\s+/)[0].replace(/^\//,'');
+    const labels={workflows:'工作流',run:'运行工作流',plugin:'插件管理',plugins:'插件管理',config:'工具配置',pack:'打包',logs:'执行记录',runs:'执行记录',tools:'工具',help:'帮助',exit:'退出'};
+    this.commandLocation=labels[name]??'/'+name;this.historyOffset=0;
+    this.clearMessages();this.feed.message('› '+safe(text));
+  }
+  endCommand(){
+    this.commandLocation=null;this.tui.requestRender();
+  }
+  transcriptText(){return [...this.logs,this.feed.text()].filter(Boolean).join('\n\n');}
+  refreshTranscript(){
+    const width=this.terminal.columns,previous=this.transcript.render===undefined?0:new Text(safe(this.lastTranscript??''),1,0).render(width).length;
+    const text=safe(this.transcriptText());
+    if(this.historyOffset>0)this.historyOffset=Math.max(0,this.historyOffset+new Text(text,1,0).render(width).length-previous);
+    this.lastTranscript=text;this.transcript.setText(text.split('\n').map(line=>line.startsWith('✗ ')?palette.error(line):/^[›✓●] /.test(line)?palette.brand(line):line.startsWith('↩ ')?palette.muted(line):line).join('\n'));this.tui.requestRender();
+  }
+  trackRun(options){this.feed.track(options);}
+  clearMessages(){this.logs=[];this.refreshTranscript();}
+  show(message,{kind='message'}={}){
+    const text=safe(message).slice(0,6000);
+    const formatted=kind==='welcome'?text.split('\n').map((line,i)=>i===0?palette.text(line):palette.muted(line)).join('\n'):text;
+    if(kind!=='welcome'){this.feed.message(formatted);return;}
+    this.logs.push(formatted);this.logs=this.logs.slice(-6);this.refreshTranscript();
+  }
+  async viewMarkdown(title,text){
+    const previousPending=this.pending??null,previousViewer=this.logViewer;
+    const children=this.tui.children;
+    let overlay;
+    try{
+      await new Promise((resolve,reject)=>{
+        this.pending={resolve,reject};
+        this.logViewer=new MarkdownLogViewer({title:safe(title),text:safe(text),terminal:this.terminal,onClose:resolve,requestRender:()=>this.tui.requestRender()});
+        this.terminal.write(mouseOn);
+        // Overlay 的基底为空，旧 transcript 不再撑高滚动区域；关闭后原样恢复。
+        this.tui.children=[];
+        overlay=this.tui.showOverlay(this.logViewer,{width:'100%',maxHeight:'100%',anchor:'top-left',margin:0});
+        this.tui.requestRender(true);
+      });
+    }finally{
+      this.tui.children=children;this.pending=previousPending;this.logViewer=previousViewer;
+      overlay?.hide();this.tui.requestRender(true);
+      this.terminal.write(mouseOff);
+    }
+  }
+  async observeRun({app,runId,record,flow,workflows=[],initialView}){
+    const previousPending=this.pending??null,children=this.tui.children;let overlay,unsubscribe;
+    const initial=app.getRun(runId)??record??await app.readRun(runId);
+    if(!initial)throw new Error('这次运行记录已不存在');
+    try{
+      await new Promise((resolve,reject)=>{
+        this.pending={resolve,reject};
+        this.runViewer=new RunViewer({record:initial,flow:initial.status==='running'?flow:undefined,workflows,catalog:app.catalog?.()??[],terminal:this.terminal,onClose:resolve,onCancel:()=>app.cancelRun(runId),requestRender:()=>this.tui.requestRender()});
+        Object.assign(this.runViewer,this.runViews.get(runId)??{});
+        if(initialView!==undefined){this.runViewer.view=initialView;this.runViewer.offset=0;}
+        unsubscribe=app.subscribe(event=>{if(event.runId===runId)this.runViewer?.update(app.getRun(runId));});
+        this.tui.children=[];this.terminal.write(mouseOn);
+        overlay=this.tui.showOverlay(this.runViewer,{width:'100%',maxHeight:'100%',anchor:'top-left',margin:0});this.tui.requestRender(true);
+      });
+    }finally{
+      if(this.runViewer){const {view,selected,offset,follow,allLogs,raw}=this.runViewer;this.runViews.set(runId,{view,selected,offset,follow,allLogs,raw});}
+      if(this.runViews.size>30)this.runViews.delete(this.runViews.keys().next().value);
+      unsubscribe?.();this.runViewer=null;this.tui.children=children;this.pending=previousPending;overlay?.hide();this.terminal.write(mouseOff);this.tui.requestRender(true);
+    }
+  }
+  async ask(message,component){
+    fit(component);
+    const title=new Text(palette.brand('› ')+palette.text(safe(message)),1,0);
+    const renderTitle=title.render.bind(title);
+    title.render=width=>[fitLine(' '+palette.border('─'.repeat(Math.max(1,width-2))),width),...renderTitle(width)];
+    if(message.startsWith('fst >'))title.render=()=>[];
+    this.prompt.clear();this.prompt.addChild(title);this.prompt.addChild(component);this.tui.setFocus(component);this.tui.requestRender();
+    try{return await new Promise((resolve,reject)=>{this.pending={resolve,reject};component.onSubmit=text=>{
+      if(this.homeInput&&text.trim()&&this.commandHistory.at(-1)!==text.trim()){
+        this.commandHistory.push(text.trim());if(this.commandHistory.length>100)this.commandHistory.shift();
+      }
+      resolve(text);
+    };component.onSelect=item=>resolve(item.value);component.onCancel=()=>reject(cancelled());});}
+    finally{if(this.homeInput)this.terminal.write(mouseOff);this.pending=null;this.editor=null;this.homeInput=false;this.prompt.clear();this.tui.requestRender();}
+  }
+  input(message,{value='',commands=[],files=true,workflows=[]}={}){
+    const editor=new Editor(this.tui,{borderColor:palette.border,selectList:theme},{paddingX:1});
+    const renderEditor=editor.render.bind(editor);
+    editor.render=width=>{
+      if(width<8)return renderEditor(width);
+      const inner=width-4,lines=renderEditor(inner);let closed=false;
+      return lines.map((line,i)=>{
+        if(i===0)return ' '+palette.border('╭'+'─'.repeat(inner)+'╮');
+        if(!closed&&/^─+$/.test(safe(line))){closed=true;return ' '+palette.border('╰'+'─'.repeat(inner)+'╯');}
+        if(closed)return '  '+line;
+        return ' '+palette.border('│')+line+' '.repeat(Math.max(0,inner-visibleWidth(line)))+palette.border('│');
+      });
+    };
+    this.homeInput=message.startsWith('fst >');
+    this.commandHistoryIndex=null;
+    if(this.homeInput)editor.onChange=text=>{
+      if(this.commandHistoryIndex!==null&&text!==this.commandHistory[this.commandHistoryIndex])this.commandHistoryIndex=null;
+    };
+    if(this.homeInput)this.terminal.write(mouseOn);
+    this.editor=editor;editor.setText(this.homeInput?(this.homeDraft??value):value);
+    if(this.homeInput)this.homeDraft=undefined;
+    if(files||commands.length)editor.setAutocompleteProvider(new FileAutocomplete(commands,this.baseDir,workflows));
+    return this.ask(message,editor);
+  }
+  async select(message,items){
+    if(!items.length)throw new Error('当前没有可选择的项目');
+    const list=new SelectList(items.map(i=>({...i,label:safe(i.label).replace(/\s+/g,' '),description:i.description?safe(i.description).replace(/\s+/g,' '):undefined})),8,theme);
+    list.render=width=>{
+      const reserved=this.headingLines(width).length+new Text(palette.text(safe(message)),1,0).render(width).length+this.hint.render(width).length+2;
+      list.maxVisible=Math.max(1,Math.min(8,this.terminal.rows-reserved));
+      const start=Math.max(0,Math.min(list.selectedIndex-Math.floor(list.maxVisible/2),list.filteredItems.length-list.maxVisible));
+      const end=Math.min(start+list.maxVisible,list.filteredItems.length),lines=[];
+      for(let i=start;i<end;i++){
+        const item=list.filteredItems[i],selected=i===list.selectedIndex,available=Math.max(1,width-4);
+        const labelWidth=item.description&&width>=56?Math.min(32,Math.floor(available*0.45)):available;
+        const label=fitLine(item.label||item.value,labelWidth),prefix=selected?'› ':'  ';
+        let line=' '+(selected?palette.brand(prefix+label):palette.text(prefix+label));
+        if(item.description&&width>=56)line+=' '.repeat(Math.max(2,labelWidth-visibleWidth(label)+2))+palette.muted(fitLine(item.description,Math.max(1,available-labelWidth-2)));
+        lines.push(fitLine(line,width));
+      }
+      if(start>0||end<list.filteredItems.length)lines.push(palette.muted(`   ${list.selectedIndex+1} / ${list.filteredItems.length}`));
+      return lines.length?lines:[palette.muted('  没有匹配项')];
+    };
+    const value=await this.ask(message,list);
+    if(this.commandLocation){
+      const item=items.find(item=>item.value===value);
+      if(item&&value!=='back'&&value!=='cancel')this.feed.message(`· ${safe(item.label??item.value)}`);
+    }
+    return value;
+  }
+  async confirm(message){return await this.select(message,[{value:'no',label:'否，返回'},{value:'yes',label:'是，继续'}])==='yes';}
+  busy(message,cancel){
+    this.cancelRun=cancel;this.prompt.clear();this.prompt.addChild(new Text(palette.text(safe(message)),1,0));this.tui.setFocus(this.prompt);this.tui.requestRender();
+    return ()=>{this.cancelRun=null;this.prompt.clear();this.tui.requestRender();};
+  }
+}

package/manual/packages/sdk/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/sdk/index.js

@@ -0,0 +1,14 @@
+export const SDK_VERSION = '0.1.0';
+
+export function definePlugin(plugin) {
+  return Object.freeze({ sdk: '^0.1.0', actions: {}, ...plugin });
+}
+
+export class FlowError extends Error {
+  constructor(message, { code = 'EXECUTION_FAILED', details, cause } = {}) {
+    super(message, { cause });
+    this.name = 'FlowError';
+    this.code = code;
+    this.details = details;
+  }
+}

package/manual/packages/sdk/package.json

@@ -0,0 +1 @@
+{"name":"@mytools/sdk","version":"0.1.0","type":"module","main":"index.js","exports":"./index.js","files":["index.js","README.md"],"license":"MIT"}

package/manual/plugins/environment/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/plugins/environment/index.js

@@ -0,0 +1,92 @@
+import os from 'node:os';
+import { readFile } from 'node:fs/promises';
+import semver from 'semver';
+import { definePlugin, FlowError } from '@mytools/sdk';
+
+const pythonProbe=String.raw`import sys,json,importlib.metadata,importlib.util
+names=json.loads(sys.argv[1])
+packages=[]
+for item in names:
+    name=item['name']
+    try:
+        version=importlib.metadata.version(name)
+        module=item.get('module')
+        if module: __import__(module)
+        packages.append({'name':name,'version':version,'ok':True})
+    except Exception as e:
+        packages.append({'name':name,'ok':False,'error':str(e)})
+print(json.dumps({'executable':sys.executable,'version':sys.version.split()[0],'prefix':sys.prefix,'packages':packages}))`;
+
+const plugin={
+  id:'@mytools/environment',version:'0.1.0',title:'环境检查',description:'检查目标机器的系统、Python/pip 与昇腾 NPU 环境，缺失必需条件时停止工作流。',
+  platforms:['win32','linux'],commands:{'env.check':{description:'检查系统、Python/pip 或 NPU',action:'check'}},
+  actions:{
+    check:{
+      title:'检查目标环境',description:'始终报告系统信息；按需检查指定 Python 及其软件包、pip 和 NPU。只检查，不安装或修改环境。',
+      input:{type:'object',properties:{
+        python:{type:'object',title:'Python 环境',required:['executable'],properties:{
+          executable:{type:'string',title:'解释器路径',description:'填写目标环境的 python/python.exe 绝对路径'},
+          version:{type:'string',title:'Python 版本要求',default:'>=3.9'},
+          pip:{type:'boolean',title:'要求 pip 可用',default:false},
+          packages:{type:'array',title:'要求的软件包',default:[],items:{type:'object',required:['name'],properties:{name:{type:'string',title:'包名'},version:{type:'string',title:'版本范围'},module:{type:'string',title:'需要尝试导入的模块（可选）'}}}},
+        }},
+        npu:{type:'boolean',title:'检查昇腾 NPU',default:false},
+        npuCommand:{type:'string',title:'npu-smi 路径',default:'npu-smi'},
+      },additionalProperties:false},
+      output:{type:'object',properties:{ok:{type:'boolean',title:'检查通过'},system:{type:'object',title:'系统信息'},python:{type:'object',title:'Python 环境',properties:{executable:{type:'string',title:'已检查的解释器'},version:{type:'string',title:'Python 版本'}}},checks:{type:'array',title:'检查明细',items:{type:'object'}}},required:['ok','system','checks']},
+      async run(input,{runProcess,signal}) {
+        const report={ok:true,system:{platform:os.platform(),architecture:os.arch(),kernel:os.release()},checks:[]};
+        if(process.platform==='linux'){
+          try{report.system.distribution=await readFile('/etc/os-release','utf8');}catch{}
+        }
+        const add=(name,ok,actual,status='error',expected)=>{report.checks.push({name,status:ok?'available':status,actual,expected});if(!ok)report.ok=false;};
+        const probe=async(file,args)=>runProcess(file,args,{signal,timeout:15000});
+        if(input.python){
+          const requested=input.python;
+          try {
+            const result=await probe(requested.executable,['-c',pythonProbe,JSON.stringify(requested.packages??[])]);
+            if(result.exitCode!==0)throw new Error(result.stderr||'Python 查询失败');
+            report.python=JSON.parse(result.stdout);
+            const parsed=semver.coerce(report.python.version);
+            const compatible=!!parsed && semver.satisfies(parsed,requested.version??'>=3.9');
+            add('python',compatible,report.python.version,'incompatible',requested.version??'>=3.9');
+            for(const pkg of report.python.packages){
+              const range=requested.packages.find(p=>p.name===pkg.name)?.version;
+              const version=semver.coerce(pkg.version??'');
+              add(`python.package:${pkg.name}`,pkg.ok&&(!range||(version&&semver.satisfies(version,range))),pkg.version??pkg.error,pkg.ok?'incompatible':'not_found',range);
+            }
+            if(requested.pip){
+              const pip=await probe(report.python.executable,['-m','pip','--version']);
+              add('pip',pip.exitCode===0,pip.stdout||pip.stderr,'not_found');
+            }
+          } catch(error){
+            if(signal?.aborted)throw error;
+            add('python',false,error.message,error.code==='ENOENT'?'not_found':'error','目标机可用解释器');
+          }
+        }
+        if(input.npu){
+          if(process.platform!=='linux')add('npu',false,'当前 NPU 适配仅支持 Linux','unsupported');
+          else try{
+            const r=await probe(input.npuCommand??'npu-smi',['info','-l']);
+            const count=r.stdout.match(/Total\s+NPU\s+count\s*:\s*(\d+)/i);
+            add('npu',r.exitCode===0&&Number(count?.[1])>0,r.stdout||r.stderr,r.exitCode===0?'not_found':'error','当前进程可见的昇腾 NPU');
+          }catch(error){if(signal?.aborted)throw error;add('npu',false,error.message,error.code==='ENOENT'?'not_found':'error');}
+        }
+        if(!report.ok)throw new FlowError('目标环境检查未通过，请根据检查明细处理后重试',{code:'ENVIRONMENT_FAILED',details:report});
+        return report;
+      },
+    },
+  },
+};
+// 报告模式将“检测完成”与“检测通过”分开；旧 check 保持失败即终止的兼容语义。
+plugin.actions.report={
+  ...plugin.actions.check,
+  title:'生成环境报告',description:'返回结构化检测结果；未通过时返回 ok:false，由工作流条件决定是否继续。',
+  conditions:{passed:{title:'环境检查通过',path:'ok',op:'eq',value:true}},
+  async run(input,context){
+    try{return await plugin.actions.check.run(input,context);}
+    catch(error){if(error.code==='ENVIRONMENT_FAILED')return error.details;throw error;}
+  },
+};
+plugin.commands['env.report']={description:'检测环境并返回报告（不因检查未通过抛错）',action:'report'};
+export default definePlugin(plugin);

package/manual/plugins/environment/package.json

@@ -0,0 +1 @@
+{"name":"@mytools/environment","version":"0.1.0","type":"module","main":"index.js","files":["index.js"],"license":"MIT","dependencies":{"@mytools/sdk":"0.1.0","semver":"7.7.4"}}

package/manual/plugins/examples/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/plugins/examples/index.js

@@ -0,0 +1,23 @@
+import { definePlugin, FlowError } from '@mytools/sdk';
+import { writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+const text={type:'string',title:'文本'};
+const textInput={type:'object',required:['text'],properties:{text},additionalProperties:false};
+export default definePlugin({
+  id:'@mytools/examples',version:'0.1.0',title:'基础示例',description:'文本处理、文件输出和目标 Python 调用示例，用于组合第一个工作流。',
+  platforms:['win32','linux'],architectures:['x64','arm64'],
+  commands:{
+    'text.upper':{description:'将文本转为大写',action:'uppercase'},
+    'text.ask':{description:'交互输入文本并转大写',async run(_input,{ui,signal}){const text=await ui.input('输入文本');signal.throwIfAborted();return {text:text.toUpperCase()};}},
+  },
+  actions:{
+    uppercase:{title:'文本转大写',description:'将输入文本中的英文字母转成大写，输出可以继续传给其他步骤。',input:textInput,output:textInput,async run({text}){return {text:text.toUpperCase()};}},
+    append:{title:'追加文本',description:'在一段文本末尾追加内容。',input:{type:'object',required:['text','suffix'],properties:{text,suffix:{type:'string',title:'追加内容',default:' ✓'}},additionalProperties:false},output:textInput,async run({text,suffix}){return {text:text+suffix};}},
+    save:{title:'保存文本文件',description:'把文本保存到本次运行的结果目录，输出文件路径。',input:textInput,output:{type:'object',properties:{path:{type:'string',title:'结果文件路径'}},required:['path']},async run({text},{outputDir}){const file=path.join(outputDir,'result.txt');await writeFile(file,text,'utf8');return {path:file};}},
+    pythonEcho:{title:'调用 Python 脚本',description:'使用目标环境解释器执行随插件分发的 Python 脚本，返回解释器和处理结果。',input:{type:'object',required:['executable','text'],properties:{executable:{type:'string',title:'Python 解释器',description:'建议选择环境检查步骤输出的 python.executable'},text},additionalProperties:false},output:{type:'object',properties:{text,executable:{type:'string',title:'实际解释器'},version:{type:'string',title:'Python 版本'}},required:['text','executable','version']},async run({executable,text},{runProcess,signal,resourceDir}){
+      const r=await runProcess(executable,[path.join(resourceDir,'scripts','echo.py'),text],{signal});
+      if(r.exitCode!==0)throw new FlowError(`Python 脚本失败：${r.stderr}`);return JSON.parse(r.stdout);
+    }},
+  },
+});

package/manual/plugins/examples/package.json

@@ -0,0 +1 @@
+{"name":"@mytools/examples","version":"0.1.0","type":"module","main":"index.js","files":["index.js","scripts"],"license":"MIT","dependencies":{"@mytools/sdk":"0.1.0"}}

package/manual/plugins/examples/scripts/echo.py

@@ -0,0 +1,5 @@
+import json
+import sys
+
+# 由插件显式指定目标环境解释器；脚本只使用 Python 标准库。
+print(json.dumps({"text": sys.argv[1].upper(), "executable": sys.executable, "version": sys.version.split()[0]}))

package/manual/tests/application.test.js

@@ -0,0 +1,75 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdir, writeFile, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createApplication } from '../packages/core/src/application.js';
+import { temporary, testPlugin, object } from './helpers.js';
+import {validate} from '../packages/core/src/validation.js';
+
+test('同 ID schema 隔离编译，保留内嵌引用且不串用旧约束',()=>{
+  const schema=type=>({$id:'https://fishtools.test/review/config',type:'object',definitions:{value:{type}},properties:{value:{$ref:'#/definitions/value'}},required:['value']});
+  assert.deepEqual(validate(schema('string'),{value:'old'},'旧配置'),{value:'old'});
+  assert.deepEqual(validate(schema('integer'),{value:2},'新配置'),{value:2});
+  assert.throws(()=>validate(schema('integer'),{value:'old'},'新配置'),/integer/);
+});
+
+test('外部带 $id 配置插件可升级，后续安装与卸载不被旧 schema 阻塞',async t=>{
+  const root=await temporary(t),projectDir=path.join(root,'project');
+  const fixture=async(version)=>{
+    const directory=path.join(root,'plugin-'+version);await mkdir(directory);
+    await writeFile(path.join(directory,'package.json'),JSON.stringify({name:'review-schema-plugin',version,type:'module',main:'index.js'}));
+    const config={$id:'https://fishtools.test/external/config',type:'object',properties:{version:{type:'string',const:version,default:version}}};
+    await writeFile(path.join(directory,'index.js'),`export default {id:'review-schema-plugin',version:${JSON.stringify(version)},config:${JSON.stringify(config)},commands:{'review.version':{action:'version'}},actions:{version:{input:{type:'object'},output:{type:'object'},async run(_, {config}){return config;}}}};`);
+    return directory;
+  };
+  const first=await fixture('1.0.0'),second=await fixture('1.0.1'),extra=path.join(root,'unrelated');await mkdir(extra);
+  await writeFile(path.join(extra,'package.json'),JSON.stringify({name:'review-unrelated',version:'1.0.0',type:'module',main:'index.js'}));
+  await writeFile(path.join(extra,'index.js'),"export default {id:'review-unrelated',version:'1.0.0'};");
+  const app=await createApplication({projectDir,plugins:[]});t.after(()=>app.close());
+  await app.installPlugin(first);await app.installPlugin(extra);await app.removePlugin('review-unrelated');await app.installPlugin(second);
+  assert.equal((await (await app.startCommand('review.version')).done).output.version,'1.0.1');
+  await assert.rejects(app.configurePlugin('review-schema-plugin',{version:'1.0.0'}),/配置/);
+  await app.close();
+  const restarted=await createApplication({projectDir});t.after(()=>restarted.close());
+  assert.equal((await (await restarted.startCommand('review.version')).done).output.version,'1.0.1');
+  await restarted.removePlugin('review-schema-plugin');assert.equal(restarted.listPlugins().length,0);
+});
+
+test('运行快照独立于之后保存，状态与日志持久化',async t=>{
+  const projectDir=await temporary(t);
+  const app=await createApplication({projectDir,plugins:[testPlugin()]}); t.after(()=>app.close());
+  const w={id:'hello',schemaVersion:1,title:'示例',inputs:object(),steps:[{id:'convert',action:'@test/text:upper',with:{text:'hello'}}],outputs:{text:{$ref:'steps.convert.output.text'}}};
+  await app.saveWorkflow(w);
+  const run=await app.startRun('hello',{});
+  await app.saveWorkflow({...w,steps:[{...w.steps[0],with:{text:'changed'}}]});
+  await run.done;
+  assert.equal(app.getRun(run.id).status,'succeeded');
+  assert.deepEqual(app.getRun(run.id).output,{text:'HELLO'});
+  const events=(await readFile(path.join(app.outputDir,run.id,'events.jsonl'),'utf8')).trim().split('\n').map(JSON.parse);
+  assert.ok(events.some(e=>e.type==='run.succeeded'));
+  assert.ok(!events.some(e=>Object.hasOwn(e,'output')));
+});
+
+test('仓库外本地插件可以安装、加载并执行，移除后目录同步',async t=>{
+  const root=await temporary(t), pluginDir=path.join(root,'外部插件'),projectDir=path.join(root,'project');
+  await mkdir(pluginDir,{recursive:true});
+  await writeFile(path.join(pluginDir,'package.json'),JSON.stringify({name:'external-flow-test',version:'1.0.0',type:'module',main:'index.js'}));
+  await writeFile(path.join(pluginDir,'index.js'),`export default {id:'external-flow-test',version:'1.0.0',sdk:'^0.1.0',actions:{hello:{title:'外部动作',input:{type:'object'},output:{type:'object'},run:async()=>({value:42})}}};`);
+  const app=await createApplication({projectDir,plugins:[]});t.after(()=>app.close());
+  await app.installPlugin(pluginDir);
+  assert.ok(app.catalog().some(a=>a.id==='external-flow-test:hello'));
+  await app.saveWorkflow({id:'external',schemaVersion:1,inputs:object(),steps:[{id:'hello',action:'external-flow-test:hello',with:{}}],outputs:{answer:{$ref:'steps.hello.output.value'}}});
+  const run=await app.startRun('external',{});await run.done;
+  assert.deepEqual(app.getRun(run.id).output,{answer:42});
+  await app.removePlugin('external-flow-test');
+  assert.ok(!app.catalog().some(a=>a.id==='external-flow-test:hello'));
+});
+
+test('外部配置覆盖项目值并在调用前验证',async t=>{
+  const projectDir=await temporary(t);
+  await writeFile(path.join(projectDir,'flow.project.json'),JSON.stringify({config:{configured:{prefix:'项目'}}}));
+  const plugin={id:'configured',version:'1.0.0',config:{type:'object',properties:{prefix:{type:'string'}},required:['prefix'],additionalProperties:false},actions:{show:{input:object(),output:object({prefix:{type:'string'}},['prefix']),run:async(_input,{config})=>config}}};
+  const app=await createApplication({projectDir,plugins:[plugin],config:{configured:{prefix:'目标'}}});t.after(()=>app.close());
+  assert.deepEqual(await app.host.invoke('configured:show',{}),{prefix:'目标'});
+  await assert.rejects(createApplication({projectDir,plugins:[plugin],config:{configured:{prefix:42}}}),/配置/);
+});

package/node_modules/@mytools/core/bin/fst.js

@@ -5,8 +5,9 @@ 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 {waitForCliRun} from '../src/cli-run.js';
+import {waitForCliRun,cliRunResult} from '../src/cli-run.js';
 import {VERSION} from '../src/version.js';
+import {listDocumentation,readDocumentation,findDocumentationRoot,exportDocumentation} from '../src/documentation.js';
 
 const program=new Command().name('fst').description('Fishtools · 插件式工作流工作台').version(VERSION);
 program.option('--maintenance','维护模式：不启动有状态服务插件');
@@ -14,13 +15,20 @@ program.option('--project <directory>','项目目录（默认当前项目或用
 async function app(){const o=program.opts();return createApplication({projectDir:await resolveProject(o.project,o.workspace),outputDir:o.output,maintenance:!!o.maintenance,config:o.config?JSON.parse(await readFile(o.config,'utf8')):{}});}
 async function use(fn){const a=await app();try{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)=>{
+  if(options.export){if(topic||options.path)throw new Error('--export 不可与文档主题或 --path 同用');console.log(await exportDocumentation(options.export));return;}
+  if(topic){const document=await readDocumentation(topic);console.log(options.path?document.path:document.text);return;}
+  if(options.path){console.log(await findDocumentationRoot());return;}
+  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('查看和检查工作流');
 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')):{});
-  const r=await waitForCliRun(a,run);console.log(JSON.stringify(r.status==='succeeded'?r.output:r.error,null,2));
-  process.exitCode=r.status==='succeeded'?0:r.status==='cancelled'?130:1;
+  const result=cliRunResult(await waitForCliRun(a,run));console.log(JSON.stringify(result.value,null,2));
+  process.exitCode=result.exitCode;
 }));
 const plugin=program.command('plugin').description('管理插件');
 plugin.command('list').action(()=>use(a=>console.log(JSON.stringify(a.listPlugins(),null,2))));
@@ -36,7 +44,7 @@ packOptions(program.command('portable').description('导出完整便携工具、
 program.command('command [name]').description('列出插件命令或执行动作命令').option('--input <file>','JSON 输入').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 result=await waitForCliRun(a,run);console.log(JSON.stringify(result.error??result.output,null,2));process.exitCode=result.status==='succeeded'?0:result.status==='cancelled'?130:1;
+  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('插件配置已保存');}));
 async function web(o){