Flowlines

Flowlines 插件

用于 MCP 可观测性的官方 Flowlines 插件。此仓库提供可移植的 flowlines 插件、面向 Claude Code 和 Codex 的市场，以及供 cursor.directory 使用的 Cursor 插件清单（plugins/flowlines/.cursor-plugin/plugin.json）：

组件	功能
flowlines MCP 服务	将 MCP 客户端连接到你的 Flowlines 工作区 https://api.flowlines.ai/mcp。查看用户如何使用你的 MCP 服务、某个版本发布后有哪些变化，以及会话在哪些地方出错。将发现记录为备注。其 onboarding 工具会返回埋点计划；check_onboarding 会检查收到的遥测数据。
flowlines-weekly-review 技能	定期审查 MCP 服务：自上次审查以来的变化、信号、结果变化，以及下次需要固定记录的内容。
flowlines-release-check 技能	对 MCP 服务版本发布前后进行比较：结果、意图、成本、信号和证据会话，并采用合适的分母。
flowlines-investigate-session 技能	从信号、用户或投诉着手，定位到发生故障的轮次，同时尽量减少终端用户内容的暴露。
flowlines-cohort-builder 技能	计算用户细分群体的规模，使用 Flowlines 队列规则词汇编写规则，并与基线进行比较。
flowlines-doctor 技能	诊断各类数据源中的数据缺失或不完整问题，包括已埋点的 MCP 服务、LangSmith 和 Langfuse 连接器，以及 OTLP 应用。

隐私声明

• Flowlines MCP 服务会读取生产环境中的 MCP 会话、工具调用和用户活动。请将其返回的所有内容视为机密；除通过明确的 save_note 和 report_outcome 工具外，它不会向你的命名空间写入任何内容。
• 从 onboarding 计划埋点的 MCP 服务会向 Flowlines 导出经过验证的工具参数、客户端可见的结果以及用户身份元数据。这些数据可能包含个人数据、客户数据、源代码或其他敏感内容。你可以在 Flowlines 入门页面选择要记录的内容。

onboarding 和 check_onboarding 均为只读：它们会返回埋点计划，并检查收到的调用。命名空间 API 密钥在 Flowlines 入门页面创建，并且只会在那里显示一次；切勿将其粘贴到聊天中。

安装

ChatGPT 和 Codex 公共插件

公共分发目标是在 OpenAI 的 Plugins Directory 中提供一个 Flowlines 插件，其中包含托管的 MCP 服务和四项共用分析技能。此仓库用于准备提交内容；合并更改不会发布插件，也不会为用户安装插件。公开上架以及在各产品中重复安装，仍需经过审核和验证。

请参阅共用插件指南，了解构建和验证步骤；请参阅提交工作表，了解上架素材和审核案例。下方现有的桌面市场安装方式仍可使用。在准备公共提交期间，个人 ChatGPT 账户可以通过开发者模式单独测试此服务。

Claude Code

claude plugin marketplace add flowlines-ai/plugins && claude plugin install flowlines@flowlines

然后在 Claude Code 中运行 /mcp，并登录 flowlines。技能可通过 /flowlines:<skill-name> 使用，例如 /flowlines:flowlines-weekly-review 或 /flowlines:flowlines-doctor。在安装命令中添加 --scope project，即可仅为一个代码库启用该插件。

本地桌面测试

在 ChatGPT 桌面应用中打开此仓库，并在软件包更改后重启应用。在 Plugins Directory 中选择 Flowlines 市场，并安装 flowlines。仓库目录 .agents/plugins/marketplace.json 指向 plugins/flowlines。完成 MCP 登录，并在新聊天中进行测试。本地市场支持情况可能因界面而异；此操作不会发布插件。

Codex CLI

codex plugin marketplace add flowlines-ai/plugins && codex plugin add flowlines@flowlines

然后使用 codex mcp login flowlines 登录，或在 Codex 中打开 /plugins。技能可通过 $<skill-name> 使用，例如 $flowlines-weekly-review 或 $flowlines-doctor。

