BB V0.4

BB V0.4 是一个“上下文一切可配置”的统一 Agent Runtime。System instructions、当前输入、history、memory、retrieval、workspace、筛选、排序、预算、压缩、渲染、注入方式和 Tool Surface 都是独立的 Context Slot；每个 Slot 通过版本化 Adapter 选择实现，最终解析成不可变 Manifest v4 后才允许模型或工具执行。

V0.4 能力

Composition 是可复用的具名默认方案；它支持 extends，也允许每个 Slot 覆盖、多实例 source 和 run-scoped graph override。
Context Adapter Catalog 提供 instructions inline/request/file，history none/full/recent，memory none/MEMORY.md/session，retrieval none/workspace-keyword，workspace none/tree，以及每个处理阶段至少两种实现。
Tool Surface 与权限策略独立配置：none、readonly、coding、allowlist 可搭配 readonly、guarded、autonomous，但永远不能越过 Kernel permission ceiling。
内置 minimal、general.chat、workspace.analyze、coding.guarded、coding.file-memory、coding.session-memory 和 analysis.retrieval。
bb compositions list|inspect、bb context adapters、--composition、--composition-file 和 --session 提供稳定公共入口；旧 --recipe 继续作为兼容入口。
Harbor Adapter 支持 composition 或完整 composition_path，不同测试集可先选择不同方案再整批运行。
Manifest v4 保存完全展开的 Context Graph、Tool Surface、权限、memory record policy、模型绑定、限制、决策与稳定 digest。
Kernel invariants 不可配置：事件顺序、凭证脱敏、路径 containment、Schema 校验、provenance、durable dispatch 和权限上限。

V0.3 的 headless CLI、Harbor、权限恢复和 Provider 能力全部保留；Manifest v1-v3 与 Recipe API 继续可读可用。

V0.2 能力全部保留：

提供 general.chat、workspace.analyze 和 coding.guarded 三套版本化 Recipe，并把具体 Tool、Planning 和 Verification Policy 写入 Manifest v3。
提供 workspace.list、workspace.read、workspace.search、workspace.apply_patch 和 workspace.run_command 五个真实工具。
读操作在 Kernel ceiling 内自动执行；补丁和命令必须产生 durable permission.requested，用户明确批准后才能越过 tool.dispatch.committed。
权限等待保存 AI SDK continuation checkpoint。Host 重启后 Run 仍保持等待状态，批准或拒绝后可以恢复，不重复执行副作用。
支持 steerRun，等待期间补充的指令会进入恢复后的模型消息。
工具参数在 durable dispatch 前执行 Schema 校验；工具结果进入 Artifact Store，canonical Event 只保存稳定引用和摘要。
提供只依赖 Runtime Client / Host Protocol 的 Reference Coding Agent。
支持 openai、deepseek、qwen 和 kimi 四种用户级 Provider。
OpenAI 使用原生 AI SDK Adapter；DeepSeek、千问和 Kimi 共享 OpenAI-compatible transport，但拥有独立模型目录和能力档案。
AgentSpec.model 与 CLI --model 会形成 ResolvedModelBinding，并在首次模型请求前写入不可变 Manifest v2。
每次实际 provider 调用都有独立的 requestId。工具循环中的后续请求也会独立捕获。
请求与响应正文存入 SHA-256 内容寻址 Artifact Store；canonical Event 只保存摘要和稳定引用。
支持 metadata、redacted、full 三种捕获模式。所有模式都强制执行 secret redaction。
默认没有 Provider 配置时继续使用 Reference Mock，不访问网络、不产生费用。

安装与验证

需要 Node.js 22 或更高版本。

npm install
npm run check
npm run pack:cli

npm run check 会执行 TypeScript 检查、V0–V0.4 离线测试、依赖边界检查和 CLI 发行物检查。默认测试不会发送网络请求。npm run pack:cli 生成 .bb/harbor/bb-cli-0.4.0.tgz。

