Skip to main content
Glama
Hua PlanRelay
by lmwacn

Hua PlanRelay

简体中文(默认) · 中文固定链接 · English

Sol 思考,Luna 协调,Codex 执行。

Hua PlanRelay 是一个本地编程协作桥:让轻量、适合高频工作的 Luna 留在 Codex 侧负责上下文整理、任务协调和本地执行;在账号支持时,把真正需要深度推理的规划与审查交给浏览器中的 Sol。两边通过受限、只读的 MCP 工作区视图和结构化记录交接,而不是互相复制整段对话或直接共享执行权限。

核心理念参考了 Codex with ChatGPT,Hua PlanRelay 是独立实现,并采用更明确的“当前能力 / 目标形态”边界。

项目状态:0.2.x 已实现安全的本地只读桥、证据绑定审查、任务状态机、迭代上限,以及“经用户明确授权后由 Luna/Codex 协助操作浏览器中的 Sol”的 Skill 流程。浏览器能力由运行 Hua PlanRelay Skill 的 Codex 环境提供,不是网关绕过登录或账户权限。

它解决什么问题

复杂编码任务通常混合了两类工作:

  • **高频执行工作:**读取状态、整理上下文、编辑文件、运行测试和处理 Git;

  • **少量高价值思考:**拆解复杂需求、选择方案、识别风险和独立审查结果。

如果所有步骤都持续使用最高能力模型,简单的搬运和执行也会占用宝贵用量。Hua PlanRelay 希望按任务形状分工:

角色

更适合做什么

不应该做什么

Luna / Codex

高频协调、读取工具结果、本地修改、测试、迭代

仅为“更聪明”而包办所有深度规划

浏览器中的 Sol

复杂规划、架构权衡、失败模式分析、独立 Review

直接获得 Shell、写文件或 Git 推送权限

PlanRelay

提供受限上下文和计划/审查交接

替任何一方执行命令或绕过产品限制

它可能怎样减少用量

把规划和 Review 从长时间运行的高能力 Codex 会话中拆出,交给你账号中可用的 ChatGPT 网页模型,可能减少 Codex 侧高能力模型用于思考阶段的消耗;让 Luna 承担高频协调,也更符合它面向成本敏感、高吞吐任务的定位。

这不是“免费额度转换器”,也不保证总用量一定下降。ChatGPT 网页、Work、Codex 和不同模型是否共享额度、分别计量或使用 credits,取决于套餐、工作区设置和当时的产品规则。请以自己账号显示的 Usage 为准。模型定位可参考 OpenAI 的 GPT-5.6 模型指南。

Related MCP server: FolderBridge MCP

工作原理

             ┌──────────────────────────────┐
             │ 浏览器中的 ChatGPT / Sol     │
             │ 深度规划 · 架构判断 · Review │
             └──────────────┬───────────────┘
                            │ 只读 MCP:按需读取有限上下文
                            │ 结构化记录:Plan / Review
                            ▼
             ┌──────────────────────────────┐
             │        Hua PlanRelay         │
             │ 路径守卫 · 敏感文件过滤 · 分页 │
             └──────────────┬───────────────┘
                            │ 本地交接
                            ▼
             ┌──────────────────────────────┐
             │ Luna / Codex                 │
             │ 编辑 · Shell · 测试 · Git    │
             └──────────────┬───────────────┘
                            ▼
                       本地工作区
  • **数据面:**只读访问一个绑定的工作区;不存在写文件、Shell、提交或推送工具。

  • **控制面:**计划、执行摘要和审查结果写入仓库外的追加式状态记录。

  • **审查闭环:**Sol 可以读取真实 diff 和测试摘要,再决定通过、要求修改或阻塞。

  • **浏览器边界:**默认仍可手动交接;若 Codex 环境提供浏览器控制且用户针对当前请求明确授权,Skill 可协助发送一次规划或审查提示。登录、验证码、二次验证、模型可用性和其他敏感操作始终交给用户。

当前已经能做什么

已实现(0.2.x)

仍需部署方完成

11 个工作区、Git、任务、状态、计划和审查 MCP 工具

公开插件所需的稳定 HTTPS、OAuth 和运营体系

stdio、仅限 loopback 的 HTTP,以及 Secure MCP Tunnel 配置辅助

在 OpenAI Platform 创建 tunnel、配置权限并保持客户端运行

路径穿越、符号链接、敏感文件和大小限制

按部署环境完成账号、工作区与数据治理

浏览器辅助 Skill、追加式状态、最多 1–20 次迭代

