Metadata-Version: 2.4
Name: alibabacloud-agent-fs
Version: 0.4.0
Summary: Virtual filesystem for Alibaba Cloud cloud-native services (AgentLoop Memory, Nacos)
Author: CMS Team
License: MIT
Project-URL: Homepage, https://github.com/aliyun/alibabacloud-agent-fs
Project-URL: Documentation, https://help.aliyun.com/product/28958.html
Keywords: alibaba-cloud,alibabacloud,nacos,agentloop,memory,fuse,filesystem,agent,ai,cloud-native
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Filesystems
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fusepy>=3.0.1
Requires-Dist: python-dotenv>=0.19.0
Requires-Dist: alibabacloud-tea-openapi>=0.3.0
Requires-Dist: alibabacloud-tea-util>=0.3.0
Requires-Dist: alibabacloud-credentials>=0.3.0
Requires-Dist: alibabacloud-cms20240330>=6.2.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Dynamic: license-file

# Alibaba Cloud Agent FS

Virtual filesystem for Alibaba Cloud cloud-native services — designed for AI Agent interaction.

Exposes **AgentLoop Memory** (CMS) and **Nacos** (Config Center + Service Registry + Skill Registry) as a standard POSIX filesystem. Interact with cloud services using nothing but `ls`, `cat`, `echo`, `cp`, `mkdir`, and `rm`.

## Features

- **Agent-Friendly Design**: Explore and operate cloud services with standard shell commands
- **Self-Describing**: `_help.txt` files at every level guide usage
- **Multi-Service**: Memory, config management, service discovery, and skill management in one mount
- **Extensible**: Plugin-based provider architecture — add new Alibaba Cloud services easily
- **POSIX Compatible**: Works with any tool that uses standard file operations

## Installation

### Install from source

```bash
pip install .
```

### Install from wheel

```bash
pip install build
python3 -m build
pip install dist/alibabacloud_agent_fs-*.whl
```

### OS Dependencies (FUSE)

#### macOS

```bash
brew install macfuse
```

#### Linux (Ubuntu/Debian)

```bash
sudo apt-get install fuse libfuse-dev
```

#### Linux (CentOS/RHEL/Alibaba Cloud Linux)

```bash
sudo yum install fuse fuse-devel
```

## Configuration

Set environment variables or use a `.env` file:

```bash
# AgentLoop Memory (CMS) - static AK/SK
export ALIBABA_CLOUD_ACCESS_KEY_ID="your-access-key-id"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-access-key-secret"
export CMS_WORKSPACE="your-workspace-name"
export CMS_ENDPOINT="cms.cn-hangzhou.aliyuncs.com"  # optional

# AgentLoop Memory (CMS) - STS
export ALIBABA_CLOUD_ACCESS_KEY_ID="your-sts-access-key-id"
export ALIBABA_CLOUD_ACCESS_KEY_SECRET="your-sts-access-key-secret"
export ALIBABA_CLOUD_SECURITY_TOKEN="your-sts-security-token"

# AgentLoop Memory (CMS) - OIDC / RRSA
export ALIBABA_CLOUD_ROLE_ARN="acs:ram::123456789012:role/example"
export ALIBABA_CLOUD_OIDC_PROVIDER_ARN="acs:ram::123456789012:oidc-provider/example"
export ALIBABA_CLOUD_OIDC_TOKEN_FILE="/var/run/secrets/tokens/oidc-token"
export ALIBABA_CLOUD_REGION_ID="cn-hangzhou"  # optional, default: cn-hangzhou

# Nacos Config & Service Discovery
export NACOS_SERVER_ADDR="localhost:8848"       # or MSE endpoint
export NACOS_NAMESPACE="public"                 # optional, default: public
export NACOS_USERNAME="nacos"                   # optional, for self-hosted Nacos
export NACOS_PASSWORD="nacos"                   # optional
export NACOS_ACCESS_KEY="your-ak"              # optional, for Alibaba Cloud MSE
export NACOS_SECRET_KEY="your-sk"              # optional
```

