據 AlphaMoat 統計,截至 2026-10,Network-AI 累計下載 7,549 次、獲 6 個星標,按累計下載量在本次參與排名的 10,914 個 AI 技能中排名第 3,710 位,在「AI 智慧體」分類(1,632 個)中排名第 496 位。
列表預設按累計下載量排序,也可按星標排序;詳情頁排名按累計下載量計算。
| 平台 | 累計下載 | 星標 | 評論 |
|---|---|---|---|
| ClawHub ↗ | 7549 | 6 | 2 |
| SkillHub ↗ | 7077 | 6 | — |
各平台的計數口徑不同,統計時間不一致。
該技能透過共享黑板、任務預算、許可權檢查和持久化專案上下文來組織工作;主文列出的狀態檔案位於專案目錄。技能卡提醒協調檔案可能長期保留專案敏感資訊,許可權授予提示也只是建議,不代表可執行敏感操作的授權。請限制工作區訪問,在上下文和理由中避免寫入金鑰或個人資料;支付、資料庫、郵件或匯出等操作仍須單獨取得人工批准。 包內 Python 指令碼只透過本地檔案協調,不負責啟動 agent、發訊息、執行 shell 或啟動單獨的 TypeScript/MCP 引擎。宿主平台的委派另有資料流和許可權;grant token 不認證 agent 身份。
資料釋出於 2026-10-29
以下是根據技能文件生成的示例,不代表實際執行結果。
2026-09 起統計方法調整:同名技能按作者分別統計,並覆蓋全部技能。圖中虛線為調整前的月份,與之後的資料不直接比較,也不計算跨越調整的增長。
| 月份 | 累計下載 | 環比 | 星標 |
|---|---|---|---|
| 2026-10 | 7549 | — | 6 |
| 2026-09 | 6992 | — | 6 |
| 2026-08 | 6583 | +10.1% | 6 |
| 2026-07 | 5978 | +7.7% | 6 |
| 2026-06 | 5549 | +12.6% | 6 |
| 2026-05 | 4927 | — | 6 |
| 2026-03 | 2152 | — | 6 |
以下是作者釋出的原始檔案,按純文字顯示,本站未做修改或稽核;其中的連結不可點選,命令請核實後再執行。抓取於 2026-10-23。
---
name: network-ai
description: "Local Python orchestration skill: multi-agent workflows via shared blackboard file, permission gating, token budget scripts, and persistent project context. The bundled Python scripts make no network calls and have zero third-party dependencies. The parent repository also contains a TypeScript engine (not included in this skill bundle)."
allowed-tools: Read Bash(python3 scripts/blackboard.py:*) Bash(python3 scripts/check_permission.py:*) Bash(python3 scripts/context_manager.py:*) Bash(python3 scripts/swarm_guard.py:*) Bash(python3 scripts/validate_token.py:*) Bash(python3 scripts/revoke_token.py:*)
metadata:
openclaw:
emoji: "\U0001F41D"
homepage: https://network-ai.org
capabilities:
filesystem: "read/write — project root `swarm-blackboard.md` (blackboard state), `data/pending_changes/<id>.json` (WAL entries), `data/pending_changes/archive/<id>.<status>.json` (committed/aborted change records), `data/audit_log.jsonl`, `data/active_grants.json`, `data/.signing_key`, `data/project-context.json`, `data/task_tracking.json`, `data/agent_health.json`, `data/budget_tracking.json`, `data/swarm_budgets.json`, `data/heartbeats.json`, `data/.blackboard.lock`. All paths are local; no data leaves the local filesystem. When NETWORK_AI_ENV is set, data paths are rooted at `data/<env>/` instead of `data/`. The `--path` argument in blackboard.py is validated against the project root at runtime — paths outside the project directory are rejected (CWE-22)."
env_vars: "read — NETWORK_AI_ENV only (environment routing for data paths). No other env vars are read and none are written."
filesystem_operations: "Local persistent state, all under the project root and data/ (or data/<env>/): create directories; create and overwrite the state files listed above; append to audit_log.jsonl; blackboard.py archives each committed or aborted change to pending_changes/archive/ and then deletes the pending file, and deletes stale .blackboard.lock markers; revoke_token.py removes revoked or expired entries from active_grants.json. Nothing outside these paths is read, written, or deleted."
tools: "Only the six bundled scripts, run via python3 (see allowed-tools), plus reading local state files. No other commands, binaries, or tools are required or invoked."
shell_exec: "none — the bundled scripts spawn no subprocesses and execute no shell commands."
tcp_port: "none — the bundled scripts open no sockets and bind no ports."
invocation: "Each script runs once per explicit command, then exits. Nothing is scheduled, kept running, or triggered without a caller. Permission scores are advisory; the caller decides whether to act on them."
bundle_scope:
clawhub_python_scripts: "Python stdlib only — scripts/*.py (blackboard.py, check_permission.py, context_manager.py, swarm_guard.py, validate_token.py, revoke_token.py). Zero network calls, zero subprocesses, zero third-party packages. This is the scope scanned by SkillSpector."
not_in_bundle: "The separate npm package (network-ai: TypeScript library, CLI, optional MCP server) is not part of this skill. This skill never installs, imports, or starts it."
network_calls:
python_scripts: none
inter_agent_comms: "none — this skill does not implement, invoke, or control inter-agent messaging or sessions_send. All coordination is via local file-based blackboard only."
sessions_send: "NOT implemented or invoked by this skill. sessions_send is a host-platform built-in entirely outside this skill's control. See data-flow notice below."
sessions_ops: "platform-provided — outside this skill's control"
requires:
bins:
- python3
optional_bins: []
env: {}
privacy:
audit_log:
path: data/audit_log.jsonl
scope: local-only
description: "Local append-only JSONL file recording operation metadata. No data leaves the machine."
pii_warning: "Justification strings are truncated to 200 characters before being written to the audit log. Audit summary output (--audit-summary --json) omits justification text from returned entries. Do not include PII, credentials, or secrets in justification fields — the truncated text still persists on disk. Grant tokens are masked to a short prefix in all listing outputs; full tokens appear only at issuance time."
data_directory:
path: data/
scope: local-only
files: ["audit_log.jsonl", "active_grants.json", ".signing_key", "project-context.json", "task_tracking.json", "agent_health.json", "budget_tracking.json", "swarm_budgets.json", "heartbeats.json", ".blackboard.lock", "pending_changes/<id>.json", "pending_changes/archive/<id>.<status>.json"]
description: "All persistent state is local-only. No data leaves the local filesystem."
blackboard_file:
path: swarm-blackboard.md
scope: local-only
description: "Shared coordination state written by scripts/blackboard.py (project root). Contains task results, grant tokens, status flags, and TTL-scoped cache entries. Access should be restricted to the local user running the swarm."
---
# Swarm Orchestrator Skill
> **Scope:** The bundled Python scripts (`scripts/*.py`) make **no network calls**, use only the Python standard library, and have **zero third-party dependencies**. Tokens are UUID-based (`grant_{uuid4().hex}`) stored in `data/active_grants.json`. Audit logging is plain JSONL (`data/audit_log.jsonl`).
> **Advisory tokens notice:** Grant tokens issued by `check_permission.py` are **advisory scoring outputs only** — the caller-supplied `--agent` identity is not cryptographically verified. Downstream systems must not treat these tokens as authenticated credentials without adding a separate identity-verification step or human approval gate, especially for PAYMENTS, DATABASE, and FILE_EXPORT resources.
> **Data-flow notice (host platform — not this skill):** This skill does NOT implement, invoke, or control `sessions_send` or any inter-agent messaging. All bundled Python scripts are local-only tools (budget guard, blackboard, permission scorer, context manager). If your platform has a `sessions_send` built-in, whether and how it is used is entirely the **host platform’s** responsibility and is outside this skill’s scope. If you need to prevent external network calls, disable or reroute delegation in your **platform settings** before installing this skill.
> **Context file integrity:** `context_manager.py` validates every field of `data/project-context.json` (project, goals, stack, milestones, decisions, banned approaches, agents) for prompt-injection and role-delimiter patterns, size, and nesting. `init` and `update` reject unsafe values before they are written; `inject` blocks on any warning and emits the context as single-line values inside a `<project_context type="reference-data">` block that labels it as data, not instructions. Treat injected context as untrusted reference material.
> **PII / sensitive-data warning:** The `justification` field in permission requests and the audit log (`data/audit_log.jsonl`) store free-text strings provided by agents. **Do not include PII, secrets, or credentials in justification text.** Consider restricting file permissions on `data/` or running this skill in an isolated workspace.
## Setup
**No pip install required.** All 6 scripts use Python standard library only — zero third-party packages.
> **Note on `requirements.txt`:** The file exists for documentation purposes only — it lists the stdlib modules used and has **no required packages**. All listed deps are commented out as optional. You do not need to run `pip install -r requirements.txt`.
```bash
# Prerequisite: python3 (any version ≥ 3.8)
python3 --version
# Run only the six bundled scripts (no other tools are needed):
python3 scripts/blackboard.py list
python3 scripts/swarm_guard.py budget-init --task-id "task_001" --budget 10000
```
File locking is built in: `blackboard.py` uses `fcntl` on Unix and an atomic lock-marker file on Windows. Nothing needs to be installed on any platform.
The `data/` directory is created automatically on first run. No configuration files, environment variables, or credentials are required.
> **Multi-environment support (v5.4.0):** All six Python scripts read the `NETWORK_AI_ENV` environment variable at startup and accept a `--env <name>` CLI argument. When set, all data paths are routed to `data/<env>/` instead of the root `data/` directory. Use this to isolate dev, staging, and production state.
>
> ```bash
> # Run against the dev environment
> NETWORK_AI_ENV=dev python3 scripts/blackboard.py list
> python3 scripts/check_permission.py --active-grants --env dev
> ```
Multi-agent coordination system for complex workflows requiring task delegation, parallel execution, and permission-controlled access to sensitive APIs.
## 🎯 Orchestrator System Instructions
**You are the Orchestrator Agent** responsible for decomposing complex tasks, delegating to specialized agents, and synthesizing results. Follow this protocol:
### Core Responsibilities
1. **DECOMPOSE** complex prompts into 3 specialized sub-tasks
2. **DELEGATE** using the budget-aware handoff protocol
3. **VERIFY** results on the blackboard before committing
4. **SYNTHESIZE** final output only after all validations pass
### Task Decomposition Protocol
When you receive a complex request, decompose it into exactly **3 sub-tasks**:
```
┌─────────────────────────────────────────────────────────────────┐
│ COMPLEX USER REQUEST │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────┼─────────────────────┐
│ │ │
▼ ▼ ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│ SUB-TASK 1 │ │ SUB-TASK 2 │ │ SUB-TASK 3 │
│ data_analyst │ │ risk_assessor │ │strategy_advisor│
│ (DATA) │ │ (VERIFY) │ │ (RECOMMEND) │
└───────────────┘ └───────────────┘ └───────────────┘
│ │ │
└─────────────────────┼─────────────────────┘
▼
┌───────────────┐
│ SYNTHESIZE │
│ orchestrator │
└───────────────┘
```
**Decomposition Template:**
```
TASK DECOMPOSITION for: "{user_request}"
Sub-Task 1 (DATA): [data_analyst]
- Objective: Extract/process raw data
- Output: Structured JSON with metrics
Sub-Task 2 (VERIFY): [risk_assessor]
- Objective: Validate data quality & compliance
- Output: Validation report with confidence score
Sub-Task 3 (RECOMMEND): [strategy_advisor]
- Objective: Generate actionable insights
- Output: Recommendations with rationale
```
### Budget Check Protocol
**Run the budget interceptor before any task delegation:**
```bash
# Run this before delegating to any sub-agent
python {baseDir}/scripts/swarm_guard.py intercept-handoff \
--task-id "task_001" \
--from orchestrator \
--to data_analyst \
--message "Analyze Q4 revenue data"
```
**Decision Logic:**
```
IF result.allowed == true:
→ Budget check passed — proceed with the delegated task
→ Note tokens_spent and remaining_budget
ELSE:
→ STOP — budget exceeded or handoff limit reached
→ Report blocked reason to user
→ Consider: reduce scope or abort task
```
### Pre-Commit Verification Workflow
Before returning final results to the user:
```bash
# Step 1: Check all sub-task results on blackboard
python {baseDir}/scripts/blackboard.py read "task:001:data_analyst"
python {baseDir}/scripts/blackboard.py read "task:001:risk_assessor"
python {baseDir}/scripts/blackboard.py read "task:001:strategy_advisor"
# Step 2: Validate each result
python {baseDir}/scripts/swarm_guard.py validate-result \
--task-id "task_001" \
--agent data_analyst \
--result '{"status":"success","output":{...},"confidence":0.85}'
# Step 3: Supervisor review (checks all issues)
python {baseDir}/scripts/swarm_guard.py supervisor-review --task-id "task_001"
# Step 4: Only if APPROVED, commit final state
python {baseDir}/scripts/blackboard.py write "task:001:final" \
'{"status":"SUCCESS","output":{...}}'
```
**Verdict Handling:**
| Verdict | Action |
|---------|--------|
| `APPROVED` | Commit and return results to user |
| `WARNING` | Review issues, fix if possible, then commit |
| `BLOCKED` | Do NOT return results. Report failure. |
---
## The 3-Layer Memory Model
Every agent in the swarm operates with three memory layers, each with a different scope and lifetime:
| Layer | Name | Lifetime | Managed by |
|-------|------|----------|------------|
| **1** | Agent context | Ephemeral — current task only | Platform (per-session) |
| **2** | Blackboard | TTL-scoped — shared across agents | `scripts/blackboard.py` |
| **3** | Project context | Persistent — survives all sessions | `scripts/context_manager.py` |
### Layer 1 — Agent Context
Each agent's own context window: the current task instructions, conversation history, and immediate working memory. Managed automatically by the OpenClaw/LLM platform. Nothing to configure.
### Layer 2 — Blackboard (Shared Coordination State)
A shared markdown file (`swarm-blackboard.md`) for real-time cross-agent coordination: task results, grant tokens, status flags, and TTL-scoped cache entries. Agents read and write via `scripts/blackboard.py`. Entries expire automatically.
### Layer 3 — Project Context (Persistent Long-Term Memory)
A JSON file (`data/project-context.json`) that holds information every agent should know, regardless of what session or task is running:
- **Goals** — long-term objectives of the project
- **Tech stack** — languages, frameworks, infrastructure
- **Milestones** — completed, in-progress, and planned work
- **Architecture decisions** — design choices and their rationales
- **Banned approaches** — approaches that have been ruled out
#### Initialising Project Context
```bash
python {baseDir}/scripts/context_manager.py init \
--name "MyProject" \
--description "Multi-agent workflow automation" \
--version "1.0.0"
```
#### Injecting Context into an Agent System Prompt
```bash
python {baseDir}/scripts/context_manager.py inject
```
Copy the output block to the top of your agent's system prompt. Every agent that receives this block shares the same long-term project awareness.
#### Recording a Decision
```bash
python {baseDir}/scripts/context_manager.py update \
--section decisions \
--add '{"decision": "Use atomic blackboard commits", "rationale": "Prevent race conditions in parallel agents"}'
```
#### Updating Milestones
```bash
# Mark a milestone complete
python {baseDir}/scripts/context_manager.py update \
--section milestones --complete "Ship v2.0"
# Add a planned milestone
python {baseDir}/scripts/context_manager.py update \
--section milestones --add '{"planned": "Integrate vector memory"}'
```
#### Setting the Tech Stack
```bash
python {baseDir}/scripts/context_manager.py update \
--section stack \
--set '{"language": "Python", "runtime": "Python 3.11", "framework": "SwarmOrchestrator"}'
```
#### Banning an Approach
```bash
python {baseDir}/scripts/context_manager.py update \
--section banned \
--add "Direct database writes from agent scripts (use permission gating)"
```
---
## When to Use This Skill
Use this skill when the task requires **local, file-based** multi-agent coordination within a single trusted workspace. All 6 bundled Python scripts run locally with zero network calls, zero subprocesses, and zero third-party packages.
### Use for
- **Task Delegation** — decompose complex work into sub-tasks routed to named in-session agents (`data_analyst`, `strategy_advisor`, `risk_assessor`)
- **Parallel Execution** — run multiple local agents simultaneously and synthesize results via the shared blackboard
- **Permission Wall** — score and gate access to abstract resource labels (`DATABASE`, `PAYMENTS`, `EMAIL`, `FILE_EXPORT`) before performing sensitive local operations
- **Shared Blackboard** — coordinate ephemeral task state across in-session agents via a persistent markdown file
### Do NOT use for
- External API or network service calls — the bundled Python scripts make **zero outbound network calls**
- Production identity or authorization — grant tokens are **advisory scoring outputs only**, not authenticated credentials; do not use as real access control
- Shell command execution or agent spawning — those capabilities require the TypeScript library (`npm install network-ai`) with operator-level `AgentRuntime` + `SandboxPolicy` configuration; they are **never activated by this skill**
- Starting an MCP or HTTP server — the optional MCP server (`bin/mcp-server.ts`) is an npm-package feature that must be explicitly started by the operator; it is **not part of this skill bundle**
- Any task solvable with a single direct tool call — this skill adds coordination overhead and is only appropriate when multiple agents must share state
## Quick Start
### 1. Initialize Budget (FIRST!)
**Always initialize a budget before any multi-agent task:**
```bash
python {baseDir}/scripts/swarm_guard.py budget-init \
--task-id "task_001" \
--budget 10000 \
--description "Q4 Financial Analysis"
```
### 2. Check Budget Before Task Delegation
Always run the budget guard before delegating any task:
```bash
# 1. Check budget (this skill's Python script)
python {baseDir}/scripts/swarm_guard.py intercept-handoff \
--task-id "task_001" --from orchestrator --to data_analyst \
--message "Analyze Q4 revenue data"
# 2. If result.allowed == true, proceed with delegation via your platform's built-in tools.
# If result.allowed == false, stop — budget exceeded or handoff limit reached.
```
### 3. Check Permission Before API Access
Before accessing SAP or Financial APIs, evaluate the request:
```bash
# Run the permission checker script
python {baseDir}/scripts/check_permission.py \
--agent "data_analyst" \
--resource "DATABASE" \
--justification "Need Q4 invoice data for quarterly report" \
--scope "read:invoices"
```
The script will output a grant token if approved, or denial reason if rejected.
### 4. Use the Shared Blackboard
Read/write coordination state:
```bash
# Write to blackboard
python {baseDir}/scripts/blackboard.py write "task:q4_analysis" '{"status": "in_progress", "agent": "data_analyst"}'
# Read from blackboard
python {baseDir}/scripts/blackboard.py read "task:q4_analysis"
# List all entries
python {baseDir}/scripts/blackboard.py list
```
## Agent-to-Agent Handoff Protocol
When delegating tasks between agents, always run the budget guard first.
### Step 1: Initialize Budget & Check Capacity
```bash
# Initialize budget (if not already done)
python {baseDir}/scripts/swarm_guard.py budget-init --task-id "task_001" --budget 10000
# Check current status
python {baseDir}/scripts/swarm_guard.py budget-check --task-id "task_001"
```
### Step 2: Identify Target Agent
Common agent types:
| Agent | Specialty |
|-------|-----------|
| `data_analyst` | Data processing, SQL, analytics |
| `strategy_advisor` | Business strategy, recommendations |
| `risk_assessor` | Risk analysis, compliance checks |
| `orchestrator` | Coordination, task decomposition |
### Step 3: Run Budget Guard Before Delegation
```bash
# Check budget AND handoff limits before delegating
python {baseDir}/scripts/swarm_guard.py intercept-handoff \
--task-id "task_001" \
--from orchestrator \
--to data_analyst \
--message "Analyze Q4 data" \
--artifact # Include if expecting output
```
**If ALLOWED:** Proceed with delegation via your platform's own tools
**If BLOCKED:** Stop — budget exceeded or handoff limit reached; do not delegate
### Step 4: Construct Handoff Message
Include these fields in your delegation:
- **instruction**: Clear task description
- **context**: Relevant background information
- **constraints**: Any limitations or requirements
- **expectedOutput**: What format/content you need back
### Step 5: Check Results
After delegation completes, read results from the blackboard:
```bash
python {baseDir}/scripts/blackboard.py read "task:001:data_analyst"
```
## Permission Scoring
> **Tokens are audit scoring outputs only.** Grant tokens from `check_permission.py` are NOT authenticated credentials and must NOT be used as real access control. They are advisory hints based on a local scoring model. Require a separate authenticated identity and explicit human approval before accessing PAYMENTS, DATABASE, or FILE_EXPORT resources.
**Always score permission before accessing:**
- `DATABASE` — Internal database / data store (abstract label — no external credentials)
- `PAYMENTS` — Financial/payment data services (abstract label — requires `--confirm-high-risk`)
- `EMAIL` — Email sending capability (abstract label)
- `FILE_EXPORT` — Exporting data to local files (abstract label — requires `--confirm-high-risk`)
> **Note**: These are abstract local resource type names used by `check_permission.py`. No external API credentials are required or used — all evaluation runs locally.
### Permission Evaluation Criteria
| Factor | Weight | Criteria |
|--------|--------|----------|
| Justification | 40% | Must explain specific task need |
| Trust Level | 30% | Agent's established trust score |
| Risk Assessment | 30% | Resource sensitivity + scope breadth |
### Using the Permission Script
```bash
# Request permission
python {baseDir}/scripts/check_permission.py \
--agent "your_agent_id" \
--resource "PAYMENTS" \
--justification "Generating quarterly financial summary for board presentation" \
--scope "read:revenue,read:expenses"
# Output if approved:
# ✅ GRANTED
# Token: grant_a1b2c3d4e5f6
# Expires: 2026-02-04T15:30:00Z
# Restrictions: read_only, no_pii_fields, audit_required
# Output if denied:
# ❌ DENIED
# Reason: Justification is insufficient. Please provide specific task context.
```
### Restriction Types
| Resource | Default Restrictions |
|----------|---------------------|
| DATABASE | `read_only`, `max_records:100` |
| PAYMENTS | `read_only`, `no_pii_fields`, `audit_required` |
| EMAIL | `rate_limit:10_per_minute` |
| FILE_EXPORT | `anonymize_pii`, `local_only` |
## Shared Blackboard Pattern
The blackboard (`swarm-blackboard.md`) is a markdown file for agent coordination:
```markdown
# Swarm Blackboard
Last Updated: 2026-02-04T10:30:00Z
## Knowledge Cache
### task:q4_analysis
{"status": "completed", "result": {...}, "agent": "data_analyst"}
### cache:revenue_summary
{"q4_total": 1250000, "growth": 0.15}
```
### Blackboard Operations
```bash
# Write with TTL (expires after 1 hour)
python {baseDir}/scripts/blackboard.py write "cache:temp_data" '{"value": 123}' --ttl 3600
# Read (returns null if expired)
python {baseDir}/scripts/blackboard.py read "cache:temp_data"
# Delete
python {baseDir}/scripts/blackboard.py delete "cache:temp_data"
# Get full snapshot
python {baseDir}/scripts/blackboard.py snapshot
```
## Parallel Execution
For tasks requiring multiple agent perspectives:
### Strategy 1: Merge (Default)
Combine all agent outputs into unified result.
```
Ask data_analyst AND strategy_advisor to both analyze the dataset.
Merge their insights into a comprehensive report.
```
### Strategy 2: Vote
Use when you need consensus - pick the result with highest confidence.
### Strategy 3: First-Success
Use for redundancy - take first successful result.
### Strategy 4: Chain
Sequential processing - output of one feeds into next.
> **TypeScript engine (v4.15.0):** These strategies map directly to the `FanOutFanIn` module (`lib/fan-out.ts`) which provides `merge`, `vote`, `firstSuccess`, and `consensus` fan-in strategies with concurrency control. For multi-phase workflows with approval gates, see `PhasePipeline` (`lib/phase-pipeline.ts`). For result scoring and threshold filtering, see `ConfidenceFilter` (`lib/confidence-filter.ts`). Matcher-based hooks (`lib/adapter-hooks.ts`) can target specific agents or tools via glob patterns. For sandboxed agent execution, see `AgentRuntime` (`lib/agent-runtime.ts`). For large-scale agent coordination, see `StrategyAgent` (`lib/strategy-agent.ts`).
### Example Parallel Workflow
```
# For each delegation below, first run the budget guard:
# python {baseDir}/scripts/swarm_guard.py intercept-handoff --task-id "task_001" --from orchestrator --to <agent> --message "<task>"
# If result.allowed == true, delegate via your platform's own tools.
1. Delegate to data_analyst: "Extract key metrics from Q4 data"
2. Delegate to risk_assessor: "Identify compliance risks in Q4 data"
3. Delegate to strategy_advisor: "Recommend actions based on Q4 trends"
4. Wait for all results and read them from the blackboard
5. Synthesize: Combine metrics + risks + recommendations into executive summary
```
## Security Considerations
1. **Never bypass the permission wall** for gated resources
2. **Always include justification** explaining the business need
3. **Use minimal scope** - request only what you need
4. **Check token expiry** - tokens are valid for 5 minutes
5. **Validate tokens** - use `python {baseDir}/scripts/validate_token.py TOKEN` to verify grant tokens before use
6. **Audit trail** - all permission requests are logged
## 📝 Audit Trail Requirements (MANDATORY)
**Every sensitive action MUST be logged to `data/audit_log.jsonl`** to maintain compliance and enable forensic analysis.
> **Privacy note:** Audit log entries contain agent-provided free-text fields (justifications, descriptions). These are stored locally in `data/audit_log.jsonl` and kept on this machine only by this skill — no audit data leaves the local filesystem. However, **do not put PII, passwords, or API keys in justification strings** — they persist on disk. Consider periodic log rotation and restricting OS file permissions on the `data/` directory.
### What Gets Logged Automatically
The scripts automatically log these events:
- `permission_granted` - When access is approved
- `permission_denied` - When access is rejected
- `permission_revoked` - When a token is manually revoked
- `ttl_cleanup` - When expired tokens are purged
- `result_validated` / `result_rejected` - Swarm Guard validations
### Log Entry Format
```json
{
"timestamp": "2026-02-04T10:30:00+00:00",
"action": "permission_granted",
"details": {
"agent_id": "data_analyst",
"resource_type": "DATABASE",
"justification": "Q4 revenue analysis",
"token": "grant_abc123...",
"restrictions": ["read_only", "max_records:100"]
}
}
```
### Reading the Audit Log
```bash
# View recent entries (last 10)
tail -10 {baseDir}/data/audit_log.jsonl
# Search for specific agent
grep "data_analyst" {baseDir}/data/audit_log.jsonl
# Count actions by type
cat {baseDir}/data/audit_log.jsonl | jq -r '.action' | sort | uniq -c
```
### Custom Audit Entries
If you perform a sensitive action manually, log it:
```python
import json
from datetime import datetime, timezone
from pathlib import Path
audit_file = Path("{baseDir}/data/audit_log.jsonl")
entry = {
"timestamp": datetime.now(timezone.utc).isoformat(),
"action": "manual_data_access",
"details": {
"agent": "orchestrator",
"description": "Direct database query for debugging",
"justification": "Investigating data sync issue #1234"
}
}
with open(audit_file, "a") as f:
f.write(json.dumps(entry) + "\n")
```
## 🧹 TTL Enforcement (Token Lifecycle)
Expired tokens stop validating on their own: `validate_token.py` rejects any grant past its `expires_at`. Removing expired entries from `data/active_grants.json` is a manual step:
```bash
# Validate a grant token
python {baseDir}/scripts/validate_token.py grant_a1b2c3d4e5f6
# List expired tokens (without removing)
python {baseDir}/scripts/revoke_token.py --list-expired
# Remove all expired tokens
python {baseDir}/scripts/revoke_token.py --cleanup
# Output:
# 🧹 TTL Cleanup Complete
# Removed: 3 expired token(s)
# Remaining active grants: 2
```
**Best Practice**: Run `--cleanup` at the start of each multi-agent task to ensure a clean permission state.
## ⚠️ Swarm Guard: Preventing Common Failures
Two critical issues can derail multi-agent swarms:
### 1. The Handoff Tax 💸
**Problem**: Agents waste tokens "talking about" work instead of doing it.
**Prevention**:
```bash
# Before each handoff, check your budget:
python {baseDir}/scripts/swarm_guard.py check-handoff --task-id "task_001"
# Output:
# 🟢 Task: task_001
# Handoffs: 1/3
# Remaining: 2
# Action Ratio: 100%
```
**Rules enforced**:
- **Max 3 handoffs per task** - After 3, produce output or abort
- **Max 500 chars per message** - Be concise: instruction + constraints + expected output
- **60% action ratio** - At least 60% of handoffs must produce artifacts
- **2-minute planning limit** - No output after 2min = timeout
```bash
# Record a handoff (with tax checking):
python {baseDir}/scripts/swarm_guard.py record-handoff \
--task-id "task_001" \
--from orchestrator \
--to data_analyst \
--message "Analyze sales data, output JSON summary" \
--artifact # Include if this handoff produces output
```
### 2. Silent Failure Detection 👻
**Problem**: One agent fails silently, others keep working on bad data.
**Prevention - Heartbeats**:
```bash
# Agents must send heartbeats while working:
python {baseDir}/scripts/swarm_guard.py heartbeat --agent data_analyst --task-id "task_001"
# Check if an agent is healthy:
python {baseDir}/scripts/swarm_guard.py health-check --agent data_analyst
# Output if healthy:
# 💚 Agent 'data_analyst' is HEALTHY
# Last seen: 15s ago
# Output if failed:
# 💔 Agent 'data_analyst' is UNHEALTHY
# Reason: STALE_HEARTBEAT
# → Do NOT use any pending results from this agent.
```
**Prevention - Result Validation**:
```bash
# Before using another agent's result, validate it:
python {baseDir}/scripts/swarm_guard.py validate-result \
--task-id "task_001" \
--agent data_analyst \
--result '{"status": "success", "output": {"revenue": 125000}, "confidence": 0.85}'
# Output:
# ✅ RESULT VALID
# → APPROVED - Result can be used by other agents
```
**Required result fields**: `status`, `output`, `confidence`
### Supervisor Review
Before finalizing any task, run supervisor review:
```bash
python {baseDir}/scripts/swarm_guard.py supervisor-review --task-id "task_001"
# Output:
# ✅ SUPERVISOR VERDICT: APPROVED
# Task: task_001
# Age: 1.5 minutes
# Handoffs: 2
# Artifacts: 2
```
**Verdicts**:
- `APPROVED` - Task healthy, results usable
- `WARNING` - Issues detected, review recommended
- `BLOCKED` - Critical failures, do NOT use results
## Troubleshooting
### Permission Denied
- Provide more specific justification (mention task, purpose, expected outcome)
- Narrow the requested scope
- Check agent trust level
### Blackboard Read Returns Null
- Entry may have expired (check TTL)
- Key may be misspelled
- Entry was never written
### Session Not Found
- Run `sessions_list` (OpenClaw platform built-in) to see available sessions
- Session may need to be started first
## Security Framework Assessment (MAESTRO / OWASP AST)
The following findings are drawn from the **MAESTRO Agent Security Threat** framework (OWASP LLM / ASVS mapping). They are addressed by existing architectural controls in Network-AI — not open vulnerabilities.
> **Engine-level OWASP Agentic AI Top 10 (2026):** the TypeScript orchestration engine maps all 10 OWASP Agentic risk categories (ASI-01 … ASI-10) to deterministic controls, verifiable programmatically via `verifyOwaspCoverage()` (`lib/owasp-compliance.ts`, exported from `network-ai`). See the coverage table in the README. The MAESTRO/AST findings below scope the bundled Python skill scripts.
### AST03 — Over-Privileged Skills · Severity: High
> *Skills are granted broader permissions than their stated function requires, creating excessive blast radius if prompt-injected.*
| Control | How Network-AI addresses it |
|---|---|
| **Permission manifest** | `metadata.openclaw` in SKILL.md frontmatter explicitly declares `capabilities` (filesystem paths, `NETWORK_AI_ENV` only, no shell, no ports, single-invocation scripts), `bundle_scope`, `network_calls: none`, and `requires.bins: [python3]`; `allowed-tools` limits the tool scope to the six bundled scripts plus `Read` — no API credentials, no external services |
| **Least-privilege resource gating** | `check_permission.py` uses a weighted scoring model (justification 40 %, trust 30 %, risk 30 %); PAYMENTS, DATABASE, and FILE_EXPORT (`HIGH_RISK_RESOURCES`) require `--confirm-high-risk` acknowledgment before any token is issued; `--scope` limits every grant to minimum required access |
| **Abstract resource labels only** | PAYMENTS, DATABASE, EMAIL, FILE_EXPORT are local scoring labels — no external credentials exist in the skill; there is nothing to leak to an external service |
| **HMAC-signed grant tokens** | Since v5.5.2, every grant record carries `_sig` (HMAC-SHA256 over canonical fields); `validate_token.py` rejects tampered records — privilege escalation via forged grants is detected at validation time |
| **Advisory-only tokens** | All grant tokens are explicitly marked `advisory: true`; downstream systems must add a separate authenticated identity check and human approval before any real sensitive action — documented in frontmatter and throughout SKILL.md |
### AST06 — Weak Isolation · Severity: High
> *Skills execute in the host agent's security context with full filesystem, shell, and network access.*
| Control | How Network-AI addresses it |
|---|---|
| **Zero network calls, no shell** | All bundled Python scripts use Python stdlib only, spawn no subprocesses, execute no shell commands, open no sockets, and make no network calls — declared in `metadata.openclaw.capabilities`, `network_calls`, and `bundle_scope`. No server, runtime, or package is installed or started by this skill. |
| **Environment isolation** | `NETWORK_AI_ENV` / `--env` routes all state to `data/<env>/`; dev, staging, and production state are fully separated; live state (`audit_log.jsonl`, `active_grants.json`) never promotes across environments |
| **Caller-driven execution** | Each script runs once per explicit command and exits; nothing is scheduled or kept running. Permission scores are advisory; the caller (or a human) decides whether to act on them. |
| **No hot-reload surface** | Bundled scripts do not implement or respond to a SkillsWatcher; skill updates require explicit `clawhub install` — no mid-session reload is possible |
> Sandboxed shell execution (`AgentRuntime`, `SandboxPolicy`, `ApprovalGate` — manual approval by default) lives only in the separate TypeScript npm package and is not part of this skill bundle.
### AST07 — Update Drift · Severity: Medium
> *Installed skills drift out of sync — either unpatched (leaving known CVEs open) or blindly auto-updated (potentially receiving malicious patches).*
| Control | How Network-AI addresses it |
|---|---|
| **Exact version pinning** | npm `package.json` uses exact `"version": "5.16.0"` — no semver range specifiers; `clawhub install network-ai` pins to a specific published version |
| **Zero transitive dependency drift** | All bundled Python scripts use Python stdlib only — `pip install` is never required; there are no third-party packages to drift, be compromised upstream, or introduce CVEs |
| **Signed, tagged releases** | Every release is committed with a signed Git tag (`v5.7.x`); commit hash is verifiable against CHANGELOG.md; GitHub releases link tag → diff → changelog entry |
| **Supply chain monitoring** | npm package continuously scored by Socket.dev (score A); any new dependency or permission change triggers an alert |
| **No auto-update mechanism** | Updates require explicit user action (`clawhub install`, `npm install network-ai@latest`); there is no background updater or hot-reload path |
| **CHANGELOG.md audit trail** | Every change — including docs-only patches — is tracked with version, date, and rationale; operators can diff any two versions to assess update risk before applying |
## Security Scan Findings (ClawHub)
The per-finding scan history and documented mitigations for this skill are kept in the repository's [SECURITY.md](https://github.com/Jovancoding/Network-AI/blob/main/SECURITY.md#clawhub-skill-scan-findings) (Security Scan Results, ClawHub Skill Scan Findings).
## Bundled Script Inventory
Complete I/O surface of every file in this skill. No script makes network calls, opens sockets, spawns subprocesses, or reads environment variables other than `NETWORK_AI_ENV`. Paths below are under `data/` (or `data/<env>/` when `NETWORK_AI_ENV` / `--env` is set).
| Script | Purpose | Reads | Writes |
|---|---|---|---|
| `scripts/blackboard.py` | Shared blackboard with propose / validate / commit | `swarm-blackboard.md`, `pending_changes/*.json`, `.blackboard.lock` | `swarm-blackboard.md`, `pending_changes/*.json`, `pending_changes/archive/*.json` (committed/aborted changes), `.blackboard.lock` |
| `scripts/check_permission.py` | Advisory permission scoring over abstract labels | `active_grants.json`, `audit_log.jsonl`, `.signing_key` | `active_grants.json`, `audit_log.jsonl`, `.signing_key` (first run) |
| `scripts/validate_token.py` | Verify an advisory grant's HMAC signature and expiry | `active_grants.json`, `.signing_key` | none |
| `scripts/revoke_token.py` | Revoke advisory grants, remove expired ones | `active_grants.json`, `audit_log.jsonl` | `active_grants.json`, `audit_log.jsonl` |
| `scripts/context_manager.py` | Validated project context (Layer-3 memory) | `project-context.json` | `project-context.json`, `audit_log.jsonl` |
| `scripts/swarm_guard.py` | Budget, handoff, and health guards | `swarm_budgets.json`, `heartbeats.json`, `task_tracking.json`, `agent_health.json`, `budget_tracking.json`, `audit_log.jsonl` | same six files |
## References
This skill is part of the larger [Network-AI](https://github.com/Jovancoding/Network-AI) project. See the repository for full documentation on the permission system, blackboard schema, and trust-level calculations.
將開發過程中的經驗、錯誤與修正記錄為 Markdown 檔案,供日後重用並提升為工作區記憶。
用自然語言描述需求,在本機與遠端技能市場尋找技能並取得推薦。
給 AI agent 用的瀏覽器自動化命令列技能。
將使用者明確糾正與自我檢視整理成分層記憶,並依使用情況升級或封存。
規劃 AI 代理主動跟進、工作記憶與回顧流程的工作區設定指南。
指導如何建立與更新有效 Claude 技能的寫作指南。
在安裝第三方技能之前,按清單審查來源、許可權與危險模式的技能。
把盛唐詩人李白的詩學觀、意象系統與口吻,蒸餾成 AI 可呼叫的角色包。
資料月份:2026-10 · 下載/星標數聚合自公開技能註冊庫(ClawHub、SkillHub),按月更新。口徑說明見資料方法。