用插件共享 AI 研发能力:一套研发流水线的落地实践

我们最初通过一个 skill 发起研发任务,按需加载设计、编码、测试和发布步骤。跨业务复用后,问题变成了:谁维护公共流程,谁维护业务差异,公共修复怎样送达各项目?

最终采用三个插件层次:core 管工作流与 harness,base 提供公共能力,scene 承载业务配方。用户仍从场景 skill 发起任务。本文记录选择依据和落地经验,业务名称与内部平台已脱敏。

Skill 继续作为执行入口,插件提供与维护边界对应的发布单元。

1. 为什么从模板复制转向公共插件

我们比较过两套方案:从模板生成完整场景实例,或把公共实现拆成插件、由场景引用。

对比维度 方案一:模板生成完整实例 方案二:公共插件与场景包
业务接手什么 可本地修改的公共实现与场景能力 场景配方、资源和适配步骤
公共修复如何传播 版本快照检查更新,合并公共变化与本地修改,支持备份恢复 发布公共包,验证兼容后更新依赖
主要维护成本 副本同步、冲突合并与结果验证 公共契约、依赖兼容与跨场景回归

第一套方案改造少、定制自由,也考虑了升级。我们选择第二套,关键在交接范围:公共团队负责初期建设,场景稳定后交给业务;公共 workflow/harness 和基础能力则长期集中维护。

这样,共性问题回到 core/base 修复,业务接手自己的配方和适配,减少公共副本的反复合并。代价是维护契约和兼容范围。如果业务需要长期深改公共实现,完整实例仍有价值。

依赖检查和更新策略仍需落地,使用插件本身不会自动解决它们。

2. 把维护边界落实到 core、base 和 scene

workflow 描述阶段如何推进,harness 通过状态、脚本和产物验收执行门禁。二者由 core 统一维护。

层次 负责什么 业务接入时主要补什么
core 工作流、状态、门禁、恢复、宿主接入与阶段事件 确认流程及产物约定适用
base 文档、设计采集、测试、公共发布与自建埋点采集 确认工具、框架和平台支持
scene 业务配方、项目上下文与私有步骤 业务规则、应用和环境映射

core 读取 scene 配方并调用 base;scene 声明能力引用,由 core 主会话执行。公共团队维护 core/base,业务团队维护 scene

实线表示主会话读取与调用,虚线表示配方的能力引用。主会话从场景入口开始,准备依赖、加载公共工作流和配方,再初始化 harness。各需求独立保存状态与产物。

能力归属按复用范围判断。例如,可共享的发布实现进入 base,场景提供应用、分支、包范围和验证地址。base 仍需明确支持范围,不能只把业务目录搬过去。

3. 场景只留一个入口,内部步骤按需读取

新场景最初暴露了五个技能:流水线入口,以及方案、任务、编码、发布四个步骤。用户需要自行判断如何组合。后来我们收敛成一个公开入口:

skills/<scene-entry>/
├── SKILL.md
├── recipe/recipe.md
├── resources/
├── scripts/bootstrap-deps.mjs
└── subskills/
    ├── spec/INSTRUCTIONS.md
    ├── tasks/INSTRUCTIONS.md
    ├── code/INSTRUCTIONS.md
    └── deploy/INSTRUCTIONS.md

目录名为示意。私有步骤使用 INSTRUCTIONS.md,主会话按阶段读取;公共 base 技能仍可独立复用。配方和资源随入口一起交付,也避免提取安装时遗漏入口外的文件。

3.1 场景到底怎样被调用

一个场景入口、一条主会话、一套 core 状态。 用户可以输入技能名或自然语言;场景不明确时先澄清,无需固定命令前缀。

现有已发布入口依次执行:

  1. 确定场景、项目和功能名,检查 core/base 依赖与宿主接入。
  2. 按安装器返回路径读取 core 工作流、场景配方和业务资源,核对能力缺口。
  3. 通过 core 初始化 harness,保存场景与配方快照;续跑复用原快照和进度。
  4. 主会话按阶段读取私有步骤、调用公共能力、生成产物,由 core 验收并推进状态。

配方是带场景、版本和工作流标识的 Markdown,声明各阶段差异。core 无需登记每个业务的分支。私有步骤不另建状态或编排器,独立评审仍按公共流程派发。