For AgentLoop Memory, you can use any one of these auth modes:
- AK/SK
- AK/SK + STS security token
- OIDC / RRSA

Either provider can be omitted — the filesystem only mounts providers whose credentials are present.

## Usage

### Mount the Filesystem

```bash
mkdir -p /tmp/alibabacloud
alibabacloud-agent-fs /tmp/alibabacloud
```

Or with explicit options:

```bash
alibabacloud-agent-fs /tmp/alibabacloud \
  --workspace my-cms-project \
  --endpoint cms.cn-shanghai.aliyuncs.com \
  --nacos-server mse.cn-hangzhou.aliyuncs.com:8848
```

Or with explicit STS / OIDC options:

```bash
alibabacloud-agent-fs /tmp/alibabacloud \
  --workspace my-cms-project \
  --access-key-id sts-ak \
  --access-key-secret sts-sk \
  --security-token sts-token

alibabacloud-agent-fs /tmp/alibabacloud \
  --workspace my-cms-project \
  --role-arn acs:ram::123456789012:role/example \
  --oidc-provider-arn acs:ram::123456789012:oidc-provider/example \
  --oidc-token-file /var/run/secrets/tokens/oidc-token
```

### AgentLoop Memory Operations

```bash
# View help
cat /tmp/alibabacloud/agentloop-memory/_help.txt

# List memory stores
ls /tmp/alibabacloud/agentloop-memory/stores/

# Create a new store
mkdir /tmp/alibabacloud/agentloop-memory/stores/my_memories

# Add a memory (WRITE-ONLY, async processing)
echo "User prefers dark mode" > /tmp/alibabacloud/agentloop-memory/stores/my_memories/_add.txt

# Wait ~30-60 seconds for processing, then search
cat /tmp/alibabacloud/agentloop-memory/stores/my_memories/search/preferences.txt

# View all memories for a user
cat /tmp/alibabacloud/agentloop-memory/stores/my_memories/users/default_user/_all.txt

# Delete a memory store
rmdir /tmp/alibabacloud/agentloop-memory/stores/my_memories
```

### Nacos Config Operations

```bash
# List namespaces
ls /tmp/alibabacloud/nacos/config/

# List groups in a namespace
ls /tmp/alibabacloud/nacos/config/public/

# List configs in a group
ls /tmp/alibabacloud/nacos/config/public/DEFAULT_GROUP/

# Read a config
cat /tmp/alibabacloud/nacos/config/public/DEFAULT_GROUP/application.properties

# Create or update a config
echo "server.port=8080" > /tmp/alibabacloud/nacos/config/public/DEFAULT_GROUP/application.properties

# Delete a config
rm /tmp/alibabacloud/nacos/config/public/DEFAULT_GROUP/old-config.properties
```

### Nacos Service Discovery Operations

```bash
# List namespaces
ls /tmp/alibabacloud/nacos/services/

# List service groups
ls /tmp/alibabacloud/nacos/services/public/

# List services in a group
ls /tmp/alibabacloud/nacos/services/public/DEFAULT_GROUP/

# View service metadata
cat /tmp/alibabacloud/nacos/services/public/DEFAULT_GROUP/my-service/_info.json

# List service instances
ls /tmp/alibabacloud/nacos/services/public/DEFAULT_GROUP/my-service/instances/

# View instance details
cat "/tmp/alibabacloud/nacos/services/public/DEFAULT_GROUP/my-service/instances/10.0.0.1:8080.json"

# Register an instance (write JSON to _register.json)
echo '{"action":"register","ip":"10.0.0.2","port":8080,"weight":1.0}' \
  > /tmp/alibabacloud/nacos/services/public/DEFAULT_GROUP/my-service/instances/_register.json

# Deregister an instance
echo '{"action":"deregister","ip":"10.0.0.2","port":8080}' \
  > /tmp/alibabacloud/nacos/services/public/DEFAULT_GROUP/my-service/instances/_register.json
```