该插件会注册一个名为 flowlines 的 MCP 服务。如果你之前手动添加了同名服务，请移除该条目，以免重复。

登录后

登录也会创建你的 Flowlines 账户。如果你还没有工作区或 API 密钥，Flowlines 入门页面会为你创建这些内容，并在服务器首次调用工具后变为绿色。若要为你的 MCP 服务添加监控，请让 MCP 客户端引导你使用 Flowlines：它会为你的命名空间调用 onboarding，执行计划，并通过 check_onboarding 验证首次调用。

MCP 连接错误

如果 Flowlines 调用反复返回 Internal error 或 -32603，且没有重新连接提示，请在已安装时使用 flowlines-doctor。它会检查可用的客户端状态和相关本地日志，然后再判断是否为身份验证问题。如果 OAuth 刷新失败，它会使用可用的原生重新连接操作，或告知你如何在客户端中重新连接，然后在恢复请求前验证工具访问权限。无需访问 Flowlines 基础设施或服务日志。

恢复流程会在 Windows、macOS 或 Linux 上使用故障客户端的登录流程。本地 CLI 登录必须完成凭据存储；托管连接器则使用其自身的连接状态。如果登录成功但工具调用仍然失败，可能需要重新加载 MCP 连接。该技能会报告剩余的恢复步骤；它不会自动重启应用。

公开分析包不包含 flowlines-doctor。其分析技能会对报告的身份验证问题使用客户端原生的重新连接操作，并将未解决的故障转交给 Flowlines 支持团队。

团队推广

Claude Code 会从仓库的 .claude/settings.json 中读取市场和插件：

{
  "extraKnownMarketplaces": {
    "flowlines": { "source": { "source": "github", "repo": "flowlines-ai/plugins" } }
  },
  "enabledPlugins": { "flowlines@flowlines": true }
}

Codex 会从 .agents/plugins/marketplace.json 中读取仓库级市场：

{
  "name": "my-team",
  "interface": { "displayName": "My team" },
  "plugins": [
    {
      "name": "flowlines",
      "source": {
        "source": "git-subdir",
        "url": "https://github.com/flowlines-ai/plugins.git",
        "path": "./plugins/flowlines",
        "ref": "main"
      },
      "policy": { "installation": "INSTALLED_BY_DEFAULT", "authentication": "ON_USE" },
      "category": "Developer Tools"
    }
  ]
}

移除旧版 Claude Code 和 Codex 遥测

0.2.0 版移除了 flowlines-agent-observability 技能。如果你曾使用它，其设置仍保留在你的机器上，并会继续向 Flowlines 发送完整提示词、助手消息和工具内容。该插件不再附带 uninstall.sh，因此请手动移除这些设置：

1. Claude Code。 在 ~/.claude/settings.json 中，从 env 删除以下键：CLAUDE_CODE_ENABLE_TELEMETRY、CLAUDE_CODE_ENHANCED_TELEMETRY_BETA、OTEL_LOGS_EXPORTER、OTEL_TRACES_EXPORTER、OTEL_METRICS_EXPORTER、OTEL_EXPORTER_OTLP_PROTOCOL、OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_HEADERS、OTEL_LOG_USER_PROMPTS、OTEL_LOG_ASSISTANT_RESPONSES、OTEL_LOG_TOOL_DETAILS 和 OTEL_LOG_TOOL_CONTENT。
2. Codex CLI。 在 ~/.codex/config.toml 中，从 [otel] 删除 environment、log_user_prompt，以及包含 x-flowlines-api-key 的 exporter。只有在不使用其他 Codex 钩子的情况下，才从 [features] 删除 hooks = true。在 ~/.codex/hooks.json 中，删除命令为 "$HOME/.local/lib/flowlines-agent-observability/codex-hook-relay.sh" 的 UserPromptSubmit、PostToolUse 和 Stop 条目。
3. 钩子中继。 删除 ~/.local/lib/flowlines-agent-observability/。
4. 状态和备份。 ${XDG_CONFIG_HOME:-~/.config}/flowlines-agent-observability/ 中保存了你原始配置文件的副本（位于 originals/）、包含 API 密钥的 curl.conf，以及可能包含提示词内容的未发送 Codex 事件 spool/。如果安装前你有自己的 OpenTelemetry 设置，请从 originals/ 恢复。然后删除该文件夹。
5. API 密钥。 如果该密钥仅用于此遥测，请在 Flowlines 应用的 Settings、API keys 中将其撤销。

