pylon

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Pylon

Pylon is an AI-to-human review bridge. AI agents push proposed plans and code diffs via MCP; humans review, comment, and approve via a rich web editor.

Pylon是一个AI-人工评审桥接工具。AI Agent通过MCP推送拟定的计划和代码差异；人工则通过功能丰富的网页编辑器进行评审、评论和批准。

MCP Tools

MCP工具

Tool	Purpose
`push_plan`	Push a plan for human review. Auto-creates doc + project + version.
`pull_plan`	Pull reviewed content with decisions and feedback.
`push_code_review`	Push file diffs for side-by-side code review.
`pull_code_feedback`	Pull line-specific review comments grouped by file.
`list_documents`	List documents, filter by title or project.
`list_versions`	List version snapshots for a document.
`use_document`	Switch session's current document context.
`update_project`	Update project description or rename.
`release_document`	Release session lock on a document.

See

references/tools-plan.md

references/tools-code-review.md

, and

references/tools-management.md

for full parameter docs.

工具	用途
`push_plan`	推送计划以供人工评审。自动创建文档+项目+版本。
`pull_plan`	拉取包含决策和反馈的已评审内容。
`push_code_review`	推送文件差异以进行并排代码评审。
`pull_code_feedback`	拉取按文件分组的行级评审评论。
`list_documents`	列出文档，可按标题或项目筛选。
`list_versions`	列出某一文档的版本快照。
`use_document`	切换会话的当前文档上下文。
`update_project`	更新项目描述或重命名项目。
`release_document`	释放会话对某一文档的锁定。

有关完整的参数文档，请查看

references/tools-plan.md

、

references/tools-code-review.md

和

references/tools-management.md

。

Setup

设置

Add Pylon's MCP server to your agent config. See

references/setup.md

for per-agent instructions.