### Nacos Skill Operations

> **Note**: Skill 功能要求 Nacos Server >= 3.2.0。

```bash
# List namespaces
ls /tmp/alibabacloud/nacos/skills/

# List skills in a namespace
ls /tmp/alibabacloud/nacos/skills/public/

# View skill metadata
cat /tmp/alibabacloud/nacos/skills/public/my-skill/_info.json

# List files in a skill package
ls /tmp/alibabacloud/nacos/skills/public/my-skill/

# Read skill content
cat /tmp/alibabacloud/nacos/skills/public/my-skill/SKILL.md

# Upload a skill (cp ZIP file)
cp my-skill.zip /tmp/alibabacloud/nacos/skills/public/my-skill.zip
```

### Unmount

```bash
# Linux
fusermount -u /tmp/alibabacloud

# macOS
umount /tmp/alibabacloud
```

## Directory Structure

```
/
├── _help.txt
├── agentloop-memory/                    # AgentLoop Memory (CMS)
│   └── stores/
│       ├── _help.txt
│       └── {store_name}/
│           ├── _info.json               # Store configuration (READ-ONLY)
│           ├── _add.txt                 # Add memories (WRITE-ONLY, async)
│           ├── _help.txt
│           ├── memories/
│           │   └── {memory_id}.json     # Individual memory (READ / DELETE)
│           ├── users/
│           │   └── {user_id}/
│           │       ├── _all.txt         # All user memories (READ)
│           │       └── _add.txt         # Add for user (WRITE)
│           ├── agents/
│           │   └── {agent_id}/...
│           └── search/
│               └── {query}.txt          # Search results (READ)
└── nacos/                               # Nacos Config & Service Discovery
    ├── config/
    │   └── {namespace}/
    │       └── {group}/
    │           └── {dataId}             # Config content (READ / WRITE / DELETE)
    ├── services/
    │   └── {namespace}/
    │       └── {group}/
    │           └── {service}/
    │               ├── _info.json       # Service metadata (READ-ONLY)
    │               └── instances/
    │                   ├── {ip}:{port}.json    # Instance details (READ-ONLY)
    │                   └── _register.json      # Register/deregister (WRITE-ONLY)
    └── skills/
        └── {namespace}/
            ├── {skillName}.zip              # Upload skill (WRITE: cp ZIP)
            └── {skillName}/
                ├── _info.json               # Skill metadata (READ-ONLY)
                ├── SKILL.md                 # Skill content (READ-ONLY)
                └── {resource_file}          # Other files in skill package (READ-ONLY)
```

## API Mapping

### AgentLoop Memory

| Shell Command | CMS API |
|---|---|
| `mkdir agentloop-memory/stores/{name}` | CreateMemoryStore |
| `rmdir agentloop-memory/stores/{name}` | DeleteMemoryStore |
| `cat agentloop-memory/stores/{name}/_info.json` | GetMemoryStore |
| `echo "text" > agentloop-memory/stores/{name}/_add.txt` | AddMemories |
| `cat agentloop-memory/stores/{name}/search/{query}.txt` | SearchMemories |
| `cat agentloop-memory/stores/{name}/memories/{id}.json` | GetMemory |
| `rm agentloop-memory/stores/{name}/memories/{id}.json` | DeleteMemory |
| `ls agentloop-memory/stores/` | ListMemoryStores |

### Nacos Config

| Shell Command | Nacos API |
|---|---|
| `ls nacos/config/` | List Namespaces |
| `ls nacos/config/{ns}/{group}/` | List Configs (search=blur) |
| `cat nacos/config/{ns}/{group}/{dataId}` | GetConfig |
| `echo "val" > nacos/config/{ns}/{group}/{dataId}` | PublishConfig |
| `rm nacos/config/{ns}/{group}/{dataId}` | RemoveConfig |

### Nacos Services

