AXF

AXF

为代码仓库适配一次。让每个 Agent 都沿着同一条铺好的路前进。

Agent 可以读取你的代码，但仍然需要重新摸索这个代码仓库希望如何构建、测试、搜索、诊断和运维。相关线索通常散落在脚本、软件包任务、说明文字、CI 和人的记忆中。

AXF（Agent eXoskeleton Framework）将这些反复出现的本地操作流程转化为小巧、自描述的能力。精心适配一次这套外骨骼；此后，Agent 就能发现正确路径、查看其契约，并直接运行，而无需从头重建流程。

recurring repository ceremony
          ↓ fit once
inspectable AXF capabilities
          ↓ reuse
agent discovers → inspects → runs

AXF 是交通指挥员，而非替换词汇的工具。默认情况下，它会保留提供方现有的命令体系，只投影或规范化那些需要更清晰的 Agent 侧契约的部分。目标不是实现判断自动化，而是减少为了重建相同路径而反复做判断。

调用方的五个概念

使用适配后的代码仓库，不需要了解框架术语：

• 工作区 — 需要了解其操作路径的代码仓库上下文。在对根目录敏感的契约中，AXF 会区分用于发现的项目根目录与作为运行时工作目录的执行根目录。
• 模块 — 可复用的能力包，例如内置的 echo 模块或代码仓库自有的验证包。
• 能力 — 一个具名操作，声明了参数、输出模式、副作用、生命周期、策略和执行目标。
• 检查 — 执行前读取完整契约。
• 运行 — 检查其影响和权限要求后，通过契约执行。

最小可行示例如下：

npm install --global @smartergpt/axf
axf doctor
axf list --compact
axf inspect echo say
axf run echo say --message hello

AXF 2.1.5 以 Apache-2.0 许可发布；更早的 npm 版本则沿用其发布时的许可条款。在未适配的工作区中，且未设置根目录覆盖项时，此示例会发现已安装软件包中自带的清单。doctor 会分别报告项目根目录和当前执行目录。显式设置的 AXF_PROJECT_ROOT 会覆盖自动发现结果；没有 axf.workspace.json 标记的空目录不包含任何能力。经过适配的代码仓库通常会添加自己的能力；echo.say 仅用于证明注册表、解析器、适配器和执行器已连通。

适配前后

使用 AXF 之前，新 Agent 需要搜索多个指令文件、逆向分析软件包脚本、猜测安全的验证子集，并在下一次会话中重复这些工作。

经过精心适配后，代码仓库可以提供 context、check 和 handoff 等稳定入口。调用方从 axf guide 开始，检查选定的能力，然后运行代码仓库自有的路径。AXF 让路径清晰可见；路径仍由代码仓库掌控。

这个代码仓库适合适配吗？

以下情况适合使用 AXF：

• Agent 反复猜测应该使用哪条构建、测试或验证命令；
• 每次编辑前都必须重新发现相同的代码仓库信息；
• 本地安全规则散落在说明文字、惯例或人的记忆中；
• 脆弱的 Shell 命令链一再被重新拼接，用于处理代码仓库特有的杂务。

如果一条明确的命令已能完成任务、操作流程不太可能重复，或者提供方接口变化太快以至于团队无法维护能力契约，那么 AXF 可能并不适用。

是否采用 AXF，取决于：

这个代码仓库是否存在反复出现的本地操作流程，值得将其适配一次，转化为稳定且可检查的 Agent 能力？

如需进行范围明确且严格只读的评估，请向 Agent 提供以下提示词：

Evaluate whether this repository is a fit for AXF by following
docs/agent-evaluation.md. Do not install AXF, edit files, scaffold or promote
capabilities, invoke MCP tools, or run repository code. Inspect only the
existing scripts, package tasks, documentation, agent instructions, CI and
platform/runtime constraints. Identify repeated mistakes and existing overlap,
then return exactly one verdict: adopt, pilot, defer, or not a fit. Include the
evidence, expected fitting cost, ongoing drift cost, authority boundaries, and
the smallest reversible pilot. Do not perform the pilot without separate
approval.

