在编辑器里"写"agent：Glean 把 agent 构建搬进 Claude Code / Cursor / Codex

一句话：agent 终于也有了"代码优先"的构建方式

2026 年 10 月 21 日，企业 AI 搜索与 agent 平台 Glean 宣布 headless agent building 正式 GA（全面可用）：开发者可以直接在 Claude Code、Cursor、Codex 这些编码环境里，用写代码的方式定义、测试、评估和发布 agent——agent 本人变成一组文件（spec.yaml + instructions.md），进 Git、走 PR 评审、出了问题直接回滚。

而运行这些 agent 的，依然是 Glean 的托管运行时：知识图谱、275+ 企业数据源的权限管控、完整的审计轨迹，一样不少。Glean 的说法是：给你代码优先的灵活性，但不用你自己重建企业级的上下文与治理底座。

工作流：四步，从文件到生产

根据 Glean 官方博客和文档，整套流程长这样：

1. 定义为文件（Define as files）。装好 Glean 插件后，在当前工作区创建一个 agent，实际就是生成一个文件夹（默认在 .glean/agents/ 下）：spec.yaml 放配置（含 agent id）、instructions.md 放行为描述，还可以挂 skills/ 和 subagents/。文档特别警告：不要手改 spec.yaml 里的 id——它是文件夹与 Glean 线上 agent 的关联键。

2. 本地测试与评估（Test & evaluate）。直接在编码环境里用代表性输入跑 agent、看输出、跑评估（evals），根据结果迭代 instructions 和配置，反馈环路紧贴代码。构建者还能监控运行进度、检查输出。

3. 评审与回滚（Review & rollback）。改动可以在 coding assistant 里评审，也可以走 Git PR。某次改动效果不好？回滚就是一次 git 操作——这是"agent 即代码"最实在的红利。

4. 发布到 Glean（Publish）。agent 成熟后发布到 Glean（而不是某个自建 runtime），团队分享链接即可。发布后的 agent 跑在托管运行时上，管理员可以在 Glean 控制台分享、管理或停用。

图：headless agent building 工作流。内容整理自 Glean 官方博客与文档。

几个值得注意的产品细节：

• 双轨并存：偏好自然语言/可视化低代码画布的用户可以继续用原来的 agent builder；headless 目前只支持 Auto mode agent，Workflow mode 仍需可视化构建器；
• 三家环境的安装各不相同：Claude Code 走 gleanwork/claude-plugins marketplace 装 glean@glean-plugins；Codex 走终端命令加 gleanwork/codex-plugins；Cursor 在 Settings 的 Marketplace 里搜 Glean；装完用工作邮箱 + Glean OAuth 绑定公司实例；
• 没有 MCP server：文档明确说这条流程只走插件的 /glean_run 聊天命令（Codex 里写作 $glean_run），不要拿 Glean MCP server 或它的 tools 来替代，也不要复用 beta 时期的 marketplace/插件名——看得出 Glean 在刻意收敛入口，避免生态碎片化。

官方示例：一个客服 escalation agent 的诞生

Glean 在博客里走了一遍完整示例：一位客服工程师想尽早发现紧急升级工单。他在 Codex 里让 Glean 创建一个 agent：从 Slack 和 Intercom 汇总客服对话、提炼紧急事项。然后细化 instructions、用真实客服场景测试、跑评估找短板。结果满意后发布到 Glean、分享给团队。

这个例子选得很准：客服工单摘要是"高频、重复、需要企业上下文"的典型任务——正好落在"代码优先构建 + 企业治理底座"的交叉点上。个人知识库问答用可视化 builder 就够了，但要读生产系统数据的 agent，没有权限和审计就是裸奔。

判断：agent 构建正在经历"软件工程化"，vibe coder 该学走一半

把这条新闻放在 2026 年的时间线里看，趋势很清晰：agent 正在从"提示词手艺"变成"软件工程"。版本控制、测试、评审、回滚、CI——这些软件工程用了几十年的实践，正在被逐一搬到 agent 构建上。Glean 的 headless 只是其中一步：BAND for Developers（我们 cycle79 报道过）解决的是多 agent 协作，Glean 解决的是单个 agent 的构建纪律。

对 vibe coder 和独立开发者，这条新闻有三层可带走的东西：