| Shell Command | Nacos API |
|---|---|
| `ls nacos/services/{ns}/{group}/` | ListServices |
| `cat nacos/services/{ns}/{group}/{svc}/_info.json` | GetService |
| `ls nacos/services/{ns}/{group}/{svc}/instances/` | ListInstances |
| `echo '{"action":"register",...}' > .../instances/_register.json` | RegisterInstance |
| `echo '{"action":"deregister",...}' > .../instances/_register.json` | DeregisterInstance |

### Nacos Skills

| Shell Command | Nacos API |
|---|---|
| `ls nacos/skills/{ns}/` | ListSkills (v3) |
| `cat nacos/skills/{ns}/{name}/_info.json` | Skill metadata (from list cache) |
| `ls nacos/skills/{ns}/{name}/` | List skill files (download ZIP + extract) |
| `cat nacos/skills/{ns}/{name}/SKILL.md` | Read skill file (from ZIP cache) |
| `cp skill.zip nacos/skills/{ns}/{name}.zip` | UploadSkill (v3, multipart ZIP) |

## For AI Agents

This filesystem is designed to give AI agents access to Alibaba Cloud services using only standard shell commands — no SDKs, no special APIs.

Prompt templates are provided in the `agent_integration/` directory:

1. **[INSTALL_PROMPT.md](agent_integration/INSTALL_PROMPT.md)**: Instructions for the agent to install dependencies, configure credentials, and mount the filesystem.
2. **[USAGE_PROMPT.md](agent_integration/USAGE_PROMPT.md)**: System prompt snippet teaching the agent how to use memory, config, and service discovery.
3. **[SKILL.md](agent_integration/skill/SKILL.md)**: Cursor Agent skill for automatic memory integration.

## CLI Reference

```
alibabacloud-agent-fs [-h] [-V] [-e FILE]
                       [--endpoint HOST] [-w NAME] [-p NAME]
                       [--access-key-id ID] [--access-key-secret SECRET]
                       [--security-token TOKEN] [--role-arn ARN]
                       [--oidc-provider-arn ARN] [--oidc-token-file FILE]
                       [--role-session-name NAME] [--region-id REGION]
                       [--nacos-server HOST:PORT] [--nacos-namespace NS]
                       [--nacos-username USER] [--nacos-password PASS]
                       [--nacos-access-key AK] [--nacos-secret-key SK]
                       [-d] [--allow-other]
                       mountpoint

Options:
  mountpoint                  Directory to mount the filesystem
  -V, --version               Show version
  -e, --env FILE              Path to .env file

AgentLoop Memory (CMS):
  --endpoint HOST             CMS endpoint (default: cms.cn-hangzhou.aliyuncs.com)
  -w, --workspace NAME        CMS workspace name
  -p, --project NAME          Alias for --workspace
  --access-key-id ID          Alibaba Cloud Access Key ID
  --access-key-secret SECRET  Alibaba Cloud Access Key Secret
  --security-token TOKEN      Alibaba Cloud STS security token
  --role-arn ARN              OIDC role ARN for AgentLoop Memory
  --oidc-provider-arn ARN     OIDC provider ARN for AgentLoop Memory
  --oidc-token-file FILE      OIDC token file path for AgentLoop Memory
  --role-session-name NAME    OIDC role session name
  --region-id REGION          Region used to derive the STS endpoint for OIDC auth

Nacos:
  --nacos-server HOST:PORT    Nacos server address
  --nacos-namespace NS        Default namespace (default: public)
  --nacos-username USER       Nacos username
  --nacos-password PASS       Nacos password
  --nacos-access-key AK       Alibaba Cloud AK for MSE Nacos
  --nacos-secret-key SK       Alibaba Cloud SK for MSE Nacos

FUSE:
  -d, --debug                 Enable debug logging
  --allow-other               Allow other users access
```

## Testing

```bash
# Unit tests
python -m pytest tests/test_unit.py

# Integration tests (requires credentials)
python tests/test_memory_api.py

# E2E tests (requires mounted filesystem)
alibabacloud-agent-fs /tmp/alibabacloud_test &
bash tests/e2e_test.sh
```

## License

MIT License
