@roarpeng/graphflow 0.6.15 → 1.0.4

package/AGENTS.md

@@ -40,7 +40,7 @@ From this repository:
 
 - Use `graphflow_plan` before multi-step edits.
 - Use `graphflow_preview_context` before large refactors or codebase-wide questions.
-- Use `graphflow_run` when you want GraphFlow to execute its own orchestration loop.
+- Use `graphflow_run` when you want GraphFlow to plan and package a task with compressed context, returning a structured execution descriptor (executionDescriptor) for you to execute. GraphFlow delegates execution to external coding agents by default (bridge mode).
 - Use `graphflow_index` after workspace changes if graph freshness matters.
 - Use `graphflow_inspect_graph` and `graphflow_skill_insights` for observability.
 - Use `graphflow_diagnose` when model/provider routing looks wrong.

package/CHANGELOG.md

@@ -4,7 +4,60 @@ All notable changes to this project are documented in this file.
 
 ## [Unreleased]
 
-## [0.6.15] - 2026-06-16
+## [1.0.3] - 2026-06-24
+
+### Fixed
+
+- **CI**：`m17` 测试不再硬编码 `/usr/bin/node`，兼容 GitHub Actions hosted Node 路径。
+- **图谱存储**：`graphify-file-client` 原子写入（temp + rename）；损坏 JSON 时优雅降级为空 store 并提示 rebuild。
+- **上下文检索**：`rankNodesForContextQuery` 降低 `.cursor/mcp.json`、`docs/integrations` 等配置噪声，优先 `src/` 与 Symbol 节点。
+- **MCP metrics**：`graphflow_metrics` 支持 `rootDir` 并绑定工作区。
+
+## [1.0.2] - 2026-06-24
+
+### Fixed
+
+- **MCP ENOENT（fnm 临时路径）**：安装 MCP 时不再写入 fnm multishell 临时 `node` 绝对路径；优先使用 IDE 自带 Electron（`ELECTRON_RUN_AS_NODE`），否则回退稳定 `node`。
+- **Trae CN 支持**：安装器识别 `~/.trae-cn` 并写入 `~/.config/Trae CN/User/mcp.json`。
+
+## [1.0.1] - 2026-06-24
+
+### Fixed
+
+- **多项目工作区隔离**：MCP / 扩展 / npm 包不再把图谱绑定到 vendor 目录或全局配置里的陈旧 `workspaceRoot`。
+- **自动发现工作区**：新增 `discover-workspace`，从 cwd 向上查找项目根；仅在 runtime 目录（vendor、extensions）时回退到 IDE 环境变量。
+- **MCP launcher**：子进程 `cwd` 与 `GRAPHFLOW_WORKSPACE_ROOT` 指向用户打开的项目，不再固定在扩展 vendor。
+- **MCP 安装器**：默认写入 `GRAPHFLOW_WORKSPACE_ROOT: "${workspaceFolder}"`，merge 已有 env，扩展有工作区时同时写用户级与项目级配置。
+- **MCP 工具**：`preview_context`、`inspect_graph`、`skill_insights`、`stats` 支持可选 `rootDir` 覆盖。
+
+## [1.0.0] - 2026-06-19
+
+首个正式版本。在 0.6.x 基础上完成「诚实执行语义」收敛与「上下文压缩」体系，所有新增能力均端到端接线到 CLI / MCP / orchestrator。
+
+### Added
+
+- **混合压缩模型策略（compressor role）**：新增 `compressor` 角色，默认复用 economy tier（`backend: "inherit"`）——配置了外部 provider（OpenAI/Anthropic/百炼）就用其 economy 模型，纯离线则回退内嵌 minicpm。零额外配置。
+- **内嵌模型首次自动下载**：无外部 LLM 时，`resolveCompressionModel` 复用既有断点续传下载器，首次按需拉取 minicpm GGUF 到 `~/.graphflow/models/`（类似 Playwright 浏览器下载）。
+- **图结构压缩（零成本，默认开启）**：`graph-compression.ts` 提供边权重加权连通子图（`extractConnectedSubgraph`）、加权 PageRank 中心性（`computePageRank`）、检索序与中心性融合重排（`blendWithCentrality`）。preview / orchestrator 默认启用。
+- **语义压缩（opt-in）**：`semantic-compression.ts` 通过 minicpm/economy LLM 对相似节点聚类合并（`clusterSimilarNodes` + `summarizeCluster`）、长节点改写（`densifyNodeContent`），由 `graphPolicy.compression.enabled` 开启。
+- **RepoMap 概览模式（opt-in）**：`repo-map.ts` 在 token 预算紧张时返回模块级地图（每模块一行 exports 摘要），由 `compression.enableRepoMapFallback` 开启。
+- **自适应 Token 预算（opt-in）**：`adaptive-budget.ts` 的 `estimateContextBudget` 按任务复杂度（refactor/多文件/架构/局部修复/加测试）动态调整预算，由 `compression.enableAdaptiveBudget` 开启。
+- **HNSW 向量索引（可选依赖）**：`hnsw-index.ts` 在候选集 ≥200 节点时使用 hnswlib-node ANN 加速（10~100x），未安装时优雅降级线性扫描。`hnswlib-node` 列为 optionalDependency。
+- **`buildEnhancedContextPackage`**：统一六步压缩 pipeline（RepoMap fallback → 关键词+向量召回 → 图压缩 → 语义压缩 → 分层配额 → 边扩展），preview 与 orchestrator 共用。
+- **压缩诊断**：`route diagnose` 输出新增 `compression=<backend>:<provider>/<model>` 行，可查当前压缩模型来源。
+- 测试 m43（bridge 模式）、m44（增强压缩）、m45（真机 benchmark）。
+
+### Changed
+
+- **执行语义诚实化（bridge 模式）**：`graphflow_run` 默认进入 bridge 模式——规划 + 压缩上下文后输出 `executionDescriptor` 移交外部 coding agent 执行，状态为 `HUMAN_REVIEW_REQUIRED` 并标注 `[DELEGATED]`，不再伪造 `COMPLETED`。
+- **校验启发式标注**：规则校验结果统一标注 `[heuristic]` 与 `heuristic_validation` riskTag；检测并拒绝 provider 占位符回显（`[openai:model] ...`）。
+- `graphPolicy.compression` 配置项扩展：`enableGraphCompression` / `enableRepoMapFallback` / `enableAdaptiveBudget` / `enableHnsw`。
+
+### Fixed
+
+- worker 兜底分支不再返回 `"Simulated change..."` 伪造输出，无可用执行模式时抛出明确错误。
+- README 版本号、测试数与失效文档引用同步至 1.0。
+
 
 ### Added
 

