概率规划，确定执行：为什么 Agent 时代我们还在认真做 CLI

今年上半年，团队里的 AI Coding 经历了两个阶段。第一阶段是把「怎么做事」写成 Skill 和 Rules，让不同同学、不同 IDE 里的 Agent 按同一套流程推进需求，3 月做了内部演示，中后台开始推广。第二阶段是发现流程跑通之后，瓶颈换了位置：代码写完要发布、要看监控、要配 AB、要补埋点，这些动作全都要碰内部基建，而 Markdown 里的规范管不住这件事。hbcli 就是从第二阶段长出来的。

这篇文章写在 9 月初，先讲第一阶段的工作流是怎么分层的，业界现在怎么做这件事，再讲它的边界在哪里；然后进入主线：hbcli 作为 Agent 执行面是怎么设计的，星枢在这条链路里管什么，哪些管控是必须的，哪些尝试有效。

AI Coding 工作流：把「怎么做事」分成三层

团队开始用 Coding Agent 之后，第一个问题是效果依赖个人：有人只让 AI 补代码，有人会先澄清需求、做计划、写测试；各项目的 Rules 和 Skill 也各自分叉。我们要做的是把「怎么做事」从个人习惯变成团队约定，并装进 Cursor、Claude Code、Codex 等不同 Host。

这套约定按来源和变化频率分成三层。

第一层是项目推进逻辑，来自开源。 回答「一个需求从提出到交付经过哪些步骤」，与公司、项目无关。我们引入 Superpowers 的开发方法论和 grill-me 的编码前质询，按内部研发阶段重排成一条主线：需求澄清 → 方案质询 → 计划 → 实现 → 测试 → Review → 验证。这一层跟社区一起演进，不掺公司内容。

第二层是公司规范，团队维护。 代码与提交规范、安全与脱敏、内部平台调用约定、算法 / 业财 / 性能审查等领域 Skill。特点是稳定、跨项目、需要强制。

第三层是项目要求，随仓库走。 架构分层、目录约定、构建测试命令、业务规则，写在仓库的 AGENTS.md 或 .cursor/rules 里，与代码一起提交和 Review，子目录可以嵌套，就近优先。

管理与分发

管理上守两条。第一，渐进披露：Rules 只放短且稳定的硬约束，Skill 按任务触发，细节放 references 分册。入口文件当目录不当百科，长文件会腐烂，模型读到后面就开始就近模式匹配。Skill 越长，模型越容易漏读和读错，删掉重复比多写一条提醒更有效。 第二，三层各有维护者和变更节奏：开源层跟上游合并，公司层由基础团队评审后发布，项目层随仓库 PR 走，不允许在项目层改写上两层的规则。

三层规范解决的是「怎么想、按什么顺序做」。它的边界三家官方文档说得一致：Markdown 里的规则塑造行为，不是硬执行层；AI 指导不应是唯一的安全控制；需要强制的约束要用机械手段。Markdown 能约束模型怎么思考，约束不了它怎么碰基建。后一半要靠确定性的东西：命令、网关、确认、审计。下面的内容都围绕这一半。

起点：基建有了，AI 用不上

大前端基础团队这几年攒下了一套还算完整的工程系统：Web / H5 / 小程序 / npm 包的发布系统，前端监控扁鹊，客户端监控谛听，移动应用全生命周期管理向日葵，埋点 SDK 天启，线上配置平台，YApi 接口管理，脚手架和规范库。这些能力都是真实的，也都在被人用，方式是 Web 控制台、SDK 或者各自的 API。

人用没有问题，Agent 用就有三个问题。第一，入口分散。接入、发布、观测、治理是一条长链路，每个环节在不同的系统里，学习成本高，没办法在一次对话里跑通。第二，调用面失控。各团队开始自建 MCP、CLI 和脚本直连基建 API，平台方看不到谁在调、调了什么、有没有风险。第三，Agent 缺少官方执行面。模型会在提示词里自己拼 host 和 curl，绕开审批和审计，行为无法复现。

4 月我们把全平台能开放给 Agent 的基础能力盘了一遍，归成创建 Skill、质检、排障与取数、监控与发布、规范与 npm 几类场景，并定下一条原则：不建大而全的 CLI，命令只跟真正能解决问题的 Skill 一起长出来。 Agent 运行时后置，先把执行面做扎实。CLI 把平台能力封装成命令，输出结构化结果和标准退出码；Skill 告诉 Agent 何时用、怎么用、结果怎么读、失败怎么办。第一个场景是 Web / H5 多环境发布，含审批和状态轮询。

一个原则：概率规划，确定执行

