pi-tsien-capability0.1.2

Capability layer: register and run reusable, verifiable execution units as pi tools.

tsien1992 Published 23 days ago MIT ~438 downloads/mo

Untested on omp

This is a pi package. No one has reported whether it works on omp yet. If you try it, add your result below.

Reports 0

No reports yet.

Readme

capability

把重复出现的任务沉淀成可复用、可验证、可分层共享的执行单元。

一个 capability = 一份契约（CAPABILITY.yaml）+ 一套实现（impl/run.mjs，可选 prompts/）+ 证据（cases.jsonl）。代码在 node --permission 沙箱里跑：无网络、读写受限，因此 API key 永不进入沙箱；模型调用由宿主代理，并统一记账。

零依赖接入

本扩展不假设任何特定仓库存在。capability 目录放在哪里都行，以下来源都会被扫描（后者覆盖前者，同名时业务能力压过通用能力）：

层	位置	说明
L1	`src/capability/capabilities/`	随本扩展内置的通用能力
L2	`<项目目录>/.pi/capabilities/`	任何仓库带上这个目录就能用，无需配置
L2	`~/.pi/agent/capability/capabilities/`	用户全局
L2	`~/.pi/agent/capability.json` 的 `roots`	指向任意仓库或目录
L2	环境变量 `PI_CAPABILITY_ROOTS`	测试 / 临时覆盖，`:` 分隔

例：让一个团队仓库贡献能力，只要在 ~/.pi/agent/capability.json 写

{ "roots": ["/path/to/your-team-repo/capabilities"] }

目录布局

两种都支持：

<root>/<name>/CAPABILITY.yaml              # 扁平
<root>/<name>/current/CAPABILITY.yaml      # marketplace 包布局

一个能力自包含：

<name>/
  CAPABILITY.yaml     # 契约
  impl/run.mjs        # 沙箱入口：stdin 收 job，stdout 出帧
  prompts/*.md        # llm 步骤的模板，{key} 占位符
  cases.jsonl         # 回归用例

CAPABILITY.yaml

name: log-triage
version: 0.1.0
sensitivity: public | internal | local   # 决定它属于哪一层
status: draft | trusted                  # 只有人工能改成 trusted
description: 一句话说明
when: 何时该用（会进入系统提示）
steps:
  - id: parse
    kind: code                           # 沙箱内确定性步骤
  - id: triage
    kind: llm                            # 宿主代理的模型调用
    prompt: prompts/triage.md
    model: provider/model
    max_tokens: 256
limits:
  max_llm_calls: 1
  timeout_ms: 30000

实现协议

impl/run.mjs 通过 stdout/stdin 每行一个 JSON 帧通信：

// 沙箱 -> 宿主
{ "__frame__": "rpc", id, prompt_id, input, max_tokens }  // 请求模型
{ "__frame__": "result", output }                          // 终止帧
// 宿主 -> 沙箱
{ "__frame__": "job", input }
{ "__frame__": "rpc_result", id, ok, data?, error? }

沙箱里拿不到密钥、也连不上网，只能这样请求模型。

工具与命令

入口	谁触发	作用
`capability_ls`	模型	列出能力（层、状态、敏感度、when）
`capability_run`	模型	在沙箱执行某个能力
`/capability`	用户	列出能力
`/capability promote <name>`	仅用户	`draft → trusted`
`/capability demote <name>`	仅用户	`trusted → draft`

promote/demote 做成命令而不是工具，因为工具是模型可调的——晋升必须由人决定。

运行产物

都写在用户目录，不污染任何仓库：

~/.pi/agent/capability/ledger/YYYY-MM-DD.jsonl     # 每次调用的 token / 成本 / 耗时
~/.pi/agent/capability/skills/capability/SKILL.md  # 自动生成，用于让模型知道有哪些能力

为什么值得用

子任务在对话里做，成本是这一轮携带的完整上下文；作为 capability 执行，是独立的最小调用。实测单步能力约 60–190 tokens，而长会话单轮上下文是 2,000–39,000 tokens。

代价是多一次工具往返（约 1 秒）和常驻的工具 schema。所以它适合重复出现、需要固定输出结构、需要留痕的任务，不适合一次性小问题。