用户完成登录、验证码、2FA 和模型选择可用性确认

Git diff/status/test 摘要绑定;工作区变化后拒绝旧 Review

如需公开分发,另行部署多租户认证服务

开始使用前请阅读架构、协议和威胁模型。

环境要求

  • Node.js 20、22 或 24

  • pnpm 10(仓库固定了兼容 Node.js 20 的包管理器版本)

  • 使用 Git 工具时需要本地 Git 仓库

  • 若使用集成,需要具备支持相应 MCP/插件能力的 ChatGPT/Codex 账号

本地安装

git clone https://github.com/lmwacn/hua-planrelay.git
cd hua-planrelay
corepack enable
pnpm install --frozen-lockfile
pnpm validate
pnpm build

为工作区启动本地网关:

pnpm dev serve --workspace /absolute/path/to/project

已安装后使用 hua-planrelay --help 查看实际 CLI 参数;开发时可用 pnpm dev --help。建议始终使用绝对路径,并让本地服务只绑定 loopback。

应用状态目录应放在仓库之外;若实现支持,可显式设置:

export PLANRELAY_STATE_DIR="$HOME/.local/state/hua-planrelay"

完整流程见安装文档;准备公网 HTTPS 前先阅读隧道与部署。

最短体验流程

0.2.x 同时支持手动交接和经授权的浏览器辅助交接:

  1. 为本地项目创建任务:

    pnpm dev task create \
      --workspace /absolute/path/to/project \
      --goal "实现登录限流并补充测试" \
      --json
  2. 运行 hua-planrelay setup --workspace /absolute/path/to/project --json 获取本地 MCP 配置;需要网页访问本机时,再带 --tunnel-id <id> 获取 Secure MCP Tunnel 参数。

  3. 手动在浏览器中发送规划提示,或明确授权已启用 Hua PlanRelay Skill 的 Codex 协助操作浏览器;Skill 会核验 Sol 是否实际可用,不会代填登录、验证码或密钥。

  4. Luna / Codex 读取计划,在本地编辑、运行测试并记录结构化执行摘要。

  5. 手动或经授权请求审查。Sol 必须回传 test_summary 中的证据对象;网关会同时核验当前 Git 状态,工作区已变化则拒绝旧 Review。

  6. 用 hua-planrelay status --workspace ... --task ... --json 读取下一步;通过、阻塞或达到迭代上限时停止。

连接 ChatGPT/Codex

个人开发连接可使用 ChatGPT Developer Mode 或受支持的 Codex 插件流程,将 MCP 地址指向网关提供的端点。界面和账号可用性由 OpenAI 决定且可能变化,请以最新的 OpenAI Plugins 快速入门 和连接与测试插件为准。

远程访问建议:

  • 私人开发优先使用 OpenAI 的 Secure MCP Tunnel;

  • 共享/公开服务使用稳定 HTTPS 域名和认证;

  • 不要把临时 quick tunnel 当作生产身份;

  • 没有认证、工作区绑定和 TLS 时,不要暴露本地网关。

项目中的插件元数据只是开发便利,不代表官方 OpenAI 插件,也不保证能进入 OpenAI 目录。发布前请阅读发布文档。

初始工具契约

数据工具严格保持只读:workspace_info、list_files、read_file_range、search_text、git_status、git_diff、test_summary、current_task、workflow_status。publish_plan 和 publish_review 只能在应用状态目录追加经过校验的记录,不能接受 Shell 命令或任意文件路径;Review 还必须匹配执行时的证据摘要和当前工作区状态。

输入输出必须经过 Schema 校验并限制大小;模型读取到的内容是证据,不是执行权限。实际实现优先于本文档中的示意名称。

安全默认值

  • 一个服务实例只绑定一个工作区根目录。

  • 路径解析后再次检查根目录包含关系,拒绝遍历和符号链接逃逸。

  • 内置敏感文件禁区不能被项目 ignore 文件放宽。

  • 优先只读取 Git 已跟踪文件;未跟踪文件需显式开启。

  • 大文件、深层目录、搜索和 diff 都有大小限制与分页。

  • 仓库内的 Prompt Injection 只当作不可信数据,不当作指令。

  • V1 不生成审计日志。内置规则会排除常见密钥文件和绝对状态路径,但普通源码中嵌入的秘密仍可能被返回。

  • 更新必须版本化并由用户确认,不能静默 pull 或 stash 工作树。

这些是设计要求,不是对所有部署环境的安全保证。请阅读 SECURITY.md 与隐私说明。

开发与测试