模型擅长的是理解意图、拆步骤、在几个候选里挑一个。它不擅长的是每次都一样。而发布、配置变更、清理资源这类动作，要求的恰恰是可预测、可回放、出了事能追责。把这两种性质的事放在同一个位置处理，得到的就是「这次成功了，下次不知道」。我们给自己定的原则只有一句：模型负责理解和规划，CLI 与网关负责确定执行。放到设计上，就是把模型的输出尽早收敛成命令、参数、风险等级和可验证的结果。越接近高风险动作，越要把模型的判断变成结构化参数、显式确认和确定性的执行。

hbcli：Agent 调用基建的官方执行面

hbcli 要解决的只有一件事：让 AI 高效、准确地调用内部基建能力。使用方式很简单：装一次 hbcli，登录，一条命令把各插件包附带的 Skill 装到 Agent 的技能目录，之后 Cursor、Claude Code、Kiro 这些 Host 里的 Agent 就按 Skill 编排命令，命令经网关到基建。高效靠一句话安装和结构化输出，准确靠命令契约、上下文补参和网关确认。

为什么第一阶段以 CLI 为核心，没有直接做 MCP？MCP 是协议，解决的是接得上：工具发现、多 Host 接入、远程连接；它不天然提供确定性、审批和安全。CLI 解决的是怎么稳定地执行：参数固定、输出结构化、退出码明确、能在本地调试、能写进脚本，人和 Agent 用同一份契约。内部发布、查询这类动作，参数和终态本来就明确，先沉淀成命令契约，再由网关补确认和审计，是成本最低的路。人机共用这一点比我预想的重要：Agent 编排出了问题，同学在终端敲同一条命令就能复现；人踩到的坑修一次命令，Agent 路径也一起修好。CLI 并不天然比 MCP 安全，安全来自凭证、服务端鉴权、网关、确认、审批和审计。等到需要动态工具目录、按用户的 OAuth 和任意 Host 的远程接入时，MCP Gateway 的优先级自然会上来，接进来的仍然是这套命令契约。

五层执行面

现在官方路径上的一次工程动作，会经过下面五层：

每层只做自己擅长的事，也各有各的坏法。Agent 负责理解、规划和选择，坏法是理解偏差、选错命令、猜参数；我们不让它成为权限边界，模型可以提出计划，但不能替人决定这件事能不能做。Rules、Skill 和工程上下文这一层，Rules 放短且稳定的硬约束，Skill 放按任务触发的 SOP，上下文回答「这是哪个应用」；坏法是流程写错、触发条件和别的 Skill 打架、旧版本残留在某台机器上，它能描述流程，替代不了运行时校验。hbcli 是唯一的执行面，坏法是参数错、输出不可解析，以及 Agent 走的 --json 路径和人机交互路径行为不一致，后面第一个事故就是这么来的；CLI 能确定性执行，但自己不带平台治理。星枢网关管所有业务 HTTP 的登记、确认、限流、代理、审计和 Trace，坏法是未登记的接口、越权、突发调用；它管入口，不替代业务系统自己的审批。最下面是基建，坏法是接口权限变化、平台自己演进了而上游没感知，第二个事故就是这么来的。

hbcli 的架构设计

基座只做公共的事

hbcli 基于 oclif 的插件体系。基座只承担所有插件都需要的能力：登录鉴权（用个人访问令牌换 token，本地缓存并自动注入，命令启动前强制检查登录态）、统一的 HTTP 客户端（所有业务请求指向网关，自动带上身份、环境、命令 ID 和链路标识）、统一的参数解析、错误结构和 --json 输出、插件的创建、安装、发布与准入测试、网关 API 的扫描与登记、Skill 的安装，以及观测埋点和经验回收。鉴权、HTTP 边界和输出格式内聚在基座，业务插件只写业务，这是后面几十个插件能保持一致行为的前提。

业务能力有两种形态。内置插件在 Monorepo 里，覆盖 Web / H5、服务端、npm、小程序、向日葵五类发布，是最早也最核心的交付能力；远程插件独立仓库、独立发布，AB、埋点、监控 APM、排障、数据库运维、接口文档这些都是这种形态。后续的改版，基座改为瘦基座，插件按需安装和升级，基座不再随插件数量膨胀；应用上下文查询也拆成独立子包。

命令与 Skill 是同一份契约

每个插件包同时交付两份东西：可执行的命令，以及告诉 Agent 怎么编排这些命令的 Skill。两者随同一个 npm 包发布，安装时 Skill 被软链到 Agent 的技能目录。这个设计最初不是这样：Skill 曾经放在独立的 Git 仓库单独安装，命令在 npm 包里，两边分开演进，马上出现「Skill 更新了、命令没发版」的错位。改成同包分发之后，改命令、改参数、改流程时两侧必须一起看。Skill 和命令是同一份契约的两种表达，必须同版本交付。

