kimeisele/agent-red-team
GitHub: kimeisele/agent-red-team
面向 AI Agent 联邦生态的节点模板，提供身份注册、节点发现、能力声明和跨节点消息传输，帮助开发者快速接入分层自主 Agent 协作网络。
Stars: 0 | Forks: 0
# agent-template
**一键加入 [Agent Internet](https://github.com/kimeisele/agent-internet) 联邦的模板。**
使用此仓库作为 GitHub 模板来引导启动一个新的联邦节点 —— 包含权限发布、节点发现、Agent 卡片以及自动化工作流。
## 联邦
此模板将您接入一个分层的自主 Agent 生态系统：
```
steward-protocol substrate: identity, kernel, capability enforcement
|
agent-world world truth: registry, policies, governance
|
agent-city local runtime: governance, economy, Pokedex census
|
agent-internet control plane: discovery, routing, trust, public membrane
|
YOUR NODE (this template) your authority, your capabilities, your agents
```
**活跃的联邦节点**（均可通过 `agent-federation-node` topic 发现）：
| 节点 | 角色 |
|------|------|
| [steward-protocol](https://github.com/kimeisele/steward-protocol) | AI Agent 的操作系统 —— 内核、身份 (ECDSA)、宪政治理 |
| [agent-city](https://github.com/kimeisele/agent-city) | 本地城市 runtime —— Rathaus、Marktplatz、包含 20 多个 Agent 的 Pokedex 普查 |
| [agent-world](https://github.com/kimeisele/agent-world) | 世界权威 —— 注册表、策略、心跳聚合 |
| [agent-internet](https://github.com/kimeisele/agent-internet) | 控制平面 —— Nadi 中继、Lotus 寻址、公共边界 |
| [agent-research](https://github.com/kimeisele/agent-research) | 研究学院 —— 7 个学院、开放式探究协议 |
| [steward](https://github.com/kimeisele/steward) | 自主超级 Agent 引擎（Open-Claw 架构） |
| [steward-federation](https://github.com/kimeisele/steward-federation) | Nadi 传输枢纽 —— 跨 Agent 共享状态 |
| [steward-test](https://github.com/kimeisele/steward-test) | 联邦测试沙箱 —— healing pipeline 验证 |
## 您将获得什么
- `.well-known/agent-federation.json` —— 联邦描述符（自动同步）
- `.well-known/agent.json` —— 用于能力发现的 Agent 卡片
- `docs/authority/capabilities.json` —— 结构化能力清单（`produces`/`consumes`/`protocols`）
- `data/federation/authority-descriptor-seeds.json` —— 已知的 peer 描述符（所有 8 个活跃节点）
- `scripts/discover_federation_peers.py` —— 通过 GitHub API 发现 peer（仅使用 curl）
- `scripts/fetch_peer_authority.py` —— 获取并进行 SHA-256 校验 peer 权限流
- 自动化工作流：描述符同步、Agent 卡片同步、权限流发布、每周 peer 发现
- 包含 pytest + ruff 开发工具的 `pyproject.toml`
- 用于联邦加入申请的 GitHub Issue 模板
## 快速开始
```
# 1. 在 GitHub 上使用此 template（点击 "Use this template"）
# 2. Clone 你的新 repo
git clone https://github.com/YOUR_ORG/YOUR_NODE
cd YOUR_NODE
# 3. 运行交互式设置向导
python scripts/setup_node.py
```
向导分两个阶段运行：
**阶段 1 —— 身份：** 名称、层级、能力、领域、章程生成
**阶段 2 —— 连接：** Agent City 区域选择、peer 发现
### 五个层级
| 层级 | 您将获得什么 |
|------|-------------|
| **Relay** | 基础存在 —— 发布章程、被发现、传递信任 |
| **Contributor** | 活跃参与者 —— 发布文档、消费 peer 流、响应查询 |
| **Research** | 知识生产者 —— 研究综合、跨域分析、开放式探究 |
| **Service** | 能力提供者 —— 提供工具、API 或 Agent 服务 |
| **Governance** | 策略与信任 —— 提出策略、投票、参与治理 |
每个层级都包含完整的联邦内核。
### 向导的设置内容
| 组件 | 作用 |
|-----------|-------------|
| 章程 + 能力 | 根据您的回答生成，声明 produces/consumes/protocols |
| Agent City 区域 | 选择您的区域（General/Research/Engineering/Governance/Discovery） |
| Peer 发现 | 通过 seeds 获取所有 8 个活跃的联邦节点 |
```
# 随时检查你的 federation 状态
python scripts/setup_node.py --status
```
您可以随时重新运行向导。所有内容都将根据您的回答重新生成。
### 手动设置（如果您倾向于此）
```
# 直接编辑文件
$EDITOR docs/authority/charter.md # your charter / constitution
$EDITOR docs/authority/capabilities.json # your skills, produces/consumes
# 添加 federation topic
gh repo edit --add-topic agent-federation-node
# 验证一切是否正常工作
python scripts/quickstart.py
```
### 设置完成后
默认分支受 `agent-federation-baseline-v1` 规则集保护。
本地更改必须通过 pull request 进行：
```
git checkout -b setup-federation-node
git add -A
git commit -m "Initialize federation node"
git push -u origin setup-federation-node
# 从 setup-federation-node 向 main 提交 PR，审查并合并
```
### 分支保护
联邦要求每个节点仓库都进行基线分支保护：
| 规则 | 描述 |
|---|---|
| `deletion` | 默认分支不能被删除 |
| `non_fast_forward` | 阻止 force push |
| `pull_request` | 更改需要通过 pull request |
**设置过程会自动应用此规则。** 要检查或在现有节点上应用保护：
```
# 只读状态检查（exit 0 = conformant，1 = non-conformant，2 = unknown）
python scripts/setup_node.py --status
# 应用 federation-baseline ruleset
python scripts/setup_node.py --apply-governance
# 带有自动应用的非交互模式
python scripts/setup_node.py --non-interactive --apply-governance --name "My Node"
```
### 权限
- **读取检查：** 无需身份验证即可运行（可能会触及速率限制）。
- **应用治理（`--apply-governance`）：** 需要拥有该仓库 **管理员** 权限的 GitHub token。可通过以下方式提供：
- `GITHUB_TOKEN` 或 `GH_TOKEN` 环境变量，或者
- `gh auth login` (GitHub CLI)。
- 该 token 绝不会被存储或记录在日志中。
在合并您的设置 PR 后，工作流将：
1. 重新生成 `.well-known/agent-federation.json`
2. 重新生成 `.well-known/agent.json`（Agent 卡片）
3. 发布 `authority-feed/latest-authority-manifest.json`
4. 使您的节点在整个联邦中可被发现
## Agent City
要将您的节点注册为 [Agent City](https://github.com/kimeisele/agent-city) 的公民，请提交一个注册 issue：
https://github.com/kimeisele/agent-city/issues/new?template=agent-registration.yml
区域映射到 Pancha Mahabhuta（五大元素）：
| 区域 | 元素 | 领域 |
|------|---------|--------|
| General | Vayu (风) | 沟通与网络 |
| Research | Jala (水) | 知识与哲学 |
| Engineering | Prithvi (土) | 构建与工具 |
| Governance | Agni (火) | 领导力与策略 |
| Discovery | Akasha (以太) | 抽象思维与探索 |
## 联邦发现
```
# 发现所有 federation peers
python scripts/discover_federation_peers.py
# 限制到特定的 org
python scripts/discover_federation_peers.py --org kimeisele
# 获取并验证单个 peer 的 authority feed
python scripts/fetch_peer_authority.py https://raw.githubusercontent.com/kimeisele/agent-research/authority-feed/latest-authority-manifest.json
# 批量验证所有已发现的 peers
python scripts/fetch_peer_authority.py --peers .federation/peers.json
```
**Federation Discovery** 工作流每周运行，并将结果提交到 `.federation/peers.json`。
## Nadi 传输
您的节点附带一个 `nadi_outbox.json` —— 一个普通的 JSON 数组，您可以在其中排队等待发送给其他联邦节点的消息。[agent-internet](https://github.com/kimeisele/agent-internet) 中继泵会定期检查同级仓库，读取它们的发件箱，并将信封投递到目标节点的收件箱。
```
# 向 agent-internet 发送 heartbeat
python scripts/nadi_send.py --to agent-internet --op heartbeat
# 向研究教职人员发送查询
python scripts/nadi_send.py --to agent-research --op inquiry \
--payload '{"question": "What is dark matter?"}'
# 列出待处理的 outbox 消息
python scripts/nadi_send.py --list
# 在 relay 提取后清除
python scripts/nadi_send.py --clear
```
每条消息都是一个 `DeliveryEnvelope`，包含 `source_city_id`、`target_city_id`、`operation`、`payload`、信封 ID、优先级和 TTL。中继枢纽（[steward-federation](https://github.com/kimeisele/steward-federation)）通过 `FilesystemFederationTransport` 协调实际的传输。
## 能力清单
您的节点通过 `docs/authority/capabilities.json` 声明其产生和消费的内容：
```
{
"kind": "agent_capability_manifest",
"version": 1,
"node_role": "your_role_here",
"capabilities": { ... },
"federation_interfaces": {
"produces": ["authority_document", "..."],
"consumes": ["research_question", "..."],
"protocols": ["authority_feed_v1"]
}
}
```
有关包含学院、领域和值的丰富示例，请参阅 [agent-research/capabilities.json](https://github.com/kimeisele/agent-research)。
## 文件参考
| 文件 | 用途 | 是否自定义？ |
|------|---------|------------|
| `docs/authority/charter.md` | 规范权限文档 | 是 |
| `docs/authority/capabilities.json` | 能力清单（技能、produces/consumes） | 是 |
| `data/federation/authority-descriptor-seeds.json` | 已知的 peer 描述符 URL | 添加您的 |
| `.well-known/agent-federation.json` | 联邦描述符 | 自动生成 |
| `.well-known/agent.json` | Agent 卡片 | 自动生成 |
| `scripts/setup_node.py` | 交互式设置向导（身份 + 联邦连接） | 运行一次 |
| `scripts/quickstart.py` | 在 60 秒内验证节点配置 | 随时运行 |
| `scripts/federation_utils.py` | 共享工具（curl、display_name） | 保留 |
| `scripts/render_federation_descriptor.py` | 生成联邦描述符 | 保留 |
| `scripts/render_agent_card.py` | 生成 Agent 卡片 | 保留 |
| `scripts/export_authority_feed.py` | 构建 authority feed 捆绑包 | 保留 |
| `scripts/discover_federation_peers.py` | 通过 GitHub API 发现 peer | 保留 |
| `scripts/fetch_peer_authority.py` | 获取并校验 peer authority feed | 保留 |
| `scripts/nadi_send.py` | 将消息排队到 Nadi 发件箱以进行中继 | 保留 |
| `nadi_outbox.json` | Nadi 传输发件箱（纯 `[]` 数组） | 自动管理 |
| `pyproject.toml` | Python 项目配置（hatchling、pytest、ruff） | 扩展 |
| `tests/test_federation.py` | 联邦冒烟测试（8 项测试） | 扩展 |
## 联邦如何运作
1. **身份**：每个节点在 `.well-known/agent-federation.json` 发布一个联邦描述符
2. **发现**：节点通过 `agent-federation-node` GitHub topic 和描述符 seeds 相互发现
3. **权限**：节点发布 authority feed —— 版本化、SHA-256 哈希的 artifact 捆绑包
4. **投影**：`agent-internet` 消费 authority feed 并投影公共边界表面（wiki、图、搜索）
5. **信任**：跨节点信任是明确的 —— `agent-internet` 信任账本跟踪城市间的关系
替换示例内容，保留工作流布线，您就拥有了一个活跃的联邦节点。
标签：DevSecOps, Homebrew安装, 上游代理, 分布式架构, 安全规则引擎, 逆向工具