package/README.md

@@ -4,54 +4,70 @@ A Context-Aware Multi-Agent Orchestration Engine.
 
 GraphFlow 是一个基于 TypeScript/Node.js 的多智能体编排引擎，将 **Graphify 式知识图谱** 与 **Superpowers 式任务编排** 整合为可本地运行的上下文层：自动建图、压缩检索、规划执行、经验沉淀，并通过 CLI、MCP 与 VS Code 扩展对外暴露。
 
-## 当前能力总览（v0.6.13）
+## 当前能力总览（v1.0.0+）
 
 | 能力域 | 说明 |
 | --- | --- |
-| **任务编排** | 按任务复杂度分流 simple / complex；DAG 并行执行、校验、重试、集成轮 |
+| **任务规划与移交** | 按任务复杂度分流 simple / complex；DAG 规划；`graphflow_plan_insight` 六顶思考帽 + 5-Why 深度分析；默认 **bridge 模式**输出结构化任务描述符交给外部 coding agent 执行 |
 | **模型路由** | Smart / Economy 双 tier；多 provider 健康探测与 fallback（OpenAI、Anthropic、百炼、豆包、OpenBMB） |
-| **知识图谱** | 工作区 AST 索引（TS/JS/Python/Rust/Go/C/C++）；File / Module / Symbol 节点 + 依赖/引用/定义边 |
-| **上下文压缩** | L1/L2/L3 分层锚点；近无损打包；可选向量召回 + RRF 融合；默认 `maxContextTokens: 1500` |
-| **持续建图** | 默认 `autoIndexOnSave`；preview / run 前按需增量索引（`hasPendingGraphIndexWork`） |
+| **知识图谱** | 工作区 AST 索引（TS/JS/Python/Rust/Go/C/C++/Java/Ruby）；File / Module / Symbol 节点 + 依赖/引用/定义边；图谱 artifact 导入/导出 |
+| **上下文压缩** | L1/L2/L3 分层锚点；近无损打包；图结构压缩（边权重+PageRank，零成本默认开启）；可选语义压缩（minicpm/economy LLM 聚类合并）；向量召回 + RRF + HNSW；RepoMap 概览；自适应预算 |
+| **持续建图** | 默认 `autoIndexOnSave`；preview / run 前按需增量索引（`hasPendingGraphIndexWork`）；MCP `graphflow_index_file` 单文件增量 |
 | **语义增强** | 可选 post-index LLM 语义 enrich；OpenBMB 本地 embedded 模式 |
 | **学习飞轮** | Episodic Memory、Reflection、Skill 节点、nightly 学习、技能提示注入规划 |