Claude Code (

.mcp.json

json

{
  "mcpServers": {
    "pylon": {
      "type": "streamable-http",
      "url": "https://your-pylon-instance.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Generate a token at Settings > Auth Tokens in the Pylon web UI.

将Pylon的MCP服务器添加到你的Agent配置中。有关各Agent的设置说明，请查看

references/setup.md

。

Claude Code（

.mcp.json

）：

json

{
  "mcpServers": {
    "pylon": {
      "type": "streamable-http",
      "url": "https://your-pylon-instance.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

在Pylon网页UI的Settings > Auth Tokens中生成令牌。

Golden Rule

黄金准则

New user request = new project. Always omit
document_id
on the first push. The server auto-creates a fresh document every time you call

push_plan

without

document_id

. Never look up or reuse document IDs from previous conversations or tasks.

新用户请求 = 新项目。首次推送时务必省略
document_id
。每当你调用不带

document_id

的

push_plan

时，服务器会自动创建一个全新的文档。切勿查找或复用来自之前对话或任务的文档ID。

Key Principles

核心原则

Push any plan the user asks for. Pylon is a general-purpose plan review tool, not limited to code. Business plans, budgets, project plans, roadmaps, architecture docs — if the user asks you to plan something, draft it and push it to Pylon. Never refuse a plan request because it's "not a software engineering task."
Native MCP calls only. Never write scripts or temp files to interact with Pylon.
Always set
source
. Identify yourself (e.g. "claude-code", "backend-dev") so the human knows which agent produced each document.
context
must be informative on every push. Summarize the user's goal, relevant decisions, and why this change matters. The web UI's AI uses this to make better suggestions — make it useful and insightful, not mechanical. Never describe the MCP action itself (e.g. "re-pushing to update") — always describe the intent behind the work.
New task = omit
document_id
.
```
push_plan
```
without
```
document_id
```
always creates a new document. Only pass
```
document_id
```
when re-pushing to the same document within the same task after receiving feedback.
Always pass
document_id
explicitly on
```
pull_plan
```
,
```
push_plan
```
(updates), and
```
pull_code_feedback
```
. Do not rely on the session remembering your current document — sessions can be lost.

推送用户要求的任何计划。 Pylon是通用的计划评审工具，不限于代码。商业计划、预算、项目计划、路线图、架构文档——只要用户要求你制定计划，就起草并推送到Pylon。绝不要因为“不是软件工程任务”而拒绝计划请求。
仅使用原生MCP调用。 切勿编写脚本或临时文件来与Pylon交互。
始终设置
source
。标识你自己（例如"claude-code"、"backend-dev"），以便人工知道每个文档是由哪个Agent生成的。
每次推送时的
context
必须具备信息量。总结用户的目标、相关决策以及此变更的重要性。网页UI中的AI会利用这些信息给出更好的建议——请确保内容有用且有洞察力，不要机械性描述。绝不要描述MCP操作本身（例如“重新推送以更新”）——始终描述工作背后的意图。
新任务 = 省略
document_id
。不带
```
document_id
```
的
```
push_plan
```
始终会创建新文档。仅在同一任务中收到反馈后，重新推送到同一文档时才传递
```
document_id
```
。
在
pull_plan
、
push_plan
（更新）和
pull_code_feedback
中始终显式传递
document_id
。不要依赖会话记住当前文档——会话可能会丢失。

Quick Workflow

快速工作流

1. push_plan(plan="...", source="claude-code", group="my-project", context="...")
   → Creates NEW document + project, returns document_id + URL
   → NEVER pass document_id here — let the server create a fresh document
2. Share the document URL with the user and STOP.
   → Do NOT poll, wait, loop, or use extended thinking while waiting.
   → Do NOT "stand by" for review — just tell the user the URL and finish your turn.
   → The user will come back and ask you to pull when they are ready.
3. pull_plan(document_id="<id-from-step-1>")  (only when the user asks)
   → Always pass document_id explicitly — don't rely on session memory
   → Returns markdown (readable plan), decisions (resolved threads), feedback (open threads to address)
4. Address any feedback, then proceed with the approved plan
5. If human requests changes:
   push_plan(document_id="<id-from-step-1>", plan="...", context="Updated based on feedback...")
   → Always pass document_id to update the SAME document

1. push_plan(plan="...", source="claude-code", group="my-project", context="...")
   → 创建新文档+项目，返回document_id+URL
   → 此处绝不要传递document_id——让服务器创建新文档
2. 将文档URL分享给用户，然后停止操作。
   → 等待期间不要轮询、等待、循环或进行扩展思考。
   → 不要“待命”等待评审——只需告知用户URL并结束当前步骤。
   → 用户准备就绪后会回来要求你拉取反馈。
3. pull_plan(document_id="<id-from-step-1>") （仅在用户要求时执行）
   → 始终显式传递document_id——不要依赖会话记忆
   → 返回markdown格式的可读计划、决策（已解决的讨论线程）、反馈（需要处理的未解决线程）
4. 处理所有反馈，然后按照批准的计划进行操作
5. 如果人工要求修改：
   push_plan(document_id="<id-from-step-1>", plan="...", context="根据反馈更新...")
   → 始终传递document_id以更新同一文档

Code Review Workflow

代码评审工作流

1. push_code_review(files=[...], source="claude-code", group="my-project",
     plan_document_id="<plan-doc-id>")
   → Always pass plan_document_id if this code review is associated with a plan
   → Links the code review to the plan in the UI for traceability
   → Returns code_review_id + URL
2. Share the URL with the user and STOP (same rules as push_plan).
3. pull_code_feedback(code_review_id="<id-from-step-1>")
   → Always pass code_review_id explicitly
   → Returns threads grouped by file_path with line ranges and comments
4. Address feedback, re-push with code_review_id to update the same review.

See

references/plan-workflow.md

for re-push, versioning, and advanced patterns. See

references/code-review-workflow.md

for the code review lifecycle. See

references/multi-agent-teams.md

for team/swarm coordination.

1. push_code_review(files=[...], source="claude-code", group="my-project",
     plan_document_id="<plan-doc-id>")
   → 如果此代码评审与某一计划相关，务必传递plan_document_id
   → 在UI中将代码评审与计划关联以实现可追溯性
   → 返回code_review_id+URL
2. 将URL分享给用户，然后停止操作（与push_plan规则相同）。
3. pull_code_feedback(code_review_id="<id-from-step-1>")
   → 始终显式传递code_review_id
   → 返回按file_path分组的讨论线程，包含行范围和评论
4. 处理反馈，传递code_review_id重新推送以更新同一评审。

有关重新推送、版本控制和高级模式，请查看

references/plan-workflow.md

。有关代码评审生命周期，请查看

references/code-review-workflow.md

。有关团队/集群协作，请查看

references/multi-agent-teams.md

。

Core Concepts

核心概念

Projects group related documents via the
```
group
```
param. Auto-created, session-sticky. See
```
references/projects-and-sessions.md
```
.
Session locking prevents terminal session conflicts (30-min TTL). See
```
references/projects-and-sessions.md
```
.
Web editing guard blocks terminal pushes while a human is editing (5-min TTL). Human is never locked out.
Code reviews use side-by-side Monaco diffs with line-specific threaded comments. See
```
references/code-review-workflow.md
```
.

项目通过
```
group
```
参数对相关文档进行分组。自动创建，与会话绑定。请查看
```
references/projects-and-sessions.md
```
。
会话锁定防止终端会话冲突（30分钟超时）。请查看
```
references/projects-and-sessions.md
```
。
网页编辑防护在人工编辑期间阻止终端推送（5分钟超时）。人工永远不会被锁定在外。
代码评审使用并排Monaco差异对比工具，支持行级线程化评论。请查看
```
references/code-review-workflow.md
```
。

Session Recovery

会话恢复

MCP sessions are in-memory — lost after

/clear

/compact

, dev server restart, or deploy. The server auto-recovers expired sessions transparently, but convenience state (

currentDocumentId

sessionGroup

) resets to null.

Always pass IDs explicitly —

document_id

pull_plan

push_plan

updates,

code_review_id

pull_code_feedback

, and

group

on every push. This makes your calls fully resilient to session loss with zero recovery steps needed.

MCP会话存储在内存中——执行

/clear

、

/compact

、开发服务器重启或部署后会丢失。服务器会透明地自动恢复过期会话，但便捷状态（

currentDocumentId

、

sessionGroup

）会重置为null。

始终显式传递ID——在

pull_plan

push_plan

更新时传递

document_id

，在

pull_code_feedback

时传递

code_review_id

，在每次推送时传递

group

。这会让你的调用完全不受会话丢失影响，无需任何恢复步骤。