3.2 一个完整例子:用活动场景开发报名页

以下为脱敏教学示例,采用拟迁移的原生调用方式;当前安装器尚未切换,验证范围见下一节。

用户输入:

用活动研发流水线新增报名页,功能名 event-signup。包含活动详情、手机号和报名按钮,设计稿使用我提供的链接。

宿主加载 event-workflow/SKILL.md,入口复用 core 工作流和下面的场景配方节选:

---
scene: event
version: 1.0.0
workflow: 2
---

其余阶段沿用 core。

## S2 设计
读取 ../resources/event-context.md,确认接口与表单规则。
读取 ../subskills/spec/INSTRUCTIONS.md,生成标准方案和测试计划。
有设计稿时调用 base 的 design-fetch。

## S4 开发
读取 ../subskills/tasks/INSTRUCTIONS.md 和 ../subskills/code/INSTRUCTIONS.md。
按任务实现代码与单测,调用 base 的 unit-test 执行选定测试。

## S5 预发
读取 ../subskills/deploy/INSTRUCTIONS.md,target=pre,提交预发报告。

## S7 线上
通过 core 授权门禁后,读取同一发布适配,target=production。
发布 S6 验证的版本,提交独立线上报告。

相对路径以配方目录为起点。业务资源提供事实,私有步骤说明业务适配;执行关系如下:

event-workflow 入口
  → 检查插件安装、兼容版本和宿主接入
  → 加载 core 工作流与场景配方,初始化 event-signup
  → 完成 S1,进入 S2
  → 读取 subskills/spec/INSTRUCTIONS.md
  → Skill("shared-base:design-fetch", args="<设计稿链接> <产物目录>")
  → 主会话执行采集、编写方案和测试计划
  → core 验收 S2,通过后进入下一阶段

这是执行关系示意。实际阶段边界由项目根下的 core 命令控制:

node "$SKILL_DIR/hooks/hooks.js" start event-signup S2
# 主会话完成设计工作并写出产物后,再验收
node "$SKILL_DIR/hooks/hooks.js" pass event-signup S2

$SKILL_DIR 指本次加载的 core 目录;片段省略初始化和 S1。S2 交付到需求目录:

docs/event-signup/
├── technical-spec.md
├── api-consumption.json
├── test-outline.md
└── unit-test-plan.json

S4 消费这些产物完成开发;S5 使用场景发布适配;S6 执行公共测试;S7 获得授权后上线。换业务主要替换配方、资源和必要的私有步骤。

3.3 公共 Skill 采用插件限定名调用,更新由插件机制负责

目标标准调用为:

Skill("shared-base:design-fetch", args="<设计稿链接> <产物目录>")

插件名为脱敏示意。插件管理安装和更新,限定名引用能力,主会话执行技能说明中的工具与步骤。 Skill(...) 是宿主加载操作;读取 Markdown 本身不会完成设计采集。

公共包发布兼容更新后,项目更新插件并刷新或开启新会话,场景继续使用同一限定名。名字不变不代表版本兼容,仍需检查依赖范围。

我们已在宿主 CLI 隔离验证:完整插件原生安装成功;真实工具记录确认限定名调用成功;测试插件更新后,新会话通过同一限定名加载到新版内容。测试使用本地发布包与本地插件市场,尚未验证 IDE 调用、线上分发鉴权及更新、在途会话热刷新,也未执行设计采集。

现有已发布安装器仍采用提取安装。 技能放入 .agents/skills/,由安装器维护版本,主会话按返回的 base_skills 路径读取执行。原生迁移尚未完成;私有说明继续按文件读取,harness 继续执行脚本门禁。

4. 第二个业务让“通用”接受了一次检验

第二个场景沿用旧的 architecture.md、detail.md 和独立任务卡,发布阶段也与公共流程不同。只改文件名无法对齐字段、测试映射和完成状态,因此我们让它直接生成公共产物:

阶段 正式交接
S2 设计 technical-spec.md、api-consumption.json、test-outline.md、unit-test-plan.json
S4 开发 tasks.md、实现、对应测试和质量证据
S5 预发 预发上下文与发布报告
S6 测试 绑定预发版本的用例、结果和证据
S7 线上 独立上下文与报告,复用已测试版本

