flowmind 1.4.6 → 1.4.8

package/docs/guide.md

@@ -0,0 +1,151 @@
+# FlowMind Detailed Guide
+
+This guide is the long-form companion to the npm homepage.
+Use it when you want the fuller product explanation, usage modes, and system model.
+
+## Core Idea
+
+FlowMind is designed for repeatable developer operations.
+Instead of rewriting the same instructions, you route work through a skill, run it through configured adapters or MCP-compatible providers, and keep explicit feedback as reusable local state.
+
+The shortest model is:
+
+1. Receive a request
+2. Select a skill
+3. Execute through adapters or integrations
+4. Capture explicit feedback
+5. Reuse that feedback on similar requests later
+
+## Usage Modes
+
+### CLI
+
+The default mode is direct CLI usage:
+
+```bash
+flowmind "查询 traceId abc123 的日志"
+flowmind "审查代码质量"
+flowmind process --skill log-audit "查询最近1小时的错误日志"
+```
+
+Use this mode when you want the fastest path with minimal setup.
+
+### Codex-Friendly JSON
+
+If another tool needs machine-readable output:
+
+```bash
+flowmind-codex "查询最近1小时的错误日志"
+flowmind-codex --skill log-audit "查询 traceId abc123 的完整链路"
+flowmind process --json "查询日志"
+```
+
+Use this mode for automation, scripts, or CI.
+
+### MCP Client Integration
+
+FlowMind can be exposed as an MCP server for tools such as Claude Code, Cursor, Windsurf, or Cline.
+Setup details live in [integration-guide.md](integration-guide.md).
+
+### AI-Enhanced Routing
+
+FlowMind can sit in front of model providers and use them for intent understanding, parameter extraction, skill selection, and result summarization.
+That improves handling for more natural or multi-step requests, while still keeping a skill-based execution path.
+
+## How It Works
+
+### 1. Skill Routing
+
+Each request is matched to a reusable skill.
+That gives FlowMind a stable execution path instead of relying on a fresh prompt every time.
+
+### 2. Adapter Execution
+
+Skills call adapters or providers for the actual work, such as logs, databases, API docs, knowledge bases, or workflow systems.
+
+### 3. Learning From Explicit Feedback
+
+FlowMind focuses on explicit learning.
+For example:
+
+```text
+User: "Use a table next time"
+FlowMind: records the preference
+```
+
+On later similar requests, that preference can be reapplied from local learning data.
+
+### 4. Local Reuse
+
+The learning layer is meant to reduce repetition, not hide work.
+You can inspect the available skills, control execution explicitly, and keep the system scriptable.
+
+## Architecture Summary
+
+FlowMind is organized around four layers:
+
+1. CLI and MCP entrypoints
+2. Skill routing and execution
+3. Provider and adapter integrations
+4. Learning and preference reuse
+
+Common component families include:
+
+- `logService`
+- `databaseManager`
+- `databaseQuery`
+- `redisMonitor`
+- `apiDoc`
+- `knowledgeBase`
+- `workflow`
+- `report`
+
+The practical goal is configuration-based switching instead of rewriting skill logic for each backend.
+
+## Best-Fit Use Cases
+
+### Log and Trace Investigation
+
+```bash
+flowmind "排查线上问题 traceId abc123"
+```
+
+Best when the same investigation pattern happens repeatedly.
+
+### Code Review
+
+```bash
+flowmind "代码审查先检查安全漏洞，再检查代码质量"
+flowmind "审查这个 PR"
+```
+
+Best when the team has a stable review sequence or standards.
+
+### Data Validation
+
+```bash
+flowmind "验证订单数据"
+flowmind "检查金额计算逻辑"
+```
+
+Best when validation repeatedly crosses logs, database state, and business logic.
+
+## When FlowMind Is a Good Fit
+
+FlowMind is a strong fit when:
+
+- You already have internal tools and want a consistent execution surface
+- You repeat the same categories of investigation or review
+- You want feedback to persist outside chat history
+
+FlowMind is a weaker fit when:
+
+- You only need a generic chat assistant
+- Every task is one-off and never repeated
+- You expect full autonomous engineering without configured tools or skills
+
+## Where To Go Next
+
+- Demo walkthrough: [../demo/DEMO.md](../demo/DEMO.md)
+- Integration setup: [integration-guide.md](integration-guide.md)
+- Release history: [../CHANGELOG.md](../CHANGELOG.md)