Skill 的内容有明确分工：主文件写门禁、路由、确认闸、轮询和失败恢复；分册写链路、场景和字段边界；需要稳定执行的轮询逻辑放包内脚本。所有业务 Skill 执行前都要先过基座自带的共享门禁：Node 版本、CLI 版本、登录态、应用类型确认。这份共享 Skill 同时是全平台的插件路由表，Agent 先在这里确定该进哪个插件，再读专题 Skill。

插件接入是一条固定流程

新插件从模板起步，走三阶段规格：需求文档、API 契约、CLI 加 Skill 实现。上线关口是固定的：本地 Mock 联调，扫描命令里的 HTTP 调用点生成登记表并登记到网关、标注风险等级，跑 smoke / schema / contract 三类准入测试，发到内部 npm，测试环境到生产环境晋级，最后线上冒烟。网关登记失败就不允许发包。插件由 Agent 生成也不能跳过这些门禁，Plugin Builder 降低的是写代码的成本，准入的成本不能省。

这条流程的价值在半年后显现出来：立项时服务对象是四个大前端平台，现在在架 22 个包，一半以上在大前端之外，风险巡检、数据库运维、接口文档、问题管理、业务取数这些都由对应团队按同一套流程接进来，服务端发布平台的团队直接复用了插件形式共建。其他团队愿意把系统接进来，看中的是接入后对调用面的掌控：谁在调、调了什么、出了事能查。 这比 CLI 本身写得好不好重要得多。

星枢：hbcli 的治理与上下文一环

hbcli 是执行面，它自己不带平台治理，也不知道「当前仓库是哪个应用」。这两件事由星枢承担。在 hbcli 的链路里，星枢是四个角色。

统一网关。所有业务 HTTP 从这里过，业务 host 不进 npm 包和 Skill。网关负责 API 登记、风险分级确认、限流、代理和审计，下一节展开。

工程上下文契约。以应用、系统绑定、分组几个实体建立应用关系，回答「这个仓库属于哪个应用、Owner 是谁、绑了哪些发布、监控、配置系统、该用哪个系统 ID」。Skill 在编排命令前先查上下文，用权威数据补齐参数。

观测与运营。命令级调用记录、CLI 调用和下游 API 的双指标、按命令步骤展示的 Trace，以及 Skill 使用统计和经验回收工作台。

管理台。能力目录、Plugin Builder、包详情和数据大盘，平台维护者和插件维护者在这里看能力面和使用情况。

星枢在规划里的定位更大，是大前端面向研发全链路的 AI 工程效能中枢，还有门户和数据洞察这些前台体验。但从 hbcli 的视角看，它的核心价值在后台：上下文、网关、观测和运营。没有这一层，CLI 只是一堆命令；有了这一层，命令才变成可治理的执行面。

管控：登记、分级确认、限流、审计

网关是整套东西的治理点。每个插件接入之前，它要调用的接口都要在网关登记并标注风险等级；接口没登记，命令就打不通。风险分成三级：低风险的读操作直通；中风险的写操作要在命令里显式带 --confirm，表达「我确实要做这件事」；高风险的动作进星枢 Web 确认页，确认通知推到操作者的即时通讯工具，确认之后命令再去轮询业务终态，业务系统原有的审批流程照旧保留。

一次高风险命令的流转是这样的：Skill 里只写一条 hbcli 命令，不写 host，不写 curl。命令进网关，网关判定为高风险，返回「待确认」状态和一个确认会话，输出里直接给出下一步该敲的状态查询命令。操作者在 Web 确认页点确认，网关代发到业务系统，业务单号一出现就带回来，后面所有轮询都围着它转。业务系统按自己的规则挂起审批或放行，Agent 持续查询直到拿到发布完成或失败的终态。参数不合法的请求在进网关之前就被命令层挡住，以结构化错误退出，不重试，也不去确认。几个细节决定 Agent 用起来稳不稳：--json 输出里不混进度条和日志；「待确认」和「确认成功」都不是终态；每一步输出都告诉 Agent 下一步是什么。

风险等级登记一次不算完。扫描工具按规则给初值：读操作低风险，写操作中风险，命中关键词高风险。上线后要按真实编排校对。我们曾把一个发布插件的 23 个接口从中风险调回低风险，因为它们全是只读查询，误标成中风险会让 Agent 每查一次都停下来问确认，编排直接卡住；反过来也有原本直通的测试环境审批被提到中风险。风险等级标错的代价是双向的：标高了 Agent 用不下去，标低了人会被绕过。
限流。网关按风险等级给每用户每接口每秒配额，超限返回 429，CLI 直接失败，Skill 要求退避后重试，禁止对同一接口连打。实现是按实例的内存固定窗口，能保护单个实例，多副本部署时集群总额度会被放大，所以不能叫严格的全局限流。这是建设初期用较低复杂度换基础保护的选择，等真实流量、429 比例和多副本一致性真的成了主要问题再引入共享状态。

为什么 Skill 不许带 host 和 curl

