@zhoudongyan/awp-cli

v0.1.1

Published

a month ago

Agent Workflow Protocol reference runtime for portable multi-agent workflows.

0High
0Medium
0Low

zhoudongyan

agent workflow multi-agent mcp awp

Agent Workflow Protocol

Agent Workflow Protocol（AWP）是一种轻量、声明式的 Agent 工作流格式，用来封装可复用的 agentic workflow 方法论。

AWP 不是另一个自主 Agent、IDE 助手或模型网关。它是一个工作流格式，以及一个很薄的参考 runtime：负责协调流程、委托执行、记录 artifacts 和 trace。

MCP 标准化 Agent 如何访问工具。
Skill 封装可复用能力。
AWP 标准化可复用工作方法论。

English: README.md

状态

AWP 仍处于实验阶段。当前原型实现了 AWP 0.1，包含 TypeScript CLI 和 dry-run runner。

为什么需要 AWP

Agent 能力正在快速提升，但很多成功的 Agent 工作流仍然依赖隐性的过程知识：应该有哪些角色参与、最终回答前需要哪些检查、应该产出哪些中间证据、结果如何被复核。如果没有一个可移植的工作流层，这些知识往往会散落在聊天记录、一次性 prompt、本地脚本或某个特定 Agent Host 中。

AWP 的价值是让这些方法论可以被复用：

把专家流程变成可版本化的 package；
把工作流结构与模型、工具、宿主实现细节解耦；
用 artifact 显式保存中间产物；
用 trace 让每次运行可检查、可审计；
让不同 Agent Host 可以用各自方式执行同一个 workflow。

从这个角度看，Agent 与 Workflow 应该是螺旋式上升的关系：

更强的 Agent 让更复杂的 Workflow 成为可能。
设计良好的 Workflow 沉淀可复用模式、约束和质量门禁。
这些模式产生更好的评测数据和运行反馈。
更好的反馈反过来改进 Agent、工具和下一代 Workflow。

AWP 是这个循环中可以标准化的一层。它不是冻结 Agent 行为，而是捕获可复用的编排意图，让 Agent 系统在持续进化时不丢失过程知识。

定位

AWP 位于 MCP 和 Skill 之上、具体应用产品之下：

Tools / APIs       → 具体动作和数据访问
MCP                → 工具与上下文连接
Skills             → 可复用的单项能力
AWP                → 可复用的多步骤工作流方法论
Agent Hosts        → 执行、模型选择、上下文管理、工具选择
Applications       → 面向领域的用户体验

AWP package 回答的是：应该执行什么流程？

Agent Host 或 runner 回答的是：在当前环境中，每一步应该如何执行？

核心原则

Delegation-first：AWP 描述工作流结构，具体如何执行由宿主环境决定。
不配置模型：AWP package 不要求用户配置 LLM provider、API key 或默认模型。
工具无关：AWP package 不声明具体 MCP server、tool、skill 或 runner。
Artifact-first：每次运行都应产生命名 artifact 和 trace。
小核心：MVP 只标准化 task、parallel、iterate。

文件结构

my-workflow/
  awp.yaml        # package 元信息和触发提示
  workflow.yaml   # 默认 workflow 入口
  agents/         # 可复用角色说明
  prompts/        # step 级任务提示词

AWP 0.1 使用 YAML 作为主要编写格式，使用 JSON Schema 做校验和编辑器支持。

最小 package

# awp.yaml
$schema: https://awp.dev/schemas/package-v0.schema.json
awp: "0.1"

metadata:
  name: investment/research-committee
  version: 0.1.0
  description: Multi-perspective investment research workflow.

capabilities:
  - investment_analysis
  - multi_perspective_review

requires:
  host:
    reasoning: high
    context_window: ">=32000"

# workflow.yaml
$schema: https://awp.dev/schemas/workflow-v0.schema.json
awp: "0.1"

metadata:
  name: investment-research-committee
  version: 0.1.0

inputs:
  ticker:
    type: string
    required: true

agents:
  analyst:
    system: You are an investment analyst.

steps:
  - id: analyze
    type: task
    agent: analyst
    prompt: Analyze {{ticker}}.
    output: analysis_report

Step 类型

AWP 0.1 只标准化三个通用 step：

task：把一个任务委托给一个 agent。
parallel：从同一上下文出发执行多个独立分支。
iterate：重复执行一组步骤，直到满足自然语言停止条件或达到最大迭代次数。

辩论、审查、投票、审批、风控挑战等领域动作不进入 v0 核心 step，应先用这些通用 step 组合成 workflow pattern。

CLI 使用

这个仓库已经包含 reference AWP CLI。npm package 通过 package.json 里的 bin 字段暴露可执行命令 awp。

安装依赖并构建：

npm install
npm run build

验证示例 workflow：

npm run validate

运行 dry-run 示例：