package/docs/guide.zh-CN.md

@@ -0,0 +1,151 @@
+# FlowMind 详细指南
+
+这份文档是 npm 首页的长说明版本。
+如果你想看更完整的产品阐述、使用方式和系统模型，就从这里继续。
+
+## 核心思路
+
+FlowMind 面向的是可重复出现的开发操作。
+它不是让你每次都重写一遍指令，而是把工作交给 skill，再通过已配置的 adapter 或 MCP 兼容提供者执行，并把显式反馈沉淀为可复用的本地状态。
+
+最短链路可以概括为：
+
+1. 接收请求
+2. 选择 skill
+3. 通过 adapter / integration 执行
+4. 记录显式反馈
+5. 在相似请求里复用这些反馈
+
+## 使用方式
+
+### CLI
+
+默认方式就是直接通过命令行使用：
+
+```bash
+flowmind "查询 traceId abc123 的日志"
+flowmind "审查代码质量"
+flowmind process --skill log-audit "查询最近1小时的错误日志"
+```
+
+如果你想先最快跑通，这是最直接的入口。
+
+### 面向 Codex 的 JSON 输出
+
+如果你的上层工具需要结构化输出：
+
+```bash
+flowmind-codex "查询最近1小时的错误日志"
+flowmind-codex --skill log-audit "查询 traceId abc123 的完整链路"
+flowmind process --json "查询日志"
+```
+
+这更适合自动化脚本、CI 或工具编排。
+
+### MCP 客户端接入
+
+FlowMind 可以作为 MCP Server 暴露给 Claude Code、Cursor、Windsurf、Cline 等工具使用。
+具体接入步骤见 [integration-guide.md](integration-guide.md)。
+
+### AI 增强路由
+
+FlowMind 也可以接在模型前面，利用模型能力做意图理解、参数提取、skill 选择和结果摘要。
+这样复杂自然语言请求会更顺，但执行路径仍然以 skill 为核心。
+
+## 它是怎么工作的
+
+### 1. Skill 路由
+
+每个请求先匹配到一个可复用 skill。
+这样执行路径是稳定的，而不是每次都重新组织 prompt。
+
+### 2. Adapter 执行
+
+skill 再去调用真正干活的 adapter 或 provider，比如日志、数据库、API 文档、知识库和工作流系统。
+
+### 3. 从显式反馈学习
+
+FlowMind 重点学习的是显式反馈。
+例如：
+
+```text
+用户："下次用表格格式"
+FlowMind：记录这条偏好
+```
+
+之后遇到相似请求时，就可以从本地学习数据里复用。
+
+### 4. 本地复用
+
+这层学习机制的目标是减少重复，而不是隐藏执行过程。
+你依然可以查看 skill、显式控制执行，并保持流程可脚本化。
+
+## 架构概览
+
+FlowMind 可以粗分为四层：
+
+1. CLI / MCP 入口层
+2. skill 路由与执行层
+3. provider / adapter 集成层
+4. 学习与偏好复用层
+
+常见组件族包括：
+
+- `logService`
+- `databaseManager`
+- `databaseQuery`
+- `redisMonitor`
+- `apiDoc`
+- `knowledgeBase`
+- `workflow`
+- `report`
+
+它的实际目标是通过配置切换后端，而不是为了换一个后端就重写 skill 逻辑。
+
+## 最适合的场景
+
+### 日志与链路排查
+
+```bash
+flowmind "排查线上问题 traceId abc123"
+```
+
+适合那类经常重复出现、步骤相对稳定的问题排查。
+
+### 代码审查
+
+```bash
+flowmind "代码审查先检查安全漏洞，再检查代码质量"
+flowmind "审查这个 PR"
+```
+
+适合团队已经有固定审查顺序或标准的情况。
+
+### 数据校验
+
+```bash
+flowmind "验证订单数据"
+flowmind "检查金额计算逻辑"
+```
+
+适合日志、数据库状态和业务逻辑需要反复联合验证的场景。
+
+## 什么情况下值得用
+
+如果满足下面几条，FlowMind 通常比较合适：
+
+- 你已经有内部工具，只是缺一个稳定的执行入口
+- 某几类排查、审查、校验任务会反复出现
+- 你希望反馈能脱离聊天记录，变成可复用状态
+
+如果是下面这些情况，FlowMind 反而不是最优解：
+
+- 你只需要一个通用聊天助手
+- 每个任务都是一次性的，从不重复
+- 你期待在没有任何配置和技能的前提下完全自治式开发
+
+## 下一步看哪里
+
+- 终端演示： [../demo/DEMO_CN.md](../demo/DEMO_CN.md)
+- 集成接入： [integration-guide.md](integration-guide.md)
+- 版本更新： [../CHANGELOG.md](../CHANGELOG.md)