请参阅Agent 适配评估，了解证据检查清单、评估结论定义和回复模板。

选择适合你的路径

你是……	从这里开始	你的工作
调用方或编码 Agent	调用方指南	发现、检查并运行他人配置的功能。
集成作者	集成作者指南	将现有代码库或提供方的流程配置为稳定的功能。
AXF 框架作者	框架作者指南	修改加载器、解析、适配器、策略、MCP 或其他 AXF 内部组件。

除非你负责配置提供方或修改 AXF 本身，否则请止步于调用方指南。完整的受众分类见 文档分层。

状态：alpha。核心循环已就绪：通过一个契约来侦察、检查、执行、 搭建脚手架并推广功能。清单版本 axf/v0 是当前的 alpha 契约。

AXF 不是什么

AXF 不是通用命令目录、授权来源、提供方身份的替代品、审核的替代品，也不是仅面向 MCP 的产品。MCP 是面向 Agent 的一种界面，它使用相同的注册表和执行路径。

安装和 MCP

许可证

AXF 根据 Apache License, Version 2.0 授权， 允许在其条款下用于商业和组织用途。请保留适用的 声明。早期版本仍遵循各自适用的条款。

SmarterGPT 由 Joseph Gustavson（Guffawaffle）创立。请参阅 项目治理、贡献指南和 项目标识。代码许可不授予运行时权限。

npm 包名为 @smartergpt/axf。它会安装两个可执行文件：

• axf — CLI 入口点，包括 stdio MCP 启动子命令 axf mcp
• axf-mcp — stdio MCP 服务入口点

MCP 客户端可以直接启动 axf-mcp。对于由注册表或包驱动的启动方式，建议使用 axf mcp，以便让包围绕基础的 axf 命令界面展开。两个入口点都会启动相同的 stdio MCP 服务。该服务恰好暴露一个名为 axf 的 MCP 工具，并将该工具路由到绑定工作区现有的 AXF 功能界面。

全局安装

npm install --global @smartergpt/axf

然后直接使用任一可执行文件：

axf doctor
axf mcp
axf-mcp

在假定已配置的服务与已安装的 CLI 匹配之前，请先审核 Codex MCP 包的固定版本：

axf integrate codex --check
axf integrate codex --write
axf integrate codex --check --smoke

写入操作仅限于 Codex config.toml 中的 AXF 包规格；之后请重启或重新打开 Codex。如需一次调用即可完成 AXF + Lex 引导，包括明确的 off | shadow KnowledgeFrame 提供方推出方式，请参阅打包的 templates/session-context 工作区配方和 docs/13-repo-onboarding.md。

仓库本地开发启动

从本地克隆仓库运行时，使用 Node 直接运行可执行文件：

node /path/to/axf/bin/axf.js doctor
node /path/to/axf/bin/axf.js mcp
node /path/to/axf/bin/axf-mcp.js

仓库本地的 MCP 配置可以调用直接 MCP 可执行文件，也可以调用 CLI 子命令。若客户端能够妥善处理命令参数，建议使用 CLI 子命令：

{
  "mcpServers": {
    "axf": {
      "command": "node",
      "args": ["/path/to/axf/bin/axf.js", "mcp"],
      "cwd": "/path/to/project",
      "env": {
        "AXF_PROJECT_ROOT": "/path/to/project",
        "AXF_EXECUTION_ROOT": "/path/to/project"
      }
    }
  }
}

直接调用可执行文件的配置仍然有效：

{
  "mcpServers": {
    "axf": {
      "command": "node",
      "args": ["/path/to/axf/bin/axf-mcp.js"],
      "cwd": "/path/to/project",
      "env": {
        "AXF_PROJECT_ROOT": "/path/to/project",
        "AXF_EXECUTION_ROOT": "/path/to/project"
      }
    }
  }
}

