# Agent Capability Hub（ACH）

**一个本地、可复用的 Agent 能力基座：统一接入和管理能力，按任务路由，按需读取。**

能力放进库里，按任务取用，不必都装进上下文。

积累的 Skill 和 Expert 越来越多，真正困难的往往不是存放，而是让 Agent 在当前任务里找到合适的能力。很多 Skill 系统已经采用渐进式披露：先提供名称和描述，需要时再读取正文。但如果宿主仍把大量能力的名称和描述放入上下文，目录本身也会成为需要处理的信息。

ACH 将来源接入、审核管理、任务路由和内容读取组织成一条可复用的路径。能力与有效审核记录保存在独立的本地库中，通过一组固定的 MCP 工具供宿主 Agent 调用。**库可以继续扩充，当前会话按任务查找和读取，不需要 ACH 在启动时把整份目录和所有正文交给宿主。** 工具数量不会随着库里的资产数量一起增长。

其中，Task Resolver 在 ACH 服务端根据任务描述筛选候选，返回少量能力的标识、匹配理由与状态。宿主 Agent 再按需要读取选中能力的内容，结合当前任务使用。这个流程把全库的初步筛选放在服务端；最终读到的内容和工具结果仍会进入宿主的处理范围。

ACH 提供命令行与可选的 MCP 接口。通过标准接口减少对单一宿主的绑定，是它的设计目标；这不代表所有 Agent 产品都已适配或验证。更换会话或宿主时，仍需正确连接同一个数据根，并遵循新宿主的工具与权限机制。

ACH 不接管宿主的调度，**需要宿主 Agent 主动调用相应工具**。若宿主本身已有动态能力发现机制，ACH 带来的额外收益会有所不同；这里没有承诺或测量固定的 Token 节省比例。

> 当前版本：**0.3.0rc7 预发布版本**，非稳定 1.0。以下为源码安装步骤。

## 基座承接哪些工作

- **统一来源接入**：把当前支持的固定 GitHub 目录或完整本地包交给同一条导入流程，不必为每个来源建立一套管理方式。
- **统一审核管理**：宿主 Agent 按相同标准完整阅读与语义审核；ACH 负责隔离来源、组织审核材料、校验记录和内容绑定，并持久化有效结果。
- **按任务路由**：服务端 Task Resolver 先给出少量候选及理由，宿主再决定读取哪些内容。能力积累与当前会话需要处理的内容不必同步增长。
- **按需读取与复用**：同一个本地库保存能力和有效审核记录，新会话继续按 ID 读取，不必反复粘贴整包资料；MCP 为不同宿主接入提供统一接口。

例如，库中同时保存文本润色 Skill 和代码评审 Expert。写作时，让 Agent 先按写作任务请求候选，再读取相关指南；评审代码时再查找代码评审能力。是否匹配成功及实际输出质量仍取决于能力描述、任务表达、来源内容和宿主 Agent。

### Task Resolver 当前如何工作

当前 Resolver 使用可解释的规则、关键词与字段权重，不调用模型进行语义检索。它最多返回 1 个 Workflow、1 个 Expert 和 3 个 Skill；候选计划不携带完整正文，也不自动执行或注入这些能力。

这不是无限规模、零开销的承诺。库增长会增加本地索引与筛选工作，规则也可能漏选或选得不够准确。尤其是新导入内容的自动描述目前较简略，必要时可提供更明确的任务关键词或能力 ID，再核对返回结果。

需要控制读取范围时，可优先采用“`resolve_task` 取候选 → `get_capability_card` 看无正文卡片 → 按 ID 读取内容”的流程。普通 `search_capabilities` 目前返回的匹配项包含正文，默认最多 20 条、上限 100 条；不要把它描述成永远只返回少量摘要。审核新来源时，宿主 Agent 也需要实际阅读完整材料。

## 一次导入，后续按需取用

1. **你提出导入请求**：提供固定提交的 GitHub 包目录 URL，或完整本地包目录。
2. **ACH 准备审核材料**：隔离来源，保留原始文件，生成当前标准和完整审核请求。
3. **宿主 Agent 按统一标准审查**：完整阅读文本，检查用途、指令、代码、权限、依赖和附件角色，如实生成审核记录并直接提交。
4. **符合标准才持久化**：通过的内容进入本地 Library/Catalog；实际风险、内容缺口、缺来源或处理条件不足分别报告。
5. **新会话继续使用**：连接同一个数据根，搜索并读取有效的已审核能力，核对本次任务的输入与条件。