第一，"agent 即文件"的方法论可以直接抄。你用不上 Glean 的企业运行时，但"把 agent 定义写成版本化的文件、用 PR 评审提示词变更、评估不过不发布"这套纪律，在任何 agent 项目里都适用。下次你的客服机器人/运营 agent 出了怪问题，先问一句：它的 instructions 在 Git 里吗？能回滚吗？如果答案是否定的，你缺的不是更好的模型，是工程纪律。

第二，spec.yaml + instructions.md 是个值得借鉴的文件结构。配置与行为分离、skills/subagents 可插拔——这比"一个 2000 行的 system prompt"健康得多。自己搭 agent 工作流时，可以直接照抄这个骨架。

第三，做 B2B agent 的人要补"治理"这一课。权限（agent 能读哪些企业数据源）、审计（它干了什么可追溯）、停用（出问题一键下线）——这三件是企业客户为 agent 付费的前提。独立开发者做面向公司的 agent 产品时，demo 可以糙，但这三件必须在路线图里。Glean 把"275+ 数据源权限 + 审计"当成核心卖点，不是偶然。

当然也要泼一盆冷水：这是企业级产品。它的目标用户是"有 Glean 实例的公司里的开发者"，独立开发者今天装不上、也用不上。本文的价值在于趋势和方法论，不在于"马上去用"。另外，Workflow mode agent 仍需可视化构建器，说明"代码优先"还没能覆盖最复杂的编排场景——agent 构建的工程化，才刚开场。

文件结构深挖：spec.yaml + instructions.md 该怎么写

Glean 的文件结构（配置与行为分离）值得单独拆开，因为它解决的是所有 agent 项目都会遇到的腐烂问题：提示词越堆越长、最后没人敢改。

spec.yaml：只放"机器要读的"。agent id、模型选择、温度、工具/集成列表、权限 scope、超时与重试策略。原则：改这里的东西会改变 agent 的"能力边界"，需要评审；它是配置，不是文案。

instructions.md：只放"行为要说的"。角色定义、任务流程、输出格式、边界情况处理、"不要做什么"的否定清单。写作原则：一条 instruction 只讲一件事；用"当 X 时，做 Y"的条件句式，少用段落式散文——模型对条件句的遵循度明显更高。

skills/ 与 subagents/：能力插件化。高频复用的能力（如"查工单系统""发 Slack 通知"）抽成 skill，复杂任务拆成 subagent。这和代码工程里的"函数抽取"是同一个思想：agent 的"代码坏味道"，就是 2000 行的 system prompt。

版本号建议：给 instructions.md 的每次实质性修改打 tag（v1.2 这种），评估报告里引用版本号——否则"上周调好的 agent 这周怎么变蠢了"会成为无头悬案。Glean 的 Git PR 评审流程天然支持这一点；自建方案的话，用 Git tag + 评估报告归档也能达到 80% 效果。

评估（evals）怎么做：代表性输入是关键

Headless 流程里最容易被跳过、也最重要的一步是"用代表性输入测试 + 跑评估"。实操建议：

• 代表性输入 = 真实流量的切片。别自己编 3 个"hello world"测试。Glean 示例里用的是"真实客服场景"——对应到你的项目，就是从生产日志/工单/用户反馈里捞 20-50 个真实输入，脱敏后做成评估集。这是评估有效性的分水岭。
• 评估标准要先于 agent 写好。在写 instructions 之前，先定义"什么叫好"：回答格式、必须包含的信息、禁止的行为、延迟上限。标准后置的评估都是自我安慰。
• 回归：每次改 instructions 都重跑全集。提示词的改动有蝴蝶效应——修好 A 场景，B 场景可能悄悄变差。没有回归的迭代，等于闭眼开车。把评估跑进 CI（对，又是 CI——和 n1 那篇呼应上了），PR 合并前必须全绿。

路线之争：自建 runtime、托管平台、开源方案怎么选

Glean 代表的是"托管平台"路线。市面上的 agent 构建路线目前有三条，各有代价：

路线	代表	优势	代价
托管平台	Glean headless、各类 agent 云	权限/审计/运行时开箱即用，不用自己建底座	锁定在平台生态；按量付费长期可能不便宜；数据过境第三方
自建 runtime	LangGraph / 自研 orchestrator + 自运维	完全可控，数据不出内网	你要自己解决权限、审计、可观测性、扩缩容——Glean 博客里那句"不用重建企业上下文底座"，针对的就是这条路线的痛
开源/轻量	Claude Code 的 skills、OpenCode、各类 agent 框架	灵活、便宜、无锁定	企业级治理（细粒度权限、审计轨迹）要自己补，小团队往往补不上

