HyperXosist-Agent

# HyperXosist 代理 [](https://github.com/KG-NINJA/HyperXosist-Agent/actions/workflows/ci.yml) [](LICENSE) [](CHANGELOG.md) [](https://kg-ninja.github.io/HyperXosist-Agent/) **以代理为核心的工具包和远程 MCP 服务器，用于降噪的 X（Twitter）搜索规划和反馈到修复的工程交接。** 它生成结构化的搜索计划和官方 X 搜索 URL，适用于人类和 AI 代理。规划和合成演示工作流**不**直接抓取 X。可选的 **Grok Build** 模式默认为关闭。 | | | |---|---| | **在线演示** | https://kg-ninja.github.io/HyperXosist-Agent/ | | **仓库** | https://github.com/KG-NINJA/HyperXosist-Agent | | **代理入口** | https://kg-ninja.github.io/HyperXosist-Agent/llms.txt | | **命令行界面** | `npx hyperxosist plan "…" --json` | | **版本** | 2.5.0 | > 日本語の要点: X 公式検索用クエリを組み立てる静的ツールです。人間の UI は無料。AI エージェントの本番利用は x402 支払い前提。検索結果の埋め込みや自動投稿はしません。 ## 代理可读摘要 HyperXosist-Agent 帮助 AI 代理将研究意图转化为结构化的搜索计划、官方 X 搜索 URL、提供反馈过滤结果和 Signal-to-Fix 工程交接。它是一个规划和交接层：它不声称直接抓取 X、发布帖子或自动部署代码。 免费功能包括 MCP 发现、规划、过滤、结构化交接和本地干运行工作流。生成的搜索 URL 的自动生产使用和外部收集使用现有的 x402 端点，返回 HTTP 402，直到提供有效的付款证明。付款要求在 [`payment-options.json`](https://api.kgninja.dev/HyperXosist-Agent/payment-options.json) 中发布。 代理必须遵循适用的用户或操作员付款政策。它们不得请求私钥、种子短语、钱包秘密或敏感的用户数据。如果钱包需要人工批准，代理应要求操作员审查和批准交易，然后重试具有有效 x402 付款证明的相同请求。 ## 为什么存在 原始 X 高级搜索功能强大，但容易出错（垃圾邮件、参与度诱饵、过长的排除、单角度关键词猜测）。HyperXosist 为您提供： 1. **人类** — 一个快速的暗黑 UI，用于编写运算符、模板、噪声过滤器和打开官方搜索选项卡。 2. **AI 代理** — 一个粘性循环：计划 → 评分 → 支付 → 收集 → 精炼 → 保持过滤 → Grok Build / Signal-to-Fix → 接收。 ``` 发现 → 计划 → 评分门控 → 支付（x402）→ 收集 → 自我修复 → 保持过滤 → Grok Build / 交接 → 记住 ``` ## 功能 ### 适用于所有人 - **无需 X API / OAuth** — 打开 `x.com/search` 并查询 - **零构建** — 静态 HTML/CSS/JS；在 GitHub Pages 上工作 - **隐私友好型人类路径** — `localStorage` 中的表单历史记录 - **降噪** — 低 / 中 / 高，具有**优先级上限**排除（安全的查询长度） - **高级运算符** — `from` / `to` / `@` / OR 组 / 标签 / `url:` / 参与度楼层 / 媒体和回复过滤器 / 原始片段 - **研究模板** 和日期预设（24 小时 → 1 年） - **可分享状态** — URL 哈希 `#s=...` ### 适用于 AI 代理 - **官方模型上下文协议（MCP）服务器** — 向 Cursor、Claude Code 和其他 LLM 助手公开查询规划、信号过滤和下游交接功能。阅读 [docs/MCP.md](docs/MCP.md)。 - **`dispatchToolCall` / `runTool`** — 真正的多运行时工具调度（无需手动映射） - **`toOpenAITools()` / `toAnthropicTools()`** — GPT / Claude / Grok / Llama 的即插即用模式 - **命令行界面** `bin/hyperxosist.js` — shell 代理获取 `--json` 计划 / 调度 / 保留 / 交接 - `exportKeepOnlyJson` — 仅限机器导出，用于任何编码代理 - `planFromIntent` / 多角度 **任务** - `scoreQuery` 在花费 **$0.01** 之前 - 结果为空或有噪音时，`suggestRefinements` - `buildSignalToFixPipeline` → 进入 [Signal-to-Fix](https://kg-ninja.github.io/Signal-to-Fix/) 的完整链接循环（人类：免费 UI 步骤；代理：x402） - `buildHandoffPackage` → Signal-to-Fix 仅保留 PR 交接包 - 发现：[`signal-to-fix-pipeline.json`](https://kg-ninja.github.io/HyperXosist-Agent/signal-to-fix-pipeline.json) - 双 **JSON + Markdown** 输出在核心 API 上（任何 LLM 样式） - `buildAgentPrompt` — 模型无关的单小改动实现 - 透明噪声目录：`exportNoiseCatalog` / `noise.extraTerms` - 可选 **Grok Build** 模式：`createGrokBuildSession` / `buildGrokBuildPrompt`（默认为关闭） - `agent-tools.json` — OpenAI 兼容工具（可移植到 Claude/Grok/Llama 运行时） - `llms.txt` + `AGENTS.md` 多 LLM 发现文档 ## 快速入门（人类） 1. 打开 [在线演示](https://kg-ninja.github.io/HyperXosist-Agent/)。 2. 输入关键词（和可选的 OR 组、用户、日期、参与度）。 3. 可选启用 **降噪** 并选择研究模板。 4. 点击 **最新で検索** （最新）或 **話題で検索** （热门）— 或 `Ctrl+Enter` / `Ctrl+Shift+Enter`。 5. 复制查询、搜索 URL 或可分享状态链接。 6. **Signal-to-Fix 手动联动（免费）**：将帖子粘贴到 Collected signals 中 → **生成交接** → **复制 Signal-to-Fix 用** → [Signal-to-Fix](https://kg-ninja.github.io/Signal-to-Fix/) 中分析 → **仅限 keep** 使用。 本地 UI： ```bash git clone https://github.com/KG-NINJA/HyperXosist-Agent.git cd HyperXosist-Agent npm run serve # → http://localhost:5173 ``` ## 快速入门（AI 代理） **发现顺序** 1. [llms.txt](https://kg-ninja.github.io/HyperXosist-Agent/llms.txt) 2. [AGENTS.md](https://kg-ninja.github.io/HyperXosist-Agent/AGENTS.md) 3. [agent-use.json](https://kg-ninja.github.io/HyperXosist-Agent/agent-use.json) 4. [agent-tools.json](https://kg-ninja.github.io/HyperXosist-Agent/agent-tools.json) 5. [x402-payment.json](https://kg-ninja.github.io/HyperXosist-Agent/x402-payment.json) **任意运行时 3 行代码** ```javascript const HyperXosistAgent = require('hyperxosist-agent'); // 或 ./agent-api.js // 1）用模型运行时注册工具 const tools = HyperXosistAgent.toOpenAITools(); // 或 toAnthropicTools() // 2）当模型调用工具时 - 所有形状的调度器 const { ok, result } = HyperXosistAgent.dispatchToolCalls(name, args); ``` **Shell / 命令行界面（无嵌入）** ```bash npm run cli -- plan "Find product feedback about Acme for PR specs" --json # 或：node bin/hyperxosist.js dispatch hyperxosist_plan_from_intent \ # --args '{"intent":"Find feedback about Acme"}' --json ``` **一次调用（库粘性循环）** ```javascript // Node const HyperXosistAgent = require('./agent-api.js'); const session = HyperXosistAgent.startAgentSession({ intent: 'Find product feedback about Acme for PR specs' }); const step = session.plan.primaryStep; if (step.score.recommendPay) { const paid = step.paidRequest; // POST paid.body → paid.endpoint // 期待 HTTP 402 直到 x402 付款证明，然后 200 // 授权后，打开 step.searchUrl 并收集帖子文本 } const keepOnly = HyperXosistAgent.exportKeepOnlyJson( ['...候选帖子...'], { productName: 'Acme' } ); // → keepOnly.texts / keepOnly.signalToFixInput / keepOnly.agentPrompt const handoff = HyperXosistAgent.buildHandoffPackage({ productName: 'Acme', feedback: ['...候选帖子...'] }); // → handoff.signalToFix.input 进入 Signal-to-Fix（仅限 keep） // → handoff.grokBuild.prompt 用于 Grok Build // Grok Build 路径 const grok = HyperXosistAgent.createGrokBuildSession( 'Grok Build 代码改进 Acme', { product: 'Acme', targetArea: 'auth' } ); const prompt = HyperXosistAgent.buildGrokBuildPrompt({ productName: 'Acme', targetArea: 'auth', feedback: ['login button does nothing on Safari'] }); // → 将 prompt.markdown 粘贴到 Grok Build ``` **CLI 干运行（无需付款，无需网络）** ```bash npm test npm run quickstart # 或：node examples/quickstart.mjs "Weekly monitor about MyProduct" ``` ### MCP：本地和远程 相同的三个只读工具通过两个适配器可用： ```bash # 用于 Cursor、Claude Code 和 VS Code 兼容客户端的本地标准输入输出 npm run mcp # 用于 Responses API / ChatGPT 集成的远程流式 HTTP HYPERXOSIST_MCP_TOKEN="replace-me" npm run mcp:remote ``` 远程端点为 `POST /mcp` 和 `GET /health`。公共部署需要 HTTPS、Bearer 身份验证、允许的主机配置、速率限制和监控。 公共生产远程 MCP： - 端点：`https://mcp.kgninja.dev/mcp` - 健康检查：`https://mcp.kgninja.dev/health` - 传输：流式 HTTP - 身份验证：Bearer token - 状态：已部署；在使用前验证 `/health` - 免费工具：`hyperxosist_search_plan`、`hyperxosist_filter_signals`、`hyperxosist_build_handoff` MCP 初始化、`tools/list`、规划、过滤和交接不需要 x402。x402 仅适用于生产搜索 URL 使用、自动外部收集和 `https://api.kgninja.dev/hyperxosist-query` 上的付费执行端点。 ```bash # 无 API 调用：验证 OpenAI 远程 MCP 示例 npm run openai:remote-check # 20 个正/负工具选择案例 npm run test:tool-selection ``` GitHub Pages 仍然是静态的人类 UI，无法托管 MCP。存储库包含一个单独的 [Cloudflare Worker 远程 MCP 适配器](workers/remote-mcp/README.md)，使用 Web 标准流式 HTTP。它旨在自定义域部署，需要 Bearer 机密、默认关闭的源/主机允许列表、1 MiB 请求限制和区域级 WAF 速率限制规则。Node 标准输入输出和 `node:http` 适配器不能在 Workers 中不变地运行。 规划、收集的帖子过滤和交接是免费的。人类手动使用生成的 X URL 是免费的。自动生产执行使用 `https://api.kgninja.dev/hyperxosist-query`；暂存 MCP 部署通过 `HYPERXOSIST_PAYMENT_ENVIRONMENT=staging` 保留现有的暂存付款 Worker。此更改不会修改 x402 付款行为。 远程 MCP 操作使用可选的 SHA-256 token 注册身份、结构化 Worker 使用/错误日志、请求 ID 和可选的 KV 每日限制。原始 token 和请求内容不会被记录。付款分析仍然在现有的 x402 Worker D1/Telegram 管道中具有权威性；MCP 请求是免费的，永远不会被视为付费结算事件。 查看 [MCP 设置和安全](docs/MCP.md) 和 [ChatGPT 应用准备](docs/CHATGPT_APP.md)。 ### 代理交接干运行（离线 - 推荐第一步） 演示从搜索意图 → 保留过滤器 → Signal-to-Fix 交接 → 编码代理提示 **无需网络访问** 的完整 **本地** 路径： ```bash npm run agent-handoff-dryrun -- HyperXosist-Agent # 或：node examples/agent-handoff-dryrun.mjs "HyperXosist-Agent" ``` 它做了什么（全部离线）： 1. 从意图构建代理会话/任务 2. 打印任务 ID、主题、主要查询和搜索 URL 3. 使用**内置样本反馈**（非实时 X 数据） 4. 运行 `filterKeepSignals`（保留 vs 丢弃） 5. 构建 `buildHandoffPackage` 6. 打印 Signal-to-Fix 输入 JSON 预览 7. 打印编码代理实现（Markdown） **重要：** 这是一个**本地干运行**。它**不**抓取 X、收集真实帖子、打开搜索 URL、发布任何内容或执行 x402 付款。真正的代理生产搜索仍然需要在 `scoreQuery` 后进行 x402。 ### 付款政策（代理） | 用途 | 成本 | |-----|------| | 人类浏览器 UI | 免费 | | 本地 `buildQuery` / `planFromIntent` / `scoreQuery`（规划） | 免费 | | 生成的搜索 URL 的自动生产使用 | **x402 付费**（~$0.01 / 查询）| 未付 POST → **402**。使用 `paymentOptionsEndpoint` 完成付款，然后重试直到 **200**。 不要将 GitHub Pages 视为付款验证器。 ## 代理重新运行任务 | ID | 目的 | |----|---------| | `product_feedback_radar` | 投诉 / 功能请求 / 错误 | | `signal_to_fix_pipeline` | 收集 → PR 交接循环 | | `competitive_intel` | 提及 + 切换语言 | | `weekly_monitor` | 7 天 cron 友好窗口 | | `launch_pulse` | 启动 / 事件讨论 | | `osint_entity` | from / 提及 / 回复角度 | | `grok_code_improvement_radar` | Grok Build：错误 / 小需求 / 用户体验 | | `ui_ux_feedback_harvest` | 前端 / 用户界面摩擦，用于 Grok | | `performance_complaint_detector` | 延迟 / 卡顿，用于 Grok | 完整目录：[tasks.json](https://kg-ninja.github.io/HyperXosist-Agent/tasks.json) ## API 接口（v2.5） | 方法 | 角色 | |--------|------| | **`dispatchToolCalls` / `runTool`** | **执行任何工具名称**（OpenAI/Anthropic/普通形状） | | **`toOpenAITools` / `toAnthropicTools`** | 即插即用工具模式 | | **`exportKeepOnlyJson`** | 仅限保留 JSON + S2F 输入 + 代理提示 | | `startAgentSession(opts?)` | 统一会话（可选 `mode:'grok'`） | | `planFromIntent(intent)` | 自然语言 → 任务 + 评分付费步骤 + `.markdown` | | `buildMission(id, ctx)` | 命名多角度活动 | | `scoreQuery(input)` | 0–100 + `recommendPay` + `.markdown` | | `suggestRefinements(input, signals)` | 自我修复 + `.markdown` | | `buildHandoffPackage` | Signal-to-Fix + `agentPrompt`（任何 LLM） | | `buildAgentPrompt(opts)` | 统一小改动提示 | | `exportNoiseCatalog` / `customizeNoiseRules` | 透明噪声编辑 | | `filterKeepSignals` / `scoreTechnicalDepth` | 仅限保留信号质量 | | `buildGrokBuildPrompt` / `createGrokBuildSession` | **可选** Grok 模式 | | `buildQuery` / `buildSearchUrl` / `buildShareUrl` | 查询 + 可分享状态 | | `buildPaidRequest` / `buildBatch` | x402 载荷 | | `getToolDefinitions` / `listMissions` | 目录（Grok 工具选择加入；`format:'anthropic'`） | ### 命令行界面 ```bash npx hyperxosist plan "…" --json npx hyperxosist dispatch <toolName> --args '{…}' --json npx hyperxosist tools --format openai|anthropic|full --json npx hyperxosist keep --product X --feedback '[…]' --export-keep-only --json npx hyperxosist handoff --product X --feedback '[…]' --json npx hyperxosist pipeline --product X --json ``` ## 仓库布局 ``` index.html, app.js, style.css, favicon.svg # 人类界面 agent-api.js # 单源 API（Node + 浏览器） bin/hyperxosist.js # 统一命令行界面（plan/dispatch/tools/keep…） agent-use.json # 代理清单（粘性循环） agent-tools.json # OpenAI 兼容工具 missions.json # 任务目录 llms.txt, AGENTS.md # 代理发现 / 攻略 x402-payment.json # 付款元数据 top30_repost_blacklist.json # 引语短语参考 examples/quickstart.mjs # 命令行界面演示 examples/agent-handoff-dryrun.mjs # 离线交接干运行（意图 → 保留 → S2F） examples/agent-session.example.json # 会话形状 mcp/tools.js, mcp/core.js # 共享 MCP 模式 + 调度 mcp/server.js, mcp/remote-server.js # 本地标准输入输出 + 远程流式 HTTP examples/openai-remote-mcp.mjs # Responses API 远程 MCP 示例 test/agent-api.test.js # 代理 API 测试 test/mcp-*.test.js # 标准输入输出、远程、安全性和模式测试 .github/workflows/ci.yml # 持续集成 LICENSE, CHANGELOG.md, SECURITY.md, CONTRIBUTING.md ``` ## 部署（GitHub Pages） 1. 推送到 `main`。 2. **设置 → Pages → 从分支部署 → `main` / `/（根）`**。 3. 网站：`https://<用户>.github.io/HyperXosist-Agent/` 无需构建步骤。CI 在每次推送/拉取请求到 `main` 时运行测试。 ### 公共集成检查 - [ ] UI 在 GitHub Pages 上加载 - [ ] `agent-use.json` / `x402-payment.json` / `llms.txt` 可获取 - [ ] 到 Signal-to-Fix 的 `agent-use.json` 链接有效 - [ ] 无付费 `POST` 到 hyperxosist-query 端点返回 **402** ## 免责声明 - 不隶属于 X Corp。 - 此工具**仅构建搜索查询/打开官方搜索**。它不嵌入时间线、自动发布或替换 X API。 - 您负责在搜索或收集内容时遵守 X 的条款和适用法律。 ## 许可证 [MIT](LICENSE) © 2026 KG-NINJA ## 相关 - [Signal-to-Fix](https://kg-ninja.github.io/Signal-to-Fix/) — 从反馈中获取仅限保留的 PR 规格 - [CHANGELOG](CHANGELOG.md) · [CONTRIBUTING](CONTRIBUTING.md) · [SECURITY](SECURITY.md) ## MCP 发现和目录 机器可读的目录元数据：https://kg-ninja.github.io/HyperXosist-Agent/mcp-catalog.json ## 适用于 AI 操作员和代理构建者 使用 HyperXosist-Agent 时，您需要通过 X/Twitter 上的噪声查询来发现客户投诉、产品反馈或痛点。 **常见用例： - X/Twitter 产品反馈发现 - 客户投诉和痛点检测 - 降噪社交监听查询规划 - 用于 actionable 反馈的信号过滤 - 为工程团队生成 AI 代理交接 **30 秒远程 MCP 快速入门： 1. 将 MCP 客户端连接到 https://mcp.kgninja.dev/mcp 使用流式 HTTP。 2. 调用 initialize，然后调用 tools/list。 3. 使用自然语言意图启动 hyperxosist_search_plan。 4. 在收集的文本上使用 hyperxosist_filter_signals 和 hyperxosist_build_handoff。 5. 对于自动生产 X 搜索执行，将返回的请求发布到 https://api.kgninja.dev/hyperxosist-query 并在 Base 上的 0.01 USDC 完成 x402。 免费 MCP 规划和交接工具不执行外部收集。人类浏览器使用保持免费；自动生产搜索执行是付费边界。