npm / npx 启动

已发布包的冒烟测试必须在干净目录（如 /tmp）中运行，而不是在 AXF 仓库根目录中运行。从仓库根目录运行可能会导致 npx 或 npm exec 使用仓库本地或全局安装的 axf 可执行文件，而不是通过包安装的可执行文件。

适合注册表的启动方式是 axf mcp，但直接使用 MCP 可执行文件进行手动配置仍然有效。以下等效的包驱动形式使用已发布的 npm 包：

npx -y --package @smartergpt/axf axf doctor
npx -y --package @smartergpt/axf axf mcp
npx -y --package @smartergpt/axf axf-mcp

npm exec --yes --package @smartergpt/axf -- axf doctor
npm exec --yes --package @smartergpt/axf -- axf mcp
npm exec --yes --package @smartergpt/axf -- axf-mcp

Windows 原生启动

对于注册表风格的 Windows MCP 配置，建议使用基础的 axf.cmd 启动器，并将 mcp 作为参数：

{
  "mcpServers": {
    "axf": {
      "command": "axf.cmd",
      "args": ["mcp"],
      "cwd": "C:\\src\\my-project",
      "env": {
        "AXF_PROJECT_ROOT": "C:\\src\\my-project",
        "AXF_EXECUTION_ROOT": "C:\\src\\my-project"
      }
    }
  }
}

直接调用可执行文件的 .cmd 配置仍然有效：

{
  "mcpServers": {
    "axf": {
      "command": "axf-mcp.cmd",
      "args": [],
      "cwd": "C:\\src\\my-project",
      "env": {
        "AXF_PROJECT_ROOT": "C:\\src\\my-project",
        "AXF_EXECUTION_ROOT": "C:\\src\\my-project"
      }
    }
  }
}

WSL / Linux 启动

对于注册表风格的 WSL/Linux MCP 配置，优先使用基础 axf 命令， 并将 mcp 作为第一个参数：

{
  "mcpServers": {
    "axf": {
      "command": "axf",
      "args": ["mcp"],
      "cwd": "/home/user/src/my-project",
      "env": {
        "AXF_PROJECT_ROOT": "/home/user/src/my-project",
        "AXF_EXECUTION_ROOT": "/home/user/src/my-project"
      }
    }
  }
}

直接调用二进制文件的配置仍然有效：

{
  "mcpServers": {
    "axf": {
      "command": "axf-mcp",
      "args": [],
      "cwd": "/home/user/src/my-project",
      "env": {
        "AXF_PROJECT_ROOT": "/home/user/src/my-project",
        "AXF_EXECUTION_ROOT": "/home/user/src/my-project"
      }
    }
  }
}

WSL 用户应使用已添加到 PATH 的原生 WSL AXF 安装，而不是 Windows npm 垫片或 npm 的 _npx 缓存。启动原生 CLI 的可选共享包也应遵循相同规则：优先使用 PATH 中更靠前的 Linux 原生工具，并避免从 WSL 跨越到 Windows 垫片。

根目录绑定

axf、axf mcp 和 axf-mcp 按以下顺序解析活动项目根目录和 执行根目录：

1. 显式指定的 --project-root 和 --execution-root
2. AXF_PROJECT_ROOT 和 AXF_EXECUTION_ROOT
3. 旧版 CLI 别名：--workspace、--registry-workspace、--execution-workspace
4. 旧版环境变量别名：AXF_WORKSPACE、AXF_REGISTRY_WORKSPACE、AXF_EXECUTION_WORKSPACE
5. 从 cwd 开始查找最近的 axf.workspace.json
6. 从已安装脚本的位置开始查找最近的 axf.workspace.json
7. 回退到 cwd

对于 axf run，不带前缀的根目录标志只有在子命令之前才是全局标志； 在 run 之后则归能力所有。非 run 命令保留其旧版位置规则， 因为它们没有下游参数所有者。在命令中由 AXF 控制的部分，之后仍可使用 --axf-project-root、--axf-execution-root 和 --axf-workspace 这些写法。在 axf run ... -- 分界符之后，类似根目录的名称归能力所有。