判断：个人和小团队选开源/轻量 + 抄 Glean 的文件结构纪律；做 B2B、碰企业数据的，治理是绕不开的，早晚要在"托管"和"自建"之间二选一——Glean 这篇新闻的价值，就是把"治理底座"这个选题摆到了台面上。以前大家比的是"谁的 agent 更聪明"，以后要比的是"谁的 agent 更可信"。

最小可行方案：不用 Glean 也能搭的 headless 流程

Glean 你用不上，但它的流程骨架可以直接抄。下面是一套零成本的"平替"方案，照着搭一下午就能跑起来：

1. 仓库结构。在你的项目里建 agents/<agent-name>/ 目录：spec.yaml（模型、温度、工具列表、权限）、instructions.md（行为描述）、evals/（评估输入 + 期望输出）。和 Glean 的结构对齐——以后迁移到任何平台都方便。

2. 本地运行。用 Claude Code 的 headless 模式（claude -p）或 Codex 的 codex exec，写一个 20 行的脚本：读 spec.yaml → 组装 system prompt（instructions.md 内容）→ 跑 evals 里的每个输入 → 把输出和期望输出一起存成 JSONL。别小看这 20 行脚本——它就是你的"agent CI"。

3. 评估进 CI。把上面的脚本挂进 GitHub Actions：每次 instructions.md 或 spec.yaml 有改动，自动跑全量评估，diff 输出，失败就红。Glean 流程里"发布前必须评估通过"的那道门，你用 CI 也能造出来。

4. 版本管理。instructions.md 的每次实质性修改打 Git tag（如 support-agent-v1.3），评估报告按 tag 归档。线上 agent 出问题，先问"当前跑的是哪个 tag"，再决定回滚到哪个 tag——和回滚代码一模一样。

5. 权限与审计（轻量版）。没有 275+ 数据源的权限系统，就用"最小工具集"原则：agent 的 spec.yaml 里只声明它真正需要的工具/MCP server，多一个都不给。审计用"结构化日志"代替：每次运行把输入摘要、工具调用、输出摘要写进日志文件，定期 review。

这套方案覆盖了 headless 流程 80% 的纪律要求，成本是零。等你的 agent 开始碰企业数据、客户开始问"它干了什么能查吗"的时候，再考虑托管平台——那时你已经有了干净的 spec.yaml 和评估集，迁移是水到渠成的事。

Auto mode vs Workflow mode：代码优先的边界在哪

Glean 明确说 headless 目前只支持 Auto mode agent，Workflow mode 仍需可视化构建器。这个限制透露了"代码优先"路线的当前边界，值得细读。

Auto mode 是"给目标、让 agent 自己规划步骤"的模式——行为主要由 instructions.md 描述，结构简单，天然适合文件化。改 instructions 就是改行为，版本控制直接生效。

Workflow mode 是"步骤编排固定"的模式——第 1 步调 A、第 2 步调 B、条件分支、人工审批节点。这种结构用 YAML/JSON 描述会迅速变成"配置地狱"：嵌套深、难阅读、改一处牵全身。可视化画布在表达"流程图"这件事上有结构性优势——流程是二维的，代码是一维的。

判断：短期内 agent 构建会稳定在"双轨制"——简单 agent 走代码（工程师友好），复杂编排走可视化（业务人员友好）。想 All in 代码优先的人要意识到：当你的 spec.yaml 超过 500 行、嵌套超过 4 层时，你正在用错误的方式表达流程——该上可视化编排了。工具选型没有信仰，只有"哪种表达更便宜"。

企业治理三件套：权限、审计、停用

Glean 把"知识图谱 + 275+ 数据源权限 + 审计轨迹"放在和 headless 同等重要的位置。对做 B2B agent 的独立开发者，这三件是拿下企业客户的入场券，逐个拆开：

