能力与初始化

能力目录与项目初始化复制本节链接

import { CapabilityRegistry, bootstrapProject, createWorkspaceTools } from './packages/sdk/src/index.mjs';

const registry = new CapabilityRegistry({
  tools: await createWorkspaceTools(cwd, { deniedPaths: [stateDir] }),
  skills: [{
    id: 'project-analysis',
    path: resolve('packages/sdk/skills/project-analysis/SKILL.md'),
    enabled: true,
    trusted: true,
  }],
});

try {
  const initial = await bootstrapProject({
    title: '数据库迁移助手',
    description: '为已有系统提供可验证、可恢复的迁移流程。',
    catalog: await registry.catalog(),
    model,
    apiKey: process.env.RNA_MODEL_API_KEY,
  });
  if (initial.status !== 'ready') throw new Error(initial.reason);

  const assigned = await registry.resolve(initial.assignments);
  console.log(initial.overview, initial.focus, assigned.tools.map((tool) => tool.name));
} finally {
  await registry.close();
}

• 所有技能、工具和 MCP 分配都必须来自启用且可信的能力目录，并逐项说明原因。
• 目录只提供技能元数据，正文在相关时再加载。
• bootstrapProject 不执行工具，也不安装插件；ready 的输出包含经过真实脚本冒烟检查的项目能力包（ProjectGenome）。
• 没有真实模型时返回 blocked。

预算准入复制本节链接

beforeRequest({ attempt, estimatedTokens, usage, signal }) 在每次生成或修复请求前调用，抛错即阻止该次请求。bootstrap_request_start 和 bootstrap_request_end 事件给出逐次的用量，结束事件包含本次 requestUsage 和累计 usage。

usage.totalTokens 包含实际报量和缺报时的估算，usage.estimatedTokens 单列估算部分。估算不是账单。

工作区工具复制本节链接

createWorkspaceTools(cwd, options) 默认只提供读取类工具。显式 includeMutations 后加入：

• hash 校验的写入与原子发布；
• 精确编辑；
• 可取消的命令执行，带超时、输出截断和完整输出日志。

命令由独立的 command guardian 运行：取消时先 TERM，300 ms 后 KILL，并回收同一进程组的后代。guardian 本身失联时，调用返回 cleanupUncertain，不会按旧 PID 猜测补杀。这是 POSIX 进程组边界，不是沙箱。

动态能力复制本节链接

beforeRequest({ signal, snapshot }) 可以返回 { tools, contextUpdates }：

• tools 是完整的新工具集合，宿主应先完成权限筛选；
• contextUpdates 的 { key, source, text } 按内容 hash 去重并持久化，作为来源明确的参考资料进入会话。

它在上一批工具全部完成后、下一次模型请求前等待。失败或取消时不会继续发请求。

MCP复制本节链接

McpClient 支持 stdio 与 Streamable HTTP 的请求和响应子集。每个 stdio 服务前有一个轻量的 guardian：宿主被强制结束后，它通过 stdin EOF 或 250 ms 的父进程检查发现失联，对自己拥有的服务进程组先 TERM、500 ms 后 KILL。Registry 关闭时会取消连接中的客户端并等待子进程退出。