【免费下载链接】plannotatorAnnotate and review coding agent plans and code diffs visually, share with your team, send feedback to agents with one click.项目地址https://gitcode.com/gh_mirrors/pl/plannotator点击查看免费下载导读本文是 Plannotator 团队对flue/runtimeApache-2.0TypeScript agent-harness 框架的一次技术适配评估实录核心回答一个问题能否把 Flue 作为继 claude / codex / cursor / opencode / pi / copilot 之后的又一 agent-job provider 接入 Plannotator 的 Agent Jobs 引擎。评估结论可概括为两条主线以「spawned job provider」形态接入Shape A可行但有真实成本以「Ask-AI 会话型 provider」接入Shape B在当前版本下不可行。读完本文你将掌握这次评估的方法论、决定性事实依据、集成草图嵌入式 Flue 项目 SERVER_BUILT_PROVIDERS新 provider buildCommand接线以及团队给出的「暂不采纳」建议与三条触发重新评估的条件。Flue 是什么以及不是什么Flue 是一个 TypeScriptagent-harness 框架评估对象为flue/runtime1.0.0-beta.1Apache-2.0位于/Users/ramos/oss-agents/flue。评估方法为「广度浅潜 三份深潜子报告」运行时执行模型、CLI 无头调用、SDK/HTTP 面与运维。Flue 的定位决定了整份评估的走向你用代码来创作 agent / workflowcreateAgent、valibot 类型化的 tools/skills、sandboxflueCLI 通过 Vite codegen 把 agent 构建成一个Hono 服务器Flue 自带的执行循环基于earendil-works/pi-agent-core/pi-ai直接调用模型 API。因此它不是claude / codex / cursor / opencode 这类 coding-agent CLI——不存在一个可委托的第三方 agent。采纳 Flue 意味着 Plannotator 需要自己编写并长期维护一个小型 agent一个 workflow、一份 agent 定义、prompt 组装、只读工具策略都成为 Plannotator 代码的一部分。评估结论总览Shape Aspawned job provider可行但有真实成本。Shape BAsk-AI session provider当前版本不可行。这一结论建立在 Plannotator 现有的 Agent Jobs 引擎之上。当前服务端的 provider 注册表SERVER_BUILT_PROVIDERS只包含claude、codex、tour、guide、cursor、opencode、pi、copilot八个 provider见 agent-jobs.ts——「claude 等第三方 CLI 自带 agent 行为Plannotator 只负责 spawn」是现有 provider 的共同前提而 Flue 要求反过来agent 行为由 Plannotator 自己维护。这正是 Shape A「可行但成本真实」的根源。Shape A 支持性事实四条决定性证据1. 真正的 one-shot 运行存在flue run workflow --target node --payload {...}会完成「构建 → 运行到结束 → 向 stdout 打印一个干净 JSON blobworkflow 的返回值」的完整链路进度信息走 stderr退出码为 0 / 1 / 130 / 143。该行为由 Flue 源码bin/flue.ts:1361-1404与官方 GitHub Actions 部署文档交叉印证。这与 Plannotator 现有 job 语义天然吻合job 的生命周期starting → running → done/failed/killed由AgentJobStatus状态机定义见 packages/core/agent-jobs.ts一个「退出码 单块 JSON」的子进程契约可以直接映射进去。2. 同类最佳的结构化输出session.prompt(text, { result: valibot schema })是 Flue 最突出的能力从 schema自动注入finish/give_up工具用原始 schema 校验模型输出把校验失败信息回喂给模型重试实现位于 Flue 的result.ts:159-303。评估者将它与 Plannotator 现状做了直接对比比 claude 的--json-schema更强远强于我们目前的 nonce marker 契约无需 marker 回退。这里的「nonce marker 契约」在仓库中有完整实现可对照packages/server/guide/guide-review.ts中的buildGuideMarkerOutputContract(nonce)以 prose 示例描述输出形状并用markerOpen(nonce)/markerClose(nonce)包裹唯一的 JSON 块解析时靠extractMarkerNonce()从job.prompt恢复 nonce见 guide-review.ts。对 Cursor / OpenCode / Pi 这类无 schema flag 的引擎marker 是「唯一的」结构化输出途径而 Flue 的 schema 原生验证可以省掉整个 marker 恢复管线。3. 任意仓库工作目录已确认local({ cwd })能把 bash / read / write / edit / grep / glob 绑定到任意绝对路径且使用真实的child_process语义abort / timeout 时按进程组 kill。环境变量采用白名单制——secrets 必须显式转发。这与 Plannotator 的 review/annotate 工作目录模型兼容job 需要cwdAgentJobInfo.cwd字段与 diff/工作区快照语义。4. 实时日志可以直接透传Plannotator 的 jobs 引擎已经会把子进程 stderr 流式广播为job:logSSE 事件。在服务端实现中stderr 以管道方式被读取、按行/块格式化后broadcast({ type: job:log, jobId: id, delta })同时保留最近 ~500 字符的 stderr 尾部用于失败诊断见 packages/server/agent-jobs.ts事件类型定义在 packages/core/agent-jobs.tssnapshot/job:started/job:updated/job:completed/job:log/jobs:cleared含 30s 心跳注释。Flue 的 ANSI 进度文本今天就能流过这条管道需要 ANSI 剥离但它是非 NDJSON的因此没有结构化日志事件——除非走两进程的flue logs --format ndjson舞蹈先 spawn 服务器再查询。另外Apache-2.0 许可无 telemetry / 无 phone-home是低风险依赖项。Shape A 的成本与反对点六条要买账的账目我们成为 agent 作者。嵌入式 Flue 项目一个 workflow、一个 agent 定义、prompt 组装、只读工具策略变成 Plannotator 代码——而现有 provider 的 agent 行为随第三方 CLI 一起交付。这是最主要的隐性维护成本。认证回退。pi-ai 从环境变量读取裸 API keyANTHROPIC_API_KEY等或优先使用ANTHROPIC_OAUTH_TOKEN。没有任何代码路径借用用户已登录的 Claude Code / Codex CLI 凭据。现有 provider 骑乘既有 CLI 登录态Flue provider 则要求用户管理 key或我们在自己侧做脆弱的 token 抽取。运行时 分发负担。需要 Node ≥ 22.18且Bun 被明确拒绝对 spawn 场景无碍但新增了一个用户机器依赖嵌入式项目需要安装 node_modules 并做 Vite 构建每次flue run都会重建——可通过安装期预构建、随后 spawnnode dist/server.mjs 一次POST /workflows/:name?waitresult来规避。先例已存在plannotator install-runtime agent-terminal已经在管理 Node 运行时安装见 agent-terminal-runtime.ts由scripts/install.sh执行Flue 运行时可以套用同一套安装-校验-提示机制。只读强制是自定义工作。Flue 没有禁用 write/edit/bash 的 flag需要自定义SandboxFactory.tools用defineTool()重实现 read/grep/glob——因为Flue 自己的工具实现不对外导出。而「只读工具策略」恰恰是 Plannotator 作为代码评审工具的核心约束。Beta 变动。1.0.0-beta.12026-06-16紧跟在快速破坏性演进的 0.x 之后进程内嵌入缝隙createFlueContext被显式标记为 internal。模型目录缺失。没有flue models我们需要对照 pi-ai 的模型目录自行维护一份列表。对比之下Plannotator 的能力探测已支持 provider 自报模型目录AgentCapability.models目前仅 Cursor 实现见 packages/core/agent-jobs.tsFlue 需要手工补齐。Shape B 为什么今天不可行四条硬性理由Shape B把 Flue 当作 Ask-AI 会话型 provider即类似当前交互式 agent 会话的模式被否决理由全部指向运行时架构不匹配flue/sdk是 HTTP 客户端指向 Flue 自有服务器不是可嵌入的运行时会话构造 API 位于flue/runtime/internal被标记为「never import from here」——没有受支持的嵌入缝隙。没有工具权限 / human-in-the-loop 钩子工具事件只是观察性的Plannotator 现有的交互式审批提示approval prompts没有对应物。HTTP 上无服务端 abort断开连接不会停止运行durable admission 是设计使然——这直接与 Plannotator 的 job 生命周期管理kill、超时、进程组终止冲突。examples/pi-provider-chat与我们无关它演示的是 pi-ai 的 OAuth 模型 provider与本项目的 Pi 集成不是一回事不能作为可复用样例。如果要做最小集成草图评估文档给出了一个可执行的接入方案若未来条件成熟嵌入式项目packages/server/flue-provider/包含flue.config.ts与一个workflows/run-job.ts入参{ prompt, repoPath, schemaKind }agent 使用local({ cwd: repoPath }) 策划过的只读工具集安装期构建。新 provider在SERVER_BUILT_PROVIDERS中注册flue能力门槛 Node ≥ 22.18 已构建项目存在 配置了 API key / OAuth token。这与现有能力探测模型一致providers 在构造期探测一次、首次/capabilities请求时惰性执行见 packages/server/agent-jobs.ts避免慢 CLI 冻结请求路径。buildCommand接线每个 job spawn 预构建的node dist/server.mjs临时端口POST /workflows/run-job?waitresultv1 也可容忍flue run的重建成本解析 stdout JSON、stderr 进日志。这与现有buildCommand接口服务端构建要 spawn 的命令拒绝则回退到前端提供命令见 packages/server/agent-jobs.ts完全吻合。复用输出管线guide / tour / review 的 schema 直接作为 workflow 的 valibotresultschema 传入——一条输出管线无 marker 解析。建议暂不采纳保留观察哨评估的最终建议是今天不值得把 Flue 作为 claude / codex / cursor / opencode 的平级 provider 采纳。原因权重排序如下认证模型裸 API key vs. 骑乘用户 CLI 登录态与author-your-own-agent 的维护负担压过了结构化输出的收益预 1.0 的 API 仍在变动稳定性不足以保证长期承诺。评估同时给出了三条重新评估的触发条件满足其一即可 revisitFlue 发布公开的 one-shot / embedding API或带机器可读事件输出的稳定flue runpi-ai 增长「从已安装 CLI 借用凭据」的能力Plannotator 足够想要一个完全自有的、schema 原生的 job agent愿意为此供养维护成本——届时Flue 是目前评估过的最强 harness 候选。对于正在规划 Plannotator provider 矩阵的工程师这份评估的可迁移价值在于它示范了「第三方 agent 框架适配」的完整决策框架——先确认 one-shot 契约与结构化输出能力再核对认证继承、只读强制、运行时分发与嵌入缝隙最后用「接入成本 vs. 收益」做取舍而不是被单一亮点如 valibot 结构化输出牵着走。参考路径速查Provider 注册表packages/server/agent-jobs.tsJob 状态机与 SSE 事件类型packages/core/agent-jobs.tsstderr 流式job:log广播与错误尾部捕获packages/server/agent-jobs.ts能力探测与模型目录packages/core/agent-jobs.tsNode 运行时安装先例install-runtime agent-terminalpackages/server/agent-terminal-runtime.ts现有 nonce marker 输出契约Flue valibot schema 的对照物packages/server/guide/guide-review.ts赞分享【免费下载链接】plannotatorAnnotate and review coding agent plans and code diffs visually, share with your team, send feedback to agents with one click.项目地址https://gitcode.com/gh_mirrors/pl/plannotator点击查看免费下载相关推荐将可观测性内置于 Harness为 AI Agent 构建可诊断的运行时与可复现的评估体系将可观测性内置于 Harness为 AI Agent 构建可诊断的运行时与可复现的评估体系 导读 本文以 learn harness engineeringFlue 集成 vitest-evals为 Agent 建立基于 HTTP 边界的可复现评估体系Flue 集成 vitest evals为 Agent 建立基于 HTTP 边界的可复现评估体系 本指南以 Flue 官方文档 Vitest Evals 生态人工智能大模型AI AgentAgent 框架工具调用Agent 沙箱MCP ClientsFlue 集成 vitest-evals为 HTTP Agent 构建真实模型评估体系Flue 集成 vitest evals为 HTTP Agent 构建真实模型评估体系 导读 本文以 blueprints/tooling vitest ev人工智能大模型AI AgentAgent 框架工具调用Agent 沙箱MCP Clients上一篇用 AGENTS.md 搭建 Agent-First 仓库learn-harness-engineering 的 OpenAI 高级路由模板实战指南下一篇legacy-rocm-build 安装文档中的 Rocky Linux 版本选择器实现原理与在 ROCm 安装指南中的实战应用创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考