toolflow 3.1.4

package/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [20.x, 22.x]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+
+      - name: Install dependencies
+        run: npm ci || npm install
+
+      - name: Run TypeScript type check
+        run: npx tsc --noEmit
+
+      - name: Run test suite
+        run: npm test

package/README.md

@@ -0,0 +1,106 @@
+# ToolFlow ⌬
+
+> Organize your installed tools into focused pipelines to hit complex goals.  
+> Dynamic capability orchestration, log dehydration to disk, and built-in prompt workbench.
+
+[English](README.md) | [简体中文](README_zh.md)
+
+---
+
+### Office Chats: Sam and Alex at the Coffee Bar
+
+> **Scene**: 3:30 PM Friday. Break room. Sam is staring at their laptop, looking exhausted with an oversized coffee. Alex walks over after wrapping up a PR.
+
+**Sam** 😫: "Alex, I'm losing my mind. To build this new feature, I loaded up every MCP I could find—browser automation, DB query tools, docs search, code reviewers. But now the model acts like a drunk intern: I ask for a pure function and it tries to spin up Chromium; I ask for an error trace and it queries the production database. Run one test suite, and 2,000 lines of console output flood the context. On top of that, I'm constantly hunting through notes to find my favorite prompt templates..."
+
+**Alex** ☕: "Haha, you strapped an entire hardware store to your back and wondered why you can't run. Having tools installed is useless if they aren't **organized to achieve your goal**. Aren't you using ToolFlow?"
+
+**Sam** 😯: "Wait, how does it organize them?"
+
+**Alex** 🛠️: "Think of it as a pragmatic, lazy architect on your team:
+1. **Orchestrates Tools by Stage**: It breaks your task into phases. During exploration, it gives the model search tools and locks write permissions. During implementation, it hides unrelated heavy MCPs so the model stays razor-sharp and never misfires. During review, it physically strips edit privileges so the model can't secretly mutate code.
+2. **Dehydrates Verbose Logs in Milliseconds**: Test threw 500 lines of stack trace? ToolFlow archives the full dump to disk, leaving only the return code, key failure summary, and file path in context. That saves tens of thousands of tokens.
+3. **Built-in Prompt Workbench**: Hit `[p]` on startup to pick your battle-tested prompts right away, or press `[+]` to draft one on the fly. You can even press `Ctrl+L` and let the LLM auto-tag and summarize it. No more copy-pasting from scratch."
+
+**Sam** 🤩: "What happens when the mission is done? Does it mess up my environment?"
+
+**Alex** 🚀: "Not a chance. Everything resets back to your original native toolset cleanly. Just run `/toolflow build a user auth system` and watch it deploy the right tools at each step."
+
+---
+
+> **Scope**: Designed for multi-tool, multi-MCP orchestration on complex tasks. For trivial single-file edits, stock Pi is sufficient. For multi-phase workflows, ToolFlow takes command.
+
+---
+
+## Installation
+
+Install directly via git:
+
+```bash
+pi install git:github.com/3ZEROS12/toolflow
+```
+
+---
+
+## Core Capabilities
+
+### 1. Dynamic Ecosystem Mounting (Persistent Core, Stage-Gated Advanced Tools)
+Instead of exposing your entire heavyweight tool catalog at all times, ToolFlow keeps the developer workflow smooth and focused:
+- **Persistent Core Tools**: Standard development tools (`read`, `edit`, `write`, `bash`, `grep`, `find`, `ls`) remain accessible at all times to prevent workflow lockups.
+- **Stage-Gated Advanced Capabilities**: Heavy external MCPs, browser controllers, dynamic workflows, and subagents are dynamically mounted only in relevant phases, keeping prompts focused and eliminating token bloat.
+
+### 2. 4-Tier Token Governance (-95% Context Overhead)
+ToolFlow enforces four runtime barriers against context bloating:
+- **Real-Time Tool Result Dehydration**: Whenever terminal outputs (`bash`/`powershell`) or fetch tools emit verbose logs (>40 lines or deep stacks), ToolFlow intercepts and archives them to disk in real-time (`.pi/toolflow/runs/...`). The context only retains concise physical head/tail summaries and the local file path.
+- **Heavy Tool JIT Allocation**: Powered by deep LLM intent reasoning, heavy MCP tools are loaded just-in-time for stages that strictly require them, completely masking their hefty JSON schemas during unrelated phases.
+- **Stage Boundary Compaction Contract**: Hooks into `session_before_compact` at stage transitions, stripping exploratory trials and reasoning chaff while handing off only verified on-disk artifact paths to downstream stages.
+- **Transparent Feedback**: Listens for `session_compact` events to surface minimal, reassuring token reduction notices in your status line—eliminating monotonically growing context anxiety.
+
+### 3. Strict Tool Lifecycle Snapshot & Restoration
+ToolFlow snapshots active tools at startup. Upon stage completion, abrupt error, or manual `/toolflow reset`, the environment is 100% restored to its original catalog, preventing orphaned states.
+
+### 4. Physical Blast Radius Guard
+A runtime safety interceptor monitoring both native write tools and terminal commands (`bash`, `powershell`). Destructive overwrites, file removals, or shell redirections targeting sensitive assets (`.env*`, `.git*`, core locks) are physically blocked at the engine level.
+
+### 5. Production Craftsmanship & Aesthetics Guard
+Prevents the LLM from outputting "toy-grade, functionally running but visually hideous" deliverables:
+- **Hard Guardrails on UI & Visuals**: Explicitly bans bare unstyled elements, crude monochrome placeholder rectangles, and naive sketch lines. Mandates professional color palettes (primary, secondary, accent, layered dark/light backgrounds), 8px grid spacing, and typographic hierarchy.
+- **Polished Vector Assets**: Requires clean vector SVG artwork or standard icon systems (e.g. Lucide/Tailwind-style icons) instead of simplistic squares or primitives acting as mock UI assets.
+- **Smooth Micro-Interactions**: Enforces transition states, hover/focus elevation, subtle shadows, and interactive feedback across all interactive components.
+- **Decoupled Architecture & Real Unit Tests**: Pure business/game logic remains strictly decoupled from rendering, backed by executable unit tests for reliable, production-ready deliverables.
+
+### 6. Lightweight Companion: Instant Prompt Teleprompter (Zero-Planning Required)
+Don't need a heavy multi-stage workflow for a small task? ToolFlow doubles as your everyday **instant prompt teleprompter and template workbench**:
+- **Zero-Friction Teleprompter Mode**: Simply hit `/toolflow` without arguments to summon the teleprompter overlay. Browse your collection with arrow keys and hit `[p]` to immediately insert the highlighted prompt directly into your terminal input. **Instant pick-and-go—no complex planning phase triggered**.
+- **Global & Local Auto-Discovery**: Automatically indexes all local and global `prompts/*.md` templates, sorted by recent activity, freeing you from digging through notes or clipboard history.
+- **On-the-Fly Template Capture**: Hit `[c]` to author new markdown templates right inside the terminal, complete with optional LLM-assisted command tags and summaries.
+
+---
+
+## Commands
+
+| Command | Description |
+| :--- | :--- |
+| `/toolflow` | Open the prompt workbench & task initialization cockpit |
+| `/toolflow <task>` | Launch a sandboxed task with phase-gated toolchains |
+| `/toolflow status` | Display active stage pipeline & mounted tool state (alias: `/sop`) |
+| `/toolflow rollback` | Revert changes to the snapshot captured at the start of current stage |
+| `/toolflow-rollback` | Direct shortcut for `/toolflow rollback` |
+| `/toolflow reset` | Clear active execution state and flush dehydrated temp caches |
+| `/toolflow export` | Export phase breakdown and architecture decisions to `BLUEPRINT.md` |
+
+---
+
+## Keybindings
+
+- `[Enter]`: Input task and generate phase-governed plan
+- `[p]`: Prefill highlighted prompt template into editor
+- `[c]`: Create new prompt template inline
+- `[1-4]` / `[←/→]`: Toggle architecture and toolchain options
+- `[Esc]`: Exit / Close overlay
+
+---
+
+## License
+
+MIT © [Jason](https://github.com/3ZEROS12)

package/README_zh.md

@@ -0,0 +1,109 @@
+# ToolFlow ⌬
+
+> 组织工具达成目标，按阶段精准编排生态能力。  
+> 动态工具装配，长日志落盘脱水，提示词模板工作台。
+
+[English](README.md) | [简体中文](README_zh.md)
+
+---
+
+### 工位日常：小周和小陈的下午茶聊聊
+
+> **场景**：周五下午三点半，茶水间。小周端着咖啡，一脸生无可恋地盯着电脑屏幕。小陈刚写完一段测试走过来。
+
+**小周** 😫：“哥，我快被搞崩溃了。为了做这个复杂业务，我把能装的 MCP 全拉满了——文档库、数据库客户端、浏览器控制、各种走查工具全在环境里。结果呢？给模型提个需求，它像个喝醉的学徒，写个简单函数它非要启动浏览器，查个报错又去连数据库；终端跑个测试刷出几千行日志，直接把上下文撑爆；更绝的是，平时顺手的几条长提示词我还得翻聊天记录复制粘贴……”
+
+**小陈** ☕：“噗，你这是把一卡车的精密仪器全绑在自己身上跳街舞呢。工具装再多，各玩各的有什么用？重点在于**把工具组织起来为你干活**啊，你没用 ToolFlow 吗？”
+
+**小周** 😯：“哈？它能怎么组织？”
+
+**小陈** 🛠️：“它就是个懂偷懒的现场架构师。三个绝招：
+1. **按阶段组装高阶工具，有条不紊**：基础开发工具（读写、搜索、终端）全程随时可用，保障编码丝滑；高阶能力（浏览器、外部 MCP、工作流）则按阶段精准装配，模型注意力高度集中，绝不选错工具。
+2. **长日志秒级脱水，守住上下文**：跑测试或构建炸出五百行日志？它毫秒级自动给你落盘封存，塞给模型的只有核心退出码、错误摘要和文件路径。你那几万 Token 就是这么保住的。
+3. **自带开箱即用的提示词工作台**：按 `[p]` 就能从历史常用模板里挑一个直接填入，按 `[c]` 还能当场写一段，模型还能帮你自动提炼标签。再也不用到处翻剪贴板了。”
+
+**小周** 🤩：“靠，完工之后呢？我装的那些 MCP 会被搞乱吗？”
+
+**小陈** 🚀：“做完任务或者一键 `/toolflow reset`，所有工具原样奉还，一点痕迹都不留。你敲个 `/toolflow 来做个用户系统` 试试，直接看它怎么帮你排兵布阵。”
+
+---
+
+> **定位**：把已安装的各种插件、MCP 和提示词编排成流水线，专为多工具协同的中大型任务设计。普通单文件修补用原生即可；长流程任务，用 ToolFlow 调度全局。
+
+---
+
+## 安装方式
+
+通过 git 直接安装：
+
+```bash
+pi install git:github.com/3ZEROS12/toolflow
+```
+
+---
+
+## 核心价值
+
+### 1. 动态生态装配（基础工具常驻，高阶工具按阶段挂载）
+ToolFlow 绝不把繁杂的高阶工具一股脑塞给大模型，而是根据执行阶段按需装配：
+- **基础编码工具常驻**：原生读写、搜索与终端（`read`, `edit`, `write`, `bash`, `grep` 等）全程保持可用，杜绝中途因权限丢失造成卡壳。
+- **高阶生态按需外挂**：外部 MCP、浏览器控制、子代理与工作流编排等高成本工具，只在对应阶段（如调研、走查）精准露头，未激活阶段彻底屏蔽，保持极度专注与低 Token 开销。
+- **验收走查阶段**：通过 `ReviewIsolationGuard` 从运行时**物理剥离**代码修改权限，确保审核员处于纯粹客观的“只读/只验证”状态。
+
+### 2. 四重 Token 治理闭环（削减 95% 冗余开销）
+ToolFlow 在运行时构筑了四道物理级 Token 节流防线：
+- **实时长日志拦截与脱水**：当终端（`bash`/`powershell`）或外部工具产生冗长日志（>40 行或异常堆栈）时，中间件毫秒级将其全量落盘归档（`.pi/toolflow/runs/...`），上下文内仅保留核心头尾指纹与磁盘归档路径，即刻阻断上下文污染。
+- **重型工具 JIT 阶段挂载**：借助 LLM 深度推理，重型 MCP 或高成本工具只在真正需要的阶段露头，未激活阶段彻底屏蔽其庞大的 JSON Schema。
+- **阶段流转物理脱水契约**：阶段交接时监听 `session_before_compact`，自动剔除历史探索痕迹、试错代码与琐碎心路历程，向后仅传递已落盘的物理产物路径。
+- **无感正向回落反馈**：配合 `session_compact`，每次精简压缩均会在状态栏给出轻量级释放提示，让用户实时感知 Token 水位下降，告别爆仓焦虑。
+
+### 3. 工具生命周期严格还原（借还闭环）
+首秒自动捕获会话初始工具快照。无论是正常竣工、意外崩溃，还是执行 `/toolflow reset`，都会 100% 将环境恢复到原生完整面貌，保证主会话无任何幽灵残留。
+
+### 4. 物理级安全护栏（Blast Radius Guard）
+在引擎底层同时监控原生写工具与终端执行指令（`bash`, `powershell`）：
+- **核心敏感硬防线坚守**：对于核心敏感与系统级文件（`.env*`, `.git*`, 包管理器锁文件等），系统从底层直接物理阻断篡改与删除；
+- **业务编码自由探索**：普通项目代码与测试文件写操作自由流畅，杜绝死板拦截导致的死锁。
+
+### 5. 交付品质与工匠标准门禁 (Anti-Crude Guard & Production Aesthetics)
+拒绝让大模型产出“能跑但极度丑陋粗糙”的玩具级代码：
+- **设计与视觉重灾区硬防线**：在 Web/UI/应用场景下，严厉拦截纯单调色块、粗制滥造的简笔线、粗陋的原生丑样式。强推经过推敲的现代调色盘（主色、衬色、强调色）、8px 间距网格与清晰字体排版。
+- **高质感矢量资产**：强制要求使用精细矢量 SVG 图案或专业矢量图标（如 Lucide/Tailwind 风格），杜绝拿小黑方块敷衍成游戏或应用界面。
+- **平滑微动效与交互反馈**：所有交互元素必须具备平滑的 Transition 动效、Hover 态、焦点反馈与微阴影质感。
+- **解耦逻辑与真实测试**：业务逻辑与视图渲染严格解耦，并配套真实的自动化单元测试断言，确保交付产物既有“高保真工业级颜值”，又有“严密可靠的底层逻辑”。
+
+### 6. 轻量伴侣：秒级 Prompt 提词器（无需完整规划，开箱即用）
+不需要走复杂的全流程蓝图规划？ToolFlow 也是你日常极简高效的**随身提词器与提示词工作台**：
+- **0 成本提词器模式**：日常遇到小任务，敲一下 `/toolflow` 即可唤起沉浸式提示词看板。直接通过上下方向键浏览你收藏的精选 Prompt，按 `[p]` 键瞬间将选中的高质量提示词一键预填进终端输入框，**即用即走，无需触发复杂规划流程**。
+- **全域自动感应**：自动扫描并聚合本地与全局 `prompts/*.md` 模板，按最近使用频率智能排序，彻底告别在剪贴板和笔记软件之间反复翻找。
+- **就地灵感沉淀**：按 `[c]` 键当场在终端创建新模板，更有 AI 自动辅助提炼命令标签与摘要，让日常经验无痛沉淀为生产力资产。
+
+---
+
+## 常用命令
+
+| 命令 | 说明 |
+| :--- | :--- |
+| `/toolflow` | 打开 Prompt 模板工作台与任务初始化面板 |
+| `/toolflow <任务内容>` | 启动带工具沙箱与阶段治理的受控任务 |
+| `/toolflow status` | 查看当前阶段流水线与挂载工具状态 (别名: `/sop`) |
+| `/toolflow rollback` | 撤销当前阶段的修改，回退到阶段开始前的快照 |
+| `/toolflow-rollback` | `/toolflow rollback` 的独立快捷指令 |
+| `/toolflow reset` | 清除当前任务状态并清理脱水临时缓存 |
+| `/toolflow export` | 将阶段规划与架构决策导出为 `BLUEPRINT.md` |
+
+---
+
+## 快捷键指南
+
+- `[Enter]`：输入任务并开始受控执行
+- `[p]`：将选中的 Prompt 模板填入输入框
+- `[c]`：在终端就地新建 Prompt 模板
+- `[1-4]` / `[←/→]`：在方案决策面板中切换选项
+- `[Esc]`：退出当前浮层
+
+---
+
+## 开源协议
+
+MIT © [Jason](https://github.com/3ZEROS12)

package/docs/reports/ADVANCED_EVOLUTION_REPORT.md

@@ -0,0 +1,44 @@
+# ToolFlow (Workflow Architect) 高阶能力演进落地报告 (P0-P3)
+
+**编制人**：Jason (ToolFlow 专项攻坚组)  
+**版本**：ToolFlow v1.4.0 (高阶前沿闭环版)  
+**状态**：P0 ~ P3 四大前沿能力已全部落地并严格测试通过
+
+---
+
+## 一、 落地四大前沿优化项
+
+### 1. P0 [最立竿见影] 动态工具按需剪枝 (Dynamic Tool Pruning)
+- **落地模块**：`degradation_matrix.ts` (`pruneToolsForStage`)
+- **效果**：
+  - 设计阶段仅暴露读取/搜索工具，彻底禁用写操作；
+  - 核心制作阶段按需开放写与执行工具；
+  - 走查验证阶段定向挂载浏览器/批注工具。
+  - **Token 节省 30%~40%**，从根本上杜绝跨阶段乱调工具。
+
+### 2. P1 [体验跃迁] 权限提升审批与人在回路 (HITL Escalation)
+- **落地模块**：`blast_radius.ts` (`requestEscalation`, `grantTemporaryAccess`)
+- **效果**：
+  - 敏感配置文件（`.env`、`*lock*`、`.git/`）实施 **100% 绝对物理阻断**（不可提权）；
+  - 普通未声明源码文件触发 **人在回路提权审批**，支持动态扩增白名单并继续执行。
+
+### 3. P2 [长期智感] 跨会话架构知识库 (Codebase Memory)
+- **落地模块**：`memory.ts` (`CodebaseMemoryManager`)
+- **效果**：
+  - 在 `.pi/toolflow/memory/` 自动沉淀仓库架构记忆、技术栈约定与避坑经验；
+  - 跨会话自动注入 Stage 契约，越用越懂项目。
+
+### 4. P3 [效能极限] DAG 独立任务多 Agent 并发派发 (Multi-Agent Fan-Out)
+- **落地模块**：`worker_orchestrator.ts` (`MultiAgentWorkerOrchestrator`)
+- **效果**：
+  - 将无依赖同波次（Wave）任务并发调度给子 Agent 执行；
+  - 汇总产物与状态，执行时间大幅压缩。
+
+---
+
+## 二、 严格回归测试与沙盒渗透验证
+
+1. **测试套件运行**：`cd C:/Users/Jason/.pi/agent/extensions/toolflow && npx tsx test_suite.ts`
+   - **结果**：**13 大模块、90+ 项细粒度物理断言 100% 绿灯全数通过**。
+2. **沙盒渗透运行**：`cd C:/Users/Jason/.pi/agent/extensions/toolflow && npx tsx sandbox_e2e.ts`
+   - **结果**：全链路真实案例、敏感写锁阻断与 Ponytail 生态优先路由 **100% 绿灯全数通过**。