Headless CLI

bb --version
bb agent --workspace /app \
  --instruction-file /tmp/instruction.md \
  --composition coding.file-memory \
  --session project-42 \
  --model openai/gpt-5.2 \
  --capture metadata \
  --max-steps 12 --max-tokens 12000 \
  --result /logs/agent/bb-result.json \
  --events /logs/agent/bb-events.jsonl \
  --yes

instruction 可以来自位置文本、--instruction、--instruction-file 或 --stdin，且必须恰好选择一种。--yes 会自动响应 Runtime 产生的权限请求，但不会绕过 durable permission 与 dispatch 记录。

Composition 与 Context Adapter

npm run bb -- compositions list
npm run bb -- compositions inspect coding.file-memory
npm run bb -- context adapters
npm run bb -- run --composition analysis.retrieval "分析这个工作区"
npm run bb -- agent --composition-file ./examples/compositions/coding.file-memory.yaml --instruction "修复测试"

项目级 Composition 放在 .bb/compositions/*.yaml。默认 Composition 可在 .bb/config.yaml 选择：

context:
  defaultComposition: coding.file-memory

完整概念词汇见 CONTEXT.md，解析边界见 docs/adr/0001-resolve-compositions-before-execution.md，示例见 examples/compositions。Memory 的读取与写入是两个独立 Slot：memory.markdown 只读 MEMORY.md；memory.session 读取此前 memory.recorded 的 durable summary。更复杂的向量、图或远端 Memory 通过 composition root 注册新的 Adapter，无需修改 Runtime。

Provider 配置

复制 examples/config.v0.2.yaml 到 .bb/config.yaml，然后按需保留 Provider。配置只能保存环境变量名称，不能保存 API Key 明文。

最小配置示例：

providers:
  openai:
    type: openai
    apiKeyEnv: OPENAI_API_KEY

models:
  default: openai/gpt-5.2

在启动 Runtime Host 前设置对应环境变量：

export OPENAI_API_KEY="..."

OpenAI-compatible Provider 可以省略 baseURL 使用内置默认值，也可以写固定 HTTPS URL 或 ${ENV_NAME} 引用。API Key 本身不能出现在配置文件中。

内置能力档案是 2026-08-02 的固定快照，不会在运行时联网刷新。模型 ID 与限制依据 OpenAI Models、DeepSeek Models & Pricing、Qwen Model Studio 和 Kimi Platform；升级模型时应同步更新 profile version 与离线 fixture。

诊断 Provider 与模型

npm run bb -- provider list
npm run bb -- provider inspect deepseek
npm run bb -- models list
npm run bb -- models inspect deepseek/deepseek-v4-pro
npm run bb -- doctor

doctor 不产生付费请求。它检查配置、显式凭证引用、默认模型、Host 协议、Artifact Store 可写性和强制脱敏规则。

运行与实时观察

npm run bb -- run "检查这个工作区"
npm run bb -- run --recipe general.chat "解释这个概念"
npm run bb -- run --recipe workspace.analyze "分析这个项目"
npm run bb -- run --recipe coding.guarded "修改代码并运行测试"
npm run coding-agent -- "修复当前测试失败"
npm run bb -- run --model openai/gpt-5.2 "分析这个项目"
npm run bb -- run --model deepseek/deepseek-v4-pro "分析这个项目"
npm run bb -- run --model qwen/qwen3-max "分析这个项目"
npm run bb -- run --model kimi/kimi-k2.5 "分析这个项目"

coding.guarded 的写入和命令默认交互式询问。--yes 会自动同意本次 Run 的权限请求，只应在调用方已经授予该自主级别时使用：

npm run bb -- run --recipe coding.guarded --yes "修改代码并运行测试"

非交互终端会保留等待状态并输出恢复命令，也可以显式响应权限或补充 steering：

npm run bb -- permission <run-id> <permission-id> allow
npm run bb -- permission <run-id> <permission-id> deny
npm run bb -- steer <run-id> "先不要改配置文件，改测试实现"

查看可用 Recipe：

npm run bb -- recipes list
npm run bb -- recipes inspect coding.guarded

实时显示模型 I/O：

npm run bb -- run --show-request "分析这个项目"
npm run bb -- run --show-response "分析这个项目"
npm run bb -- run --show-io "分析这个项目"

未显式指定 capture mode 时，显示选项会把有效模式从默认的 metadata 提升到 redacted；显式 --capture metadata 会被尊重，此时只显示 metadata。显示选项不会改变模型可见消息、工具、预算、执行结果或终止原因。

显式选择捕获模式：

npm run bb -- run --capture metadata "分析这个项目"
npm run bb -- run --capture redacted "分析这个项目"
npm run bb -- run --capture full "分析这个项目"

full 只表示保留完整业务正文，不会关闭凭证脱敏。

运行后恢复 I/O

npm run bb -- inspect <run-id> --request
npm run bb -- inspect <run-id> --response
npm run bb -- inspect <run-id> --io
npm run bb -- inspect <run-id> --io --step 2
npm run bb -- inspect <run-id> --io --request-id <request-id>
npm run bb -- manifest <run-id>

持久化目录：

.bb/runs/<run-id>.jsonl
.bb/artifacts/sha256-<digest>.json

Artifact 目录和文件分别使用当前用户权限 0700 与 0600。读取时会重新验证内容摘要。

从 V0.2 迁移

原有源码入口 npm run bb -- ...、Host Protocol v2、Manifest v3、Recipe、权限恢复和 Provider 配置继续兼容。
自动化调用方应改用 bb agent，并消费 schema-versioned result 和 Runtime envelope JSONL，而不是解析交互 CLI 输出。
Provider function-name 限制由 Engine Adapter 内部处理；Recipe 和用户代码继续使用 workspace.apply_patch 等 canonical 名称。
Harbor 是可选 Adapter，不进入 Core/Runtime，也不要求安装 SWE-bench harness。

V0.1 到 V0.2 的兼容说明仍适用：

无配置的 Reference Mock 路径保持兼容，原有 bb run、bb inspect 和 bb manifest 仍可使用。
新运行使用 Manifest v2 并增加 modelBinding 与 captureMode；Manifest v1 仍可读取。
老式无 envelope 的 JSONL 事件可以兼容读取，Host 启动不会因历史记录失败。
V0 默认 observability 曾偏向完整内容；V0.1 默认 capture mode 改为更安全的 metadata。
Provider 选择不再只是字符串标签。不存在、未配置、缺少凭证或能力不兼容会在请求发送前失败。
DeepSeek 的 deepseek-chat 与 deepseek-reasoner 已在 2026-07-24 停用，V0.1 目录使用 deepseek-v4-flash 与 deepseek-v4-pro。DeepSeek adapter 会持久化并在工具循环中回传 Provider 返回的 reasoning_content。
Host Protocol 升级到 v2；V0.2 Host 会声明 manifest-v3、recipes-v1、permissions-v1 和 steer-v1 capability。
未指定 Recipe 时 Host 默认使用 general.chat。需要读取工作区时显式选择 workspace.analyze，需要修改或运行命令时选择 coding.guarded。
Manifest v1/v2 继续可读取；新 Run 写入 Manifest v3。

故障排查

credential_missing：确认 .bb/config.yaml 的 apiKeyEnv 名称正确，并在启动 Host 的同一环境中设置变量。已运行的 Host 不会自动继承后来设置的变量，需要重启。
provider_not_configured：在配置文件中添加对应 Provider；仅模型目录中存在并不代表 Provider 已启用。
model_not_found：使用 bb models list 中的完整引用，或检查 alias 指向。
invalid_base_url：使用有效的 HTTP/HTTPS URL；${ENV_NAME} 引用必须在 Host 启动前存在。
capability_mismatch：当前 Reference Recipe 需要 streaming 和 tool calling，请选择支持这些能力的模型。
Artifact 无法读取：运行 bb doctor 检查目录写权限；摘要不匹配表示文件被修改，应保留 journal 并隔离损坏 artifact。

真实 API smoke

真实请求测试默认跳过。只有在人工确认费用并配置全部四种凭证后才运行：

BB_REAL_PROVIDER_SMOKE=1 npm run test:smoke

也可以把四家凭证填入 Git 忽略且仅本机可读的 .bb/provider-keys.env，然后运行：

npm run test:smoke:file

如只获准测试部分 Provider，可显式指定逗号分隔的子集；receipt 会同时记录已测和跳过项：

BB_SMOKE_PROVIDERS=openai,deepseek,qwen,kimi npm run test:smoke:file

Runtime Host 会自动识别大小写形式的 HTTP_PROXY、HTTPS_PROXY、ALL_PROXY 和 NO_PROXY；正常 CLI 与 smoke 使用相同的代理路径，代理凭证也会加入强制脱敏集合。

该测试会对四种 Provider 各发送一次最大输出 64 token、最多一步的请求，并把不含正文和凭证的 smoke receipt 写入 .bb/smoke/v0.4-<timestamp>.json。离线 CI 不把真实 smoke 当作自动网络步骤。

汇总多次 receipt 并检查完成度：

npm run audit:smoke
BB_SMOKE_REQUIRED_PROVIDERS=openai,deepseek,qwen,kimi npm run audit:smoke

默认要求四家全部成功；子集只用于明确暂缓某些 Provider 的阶段性验收。新 receipt 还会验证固定输出标记和 token usage，但不会保存模型正文。

架构边界

core 仅包含纯合同，不依赖 Node、网络、文件系统、AI SDK 或 Provider SDK。
runtime 负责模型解析、能力预检、Manifest、artifact/event commit 顺序和终止语义，不读取 API Key。
engine-ai-sdk 是唯一允许依赖 ai 和 @ai-sdk/openai 的包。
runtime-host 是唯一 composition root，负责配置、环境变量凭证解析、Registry、Engine、Artifact Store 和恢复。
CLI 与 Benchmark 只通过版本化 Host Protocol 工作。
Runtime 是权限和副作用顺序的最终 authority；AI SDK approval 只作为可序列化 continuation，不代替 Kernel policy。

Harbor Adapter

env -u all_proxy uv tool install --with-editable ./integrations/harbor harbor==0.16.1
npm run pack:cli
harbor run \
  --path integrations/harbor/fixtures/file-repair \
  --agent bb_harbor_adapter.agent:BBAgent \
  --model openai/gpt-5.2 \
  --agent-env 'OPENAI_API_KEY=${OPENAI_API_KEY}' \
  --env-file .bb/provider-keys.env \
  --n-concurrent 1 --yes

更完整的 Adapter 说明见 integrations/harbor/README.md。完整 V0.4 验收标准见 ../study/bb-v0.4-implementation-plan.md。

Name		Name	Last commit message	Last commit date
apps		apps
docs/adr		docs/adr
examples		examples
integrations/harbor		integrations/harbor
packages		packages
scripts		scripts
tests		tests
.gitignore		.gitignore
CONTEXT.md		CONTEXT.md
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

BB V0.4

V0.4 能力

安装与验证

Headless CLI

Composition 与 Context Adapter

Provider 配置

诊断 Provider 与模型

运行与实时观察

运行后恢复 I/O

从 V0.2 迁移

故障排查

真实 API smoke

架构边界

Harbor Adapter

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

BB V0.4

V0.4 能力

安装与验证

Headless CLI

Composition 与 Context Adapter

Provider 配置

诊断 Provider 与模型

运行与实时观察

运行后恢复 I/O

从 V0.2 迁移

故障排查

真实 API smoke

架构边界

Harbor Adapter

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages