bf-skillsruntime-dev

star 48

用 Skills Runtime SDK（Python）开发复杂业务 agent、skills、workflow 的编码智能体指南。用户一旦提到 skills_runtime、Skills Runtime SDK、overlay YAML、FakeChatBackend、AgentBuilder、Coordinator、skill_ref_read、skill_exec、approvals/sandbox、WAL/replay、exec sessions、spawn_agent/send_input/wait、waiting_human/resume、examples/apps/workflows，或要在本仓上落地复杂业务开发/修复/回归，就应优先使用本技能。不要用于与本框架无关的通用编码或纯文案任务。

okwinds By okwinds schedule Updated 4/2/2026
play_arrow Run Skill in Manus View GitHub

name: bf-skillsruntime-dev version: 0.1.0 description: "用 Skills Runtime SDK（Python）开发复杂业务 agent、skills、workflow 的编码智能体指南。用户一旦提到 skills_runtime、Skills Runtime SDK、overlay YAML、FakeChatBackend、AgentBuilder、Coordinator、skill_ref_read、skill_exec、approvals/sandbox、WAL/replay、exec sessions、spawn_agent/send_input/wait、waiting_human/resume、examples/apps/workflows，或要在本仓上落地复杂业务开发/修复/回归，就应优先使用本技能。不要用于与本框架无关的通用编码或纯文案任务。" compatibility: "需要 Python 3。允许读取目标仓库与当前工作区文件；本技能自身不依赖技能目录外文档，所有参考资料均在本技能 references/ 内。脚手架脚本会在用户指定目录写入 run.py、config/runtime.yaml、skills/、tests/。"

Skills Runtime SDK 业务开发指南

核心原则：

  • 离线优先：先让 FakeChatBackend 跑通最小闭环，再接真模型
  • Skills-First：角色能力先沉淀成 SKILL.md，编排层只负责组合
  • 证据优先：副作用必须能在 WAL / approvals / tool events 中回放
  • 双轨协作：固定角色用 Coordinator，动态子任务用 collab primitives

事实快照：

  • 当前技能按 2026-04-02 / SDK 0.1.11 校对
  • 本技能只引用当前目录内的 references/ 与 scripts/
  • 如果你发现仓库事实再次变化，先更新本技能的本地 references，再继续使用

开场动作

  1. 先定位本地仓库根目录，不要默认联网克隆。
  2. 优先确认当前环境是否已经安装 skills-runtime-sdk；未安装时再用本地仓库做 editable install。
  3. 先选开发形态，再决定读哪份本地 reference：
    • 单 agent + 工具：看 references/recipes-index.md
    • Skills 注入 / references / actions：看 references/config-templates.md
    • 多 agent / 动态协作：看 references/api-cheatsheet.md + references/recipes-index.md
    • 安全 / 审批 / 沙箱：看 references/safety-and-sandbox.md
    • 回归 / 验证 / 证据：看 references/testing-strategy.md

本地环境准备

如果已知仓库根目录，记为 REPO_ROOT：

export REPO_ROOT=/abs/path/to/skills-runtime-sdk

安装 SDK 二选一：

# 方式 A：开发模式安装（推荐）
pip install -e "$REPO_ROOT/packages/skills-runtime-sdk-python"

# 方式 B：临时 PYTHONPATH（不安装）
export PYTHONPATH="$REPO_ROOT/packages/skills-runtime-sdk-python/src"

CLI 两种入口都可用：

skills-runtime-sdk --help
python3 -m skills_runtime.cli.main --help

快速开始

1) 生成业务骨架

python3 scripts/scaffold_app.py my-app --out . --with-skills
# 预览：加 --dry-run
# 覆盖：加 --force

默认生成：

  • run.py
  • config/runtime.yaml
  • skills/
  • tests/

2) 离线跑通

python3 run.py --workspace-root /tmp/my-app --mode offline

3) 最小回归

pytest -q tests

如果你正在本仓内开发，再跑仓库门禁：

bash scripts/pytest.sh
pytest -q packages/skills-runtime-sdk-python/tests/test_examples_smoke.py

推荐导入与运行骨架

最小 Agent

from pathlib import Path
from skills_runtime.agent import Agent
from skills_runtime.llm.fake import FakeChatBackend, FakeChatCall
from skills_runtime.llm.chat_sse import ChatStreamEvent

agent = Agent(
    workspace_root=Path("/tmp/demo").resolve(),
    backend=FakeChatBackend(calls=[
        FakeChatCall(events=[
            ChatStreamEvent(type="text_delta", text="EXAMPLE_OK: done."),
            ChatStreamEvent(type="completed", finish_reason="stop"),
        ])
    ]),
)
result = agent.run("完成任务")
print(result.status, result.final_output, result.wal_locator)

生产级 AgentBuilder

from pathlib import Path
from skills_runtime import AgentBuilder
from skills_runtime.state.wal_protocol import InMemoryWal
from skills_runtime.safety import ApprovalRule, RuleBasedApprovalProvider
from skills_runtime.safety.approvals import ApprovalDecision

provider = RuleBasedApprovalProvider(
    rules=[
        ApprovalRule(tool="read_file", decision=ApprovalDecision.APPROVED),
    ],
    default=ApprovalDecision.DENIED,
)

agent = (
    AgentBuilder()
    .workspace_root(Path(".").resolve())
    .backend(backend)
    .wal_backend(InMemoryWal())
    .approval_provider(provider)
    .event_hooks([lambda ev: print(ev.type)])
    .build()
)

