bf-skillsruntime-dev

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)