**不要求用户逐项人工审核内容，也不要求手工填写或搬运审核 JSON。** 但审核并没有被省略：由宿主 Agent 执行统一标准审核，ACH 校验记录和原始内容、标准版本的绑定。它不保证来源全部通过，也不保证 Agent 的判断绝对正确。

用户对具体外部动作的授权仍然独立存在。能力入库不等于允许安装来源软件、执行脚本、发送消息或扩大权限。

## 快速开始

### 1. 安装带 MCP 支持的版本

已验证的环境为 Python 3.12+ 和 POSIX 系统；Windows 尚未认证。需要一个支持配置 stdio MCP 服务并调用工具的宿主 Agent，具体宿主配置方式以其文档为准。

进入包含 `pyproject.toml` 的源码根目录，使用新的虚拟环境和独立数据根，不要直接连接已有生产库：

```sh
unset PYTHONHOME PYTHONPATH
python3.12 -m venv "$HOME/.venvs/ach"
"$HOME/.venvs/ach/bin/python" -m pip install '.[mcp]'
mkdir -p "$HOME/.local/share/ach"
"$HOME/.venvs/ach/bin/ach" --root "$HOME/.local/share/ach" doctor
```

只安装 `.` 不包含完整的可选 MCP 运行依赖。核心 Registry 和 CLI 使用 Python 标准库；安装 MCP 版本会另外获取 MCP SDK 及其依赖。`doctor` 成功只表示本地检查完成，不代表宿主已连接。

### 2. 在宿主中添加 stdio 服务

下面是通用服务配置示例。将路径替换为你实际使用的完整绝对路径；不同宿主的外层配置键与保存位置可能不同。

```json
{
  "command": "/home/alice/.venvs/ach/bin/ach",
  "args": [
    "--root", "/home/alice/.local/share/ach",
    "serve", "--transport", "stdio"
  ]
}
```

配置中不要保留 `~` 或 `$HOME`，宿主通常不会替你展开。连接后可让 Agent 调用 `get_recommended_profile()` 检查工具是否可用；返回推荐清单不代表已经下载或审核其中的内容。

### 3. 让 Agent 导入一个包

可以向宿主 Agent 发出这样的请求：

> 请把下面固定提交中的 Humanizer Skill 导入 ACH。按 ACH 当前完整标准审查内容，通过后持久化为可检索的指南；不要执行包内代码或做原生安装，并如实报告未通过或缺条件的部分。
>
> https://github.com/infometa/workbuddyskills/tree/4d5544f81d2d5d37a3e6c2ab579544fc281e6c75/skills/humanizer

Expert 使用相同流程。例如，同一固定提交中的目录：

https://github.com/infometa/workbuddyskills/tree/4d5544f81d2d5d37a3e6c2ab579544fc281e6c75/experts/code-review-expert

目前原生 URL 导入支持公开 GitHub 仓库中**完整 40 位 commit 固定的目录地址**，不是任意网站、分支名、短 SHA 或单文件链接。也支持完整本地包目录。网络访问被拒绝或限流时，应保留错误并正常等待或处理，不能绕过限制。

Agent 使用 `prepare_package_import` → `get_package_review_request` → `submit_package_review` 完成导入审核。只有实际返回 `status=admitted` 才表示已持久化准入。

**第一次使用时，把“导入成功”和“读到内容”分开确认：**

1. 让 Agent 从实际准入返回中保留 `capability_id` 和 `capability_type`。不要把示例名称当作服务器一定返回的 ID，也不要把 `import_id` 当成能力 ID。
2. 使用这两个真实返回值调用 `read_reviewed_capability(capability_id=实际返回值, capability_type=实际返回值)`。这里的“实际返回值”只是说明，不是可直接复制的字面参数。
3. 核对实际读取结果、当前审核状态及任务所需条件，再让 Agent 将指南用于你提供的真实任务。若未通过、缺来源或缺条件，报告实际状态，不展示虚构的成功输出。

读取成功后，再测试下一步的新会话复用。

### 4. 新会话复用，以及需要时的批量起步

新会话重新连接同一个数据根，可以先用上一步记录的真实能力 ID 和类型读取，确认内容仍可用；也可以把新任务交给 `resolve_task`，再按候选 ID 读取。新会话不会因为上次入库就自动获得外部执行权限。