说明：

  • Agent 推荐从 skills_runtime.agent 导入
  • AgentBuilder / Coordinator 推荐从包根 skills_runtime 导入
  • RunResult.status 当前应按 completed|failed|cancelled|waiting_human 处理

复杂任务落地路由

路由 A：单 agent + 标准工具

适用：

  • 代码修改、读写文件、最小命令执行、离线 smoke

做法：

  • 用 Agent 或 AgentBuilder
  • 工具优先走 builtin tools：read_file / apply_patch / file_write / shell_exec
  • 所有副作用保留 approval_* + tool_call_*

先读：

  • references/recipes-index.md
  • references/testing-strategy.md

路由 B：Skills-First 业务能力

适用：

  • 需要把能力打包为可复用 skill
  • 需要 mention 注入、skill_ref_read、skill_exec

做法：

  • 先配 skills.spaces + skills.sources
  • mention 必须使用唯一合法格式：$[namespace].skill_name
  • references / actions 默认关闭，只有明确需要时再开启
  • 先跑 skills preflight，再跑 skills scan
  • 如果要落 skill_exec，先在 skill frontmatter 明确声明 actions

先读：

  • references/config-templates.md
  • references/recipes-index.md

路由 C：固定角色多 agent 流水线

适用：

  • Analyze → Patch → QA → Report
  • Planner → Worker → Reporter
  • 角色固定、数量稳定

做法：

  • 用 Coordinator
  • 每个角色能力先沉淀成独立 skill
  • 主任务文本显式带 mention，确保出现 skill_injected

先读：

  • references/api-cheatsheet.md
  • references/recipes-index.md

路由 D：动态子任务 / 并行协作

适用：

  • 子任务数量不固定
  • 运行中途需要追加输入
  • 需要 spawn_agent / send_input / wait

做法：

  • 用 collab primitives，不要硬套 Coordinator
  • spawn_agent / send_input / close_agent 一般都要纳入审批治理
  • 子 agent 仍然要 Skills-First，各自维护独立 WAL

先读：

  • references/api-cheatsheet.md
  • references/safety-and-sandbox.md
  • references/recipes-index.md

路由 E：长任务 / 等待人工 / 可恢复执行

适用：

  • request_user_input
  • ask_human
  • waiting_human 暂停恢复
  • WAL replay / fork / resume
  • exec sessions 工程式交互

做法：

  • 先明确终态和恢复语义
  • waiting_human 不是失败态，必须单独处理
  • 长会话默认带 WAL、审批策略和超时/恢复策略

先读：

  • references/api-cheatsheet.md
  • references/testing-strategy.md

Skills 落地检查清单

  1. skill 目录结构最小形态：
    • skills/<skill_name>/SKILL.md
    • references/ 只放需要被读取的材料
    • actions/ 只放明确允许 skill_exec 调用的脚本
  2. 任务文本必须带 mention：
    • 正确：$[biz:myapp].order-summarizer
  3. 先做 CLI 校验：
skills-runtime-sdk skills preflight --workspace-root . --config config/runtime.yaml --pretty
skills-runtime-sdk skills scan --workspace-root . --config config/runtime.yaml --pretty

  1. 只有在 overlay 显式开启时才用：

    • skills.references.enabled=true
    • skills.actions.enabled=true

  2. skill_exec 的最小 frontmatter 例子：

---
name: artifact_builder
description: "动作型 skill：执行 actions/ 中声明的脚本。"
actions:
  build:
    kind: shell
    argv: ["python3", "actions/build_artifact.py"]
    timeout_ms: 5000
    env:
      ARTIFACT_KIND: "demo"
---

Agent / Workflow 落地检查清单

  1. 固定角色协作优先 Coordinator
  2. 动态并发/补充输入优先 collab primitives
  3. 默认使用 AgentBuilder 组装生产级能力：
    • backend
    • WAL
    • approval provider
    • hooks
  4. 人工介入流程必须检查：
    • waiting_human
    • run_waiting_human
    • resume / replay / fork
  5. 交付必须至少给出一条可运行回归命令

证据与完成定义

业务交付至少要有：

  1. 可运行入口：run.py 或等价主入口
  2. 最小 overlay：不写死 secrets，只声明 llm.api_key_env
  3. 离线回归：FakeChatBackend + 最小 smoke tests
  4. WAL 证据：
    • run_started
    • tool_call_*
    • approval_*（如有副作用）
    • skill_injected / plan_updated / human_request / human_response（按场景）
    • run_completed / run_failed / run_cancelled / run_waiting_human

常见误区

误区 正解
直接默认联网克隆仓库 先定位本地仓库；已有本地仓库时不要重新克隆
只写 agent，不写 skill 复杂项目先定 skill 边界，再写编排
把 waiting_human 当成失败 它是可恢复暂停态
默认放开所有工具审批 无人值守优先规则审批，默认 fail-closed
skill_ref_read / skill_exec 直接用 必须先显式开启 references/actions
只看最终输出，不看 WAL 副作用链路必须可审计、可回放

本地参考导航

  • API 与状态/事件：references/api-cheatsheet.md
  • 配置模板：references/config-templates.md
  • 场景配方：references/recipes-index.md
  • 安全/审批/沙箱：references/safety-and-sandbox.md
  • 测试与验证：references/testing-strategy.md
  • 仓库事实快照：references/repo-reading-map.md
Install via CLI
npx skills add https://github.com/okwinds/miscellany --skill bf-skillsruntime-dev
Repository Details
star Stars 48
call_split Forks 3
navigation Branch main
article Path SKILL.md
More from Creator
okwinds
okwinds Explore all skills →