技能驱动的交付方法（Skill-Driven Delivery）

Status: Active Updated: 2026-03-01

文档定位

• 本文档用于设计与演进讨论，可能包含“目标态/候选方案”。
• 当前已落地行为以代码与 docs/quality/verification-status.md 为准。
• 若文档与代码冲突，请在同一 PR 同步修正文档。

背景

ForgeOps 的定位是“AI 研发流水线控制平面”，不是覆盖所有技术环境细节的执行平台。 真实项目的观测与验证方式高度依赖场景，无法通过预置产品实体一次性枚举。

例如：

• 本地 Web 项目可能需要浏览器调试能力（如 DOM、Console、Network）。
• 远程 ECS/VM 部署可能需要 SSH 与日志/指标脚本。
• 移动端项目可能需要平台专属工具链（模拟器、构建日志、崩溃符号）。

结论：这些能力应由技能与项目脚本承载，而不是在 ForgeOps 内部扩展为通用实体。

核心原则

1. 控制平面只做编排与治理

• 管理 run/step/session 状态、依赖、并发、恢复与审计。
• 提供项目初始化、流程配置、系统配置与可视化。
• 不负责穷举所有环境探测方式。

2. 场景能力由技能包定义

• 角色只是职责边界；具体执行能力由技能装配。
• 技能可组合、可替换、可按项目演进迭代。
• 同一角色可挂多个技能（例如前端测试 + 后端集成测试）。

3. 强约束管边界，局部实现给自治

• 平台机械化强制不变量（依赖方向、边界校验、结构化输出）。
• 在约束内不微观规定“必须用哪一个库/写法”。

4. 证据优先，口头结论无效

• 每个关键结论都应有可回溯证据（日志片段、指标快照、截图、命令输出）。
• 证据由技能定义采集方式和产出格式。

技能契约建议（推荐模板）

每个技能建议至少明确以下五部分：

1. Prerequisites（前置条件）

• 运行环境与工具依赖（例如 node、gh、ssh、浏览器调试通道）。
• 所需凭据与权限边界（只读/读写、目标主机范围）。

2. Probe Methods（探测手段）

• 能访问哪些信号：日志、指标、追踪、DOM、接口响应、进程状态。
• 使用哪些命令/脚本/工具，不可用时的降级方案。

3. Verification Targets（验证目标）

• 明确可测阈值或通过条件。
• 例如启动耗时上限、错误率、关键路径时延、功能断言。

4. Evidence Outputs（证据产物）

• 结果写入路径与命名约定（例如 .forgeops/artifacts/<runId>/...）。
• 输出结构化摘要，便于 reviewer/cleanup 二次处理。

5. Failure Handling（失败处理）

• 区分“可重试失败”与“需要升级处理”。
• 给出最小下一步动作，而不是笼统失败。

与 ForgeOps 现有模型的映射

• 角色到技能装配：<projectRoot>/.forgeops/agent-skills.json
• 技能实现入口：<projectRoot>/.forgeops/skills/*/SKILL.md
• 项目意图上下文：<projectRoot>/.forgeops/context.md
• 流水线定义：<projectRoot>/.forgeops/workflow.yaml
• 调度与 GC 周期：<projectRoot>/.forgeops/scheduler.yaml

这套映射已经足够承载“具体问题具体分析”的实践，不需要新增平台实体。

角色落地建议

1. Architect

• 在初始化阶段确定项目类型、边界、技能包与约束基线。
• 定义“什么必须被验证、证据放在哪里”。

2. Implement

• 按技能能力执行实现与自测。
• 输出结构化变更说明与验证证据。

3. Test / Reviewer

• 基于同一套证据契约做验收，不依赖口头解释。
• 发现重复问题优先提炼为规则或技能升级。

4. Cleanup（Entropy GC）

• 周期扫描漂移与劣化模式。
• 回写质量文档并提交小步修复建议。

反模式

• 把所有场景写进平台功能，导致实体膨胀。
• 用超长统一指令替代可维护的文档索引与技能契约。
• 只写规范不写检查机制。
• 把一次性修复当成长期治理。

最小执行清单

1. 为项目定义最小角色与技能装配。
2. 为关键步骤定义可测目标与证据产物。
3. 把重复失败提升为机械约束或技能更新。
4. 通过 cleanup 周期持续偿还技术债。
5. 保持 AGENTS.md 与 docs/00-index.md 为可导航的短地图。