S2 建立页面、源码与测试文件映射,S4 随代码生成测试,S6 据此验证。默认跑增量单测,每轮测试再询问是否补跑改动页面的全部单测;预发接口、UI 和冒烟仍需完成。映射缺失或运行器不支持时补适配,不用全仓测试兜底。

接入还发现:公共质量脚本能找到变更文件所在子包,却可能漏掉单应用根构建。我们在 core 修复,并用非零退出样例验证门禁阻断。一个业务发现的问题,有了统一修复位置,其他兼容场景也能采用。

5. 公共能力能独立升级,也需要明确边界

场景通过兼容范围依赖 core/base,无需与它们绑定同一个版本号:

最低兼容版本 ≤ 已安装版本 < 不兼容边界

现有提取安装器在启动时安装缺失依赖、更新已有依赖,版本和文件校验有效则跳过。它只检查 latest,超出范围就停止,不自动搜索历史兼容版本。

在途需求保存配方快照,但尚未锁定 core/base 精确实现,不能据此完整复现运行环境。旧工作流需求继续用原版本完成,不自动重编号迁移。兼容范围、回归和精确版本记录仍是维护责任。

6. 新场景需要主动发现缺口

创建向导要从需求到收尾逐阶段盘点,而不只生成目录。缺口也要明确归属:

缺口 处理位置
公共执行器不支持测试框架 更新 base
应用、环境或业务规则缺失 补 scene 适配
工具、账号或验证目标不可用 准备运行环境

公共流程、执行能力和业务配方可以由不同团队维护,通过统一仓库、验证和插件版本交付。接入发现的问题应回到对应维护者,而不是全部堆进 core。

7. 初始化也是公共流程的一部分

真实项目曾出现“场景能启动,宿主 hooks 却没注册”。安装技能、初始化需求和配置宿主,需要分别落实。

我们将首次启动和续跑接到同一条初始化路径:core 检查注册,base 提供采集器,场景复用。旧项目缺 hooks 可以补注册,保留其他配置及原阶段、任务和配方。

领域选择也放进 core 的需求澄清,由用户从已有领域中确认。业务归属不能用仓库名或知识库标识推断,各场景无需重复实现选择器。

8. 让真实执行留下可核对的数据

hooks 注册后,看板仍可能缺阶段数据;阶段事件接上后,用量也可能未知。注册、接口接收和有效指标可见,需要分别验证。

我们沿用自建埋点:core 在状态变更提交时生成事件,base 采集器将真实会话与事件关联,按时间窗口统计输入/输出 token 和用户/模型轮次。工具结果不计轮次,流式消息去重;窗口统计不等于整场会话或账单总量。

记录先落本地再发送。来源缺失或用量晚到时等待补齐,不填零;失败使用原 event_id 和数值补传,接收端负责更新与去重。历史指标只恢复能关联需求、阶段、会话和时间窗口的部分,归档保留必要元数据,不复制对话正文。

我们在已有项目用独立子任务验证采集与看板:暂停发送再恢复,核对补传标识与数值,并从归档独立重算、恢复有来源的历史指标,主流程进度保持。相关修复进入公共包,供其他场景复用。

9. 目前验证了什么

截至 11 月 2 日,已完成以下验收:

  • 回归与隔离冒烟实际执行 core、公共单测执行器、Vitest、ESLint、TypeScript 和根构建,覆盖八阶段及关键门禁。
  • 公共包和两个场景已发布,下载内容核对、远端安装、依赖更新及已有状态保持经过验证。
  • 已有项目验证了接入修复、真实指标、历史恢复和失败补传;原生 CLI 验证范围见第 3.3 节。

隔离样例中的业务平台与浏览器证据使用模拟契约,未执行真实业务预发或生产部署,也未验证接收端去重。

这套结构已缩小业务交接范围,并让公共问题有统一修复位置。能否持续降低维护成本,还要观察后续业务的接入耗时、公共修复采用情况和返工情况。

相关阅读

插件把维护边界拆开之前,Skills 与完整软件生产见 OPC 软件研发实践。垂直场景 Skills 与 spec/TDD 见 Loop Engineering。从 Demo 到生产要补齐的工程闭环见 AI 研发从 Demo 到生产环境差了什么。

评论

加载中…
评论通过 GitHub 安全存储,提交后稍等片刻显示。