-| **Agent 接入** | CLI `--json`；MCP stdio（9 工具）；Cursor / Claude Code 规则与示例配置 |
-| **VS Code 扩展** | Settings、建图、路由测试、Context Preview、**知识图谱可视化**、Skill Insights、Chat Agent |
+| **可观测性** | `graphflow_stats` 累计 token 节省；`graphflow_metrics` Prometheus 指标；VS Code 知识图谱 Snapshot |
+| **Agent 接入** | CLI `--json`；MCP stdio（**16 工具**）；Cursor / Claude Code 规则与示例配置 |
+| **VS Code 扩展** | Settings、建图、路由测试、Context Preview、**知识图谱可视化**、Skill Insights、Chat Agent、一键安装 MCP |
 | **存储后端** | `file`（JSON）/ `memory` / `sqlite`（FTS5）/ `mcp-http`（Graphify） |
-| **工程质量** | TypeScript strict；**41 测试文件 / 177 tests**；`npm run ci` 含扩展 esbuild 打包与 bundled runtime smoke |
+| **多项目隔离** | 全局配置共享 LLM/路由；**图谱路径按当前工作区解析**，不再串读其它项目的 `graphflow-out` |
+| **工程质量** | TypeScript strict；**49 测试文件 / 200+ tests**；`npm run ci` 含扩展 esbuild 打包与 bundled runtime smoke |
 
 ### 一句话总结
 
-> 从 task 描述出发，自动规划 → 路由模型 → 压缩图谱上下文（含向量召回）→ 执行/校验/重试，并把经验沉淀回知识图谱；Coding Agent 通过 MCP/CLI 优先消费压缩上下文而非整库扫描。
+> 从 task 描述出发，自动规划 → 路由模型 → 压缩图谱上下文（含向量召回）→ **输出结构化执行描述符交给外部 coding agent**，并把经验沉淀回知识图谱；定位为 **上下文与规划服务（context service）**，而非独立执行器。
 
-### v0.6.7 – v0.6.13 近期演进
+### v1.0.0 核心（2026-06）
 
-1. **知识图谱可视化（v0.6.12–0.6.13）**
-   - 可读标签（文件名、符号名、目录组）、代码层 / 学习层 Tab
-   - 暗色面板、目录聚类着色、关系线型、缩放/平移
-   - 双击节点或「打开源文件」跳转源码行
-   - 布局归一化修复大图谱「只剩角落小点」问题
+- **诚实执行语义（bridge 模式）**：`graphflow_run` 规划 + 压缩上下文后输出 `executionDescriptor`，交给 Cursor / Claude Code 等外部 agent 执行，不再伪造 `COMPLETED`。
+- **三层渐进压缩**：图结构压缩（默认零成本）→ 向量召回 + HNSW → 可选语义压缩（economy / minicpm）。
+- **混合压缩模型**：`compressor` 角色默认继承 economy tier；纯离线时首次按需下载 minicpm GGUF。
 
-2. **持续静默建图（v0.6.11）**
-   - `autoIndexOnSave` 默认开启；保存文件后 debounce 增量索引
-   - 旧配置 `maxContextTokens: 400` 自动升级到 1500
+### 最新更新（v1.0.x / main）
 
