polylane

Polylane Platform

Polylane 是一个由 Agent 驱动的生产运营平台：它会构建技术栈的实时上下文图谱，从遥测数据中检测问题，使用 Agent 调查问题，并通过可逆操作和经过审核的拉取请求进行修复。

本文介绍流程和约定——不包含目录、架构或限制，这些内容都有实时来源。引用前请先检索。

检索来源

来源	检索方式	用途
Polylane 文档	https://docs.polylane.com — Agent 索引位于 /llms.txt，每个页面的原始 Markdown 位于 /raw/<path>.md	概念、功能行为、架构
文档 MCP	https://docs.polylane.com/mcp — list-pages、get-page（无需身份验证）	相同内容，以工具形式提供
平台 MCP	https://mcp.polylane.com/mcp	实时工作区查询：图谱、遥测数据、代码
CLI 帮助	polylane --help、polylane <resource> <verb> --help	已安装版本的命令范围
API	https://api.polylane.com/v1/reference；polylane api list / api describe <op>	每个 REST 操作及其架构
公共目录	GET /v1/public/integrations/catalog、GET /v1/public/billing/plans（无需身份验证）；GET /v1/scopes（需身份验证）	集成类型、套餐和限制、范围

四步循环

Context ──▶ Detection ──▶ Investigation ──▶ Remediation
(connect)   (find issues)  (root-cause)      (fix + prevent)

每个基本操作都属于其中一个步骤。文档章节也与之对应：/connect、/detect、/investigate（调查和修复）。

概念	一句话说明
工作区	租户单位；以下所有内容均限定在工作区范围内
上下文图谱	节点（资源）+ 类型化边（deploys_to、connects_to、invokes，等等），由云同步和集成填充
问题	一条检测记录（Polylane 检查或提供商告警）；按指纹去重——匹配到未解决的问题时会更新该问题，而过去 24 小时内已解决的问题会重新打开，而不是创建重复项；分诊结论为 Incident / No incident
线程	持久化的 Agent 运行记录；每次调查和聊天都对应一个线程
调查	针对已确认问题的修复运行：一个 Agent 线程会得出结论、追踪原因，并在可修复时创建 PR
自动修复	由 Agent 编写的修复，始终以拉取请求的形式提交，不会直接推送
记忆	保存的已确认发现，会在未来的 Agent 运行中再次呈现

连接技术栈

按以下顺序连接——每个阶段都会解锁下一阶段：

1. 一个云平台 + 一个可观测性工具 → 填充图谱并开始检测。通过目录了解可连接的内容（polylane integration catalog，或 GET /v1/public/integrations/catalog），并在推荐之前检查用户的代码仓库中是否有提供商配置文件。
2. 代码托管平台（GitHub） → 获得 PR 变更情报、代码感知调查和自动修复能力。
3. 聊天工具（Slack） → 触发消息并设置结果接收位置。

连接方式（各提供商的标志：polylane integration connect --help / cloud connect --help）：

• AWS — 创建只读角色的 CloudFormation 堆栈；不会存储密钥。
• GitHub、Sentry、Vercel、Slack — 通过应用安装的浏览器流程。在交互式终端中，CLI 会等待安装完成；使用 --output json、--non-interactive 或没有 TTY 时，CLI 会在打印 URL 后以状态码 0 退出，而不是等到安装完成后退出——之后请确认安装状态。
• 大多数可观测性工具和云平台 — API 令牌。
• 任何 MCP 服务 — 均可作为集成连接；其工具会提供给 Agent 使用。

请验证，不要想当然： 依次运行 integration list、cloud list，然后运行 service list — 资源显示出来就意味着首次同步成功。要从零开始完全由 Agent 引导完成接入（账户 → 工作区 → API 密钥 → MCP → 云平台），请参阅 https://polylane.com/for-agents。

使用 Polylane 调查

无论使用哪种界面，方法都一样（此处展示的是 CLI 命令；平台 MCP 的 runTool 可使用相同功能）：

1. 确定问题 — 是否已标记？使用 issue show <id> 和 issue timeline <id>。只有症状信息？使用 service find "<query>" 查找资源。还没有线索？使用 issue list --active。
2. 先检查发生了哪些变更 — 大多数事件都与变更有关：feed list --category change|release --since 24h。
3. 收集受影响服务的证据 — 使用 service logs <id> --since 1h --grep error、service metrics <id> --since 1h；使用 service graph <id> --direction both 查看影响范围。
4. 关联代码 — 使用 repo grep <repo> "<pattern>"、repo read <repo> <path>。
5. 必要时深入查看固定范围之外的信息 — 使用 tools search "<capability>"，然后运行 tools run <name>，即可执行已连接技术栈所支持的任何提供商原生查询（CloudWatch、Datadog、Honeycomb 等）。
6. 随时记录 — 使用 issue note 记录已采取的措施，在状态变更时使用 issue milestone（“已缓解”），仅将已确认的发现保存到 memory save — 记忆会用于每一次后续运行。
7. 适时交接 — 使用 thread ask "<question>" --context <ids> 将累积的上下文提供给 Polylane 自带的 Agent（ID 按前缀区分类型，详见下文）。

当找到根因或有证据支持的主要假设，并将其记录在问题中后，调查即可结束。

变更前检查生产环境影响

在修改或发布会影响实时系统的代码之前，使用图谱查看即将影响的内容：