npm run demo

直接使用 CLI：

awp validate examples/investment-research-committee/workflow.yaml

# dry-run 必须显式指定。纯 `awp run ...` 在没有 runner 时会失败。
awp run examples/investment-research-committee/workflow.yaml \
  --input ticker=NVDA \
  --input horizon=long_term \
  --dry-run

# 把每个 step 委托给本地命令。step payload 通过 stdin 传入；
# stdout 会作为 step artifact。
awp run examples/investment-research-committee/workflow.yaml \
  --input ticker=NVDA \
  --input horizon=long_term \
  --runner command \
  --command "claude -p"

发布前的本地开发用法：

node dist/cli.js validate examples/investment-research-committee/workflow.yaml
npm link
awp --help

发布到 npm 后，用户可以这样安装或直接运行：

npm install -g @zhoudongyan/awp-cli
awp --help

# 或不全局安装，直接使用 npx
npx @zhoudongyan/awp-cli validate ./workflow.yaml

输出结构：

runs/<run_id>/
  trace.json
  artifacts/
    company_brief.md
    final_report.md

如何使用 AWP

AWP 主要有三种使用方式。

1. 编写 workflow package

创建一个 package 目录，包含 awp.yaml、workflow.yaml、可选的 agents/ 和可选的 prompts/ 文件。agents/ 用于可复用角色说明，prompts/ 用于 step 级任务提示词。

my-workflow/
  awp.yaml
  workflow.yaml
  agents/reviewer.md
  prompts/review.md

然后进行校验：

node dist/cli.js validate my-workflow/workflow.yaml

2. 使用参考 runtime 运行

当前 runtime 支持显式 dry-run 执行。它适合在接入真实 Agent Host 之前检查 workflow 结构、prompt 渲染、artifact 连接和 trace 生成是否正确。

node dist/cli.js run my-workflow/workflow.yaml \
  --input ticker=NVDA \
  --dry-run

它也支持显式 command runner，用于委托本地命令执行：

node dist/cli.js run my-workflow/workflow.yaml \
  --input ticker=NVDA \
  --runner command \
  --command "claude -p"

AWP 不会隐式调用本地 Agent CLI。如果既没有提供 --dry-run，也没有提供 --runner，awp run 会直接报错。

3. 集成到 Agent Host

Agent Host 可以把 AWP 当作类似 Skill 的可安装 workflow package。宿主应当：

通过 awp.yaml 的 metadata 和 activation hints 发现 package；
根据 schema 和语义规则校验 workflow.yaml；
把每个 AWP agent/step 映射到宿主自己的执行机制；
自行决定使用哪个模型、工具、MCP server、skill 和上下文；
写入 artifacts 和 trace.json，保证可审计。

在宿主集成模式下，AWP 仍然是声明式的。它不直接调用模型，也不要求用户配置单独的 AWP model provider。

Package 生态与本机安装目录

用户编写的 AWP workflow 应该以 AWP package 的形式分发：一个目录或归档文件，包含 awp.yaml、workflow.yaml，以及可选的 agents/ 和 prompts/。CLI/runtime 自身可以作为 @zhoudongyan/awp-cli 发布到 npm，但 workflow package 应该形成独立的 AWP 生态。

推荐生态模型：

Author workspace       → 作者创建和测试 package 的地方
AWP Registry           → 可搜索 metadata、版本、可信信号、package URL
Package artifact store → tarball、Git repo、npm package、OCI artifact 或托管 archive
Local AWP store        → 用户机器上已安装的 package
Agent Host             → 发现已安装 package，并委托执行

推荐的本地安装目录不是 ~/.awp/workflow，因为安装单元不是单个 workflow 文件，而是 package。建议使用：

~/.awp/
  packages/
    <package-name>/
      <version>/
        awp.yaml
        workflow.yaml
        agents/
        prompts/
  registry/
    installed.json
  cache/
  runs/

例如，investment/research-committee 这个 package 的 0.1.0 版本会安装到：

~/.awp/packages/investment/research-committee/0.1.0/

也可以通过 AWP_HOME 覆盖安装位置：

AWP_HOME=/tmp/awp awp install ./examples/investment-research-committee

当前 package-management 命令：

awp home
awp install ./examples/investment-research-committee
awp install git+https://github.com/org/awp-investment-research-committee.git
awp install git+https://github.com/org/awp-investment-research-committee.git#v0.1.0
awp install https://example.com/packages/foo-0.1.0.tgz
awp install ./foo-0.1.0.tgz
awp list
awp uninstall investment/research-committee 0.1.0

awp install 当前支持：

本地 package 目录；
带 git+ 前缀的 Git repository URL，并支持在 # 后指定 branch/tag；
来自本地路径、file:// URL 或 HTTP(S) URL 的 .tgz、.tar.gz、.tar archive。

