[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81466":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":12,"openIssues":13,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":14,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":15,"rankGlobal":9,"rankLanguage":9,"license":16,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":9,"pushedAt":9,"updatedAt":21,"readmeContent":22,"aiSummary":23,"trendingCount":14,"starSnapshotCount":14,"syncStatus":24,"lastSyncTime":25,"discoverSource":26},81466,"iflow-search-js","zhengyanglsun\u002Fiflow-search-js","zhengyanglsun","Official JavaScript SDK and integrations for iFlow Search",null,"TypeScript",31,1,4,0,0.9,"MIT License",false,"main",true,[],"2026-06-12 02:04:15","# iflow-search-js\n\nJavaScript \u002F TypeScript integrations for **iFlow Search (心流搜索)** — a search API that provides web search, image search, and web page fetching with AI-friendly structured output.\n\n- **Product:** \u003Chttps:\u002F\u002Fplatform.iflow.cn\u002F>\n- **API docs:** \u003Chttps:\u002F\u002Fplatform.iflow.cn\u002Fdocs\u002F>\n- **Operator:** 杭州星辰千寻科技有限公司\n\nThis monorepo contains:\n\n- A framework-agnostic core SDK\n- A LangChain JS tool adapter (also usable from LangGraph)\n- A LangGraph agent example\n- An MCP stdio server for Hermes \u002F Claude Code \u002F Claude Desktop \u002F other MCP clients\n\n## Package \u002F usage matrix\n\n| Path | Package | Status | Publish target | Depends on | When to use |\n|---|---|---|---|---|---|\n| `packages\u002Fsearch-core` | `@iflow-ai\u002Fsearch-core` | implemented | npm | — (zero runtime deps) | You are building a framework adapter, calling iFlow directly from a backend, or you don't use LangChain. |\n| `packages\u002Fsearch-langchain` | `@iflow-ai\u002Fsearch-langchain` | implemented | npm | `@iflow-ai\u002Fsearch-core`, `@langchain\u002Fcore`, `zod` | You are building a LangChain JS agent **or** a LangGraph agent — both reuse the same tool factories. |\n| `examples\u002Flanggraph-agent` | `@iflow-examples\u002Flanggraph-agent` | implemented | **not published** (workspace example) | `@iflow-ai\u002Fsearch-langchain`, `@langchain\u002Flanggraph` | Reference for wiring `createReactAgent` with iFlow Search tools. Copy the pattern, don't depend on it. |\n| `packages\u002Fsearch-mcp` | `@iflow-ai\u002Fsearch-mcp` | implemented | npm | `@iflow-ai\u002Fsearch-core`, MCP SDK | You want to expose iFlow Search to MCP clients (Hermes Agent, Claude Code, Claude Desktop, etc.). Stdio transport. |\n\n### Why there is no `@iflow-ai\u002Fsearch-langgraph`\n\nLangGraph consumes LangChain tools directly. A separate `search-langgraph` package would be a thin re-export with no added value — use `@iflow-ai\u002Fsearch-langchain` for both. See `examples\u002Flanggraph-agent` for a working `createReactAgent` wiring.\n\n## Current status\n\n- ✅ `@iflow-ai\u002Fsearch-core` — implemented, framework-agnostic client\n- ✅ `@iflow-ai\u002Fsearch-langchain` — implemented, three tools (`iflow_web_search`, `iflow_image_search`, `iflow_web_fetch`)\n- ✅ `examples\u002Flanggraph-agent` — implemented, ReAct agent end-to-end smoke validated against real iFlow API\n- ❌ no separate `@iflow-ai\u002Fsearch-langgraph` package (intentional — see above)\n- ✅ `@iflow-ai\u002Fsearch-mcp` — implemented, stdio MCP server with three tools mirroring the LangChain adapter; optional MCP-host attribution via `IFLOW_MCP_CLIENT` \u002F `IFLOW_MCP_CLIENT_VERSION`\n\n## Workspace development\n\n```bash\npnpm install\npnpm -r run typecheck\npnpm -r run build\npnpm -r run test\n```\n\nThe workspace pins `@langchain\u002Fcore` to `^1.1.44` via `pnpm-workspace.yaml` `overrides:` to keep LangGraph's runtime and LangChain's tool types on a single major. Removing this override re-introduces `ToolMessage` cross-version serialization bugs in LangGraph agent loops; rerun the LangGraph agent tests before you touch it.\n\n## Basic usage — core SDK\n\n```ts\nimport { createIFlowSearchClient } from \"@iflow-ai\u002Fsearch-core\";\n\nconst client = createIFlowSearchClient({\n  apiKey: process.env.IFLOW_API_KEY!,\n  source: \"core\",\n  integrationName: \"my-app\",\n  integrationVersion: \"1.0.0\",\n});\n\nconst result = await client.webSearch({ query: \"flash attention\", count: 5 });\nif (!result.ok) {\n  console.error(result.error.code, result.error.message);\n} else {\n  for (const r of result.data.results) console.log(r.title, r.url);\n}\n```\n\nSee `packages\u002Fsearch-core\u002FREADME.md` for the full API surface.\n\n## Basic usage — LangChain\n\n```ts\nimport { createIFlowSearchTools } from \"@iflow-ai\u002Fsearch-langchain\";\n\nconst tools = createIFlowSearchTools({\n  apiKey: process.env.IFLOW_API_KEY!,\n});\n\n\u002F\u002F Hand `tools` to any LangChain JS agent that supports `bindTools`.\n```\n\nSee `packages\u002Fsearch-langchain\u002FREADME.md` for tool-by-tool docs.\n\n## Basic usage — LangGraph\n\nLangGraph does **not** need a separate iFlow package. Pass the same `@iflow-ai\u002Fsearch-langchain` tools into `createReactAgent`:\n\n```ts\nimport { createReactAgent, ToolNode } from \"@langchain\u002Flanggraph\u002Fprebuilt\";\nimport { createIFlowSearchTools } from \"@iflow-ai\u002Fsearch-langchain\";\n\nconst tools = createIFlowSearchTools({ apiKey: process.env.IFLOW_API_KEY! });\nconst agent = createReactAgent({ llm, tools: new ToolNode(tools) });\n```\n\nThe working end-to-end example lives at `examples\u002Flanggraph-agent` — bring your own tool-calling LLM (DeepSeek, OpenAI, Anthropic, …).\n\n## Attribution headers\n\nEvery request to iFlow goes through `@iflow-ai\u002Fsearch-core` and carries:\n\n```\nIFlow-Source:              \u003Cruntime>\nIFlow-Integration:         \u003Cpackage-name>\nIFlow-Integration-Version: \u003Cpackage-version>\nUser-Agent:                \u003Cpackage-name>\u002F\u003Cpackage-version>\n```\n\nCurrently emitted values:\n\n| Integration | `IFlow-Source` | `IFlow-Integration` |\n|---|---|---|\n| `@iflow-ai\u002Fsearch-langchain` (also from LangGraph) | `langchain` | `@iflow-ai\u002Fsearch-langchain` |\n| `@iflow-ai\u002Fsearch-mcp` | `mcp` | `@iflow-ai\u002Fsearch-mcp` |\n\n`@iflow-ai\u002Fsearch-mcp` additionally emits `IFlow-MCP-Client` and `IFlow-MCP-Client-Version` when the MCP host declares itself via `IFLOW_MCP_CLIENT` \u002F `IFLOW_MCP_CLIENT_VERSION` environment variables (e.g. `hermes`, `claude-code`, `claude-desktop`). Absence of these headers is meaningful — there is no `unknown` placeholder, so hosts that opt out remain indistinguishable from hosts that have not adopted the convention.\n\nLangGraph traffic shows up as `IFlow-Source: langchain` because it consumes the same LangChain adapter — there is no separate `langgraph` source ID for this reason.\n\n## Security \u002F key handling\n\n- Never commit real API keys. Use environment variables (`IFLOW_API_KEY`, plus your LLM provider key for agent examples).\n- Don't write keys into `.env` files that get committed, into `package.json`, or into test fixtures.\n- The unit tests in this repo use fake keys and a mocked `fetch` — they never touch the real iFlow API.\n- Real-API smoke tests are opt-in. The committed smoke scripts (e.g. `packages\u002Fsearch-langchain\u002Fscripts\u002Fsmoke-direct.mjs`) read `IFLOW_API_KEY` from the environment at runtime and never persist it.\n\n## Roadmap\n\n- **P0** ✅ `@iflow-ai\u002Fsearch-core` — framework-agnostic SDK\n- **P1** ✅ `@iflow-ai\u002Fsearch-langchain` — LangChain JS tool adapter\n- **P2** ✅ `examples\u002Flanggraph-agent` — LangGraph ReAct agent example\n- **P3** ✅ `@iflow-ai\u002Fsearch-mcp` — MCP server for Hermes \u002F Claude Desktop \u002F other MCP clients\n- **P4** 🟡 docs and examples polish — broader recipes, additional LLM providers\n- **P5** optional — refactor the OpenClaw community iFlow plugin to reuse `@iflow-ai\u002Fsearch-core`\n\n## Maintenance and roadmap\n\nLong-form docs for maintainers and contributors live under [`docs\u002F`](.\u002Fdocs):\n\n- [`docs\u002Fpackage-strategy.md`](.\u002Fdocs\u002Fpackage-strategy.md) — which npm packages we publish, which we explicitly will not, and the decision rubric for new ones.\n- [`docs\u002Fintegration-roadmap.md`](.\u002Fdocs\u002Fintegration-roadmap.md) — how each framework (LangChain, LangGraph, OpenClaw, Hermes, Claude Code, iFlow CLI, Open WebUI, Coze, CrewAI) reaches iFlow Search, with phased execution order.\n- [`docs\u002Frelease-policy.md`](.\u002Fdocs\u002Frelease-policy.md) — versioning, `next` vs `latest`, the per-release checklist, and the manual publish commands.\n- [`docs\u002Fmcp-design.md`](.\u002Fdocs\u002Fmcp-design.md) — design for the planned `@iflow-ai\u002Fsearch-mcp` server (P3): package decision, transport scope, tool schema, attribution headers, MCP client config example, and test strategy.\n\n## License\n\nMIT — see [LICENSE](.\u002FLICENSE).\n","iflow-search-js 是一个为 iFlow Search 提供的官方 JavaScript\u002FTypeScript SDK 及集成工具，支持网页搜索、图片搜索和网页抓取，并输出结构化的AI友好数据。该项目的核心功能包括框架无关的核心SDK、LangChain JS工具适配器（也可用于LangGraph）、LangGraph代理示例以及针对Hermes\u002FClaude Code等MCP客户端的stdio服务器。适用于需要直接调用iFlow API进行搜索或构建基于LangChain\u002FLangGraph的智能代理的应用场景。采用MIT许可证发布，确保了开源社区的广泛使用与贡献。",2,"2026-06-11 04:05:11","CREATED_QUERY"]