-3. **Runtime 模块化与扩展打包（v0.6.10）**
-   - `runtime/` 子模块 + `GraphFlowRuntimeModule` 类型校验
-   - VS Code 扩展 esbuild 单文件 bundle
+1. **多项目图谱隔离**
+   - 全局配置（`~/.graphflow.config.json`）只保存 LLM、路由等**机器级**设置，**不再持久化 `workspaceRoot`**
+   - 运行时按 `process.cwd()` 或 `GRAPHFLOW_WORKSPACE_ROOT` 解析 `graphflow-out/graphflow-graph.json`
+   - 修复：切换项目后 Snapshot / MCP 仍显示旧项目图谱的问题
 
-4. **配置与健壮性（v0.6.7–0.6.9）**
-   - 全局配置优先（`~/.graphflow.config.json`）
-   - 损坏 JSON 容错；postinstall 需显式 `GRAPHFLOW_ENABLE_POSTINSTALL=1`
-   - 无工作区也可打开 Settings；CI 可复现 `npm ci`
+2. **索引与语言扩展**
+   - 新增 **Java**（`.java`）、**Ruby**（`.rb`）tree-sitter 索引器
+   - C/C++、Rust 索引器增强；WASM 语法包可随 npm 包离线分发（`npm run wasm:download`）
+   - MCP 新增 `graphflow_index_file` 单文件增量索引
 
-5. **无 LLM 也能建图（v0.6.6 起）**
+3. **MCP 工具扩展（9 → 16）**
+   - `graphflow_plan_insight`：六顶思考帽 + 5-Why 深度规划
+   - `graphflow_export_artifact` / `graphflow_import_artifact`：图谱压缩包导入导出
+   - `graphflow_stats`：累计 token 节省统计
+   - `graphflow_metrics`：Prometheus 格式可观测性指标
+
+4. **知识图谱可视化（延续 v0.6.12+）**
+   - 可读标签、代码层/学习层 Tab、目录聚类、缩放平移、跳转源码
+   - Snapshot 为**采样视图**（默认约 120 节点 / 200 边），顶栏显示全库真实规模
+
+5. **配置与工程**
+   - 全局配置优先；损坏 JSON 容错；CI 全链路 validate + VSIX 打包
    - Settings「建立图谱（无需 LLM）」或 `graph index` 即可生成结构图谱
-   - 可选「测试路由并建立图谱」在 LLM 连通后触发语义 enrich
+
+### 历史演进（v0.6.7 – v0.6.13 摘要）
+
+- v0.6.12–0.6.13：知识图谱面板、布局归一化、Snapshot 可读标签
+- v0.6.11：`autoIndexOnSave` 默认开启；`maxContextTokens` 400 → 1500 自动升级
+- v0.6.10：runtime 模块化、VS Code esbuild bundle
+- v0.6.7–0.6.9：全局配置脚手架、无工作区也可打开 Settings
 
 ### 发布信息
 