Run 参数归属

AXF 将 --axf-* 命名空间保留为框架控制项，并将自然的公共参数名称留给能力。 如果需要在命令本身中明确显示参数归属，请使用显式分界符：

axf --project-root /repo run global.logs.query \
  --axf-json --axf-any-lifecycle -- \
  --json --limit 20 --workspace downstream-name

-- 之前的选项是 AXF run 控制项。-- 之后的选项是能力的公共参数： AXF 仍会解析这些参数，使用 argsSchema 验证并转换参数，通过 argMap 映射参数， 并通过声明的适配器执行。该分界符不会启用原始或绕过架构的 argv。 同一个名称可以出现在分界符两侧并具有不同归属，但同一显式区域内的重复项会被拒绝。

仍支持 axf run echo say --message hello 这类无分界符的现有调用。 在这种兼容形式下，旧版 --json、--any-lifecycle 和 --allow-draft 仍是 AXF 控制项， 除非能力显式声明了同名参数。如果需要明确归属 AXF，请使用 --axf-json 和 --axf-any-lifecycle。

Agent 优先发现

从有界的工作区指南开始，而不是请求每份完整清单：

axf guide
axf guide context --json
axf list --compact --search lex --limit 20 --json
axf explain global.lex
axf inspect global.lex.status --json

MCP 路由器也会提供相同的 guide、精简列表 / 搜索 list、explain 和 inspect 结果。guide 会返回工作区或系列声明的上下文、验证和交接入口， 但不会执行这些入口。精简列表条目会保留生命周期、副作用和来源信息， 同时省略完整架构和执行目标，直到调用 inspect。

AI Agent 是 MCP 结果的主要使用者，因此 AXF 默认采用 responseDetail: "compact"：以确定性方式提供最少且安全的封装，其中包含能力数据、 可执行的错误信息、警告和必需的安全状态。需要扩展的规范结果时，请请求 responseDetail: "standard"；调查来源信息、工作区绑定或启动行为时，请显式请求 responseDetail: "diagnostic"。调用跟踪不会出现在常规成功或失败结果中。 诊断框架元数据中的敏感字段名称和值会被脱敏。响应详细程度不会截断、脱敏或以其他方式转换 能力拥有的 data。 所有响应配置文件都会保留绑定的 projectRoot 和 executionRoot，即使两个根目录指向同一个检出目录也是如此。MCP 能力条目会在兼容的 scope 字段旁公开 registryScope。global 表示 AXF 注册表命名空间；它与提供方的存储目标无关。CLI inspect 结果会保留经过脱敏的命令／参数／工作目录启动摘要，即使采用精简详情也是如此。根目录和启动元数据描述的是路由，而非提供方授权。提供方的目标位置预检和写入回执仍由提供方拥有，属于 data，并会原样传递。

{
  "operation": "run",
  "responseDetail": "compact",
  "target": { "id": "global.lex.status" },
  "args": {}
}

compact 列表选项与 responseDetail 是有意分开的：compact 用于选择摘要形式的能力条目，而 responseDetail 用于控制面向 Agent 的外围响应信封。默认的精简 MCP list 响应在未指定 limit 时会独立限制为 25 条结果；这不会启用列表项的 compact 选项。提供显式的 limit 可替换该上限；或者在不指定 limit 的情况下显式请求 standard 或 diagnostic，以取消默认上限。

AXF 2.0 将隐式 MCP 响应从 2.0 之前的丰富信封改为 compact。使用来源信息或启动元数据的调用方必须请求 diagnostic；需要展开结果但不需要调用跟踪信息的调用方可以请求 standard。