启动新的 Claude Code 和 Codex 会话以应用更改。

仓库布局

.claude-plugin/marketplace.json     Claude Code marketplace
.agents/plugins/marketplace.json    Codex marketplace
server.json                         Official MCP Registry entry
plugins/flowlines/
  plugin.json                       Portable identity and OpenAI listing metadata
  mcp.json                          Portable MCP server (streamable-http)
  .claude-plugin/plugin.json        Claude Code manifest
  .codex-plugin/plugin.json         Codex compatibility manifest
  .mcp.json                         Compatibility MCP server (http)
  assets/                           Shared icons
  skills/                           Shared skills

可移植软件包遵循 OpenAI 的打包指南。 宿主会在插件根目录下查找 skills/ 和 mcp.json。OpenAI 列表字段位于 plugin.json 的 extensions.com.openai.interface 下。该扩展会替代兼容性覆盖层；两者不会合并。请确保身份信息、 列表字段、版本和 MCP 端点与兼容性文件保持一致。 测试会检查这些值。现有客户端仍可使用原来的 清单和 .mcp.json。

开发

先用实际 CLI 验证清单，再验证技能包：

scripts/validate_plugins.sh
python3 scripts/validate_skills.py
python3 -m unittest discover -s scripts -p 'test_public_submission.py'

validate_plugins.sh 需要在 PATH 中找到 claude 和 codex。脚本离线运行： Claude 会验证清单，Codex 会分别在临时主目录中安装公开软件包和仓库 插件。每次安装都必须恰好注册一个 MCP 服务，地址为 https://api.flowlines.ai/mcp。这些检查不会完成 OAuth 授权，也不会调用服务。

若要从检出目录试用插件而不进行安装，请运行 claude --plugin-dir plugins/flowlines，或使用 codex plugin marketplace add . 将此目录添加为本地市场。

发布

插件 0.5.0 使用 MCP 服务 2.0.0 中的 onboarding 和 check_onboarding 工具。 发布此插件前，请先部署该服务版本。旧的 onboard 工具已弃用； 由用户调用的名为 onboard 的 MCP 提示词仍可使用。

1. 在 plugins/flowlines/plugin.json、plugins/flowlines/.claude-plugin/plugin.json、plugins/flowlines/.codex-plugin/plugin.json 以及 .claude-plugin/marketplace.json 中的插件条目中更新 version。
2. 合并到 main。市场安装会跟踪 main；用户可通过 claude plugin update flowlines@flowlines 或 codex plugin marketplace upgrade 获取新版本。
3. 使用 claude plugin tag plugins/flowlines 为发布版本打标签。

公开插件目录的发布需遵循单独的 提交和发布流程。合并到仓库或打标签都不会发布该目录条目。

MCP 注册表

server.json 会将远程 MCP 服务（而非插件）列入 官方 MCP 注册表，名称为 ai.flowlines/flowlines。合并不会发布该服务。其 version 与 MCP 服务的 serverInfo 版本保持一致，每次发布都需要使用新版本。

注册表通过 flowlines.ai 根域名上的 TXT 记录验证 ai.flowlines 名称 （v=MCPv1; k=ed25519; p=<public key>）。使用匹配的私钥登录，然后通过 mcp-publisher 发布：

mcp-publisher validate
mcp-publisher login dns --domain flowlines.ai --private-key "$(openssl pkey -in key.pem -noout -text | grep -A3 'priv:' | tail -n +2 | tr -d ' :\n')"
mcp-publisher publish

历史

这些技能从 flowlines-ai/mcp-server-observability 和 flowlines-ai/coding-assistant-observability 移至此处。

支持

如有疑问或问题，请联系 [email protected]，或在此仓库中提交问题。

许可证

MIT