权限：agent 能读什么，谁说了算。275+ 企业数据源（Slack、Google Drive、Salesforce、Jira……）每个都有自己的权限模型。Glean 的做法是"权限继承"——agent 以"调用它的那个用户"的身份去读数据，用户看不到的东西，agent 也看不到。这比"给 agent 一个上帝账号"难做 10 倍，但这是企业采购时安全评审的第一问："你们的 agent 会不会把 CEO 的邮件读给实习生？"答不上来，单子就没了。独立开发者做 B2B agent 时，最小可行方案是：每个 agent 绑定最小 scope 的 OAuth，该 agent 只能以授权用户的身份行动——不要为了省事用一个 admin token 跑全场。

审计：agent 干了什么，可追溯。审计轨迹记录每一次工具调用：谁触发的、读了什么数据、做了什么操作、什么时候。Salesforce 里改了条客户记录？审计日志要能回答"哪个 agent、根据哪条指令、在什么时候改的"。这是出事后的"黑匣子"，也是合规（SOC2 等）的硬性要求。轻量实现：每次 agent 运行写结构化日志（输入摘要、工具调用序列、输出摘要），存 90 天，定期抽查。

停用：一键下线。Glean 控制台可以 share/manage/disable 已发布的 agent。对应的独立开发者版本：每个 agent 有一个"总开关"（feature flag），出问题 10 秒内全量停用；以及"灰度发布"——新版 instructions 先给 10% 流量，评估没问题再全量。没有总开关的 agent，就像没有刹车的车，快是快，不敢开。

三件套的共性：都是"出事前觉得多余，出事后觉得不够"的东西。个人项目可以先欠着，但欠账要记在路线图里——企业客户问起来的那天，就是还账的日子。

三个带走：不管用不用 Glean

1. agent 即文件：spec（配置）+ instructions（行为）+ evals（评估）三分家，进 Git、走评审、可回滚——这是 2026 年之后做 agent 的默认姿势；
2. 评估前置：先定义"什么叫好"，再写 instructions；每次改动全量回归。没有评估的 agent 迭代是玄学；
3. 治理是 B2B 的入场券：权限继承、审计轨迹、一键停用——个人项目可以先欠着，但要记在路线图里，企业客户问起来的那天就是还账的日子。

Glean 的 headless 最大的意义，不是它本身多好用（你还用不上），而是它把"agent 构建软件工程化"这件事做成了 GA 产品——这是一个信号：agent 行业正在从"比谁聪明"转向"比谁可信、比谁好管"。下一次你评估 agent 方案时，除了看它多能干，多问一句：它的行为在 Git 里吗？能回滚吗？出事了能查吗？这三个问题的答案，决定了它能不能进生产。

快问快答

Q：我是独立开发者，能直接用 Glean 的 headless 吗？
A：不能——它需要企业 Glean 实例。但"spec.yaml + instructions.md + evals 进 CI"这套纪律可以直接抄，本文给了零成本平替方案。

Q：headless 和直接写 LangGraph 代码做 agent 有什么区别？
A：LangGraph 是"编排框架"（你写执行逻辑），headless 是"构建方式"（你写定义文件，运行时托管）。前者灵活、后者省心；前者你要自己管权限审计，后者平台给了。按需选。

Q：instructions.md 写多长合适？
A：经验值：超过 300 行就该拆 skills/subagents 了。判断标准：改一行 instruction，你能不能预测到它会影响哪些场景？预测不了，就是太长了。

Q：评估集要多少条？
A：起步 20-50 条真实输入。关键不是数量，是"覆盖你的核心场景 + 包含已知的坏案例"。每出一次线上事故，就往评估集里加一条回归用例——这是评估集长大的健康方式。

透明度

发布日期口径：Glean 官方博客页未显示发布日期，"2026 年 10 月 21 日 GA"来自 unite.ai 2026-10-21 报道与 Glean 文档的交叉；博客原文确认"generally available"。三家环境的安装命令细节来自 Glean 官方文档（docs.glean.com），经 unite.ai 转述交叉。275+ 数据源、知识图谱、审计轨迹为 Glean 官方口径。Workflow mode 限制为官方明确说明。

最后再强调一遍方法论的普适性：Glean 的 headless 之所以值得写 4000 字，不是因为它是个大新闻，而是因为它把"散装"的最佳实践（版本控制、评估、回滚、治理）打包成了一个 GA 产品。当最佳实践变成产品功能，说明这个领域成熟了——而成熟领域的红利，属于先把纪律搭起来的人，不是属于先看到新闻的人。