-- 最新版本：**v0.6.13**（root + vscode-extension）；npm：`@roarpeng/graphflow@0.6.13`
+- 最新版本：**v1.0.4**（root + vscode-extension）；npm：`@roarpeng/graphflow@1.0.4`
 - **GitHub Release**：push 到 `main` 且 CI 通过后自动发布 VSIX（见 [Actions](https://github.com/Roarpeng/GraphFlow/actions)）
 - 变更日志：`CHANGELOG.md`
 
@@ -68,7 +84,7 @@ npm install
 npm run ci
 ```
 
-预期：`lint` 无错误、`build` 成功、**177 tests** 通过、扩展 bundle 与 runtime smoke 通过。
+预期：`lint` 无错误、`build` 成功、**200+ tests** 通过、扩展 bundle 与 runtime smoke 通过。
 
 ## Agent 工具接入
 
@@ -83,19 +99,32 @@ GraphFlow 支持两种对外接入方式：
 npm run start:mcp
 ```
 
-### MCP 工具一览
+### MCP 工具一览（16 个）
 
 | 工具 | 用途 |
 | --- | --- |
-| `graphflow_preview_context` | 压缩任务相关上下文（优先调用） |
-| `graphflow_plan` | 多步任务分解 |
-| `graphflow_run` | 执行编排循环 |
-| `graphflow_index` / `graphflow_rebuild` | 增量 / 全量建图 |
-| `graphflow_inspect_graph` | 图谱快照与统计 |
-| `graphflow_enrich_graph` | 语义增强 |
+| `graphflow_preview_context` | 压缩任务相关上下文（**优先调用**） |
+| `graphflow_plan` | 多步任务分解与 DAG 规划 |
+| `graphflow_plan_insight` | 六顶思考帽 + 5-Why 深度分析后规划（复杂任务） |
+| `graphflow_run` | 规划 + 压缩上下文，输出 bridge 执行描述符 |
+| `graphflow_index` | 全工作区增量建图 |
+| `graphflow_index_file` | 单文件增量建图（适合 onSave / watcher） |
+| `graphflow_rebuild` | 清空缓存后全量重建 |
+| `graphflow_inspect_graph` | 图谱快照统计与样本节点 |
+| `graphflow_enrich_graph` | 符号节点语义增强 |
 | `graphflow_skill_insights` | 技能学习洞察 |
-| `graphflow_diagnose` | 路由健康诊断 |
-| `graphflow_model_download` | OpenBMB 模型下载 |
+| `graphflow_diagnose` | 路由与压缩模型健康诊断 |
+| `graphflow_model_download` | OpenBMB / minicpm 模型下载 |
+| `graphflow_export_artifact` | 导出压缩图谱 artifact |
+| `graphflow_import_artifact` | 导入图谱 artifact |
+| `graphflow_stats` | 累计 token 节省 ROI 统计 |
+| `graphflow_metrics` | Prometheus 格式运行指标 |
+
+**MCP 建图提示**：用户级 MCP 进程的 `cwd` 不一定是当前项目。请任选其一：
+
+- 调用 `graphflow_index` 时传入 `rootDir`（项目绝对路径）
+- 在 MCP 配置中设置 `GRAPHFLOW_WORKSPACE_ROOT` 环境变量
+- 使用 VS Code 扩展「建立图谱」或项目级 `.cursor/mcp.json`
 
 CLI 示例：
 
@@ -143,6 +172,54 @@ npm run start -- skill insights
 
 ## 进阶能力
 
+### 上下文压缩（v1.0 核心）
+
+GraphFlow 的压缩采用「三层渐进」策略，先用零成本图结构压缩砍掉冗余节点，再按需用 LLM 做语义合并：
+
+| 层 | 机制 | 成本 | 默认 |
+| --- | --- | --- | --- |
+| 图结构压缩 | 边权重连通子图 + PageRank 中心性重排 | 零 LLM | **开启** |
+| 向量召回 | embedding + RRF 融合；候选 ≥200 自动用 HNSW ANN | 零 LLM | 配 embedding 时开启 |
+| 语义压缩 | minicpm/economy LLM 聚类合并相似节点 + 长节点改写 | LLM | opt-in |
+| RepoMap 概览 | 预算紧张时返回模块级地图 | 零 LLM | opt-in |
+| 自适应预算 | 按任务复杂度动态调整 token 预算 | 零 LLM | opt-in |
+
+**压缩模型策略（零额外配置）**：压缩复用 economy tier——
+
+- 配了外部 provider（OpenAI/Anthropic/百炼）→ 自动用其 economy 模型（如 `gpt-4.1-mini`）
+- 纯离线无外部 LLM → 自动回退内嵌 minicpm，**首次使用按需下载** GGUF 到 `~/.graphflow/models/`（约 650MB，仅一次）
+
+配置示例：
+
+```json
+{
+  "graphPolicy": {
+    "compression": {
+      "enabled": true,
+      "backend": "inherit",
+      "enableGraphCompression": true,
+      "enableHnsw": true,
+      "enableRepoMapFallback": false,
+      "enableAdaptiveBudget": false,
+      "autoDownloadEmbedded": true
+    }
+  }
+}
+```
+
+查看当前压缩模型来源：
+
+```bash
+npm run start -- route diagnose
+# 输出含：compression=inherit:openai/gpt-4.1-mini
+```
+
+**HNSW 加速（可选依赖）**：大仓库（候选 ≥200 节点）向量召回自动使用 HNSW ANN（10~100x 提速）。需安装可选依赖：
+
+```bash
+npm install hnswlib-node   # 未安装时自动降级线性扫描，不影响功能
+```
+
 ### SQLite / FTS5 后端
 
 ```json
@@ -189,8 +266,10 @@ const run = await orchestrate(
 | Rust | `.rs` |
 | Go | `.go` |
 | C / C++ | `.c .h .cc .cpp .cxx .hpp .hxx` |
+| Java | `.java` |
+| Ruby | `.rb` |
 
-通过 `graphPolicy.includeExtensions` 限制扫描范围。
+通过 `graphPolicy.includeExtensions` 限制扫描范围。tree-sitter WASM 语法包随 npm 包分发；开发/发布前可执行 `npm run wasm:download` 预下载到 `wasm/`。
 
 ## 配置文件
 
@@ -200,12 +279,26 @@ const run = await orchestrate(
 cp graphflow.config.example.json graphflow.config.json
 ```
 
+### 全局 vs 项目配置
+
+| 层级 | 路径 | 适合存放 |
+| --- | --- | --- |
+| 全局 | `~/.graphflow.config.json` | Provider、API Key、Smart/Economy 模型、路由策略 |
+| 项目根 | `graphflow.config.json` | 项目专属覆盖（可选） |
+| 项目覆盖 | `.graphflow/config.json` | 工作区局部覆盖（`graphflow init` 生成） |
+
+**多项目重要约定**：
+
+- 图谱文件默认写在**当前工作区**下的 `graphflow-out/graphflow-graph.json`
+- 全局配置**不应**包含固定的 `workspaceRoot`（旧版本若已写入，请删除该字段）
+- MCP / 脚本可通过环境变量指定工作区：`GRAPHFLOW_WORKSPACE_ROOT=/path/to/project`
+
 关键项：
 
 | 配置 | 说明 |
 | --- | --- |
 | `graphPolicy.transport` | `file` / `memory` / `sqlite` / `mcp-http` |
-| `graphPolicy.graphStorePath` | JSON 或 `.sqlite` 路径 |
+| `graphPolicy.graphStorePath` | 相对当前工作区的 JSON 或 `.sqlite` 路径 |
 | `graphPolicy.maxContextTokens` | 压缩上下文预算（默认 **1500**） |
 | `graphPolicy.autoIndexOnSave` | 保存后增量索引（默认 **true**） |
 | `graphPolicy.autoIndexOnPreview` / `autoIndexOnRun` | preview / run 前自动索引 |
@@ -265,11 +358,22 @@ code --install-extension artifacts/graphflow-vscode-*.vsix
 3. `context preview` → `summary > 0` 且 `anchors > 0`
 4. VS Code **Show Graph** → 画布正常显示节点聚类（非角落小点）
 5. `plan` / `run` 返回正常输出
-
-正式测试文档：`docs/testing/2026-05-28-formal-usage-test-plan.md`
+6. `route diagnose` → 显示 `compression=<backend>:<provider>/<model>`
 
 ## 常见问题
 
+**切换项目后 Snapshot 显示别的仓库的图谱**
+
+- 检查 `~/.graphflow.config.json` 是否含有旧的 `workspaceRoot`，**删除该字段**后重载窗口
+- 在当前项目重新「建立图谱」，确认顶栏 `store` 路径指向本项目的 `graphflow-out/`
+- 使用 v1.0.x 最新版（已修复全局 `workspaceRoot` 串项目问题）
+
+**MCP 建图失败或索引到错误目录**
+
+- `graphflow_index` 传入 `rootDir: "/你的项目绝对路径"`
+- 或在 MCP 配置中加 `"env": { "GRAPHFLOW_WORKSPACE_ROOT": "/你的项目绝对路径" }`
+- 离线环境首次索引多语言项目时，确保 `wasm/` 语法包存在或网络可访问 unpkg
+
 **`context preview` 返回 0 anchors**
 
 - 先执行 `graph index` 或 Settings 建图
@@ -277,8 +381,9 @@ code --install-extension artifacts/graphflow-vscode-*.vsix
 
 **知识图谱面板空白或只有小点**
 
-- 升级到 **v0.6.13+** 并重载窗口
+- 升级到 **v1.0.0+** 并重载窗口
 - 点击画布工具栏 **「适应」**
+- 注意：画布展示的是**采样子图**（约 120 节点），全库规模请看顶栏统计
 
 **API Key 未配置**
 
@@ -300,7 +405,7 @@ GraphFlow/
 │   └── surfaces/
 │       ├── cli/        # CLI + runtime 子模块
 │       └── mcp/        # MCP server
-├── tests/              # 41 文件 / 177 tests
+├── tests/              # 49 文件 / 200+ tests
 ├── vscode-extension/   # VS Code 面板与命令
 ├── docs/
 └── CHANGELOG.md

package/dist/agents/insight.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Six Thinking Hats + Five Whys Insight Engine.
+ *
+ * Borrowed from Edward de Bono's "Six Thinking Hats" framework —
+ * before planning a task, analyze it through 6 distinct perspectives,
+ * and auto-apply 5-level Why chains to key observations that fall
+ * below a confidence threshold.
+ *
+ * The 5 Why triggers are automatic: whenever a hat produces an
+ * observation with low certainty (< 0.6), the chain is applied to
+ * drill toward root cause.
+ */
+import type { TaskNode } from "../core/types";
+import type { ModelSelection } from "../routing/model-router";
+import { type PromptContext } from "../routing/provider-executor";
+/** === Hat Definitions === */
+export interface HatDefinition {
+    name: string;
+    color: "white" | "red" | "black" | "yellow" | "green" | "blue";
+    role: string;
+    focus: string;
+    question: string;
+    whyFocus: string;
+    whyRootFocus: string;
+}
+export declare const SIX_HATS: HatDefinition[];
+/** === Five Whys Chain === */
+export interface WhyStep {
+    level: 1 | 2 | 3 | 4 | 5;
+    question: string;
+    answer: string;
+    certainty: number;
+}
+export interface FiveWhyResult {
+    initialObservation: string;
+    certainty: number;
+    steps: WhyStep[];
+    rootCause: string;
+}
+export interface WhyChainSection {
+    hat: HatDefinition;
+    /** Key observation produced by this hat */
+    observation: string;
+    certainty: number;
+    /** 5-level why chain (only non-trivial ones are expanded) */
+    whyChain: FiveWhyResult | null;
+    /** Critical findings that should influence the plan */
+    criticalInsight: string;
+}
+/** === Six Hats Analysis Result === */
+export interface SixHatsInsight {
+    task: string;
+    hats: WhyChainSection[];
+    blueHatSynthesis: string;
+    rootCauses: string[];
+    criticalRisks: string[];
+    coreValue: string;
+    refinedTaskStatement: string;
+}
+/** === Main Entry Points === */
+export interface PlanInsightOptions {
+    selection: ModelSelection;
+    context?: PromptContext;
+}
+/**
+ * Run the full Six Thinking Hats + Five Whys analysis on a task,
+ * then generate a DAG-style plan that incorporates the insights.
+ *
+ * @param task The task to analyze
+ * @param options Model selection and context options
+ */
+export declare function planInsight(task: string, options: PlanInsightOptions): Promise<{
+    insight: SixHatsInsight;
+    plan: TaskNode[];
+}>;
+/**
+ * Run the Six Thinking Hats analysis with automatic 5 Why triggers.
+ *
+ * Each hat produces an observation. If the observation's certainty
+ * is below THRESHOLD (0.6), a 5 Why chain is automatically applied.
+ */
+export declare function analyzeWithSixHats(task: string, options: PlanInsightOptions): Promise<SixHatsInsight>;
+//# sourceMappingURL=insight.d.ts.map

package/dist/agents/insight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"insight.d.ts","sourceRoot":"","sources":["../../src/agents/insight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9D,OAAO,EAAqB,KAAK,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAGrF,8BAA8B;AAE9B,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,OAAO,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;IAC/D,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,QAAQ,EAAE,aAAa,EAuDnC,CAAC;AAEF,8BAA8B;AAE9B,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,kBAAkB,EAAE,MAAM,CAAC;IAC3B,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,OAAO,EAAE,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,GAAG,EAAE,aAAa,CAAC;IACnB,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,6DAA6D;IAC7D,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/B,uDAAuD;IACvD,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,uCAAuC;AAEvC,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED,gCAAgC;AAEhC,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,cAAc,CAAC;IAC1B,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC;IACT,OAAO,EAAE,cAAc,CAAC;IACxB,IAAI,EAAE,QAAQ,EAAE,CAAC;CAClB,CAAC,CAID;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,cAAc,CAAC,CAkCzB"}