这是我们定下的少数几条硬规则之一：Skill 只写 SOP 和参数编排，所有对内部系统的调用都走 hbcli 命令，不允许出现业务 host，不允许出现 curl。如果每个 Skill 都能自己访问内部 API，登记、确认、限流、审计和接口迁移这些事就会再一次散落到几十份 Markdown 里，回到开头描述的那个状态。把 HTTP 边界收敛到命令和网关之后，基建接口变了只改插件或网关；Skill 描述的是「做什么」，不需要跟着动。

双层确认为什么不能合并

有同学问过：既然星枢已经让用户点了一次确认，为什么发布系统那边还要再审批一次，能不能合成一步？

不能，因为这两步验证的是不同的事实。平台确认回答的是「这是不是操作者和 Agent 当前真正想执行的动作」，它防的是 Agent 误触，把用户的一句话直接变成生产变更。业务审批回答的是「这个动作是否符合发布窗口、业务责任人和变更制度」，这是组织规则，星枢没有资格也没有信息去判断。

硬合并只有两种结局：要么星枢去承担本不该它承担的业务判断，比如今天是不是封网期；要么确认退化成形式，点一下就过，等于没做。所以我们把责任主体拆开：网关确认解决「用户是否允许 Agent 发起」，业务审批解决「组织是否允许执行」。双层确认会让高风险操作变慢，所以分级才重要：读操作直通，中风险只加一个 --confirm，高风险才进 Web 页。

让 Agent 用得准的几个设计

管控解决的是「不该做的做不了」，另一半问题是「该做的做得准」。

先回答「这是哪个应用」

执行面搭好之后，我们发现另一类错误更隐蔽：Skill 选对了命令，参数却绑错了应用。命令没报错，网关也放行了，因为那个应用 ID 是合法的，只是不是用户想要的那个。所以 Agent 执行内部任务之前，先要通过星枢的上下文契约回答当前仓库属于哪个应用、Owner 是谁、绑定了哪些系统、该用哪个系统 ID。存量应用和绑定关系批量导入，新应用在发布系统创建时自动同步到星枢并建立绑定，再补上组织架构和服务端应用的正查反查。Skill 用权威数据补齐参数，不让模型从 README 里猜。

编排纪律写进命令输出

一个重要的改动是把编排约束从 Host 的 Hook 转移到命令输出。Hook 在不同 Host 行为不一致，Agent 也可能根本不触发；命令输出里直接给下一步命令和门禁状态，Agent 只要能读 JSON 就能跟上。同一个思路后来用在几处：首次调用某个子命令前先查 --help，减少猜参数；排障主流程把建案、取证、报告、FAQ 入库四个阶段各自对应到真实命令并写成硬规则，网关按前驱阶段落表，跳过前一步后一步就打不通。约束写在命令输出里比写在提示词里可靠，因为前者不依赖模型记得住。

观测与经验回流

Skill 使用埋点刚上线时回收明显偏低，排查发现埋点写在门禁段落里，同一会话不重复触发。后来改为命令层自动生成链路标识随网关上报，轮次结束自动汇总，多对话框的会话隔离，Trace 页支持按 Skill、异常筛选和链路标识搜索，并展示意图摘要。观测要挂在确定性的命令层，靠 Agent 自觉上报的数据不能信。

经验回流的设计是：Agent 在本地记录踩过的坑，写入和命中事件上报到平台；平台按热度判阈，达阈自动生成提案；维护者在工作台审核，批准后拉到本地融合进官方 Skill 的对应层级，再回标处理完成。目前用户侧的记录、上报、判阈和提案已经贯通，维护者端到端融合还在验收。

Trace 不等于 Eval

现在有了命令级调用记录、CLI 调用和下游 API 的双指标，以及按命令步骤展示的 Trace。它能回答「这次调用经过了哪里、哪一步失败」，能区分是 Skill 选错了、命令执行失败、网关拒绝还是业务平台自己挂了。排障和回放靠它够用。但 Eval 需要固定的任务集、判分规则、版本基线和失败样本回归，回答的是「这一类任务是否稳定达到质量要求」，这是另一件事。

写在最后

目前的平台使用情况，从9月初的周口径：7日命令调用约 9400 次，活跃 92 人，在架 22 个包，hbcli已逐步成为公司软研的内部基建 AI 入口。

标题写的是「为什么 Agent 时代我们还在认真做 CLI」，写完发现真正想说的在 CLI 之外。CLI 只是我们当前找到的、最便宜的确定执行面，换个团队、换个时间也许是别的东西。不变的是那句原则：模型负责理解和规划，确定性的部分交给契约、确认和网关。可靠性的重点在 Schema 写清了没有、写操作幂等了没有、状态能不能恢复、结果有没有回执；确认要按责任主体拆，平台管意图，组织管制度。这些都是老办法，只是 Agent 把它们重新逼到了台前。