Archive 和 Git source 可以把 AWP package 放在仓库/archive 根目录，也可以放在顶层子目录中。installer 会搜索 awp.yaml 和 workflow.yaml，校验 workflow，把 package 文件复制到本地 store，并写入 registry/installed.json。

Registry 能力建议分阶段演进：

Local install：从本地 package 目录安装。
Git/URL install：从 Git repo 或 tarball URL 安装。reference CLI 已经提供基础支持。
Registry install：通过 AWP registry index 解析 name@version。
Host discovery：Agent Host 读取本机 store，把已安装 workflow 像 skill 一样展示和触发。

作为 library 使用

当前 package 主要是 reference CLI，但也导出了一个很小的编程 API，方便 runtime 和 host integration 复用 parser、validator、dry-run runner 和核心类型。

import { DryRunStepRunner, loadWorkflow, runWorkflow, type WorkflowDocument } from "@zhoudongyan/awp-cli";

const workflow: WorkflowDocument = await loadWorkflow("./workflow.yaml");

const result = await runWorkflow({
  workflowPath: "./workflow.yaml",
  inputs: { ticker: "NVDA" },
  dryRun: true
}, new DryRunStepRunner());

console.log(workflow.metadata.name, result.tracePath);

这个 API 会保持尽量小。未来更适合提供独立的 @awp/sdk package，用来提供稳定的 host integration interface、package discovery、registry client、typed schema helper 和 runner adapter。

发布到 npm

发布到公开 npm registry：

npm login
npm run check
npm run pack:dry-run
npm publish --access public

注意：

@zhoudongyan/awp-cli 这类 scoped public package 第一次发布时需要 --access public。
如果 @awp scope 或 package name 不可用，可以先使用自己拥有的 scope，例如 @your-scope/awp-cli，后续再迁移。
如果发布到私有 registry，显式指定 registry：

npm publish --registry https://registry.example.com

当前 package 会包含 dist/、schemas/、spec/ 和 examples/。prepublishOnly 会在发布前执行 npm run check。

注册 npm scope

npm scope 是 package 名称里斜杠前面的命名空间，例如 @zhoudongyan/awp-cli 里的 @zhoudongyan。

实际有两种方式：

用户 scope：每个 npm 账号天然拥有自己的用户 scope。如果你的 npm 用户名是 alice，登录后可以发布 @alice/awp-cli 这类 package。
组织 scope：如果想使用 @awp 这种共享项目 scope，需要在 npmjs.com 创建名为 awp 的 organization，然后在该组织下发布 @awp/* package。

推荐的首次公开发布流程：

# 1. 创建或登录 npm 账号
npm login

# 2. 检查目标 org/scope 是否存在，以及你是否有权限
npm org ls awp

# 3. 如果你拥有该 org/scope，公开发布 scoped package
npm publish --access public

如果 awp organization 已经被占用，或者你没有权限，先使用自己拥有的 scope：

{
  "name": "@your-scope/awp-cli"
}

然后发布：

npm publish --access public

如果要长期做生态品牌，最好保留一个 organization scope，例如 @awp 或 @agent-workflow-protocol，后续可以发布：

@awp/cli
@awp/sdk
@awp/schema
@awp/create-package

Roadmap

AWP 0.1 是最小可用协议和 reference runtime。后续重点应该放在生态接入，而不是把 runtime 做成完整 Agent Host。

AWP SDK：优先提供 Node.js SDK，后续可扩展 Python，提供稳定的 workflow 加载、校验、运行、trace 和嵌入式集成 API。
Host integration API：让 Claude Code、Codex-like CLI、IDE Agent 和内部 Agent Host 能安装并执行 AWP package，但不让 AWP 接管模型执行。
Runner adapters：支持 host delegation、local command、MCP tool、skill 和 test/dry-run 环境。
Package management：提供本地 AWP workflow package 的 install/list/update/remove 命令。
Registry metadata：支持可搜索 package metadata、capabilities、activation hints、兼容性信息和可信信号。
Conformance tests：提供共享测试夹具，验证第三方 runtime 是否一致实现 AWP 语义。
Editor tooling：提供 schema-aware 编写支持、校验诊断、流程图可视化、artifact/trace 查看器。
Workflow patterns：沉淀 review、debate、research、coding、incident response、due diligence、evaluation 等可复用模式。

规范

英文规范：spec/v0.md
中文规范：spec/v0.zh-CN.md

Schema

Community

贡献指南：CONTRIBUTING.md
安全策略：SECURITY.md
行为准则：CODE_OF_CONDUCT.md

非目标

AWP 不替代 Claude Code、Codex、Gemini CLI、Cursor、MCP 或 Skills。

AWP 不决定使用哪个 LLM、tool、MCP server、skill 或 runner；这些由 Agent Host 或执行环境决定。

License

MIT