框架提供 WorkBuddy 公开归档来源的推荐清单与固定文件元数据，方便起步；**不随框架打包这些第三方能力正文，也不附带默认通过的审核记录**。

需要推荐起步包时，让 Agent 按[完整导入指南](docs/agents/persistent-agent-import.md)获取固定快照，将同时包含 `experts/` 和 `skills/` 的仓库根目录交给推荐导入流程，再逐项按相同标准审查。无需用户手动下载和审批每个包；推荐不代表全库导入或全部通过。

新会话连接相同的数据根后，可明确要求 Agent 先调用 `resolve_task` 获取候选计划，再按 ID 读取 Skill、Expert 或通用审核内容；没有合适候选时，可进一步搜索或指定已知能力。相同内容与标准下的有效记录可以复用；当前任务缺少必要输入或依赖时，仍需如实报告，不能直接宣称可用。

## 当前能力与边界

**当前提供：**

- 本地能力索引、检索、读取与命令行操作。
- 可选 MCP 接口，明确分开只读检索与用户显式请求的导入写入。
- Skill/Expert 单包导入与批量审核，包括推荐来源的批量准备、宿主 Agent 逐项审核和持久化；批量处理不代表全部通过。
- 审核记录和内容、标准的绑定，以及重复导入、保留原库和写入失败处理的契约校验。

**当前不提供或不承诺：**

- 不把 MCP 服务器本身当作 Skill/Expert 能力资产导入。
- 不执行来源包中的代码，不因入库而授予外部动作权限。
- 不运行中心常驻审核模型，不代选付费模型；宿主自身可能仍有使用成本。
- 不自动定时更新来源，不保证自动把指南注入每次对话，也不保证模型一定遵循。
- 不承诺与所有 Agent 产品直接兼容；各宿主的连接、工具调用与权限处理仍需分别验证。
- 不附带历史个人审批与信任记录，不把其他人的旧审核直接当作你的默认授权。

首次试用请保持独立数据根。升级前备份，不要让不同版本的写入服务同时使用一个根目录；写入结果不确定时先检查状态，避免盲目重试。

## 已验证什么

本候选的干净源码快照构建并独立安装后，核心门槛 **221 项**、含 MCP 的门槛 **223 项**通过，无跳过断言；覆盖导入、拒绝、标准绑定、重复提交、保留原库、失败回滚及真实本地 MCP 传输。

此前还做过空库中的真实 Skill + Expert 审核与新会话读取验收。这些是有界验证，不代表所有第三方能力、所有宿主或所有历史研究测试都已通过，也不是安全性或内容质量的绝对保证。

开发者可从源码根使用已安装候选 wheel 的独立虚拟环境复现：

```sh
/absolute/path/to/venv/bin/python -I scripts/verify_private_candidate.py --require-mcp --report /absolute/path/to/ach-gate.json
```

脚本必须从虚拟环境中的已安装 wheel 导入 ACH，而不是回退到源码目录。详细安装、宿主连接、推荐快照获取和 Agent 审核契约见[完整指南](docs/agents/persistent-agent-import.md)。

## 未来可以怎样提升

以下是后续方向，尚未实现或仍待评估，不是本次预发布的上线门槛，也没有承诺交付时间：

- **CLI 易用化**：核心 CLI 已存在。后续可以让常见的导入、查看状态、任务路由和读取操作更连贯，减少配置成本，改善诊断信息。
- **可替换的决策路由**：在现有规则路由之上，评估语义检索及 jEV 类决策思路，探索可替换的路由方式。当前尚未接入这类方案，也不预设其效果一定优于现有规则。
- **更好的检索元数据与精简接口**：改善导入能力的任务描述、标签与候选解释，探索更小的接口和响应，减少不必要的正文返回与工具选择负担。
- **来源更新管理**：以后再考虑变化检测、重新审核和更新策略；当前没有自动更新，不能把旧审核直接当作变更后内容的批准。

这些方向服务于同一个目标：让能力可以长期积累，而来源管理、任务选择和读取方式能持续改进，不把复杂度都留给每一次对话。

## 许可证

ACH 框架及自编示例采用 [MIT](LICENSE)。外部导入的 Skill、Expert、附件和用户数据保留各自权利与许可证；通过审核不等于获得再次分发的许可。详见[许可证与分发范围](LICENSE-STATUS.md)。