package/docs/integration-guide.md

@@ -0,0 +1,424 @@
+# FlowMind 集成指南
+
+## 把 FlowMind 作为 Agent/Skill 安装到 AI CLI 工具
+
+---
+
+## 目录
+
+- [Claude Code 集成](#claude-code-集成)
+- [Cursor 集成](#cursor-集成)
+- [Windsurf 集成](#windsurf-集成)
+- [Cline 集成](#cline-集成)
+- [Codex 集成](#codex-集成)
+- [通用 MCP 客户端](#通用-mcp-客户端)
+
+---
+
+## Claude Code 集成
+
+### 方式 1：作为 MCP Server（推荐）
+
+这是最完整的集成方式，让 Claude Code 可以直接调用 FlowMind 的所有技能。
+
+#### 步骤 1：安装 FlowMind
+
+```bash
+npm install -g flowmind
+```
+
+#### 步骤 2：配置 MCP Server
+
+在项目根目录创建或编辑 `.claude/settings.local.json`：
+
+```json
+{
+  "mcpServers": {
+    "flowmind": {
+      "command": "flowmind-mcp",
+      "args": [],
+      "env": {
+        "OPENAI_API_KEY": "${OPENAI_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+#### 步骤 3：重启 Claude Code
+
+配置完成后，重启 Claude Code 即可生效。
+
+#### 步骤 4：使用
+
+在 Claude Code 中直接使用自然语言：
+
+```
+你：帮我查询最近1小时的错误日志
+Claude：我来调用 FlowMind 帮你查询...
+
+你：审查一下这个项目的代码质量
+Claude：我来使用 FlowMind 的代码审查技能...
+```
+
+### 方式 2：作为 Slash Command（技能）
+
+把 FlowMind 的技能注册为 Claude Code 的 Slash Command。
+
+#### 步骤 1：创建技能目录
+
+```bash
+mkdir -p ~/.claude/skills
+```
+
+#### 步骤 2：创建 FlowMind 技能文件
+
+创建 `~/.claude/skills/flowmind.md`：
+
+```markdown
+---
+name: flowmind
+description: FlowMind - AI Agent for development workflows
+---
+
+# FlowMind Agent
+
+FlowMind is an intelligent development workflow automation agent.
+
+## Available Skills
+
+### Log Audit
+- Trigger: "日志", "traceId", "排查"
+- Usage: `flowmind "查询 traceId abc123 的日志"`
+
+### Code Review
+- Trigger: "代码审查", "review", "PR"
+- Usage: `flowmind "审查代码质量"`
+
+### Data Validation
+- Trigger: "数据验证", "逻辑检查"
+- Usage: `flowmind "验证订单数据"`
+
+## How to Use
+
+When the user asks about:
+1. Log analysis or debugging → Use flowmind log-audit skill
+2. Code review or quality check → Use flowmind code-review skill
+3. Data validation → Use flowmind data-validation skill
+4. API documentation → Use flowmind api-sync skill
+
+Execute: `flowmind "user's request"`
+```
+
+#### 步骤 3：使用
+
+在 Claude Code 中输入 `/flowmind` 即可调用。
+
+### 方式 3：作为 Tool（工具）
+
+在 Claude Code 的 `settings.json` 中注册 FlowMind 为自定义工具。
+
+```json
+{
+  "tools": {
+    "flowmind": {
+      "command": "flowmind",
+      "args": ["process", "--json", "{{input}}"],
+      "description": "FlowMind AI Agent for development workflows"
+    }
+  }
+}
+```
+
+---
+
+## Cursor 集成
+
+Cursor 支持 MCP 协议，可以像 Claude Code 一样集成 FlowMind。
+
+### 步骤 1：配置 MCP Server
+
+在 Cursor 的设置中，找到 MCP Server 配置，添加：
+
+```json
+{
+  "flowmind": {
+    "command": "flowmind-mcp",
+    "args": []
+  }
+}
+```
+
+### 步骤 2：使用
+
+在 Cursor 的 AI 对话中直接使用：
+
+```
+@flowmind 查询最近1小时的错误日志
+@flowmind 审查代码质量
+```
+
+---
+
+## Windsurf 集成
+
+Windsurf 是 Codeium 的 AI IDE，支持 MCP 协议。
+
+### 步骤 1：配置 MCP Server
+
+在 Windsurf 的设置中，找到 MCP 配置，添加：
+
+```json
+{
+  "mcpServers": {
+    "flowmind": {
+      "command": "flowmind-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+### 步骤 2：使用
+
+在 Windsurf 的 AI 聊天中使用 FlowMind。
+
+---
+
+## Cline 集成
+
+Cline 是 VS Code 的 AI 编程助手，支持 MCP 协议。
+
+### 步骤 1：安装 Cline
+
+在 VS Code 中安装 Cline 扩展。
+
+### 步骤 2：配置 MCP Server
+
+在 Cline 的设置中，找到 MCP Servers 配置，添加：
+
+```json
+{
+  "flowmind": {
+    "command": "flowmind-mcp",
+    "args": []
+  }
+}
+```
+
+### 步骤 3：使用
+
+在 Cline 的聊天中直接使用 FlowMind。
+
+---
+
+## Codex 集成
+
+Codex 是 OpenAI 的 CLI 工具，通过 JSON 输出集成 FlowMind。
+
+### 方式 1：使用 `flowmind-codex`（推荐）
+
+安装后直接使用专门的 Codex 包装命令：
+
+```bash
+# 处理请求
+flowmind-codex "查询最近1小时的错误日志"
+
+# 强制指定技能
+flowmind-codex --skill log-audit "查询 traceId abc123 的完整链路"
+
+# 列出技能
+flowmind-codex skills
+
+# 查看单个技能
+flowmind-codex skill log-audit
+
+# 健康检查
+flowmind-codex doctor
+```
+
+这个命令固定输出 JSON，适合 Codex、脚本和 CI 直接消费。
+默认会把配置、缓存和学习数据写到当前工作区的 `.flowmind-codex/`。
+如需改路径，可设置 `FLOWMIND_CODEX_HOME=/your/path`。
+
+### 方式 2：直接调用 `flowmind --json`
+
+```bash
+# 获取技能列表
+flowmind skills --json
+
+# 执行任务
+flowmind process --json "查询日志"
+```
+
+### 方式 3：创建 Wrapper 脚本
+
+创建 `flowmind-codex.sh`：
+
+```bash
+#!/bin/bash
+# FlowMind Codex Integration Wrapper
+
+INPUT="$1"
+RESULT=$(flowmind process --json "$INPUT")
+
+# 提取结果
+echo "$RESULT" | jq -r '.data // .message // .error'
+```
+
+### 方式 4：Python 集成
+
+```python
+import subprocess
+import json
+
+class FlowMindAgent:
+    def __init__(self):
+        self.name = "flowmind"
+
+    def run(self, query: str) -> dict:
+        result = subprocess.run(
+            ['flowmind', 'process', '--json', query],
+            capture_output=True,
+            text=True
+        )
+        return json.loads(result.stdout)
+
+    def list_skills(self) -> list:
+        result = subprocess.run(
+            ['flowmind', 'skills', '--json'],
+            capture_output=True,
+            text=True
+        )
+        return json.loads(result.stdout)['skills']
+
+# 使用
+agent = FlowMindAgent()
+result = agent.run("查询 traceId abc123 的日志")
+print(result)
+```
+
+---
+
+## 通用 MCP 客户端
+
+任何支持 MCP 协议的客户端都可以集成 FlowMind。
+
+### MCP Server 配置
+
+```json
+{
+  "name": "flowmind",
+  "transport": {
+    "type": "stdio",
+    "command": "flowmind-mcp",
+    "args": []
+  }
+}
+```
+
+### MCP 工具列表
+
+| 工具名称 | 描述 | 参数 |
+|---------|------|------|
+| `flowmind_process` | 处理请求 | `{input: string, context?: object}` |
+| `flowmind_list_skills` | 列出技能 | `{}` |
+| `flowmind_get_skill` | 技能详情 | `{name: string}` |
+| `flowmind_ai_status` | AI 状态 | `{}` |
+| `flowmind_learning_stats` | 学习统计 | `{}` |
+| `flowmind_skill_<name>` | 执行技能 | `{input: string, context?: object}` |
+
+---
+
+## 集成架构图
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    AI CLI 工具                               │
+│         (Claude Code / Cursor / Windsurf / Cline)           │
+└───────────────────────────┬─────────────────────────────────┘
+                            │
+                            │ MCP Protocol
+                            │
+┌───────────────────────────v─────────────────────────────────┐
+│                    FlowMind MCP Server                       │
+│                      (mcp/server.js)                         │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
+│  │ Intent      │  │ Skill       │  │ Learning    │         │
+│  │ Understanding│  │ Selection   │  │ Engine      │         │
+│  └─────────────┘  └─────────────┘  └─────────────┘         │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │              FlowMind Skills                          │   │
+│  │  log-audit │ code-review │ data-validation │ ...      │   │
+│  └─────────────────────────────────────────────────────┘   │
+├─────────────────────────────────────────────────────────────┤
+│  ┌─────────────────────────────────────────────────────┐   │
+│  │              External Services (MCP)                  │   │
+│  │  SLS │ DMS │ Redis │ YApi │ Yuque │ Friday │ ...     │   │
+│  └─────────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 常见问题
+
+### Q1: Claude Code 无法识别 FlowMind MCP Server？
+
+1. 检查 `.claude/settings.local.json` 配置是否正确
+2. 确认 `flowmind-mcp` 命令可用：`which flowmind-mcp`
+3. 重启 Claude Code
+
+### Q2: 如何让 FlowMind 在所有项目中可用？
+
+在用户级别配置 MCP Server：
+
+```bash
+# 编辑全局配置
+vim ~/.claude/settings.json
+```
+
+添加：
+```json
+{
+  "mcpServers": {
+    "flowmind": {
+      "command": "flowmind-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+### Q3: 如何同时使用多个 AI CLI 工具？
+
+FlowMind 支持同时被多个客户端调用，学习数据会自动同步。
+
+### Q4: 如何自定义 FlowMind 技能？
+
+1. 在 `skills/` 目录创建新技能
+2. 创建 `SKILL.md` 定义触发词
+3. 创建 `index.js` 实现逻辑
+4. 重启 MCP Server
+
+---
+
+## 快速开始
+
+```bash
+# 1. 安装 FlowMind
+npm install -g flowmind
+
+# 2. 初始化
+flowmind init --ai openai
+
+# 3. 配置 Claude Code
+echo '{"mcpServers":{"flowmind":{"command":"flowmind-mcp"}}}' > .claude/settings.local.json
+
+# 4. 重启 Claude Code
+
+# 5. 使用
+# 在 Claude Code 中直接说：帮我查询日志
+```