AXF 项目根目录和执行根目录是文件系统发现／执行绑定，并非租户、仓库、工作区、授权授予或授权证据。环境中已有的根目录变量仅作为兼容性／配置输入；AXF 绝不会将其视为权威依据。对安全敏感的宿主应显式传入根目录，并在调用 AXF 前授权该操作。提供方拥有的身份和授权仍由提供方负责；AXF 不要求使用 Lex，也不会重建 Lex 授权信息。

有关推荐声明、缺失能力诊断以及 CLI/MCP 示例，请参阅Agent 发现与工作流指南。

当能力的即时结果表明某个确切的外部操作仍在进行中时，也可以返回经过验证且类型明确的续接项。第一种续接类型通过 global.wait.external 路由；其进程绑定的 GitHub 提供方会监控针对某个确切提交 SHA 的显式必需检查，或来自某个确切审核者身份的拉取请求审核。有关描述符、权限、取消和结果边界，请参阅可等待的完成项。

如果发现和执行应使用同一个仓库，请将 AXF_PROJECT_ROOT 和 AXF_EXECUTION_ROOT 都设为同一路径。如果两者应不同，请分别设置。旧版 AXF_WORKSPACE 仍是兼容别名，会将两个根目录绑定到同一路径。

对于 MCP 客户端，将 cwd 设为预期的调用方执行目录，并在可能时显式设置 AXF_PROJECT_ROOT／AXF_EXECUTION_ROOT。这样可确保清单发现和面向调用方的执行具有确定性。

若要让用户级或计算机级 AXF 根目录为多个项目提供可选的共享包，请设置 AXF_MACHINE_ROOT。项目根目录下的同名系列会覆盖计算机级系列。

安装后，可在任意目录运行：

axf doctor
axf list
axf inspect echo say
axf run echo say --message hello
axf scout --check
axf run toy echo say --message hello
axf init capability global.acme.status

axf doctor 会报告其选定的工作区来源；在 WSL 下，如果 axf、lex、node 或 npm 通过 /mnt/c/... 下的 Windows PATH 条目解析，还会发出警告。

MCP 路由与治理

MCP 服务公开了一个名为 axf 的工具。支持的操作包括：

• help
• guide
• list
• explain
• inspect
• run
• doctor
• scout_check

这些操作会路由到 AXF 基于清单的发现、解析器、生命周期、策略、适配器和执行器路径。MCP 不会增加第二套治理模型，也不会提供绕过 AXF 的原始 shell 通道。

AXF MCP 目前有意不与 CLI 完全保持功能对等。对于 init、promote、demote、scout --write 以及其他注册表/物化流程等命令，CLI 仍是权威的变更与控制平面。

global.echo.say 等能力不是独立的 MCP 工具。使用 operation=help 了解路由器约定，使用 operation=list 发现能力，并在执行 operation=run 之前先执行 operation=inspect。将能力的 lifecycleState、sideEffects、policies 和工作区绑定视为执行约定的一部分。

scout_check 是 AXF 专用于 MCP 的只读结构化 scout 诊断接口。它并不承诺与 axf scout --check 在字面上完全对等。

注册表和清单仍通过常规 AXF CLI 及文件系统/控制平面流程更新。MCP 服务会在每次请求时重新加载注册表状态，因此外部 AXF 更新会在后续 MCP 调用中生效，无需重启服务。

未来可能会在明确的策略和审批门控下考虑实现与 CLI 完全对等。

只有当绑定的 AXF 项目根目录或机器层发现或挂载共享包中的能力时，这些能力才会通过 AXF 显示。

已接入内容

内置适配器

AXF 提供两种公开的内置适配器类型：

• internal — 在进程内运行处理程序（adapters/internal/）
• cli — 通用子进程分发器，支持解析 stdout JSON（adapters/cli/）

共享命令系列使用与项目自有能力相同的适配器约定。共享包可以使用通用 cli 适配器、提供程序适配器或内部处理程序，但 AXF 核心不会将该包设为运行时依赖。

内置能力