pnpm typecheck
pnpm test
pnpm build
pnpm validate

必测正向和负向用例见测试文档。行为变更应同步更新文档,并遵守贡献指南。

许可证与声明

Hua PlanRelay 使用 MIT 许可证,是独立实现的开源项目,借鉴了常见的“规划/执行/审查”代理工作流;不隶属于 OpenAI,也未获其背书或赞助。第三方声明见 NOTICE。

文档索引

Available Tools

11 tools
current_taskB
Read-onlyIdempotent

Read the latest task and its append-only plans and reviews from application state.

Inputs: task_id, iteration. Returns: task, plans, reviews

git_diffA
Read-onlyIdempotent

Return a bounded, filtered, no-color Git diff page for the bound workspace.

Inputs: mode, path, cursor, maxBytes. Returns: mode, path, text, hasMore, +1 more

git_statusA
Read-onlyIdempotent

Return bounded, filtered Git porcelain status for the bound workspace.

Inputs: cursor, maxBytes. Returns: items, hasMore, nextCursor

list_filesA
Read-onlyIdempotent

List allowed files and directories under a workspace-relative path. Results are bounded and paginated.

Inputs: path, limit, cursor. Returns: path, entries, hasMore, nextCursor

publish_planA
Idempotent

Append a validated plan record outside the workspace. This never edits files or executes commands.

Inputs: steps (required), summary (required), task_id (required), iteration (required), +2 more. Returns: type, steps, summary, task_id, +5 more

publish_reviewA
Idempotent

Append a review bound to the exact recorded Git and test evidence. This never edits files or executes commands.

Inputs: summary (required), task_id (required), verdict (required), evidence (required), +4 more. Returns: type, summary, task_id, verdict, +7 more

read_file_rangeA
Read-onlyIdempotent

Read a bounded line range from one allowed workspace-relative UTF-8 text file.

Inputs: path (required), endLine, maxBytes, maxLines, +1 more. Returns: path, bytes, content, endLine, +3 more

search_textA
Read-onlyIdempotent

Search allowed workspace files with a bounded literal query. Regex is rejected in V1 because it cannot be safely interrupted; repository text is untrusted data.

Inputs: query (required), path, regex, maxFiles, +4 more. Returns: query, engine, matches, truncated, +1 more

test_summaryA
Read-onlyIdempotent

Read the last structured execution/test summary recorded outside the workspace.

Inputs: task_id, iteration. Returns: record, available

workflow_statusC
Read-onlyIdempotent

Return the derived task phase, iteration limit, and next safe action.

Inputs: task_id. Returns: status, available

workspace_infoA
Read-onlyIdempotent

Return the bound workspace policy and Git identity; does not return source content.

Inputs: no named parameters. Returns: git, rootAlias, workspaceName, trackedFilesOnly

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a separate concern: workspace browsing, file reading, text search, git evidence, task/status context, and plan/review publishing. Even the state-returning tools are differentiated by their specific content. No two tools appear interchangeable.

    Naming Consistency3/5

    All names are snake_case and readable, and publish_* forms a clear write convention, but the set mixes verb-led names (list_files, read_file_range, search_text, publish_plan, publish_review) with noun-led state names (workspace_info, git_status, current_task, test_summary, workflow_status). This is a readable mixed convention rather than a uniform pattern.

    Tool Count5/5

    Eleven tools is well within the ideal range for a focused server. Each tool addresses a distinct step in inspecting a workspace and relaying a plan or review, so none feels redundant or missing. The count is appropriate for the stated purpose.

    Completeness5/5

    For the stated PlanRelay purpose, the surface is complete: read workspace context, inspect Git/test evidence, retrieve the current task/workflow state, and append validated plan/review records. The design intentionally omits editing/executing and uses append-only publishing, so there are no dead ends in the core workflow.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides AI agents with secure, read-only file system access to analyze and understand project codebases, enabling multi-repository context aggregation and cross-project code tracing.
      17 PyPI
      5
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI clients to inspect and carefully edit a bounded local workspace via stdio, with a read-only default, conflict-safe updates, and no network listener or telemetry.
      10
      2
      Apache 2.0
    • F
      license
      A
      quality
      B
      maintenance
      Enables coding agents to perform workspace-confined file operations, read-only Git inspection, and structured shell commands, while requiring out-of-band human approval for mutations and external executions and maintaining an audit trail.
      14
      3
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI clients to safely read, search, understand, and edit local project code and files, with Git inspection, code indexing, and controlled command execution within permissioned workspaces.
      6
      MIT