1. 将变更关联到生产环境 — 此代码服务于哪些资源？使用 service find "<name>"，或查看仓库的 deploys_to 边（repo show、tools run findNodes）。
2. 查看影响范围 — 使用 service graph <id> --direction inbound，查看所有依赖于你要修改内容的对象。
3. 是否已出现性能下降？ — 使用 issue list --active 并筛选该服务。不要在未解决的事件期间发布任何内容。
4. 还有哪些变更正在进行？ — 使用 feed list --category change|release --since 24h；避免在尚未稳定的部署上叠加变更。
5. 发布时持续监控 — Polylane 的 PR 审查会自动在 PR 上评论生产环境影响（它会遍历 deploys_to 边）。
6. 部署后确认 — 将 service logs / service metrics --since <deploy> 与变更前的基线进行对比，并检查 Feed 中该部署的变更记录。

接口

├─ Terminal / scripts / CI → polylane CLI (see polylane-cli skill)
├─ Coding agent → platform MCP or CLI; wire both with `polylane setup`
├─ Programmatic → REST API (api.polylane.com/v1)
├─ No account yet → `polylane auth signup`, or hand any coding agent
│  https://polylane.com/for-agents to onboard from scratch
└─ Humans → console.polylane.com (every API object carries a _html_url deep link)

Platform MCP：六个工具，触达一切

https://mcp.polylane.com/mcp（streamable HTTP；使用动态客户端注册的 OAuth，或供无头模式使用的 x-api-key）。无论连接了多少内容，它都提供固定的 六个工具（以下五个，另加用于报告服务摩擦问题的 reportFeedback）——它不会为每项能力提供一个 MCP 工具，而是会在 Polylane 后端执行你的代码，在那里绑定了完整功能：

工具	功能
searchTools	发现工作区的 Agent 工具及其架构——与 Polylane 自带 Agent 使用的工具相同（跨所有已连接提供商的可观测性查询、图遍历、代码搜索、部署、审计日志）。请先调用此工具；工具列表会根据你的凭证进行筛选。
runTool	按确切名称运行一个 Agent 工具，参数作为与其架构匹配的嵌套 params 对象传入。
runCode	在后端运行无参数的异步 TypeScript 箭头函数；每个 Agent 工具都可通过 await tools.<name>(args) 调用（使用 tools.__describe(["name"]) 获取类型）。任务需要调用多个工具时，请使用此工具。
search	查询 Polylane OpenAPI 规范（已预先解析 $refs）：使用沙盒全局对象 codemode.spec() 的无参数异步箭头函数。
execute	调用任意 REST 操作：codemode.request({ method, path, query, body })。请先用 search 查找端点。

代码执行为何重要： 串联 N 次工具调用只需一次往返，中间数据（日志行、节点列表、完整规范）会留在后端——只有代码返回的内容才会进入你的上下文，且大型结果会被截断。因此，请在代码中筛选、联接和汇总，并返回摘要：

async () => {
  const types = await tools.__describe(["findNodes"]);  // exact input/output types
  const nodes = await tools.findNodes({ query: "checkout" });
  // ...chain further tools.<name>() calls on the results here...
  return nodes;  // return only what you need in context
}

写入限制： 写入需要 agent_tools:write 作用域，并且需要 x-polylane-allow-writes: true 标头；安全模型无论如何都会审核每次写入，支持 elicitation 的客户端还会请求批准。一个 OAuth 会话可以跨工作区使用——每次调用都传入 workspaceId（ID 或 slug）；API 密钥则绑定到单个工作区——无需传入该参数。

查询时不会告诉你的约定

REST。 列表、获取、修补和删除操作会在路径中传入 workspaceId（/v1/{resource}/{workspaceId}[/{id}]）；创建操作使用 POST /v1/{resource}，并在请求正文中传入 workspaceId，而不是路径中——如果 POST 的路径和请求正文指定了不同的工作区，将返回 403。响应采用封装格式（success、result、error）；超出计划限制时会返回 HTTP 402（application/problem+json），并指出超出的维度。单个对象带有 _html_url（控制台深层链接）和 _links（后续操作）——请遵循 _links，不要猜测路径。

ID 带有类型前缀——根据前缀推断资源类型（CLI 的 --context 可识别 repo_、acc_、thrd_、mem_，并将其他所有内容视为资源节点）：ws_ 工作区、usr_ 用户、thrd_ 线程、iss_ 问题、acc_ 云账户、int_ 集成、repo_ 仓库、mem_ 记忆、fix_ 自动修复、ask_ 升级请求、art_ 工件、sk_ API 密钥。

作用域是 resource:action 格式的字符串（issues:read、agent_tools:write）；通过 GET /v1/scopes 枚举。CLI 的 OAuth 登录默认请求 agent_tools:read 和 agent_tools:write；用于写入工具的 API 密钥必须包含 agent_tools:write。

安全模型（自主程度调节）

1. 默认只读——云账户以只读方式连接；除非工作区管理员关闭只读模式，否则会拒绝写入。
2. 可逆操作——启用后可执行重启、部署回滚等操作。每次写入都会经过安全审核。在 Polylane 内，只有在有人参与的对话轮次中才会执行写入，并且需要明确确认；无人值守的后台运行始终为只读。Platform MCP 的写入需要启用上述选项。
3. 代码须经审核——Agent 绝不会推送到默认分支；修复会通过 CI 和人工批准，以 PR 形式提交。