能力	提供程序	生命周期	备注
global.echo.say	internal	active	最精简的进程内能力示例
global.wait.timed	wait	active	进程绑定的挂起，时长为 1 秒至 30 分钟；经过的时间不代表外部操作已完成
global.wait.external	wait	active	进程绑定的类型化外部完成状态观察；GitHub 精确头部检查和拉取请求评审是随附的提供程序
global.await.external	await	active	兼容性别名，已弃用；根据已发布的 2.0.0 约定，它指向 global.wait.external

可在机器级或项目级添加可选共享包，包括 Lex 包。这些包会通过相同的解析器、生命周期、策略、适配器和执行器路径进行路由，而无需定义框架本身。

工具空间

• toy — 最精简的挂载示例；使用本地默认值重新挂载 echo.say

仓库接入

推荐的仓库接入流程如下：

1. 在仓库根目录添加 axf.workspace.json，以明确工作区绑定。
2. 如果仓库需要共享包，请在机器级或项目级有意添加。
3. 在 manifests/capabilities/ 或 manifests/families/ 下单独添加仓库专属能力。
4. 保持 MCP 为可选项；不使用 MCP，AXF 仍可作为纯 CLI 能力路由器运行。
5. 将会产生变更的能力标记为 sideEffects: "write"。AXF 目前尚无一等的 approvalRequired 字段，因此审批门控暂由仓库策略或评审惯例负责。

具体接入模式和平台说明见 docs/13-repo-onboarding.md。

如何添加新提供方

这份契约是开放的。首先决定提供方需要命令族、选择性物化覆盖，还是提供方适配器。 集成作者指南介绍了如何做出这一选择。只有当通用 CLI 路径无法表达提供方的参数、封装、失败或输出契约时，才需要提供方适配器。

如果确有必要使用提供方适配器，应从 draft 状态开始搭建：

# 1. Scaffold a draft provider adapter (only if the provider has an
#    envelope or quirks the generic cli adapter shouldn't carry):
axf init adapter --kind provider acme --composes cli

# 2. Scaffold each capability:
axf init capability global.acme.status

# 3. Edit the drafts, then:
axf doctor
axf inspect global.acme.status --json

prompts/ 下的四个规范提示词会引导 Agent 根据实际文件契约完成发现 → 规划 → 搭建 → 审核。优先使用 JSON 的提供方通常可直接使用通用 cli 适配器；提供方适配器适用于需要在通用路径之外进行封装、错误或参数规范化的包装器。

运行非活动能力需要明确选择加入生命周期，并且仍可能触发真实的提供方操作。只有在完成检查并遵循仓库的常规审批流程后，才能这样做。生命周期变更会验证清单，但不会执行审核。

目录结构

axf.workspace.json               # workspace marker
bin/axf.js                      # CLI entrypoint
src/cli/                        # CLI parsing + main dispatch
src/core/                       # registry, resolver, executor, adapters, doctor, policy
adapters/<type>/                # type adapters (internal, cli, ...)
adapters/<provider>/            # optional provider adapters for wrapped CLIs
manifests/capabilities/         # capability manifests
manifests/toolspaces/           # toolspace mount manifests
prompts/                        # canonical prompts for agent-authored adapters
docs/                           # architecture, contract, lifecycle, prompts
test/                           # node:test suite

文档

根据你当前的工作，先阅读相应指南：

• 调用方指南 — 发现、检查并运行已适配的能力。
• 集成作者指南 — 在保留提供方术语的同时，适配反复出现的仓库或提供方流程。
• 框架作者指南 — 修改 AXF 内部实现和跨界面契约。
• 可等待的完成项 — 返回带类型的延续，并观察精确的外部完成情况，而不进行调度。

文档路径会根据不同受众指向相关参考文档。在为尚未决定的仓库接入前，请使用只读 Agent 适配评估。

测试

npm test

使用 Node 内置的 node:test；无需外部测试运行器。

此处有意不包含的内容

• 广泛的命令别名层
• 特权集成路径
• 插件市场
• 强制远程执行或 MCP 支持
• 自动晋升的 Agent 生成能力