### Skills Feature Command-Line Usage Examples

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/skills.md

Illustrates common commands for managing skills, such as listing, finding, inspecting, and installing skills from a remote repository.

```bash
x-skills list
x-skills find testing
x-skills info testing-strategy
x-skills install https://github.com/example/agent-skills@testing-strategy
```

--------------------------------

### Create Project in Workspace Example

Source: https://github.com/niapya/ai-sdk-x/blob/main/_autodocs/api-reference/Workspace.md

A comprehensive TypeScript example demonstrating how to initialize a workspace, set up a Git repository, create project files using a patch, record actions in memory, and perform an initial commit.

```typescript
import { X, encodeUtf8ToBytes } from 'ai-sdk-x';

async function createProjectInWorkspace() {
  const x = X.init({
    workspace: { mountPoint: '/home/user/workspace' },
    patch: true,
    git: true,
    memory: true
  });

  console.log('开始创建项目在 Workspace...\n');

  // 1. 初始化 Git
  await x.exec('git init');
  await x.exec('git config user.name "AI Agent"');
  await x.exec('git config user.email "ai@agent.dev"');

  // 2. 创建项目结构
  const projectSetup = `*** Begin Patch
*** Add File: $WORKSPACE_HOME/package.json
+{
+  "name": "ai-workspace-project",
+  "version": "1.0.0",
+  "description": "AI 代理创建的项目",
+  "main": "src/index.ts",
+  "scripts": {
+    "dev": "ts-node src/index.ts",
+    "build": "tsc",
+    "test": "jest"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "jest": "^29.0.0"
+  }
+}
*** Add File: $WORKSPACE_HOME/README.md
+# AI Workspace 项目
+
+由 AI 代理创建的演示项目。
+
+## 快速开始
+
+\`\`\`bash
npm install
npm run dev
\`\`\`
+
+## 项目结构
+
+- 
+src/
+: 源代码
+- 
+tests/
+: 测试文件
+- 
+docs/
+: 文档
*** Add File: $WORKSPACE_HOME/src/index.ts
+import { sayHello } from './greet';
+
+console.log(sayHello('Workspace'));
*** Add File: $WORKSPACE_HOME/src/greet.ts
+export function sayHello(name: string): string {
+  return 
`Hello, 
${name}!
`;
}
*** Add File: $WORKSPACE_HOME/tests/greet.test.ts
+import { sayHello } from '../src/greet';
+
+describe('greet', () => {
+  test('sayHello 返回问候', () => {
+    expect(sayHello('World')).toBe('Hello, World!');
+  });
+});
*** Add File: $WORKSPACE_HOME/.gitignore
+node_modules/
dist/
.env
*.log
coverage/
*** End Patch`;

  await x.exec('x-patch', {
    stdin: encodeUtf8ToBytes(projectSetup)
  });

  // 3. 记录到 Memory
  const memoryEntry = `项目在 Workspace 中创建，包含：
- TypeScript 项目配置
- 源代码和测试框架
- 完整的 npm 脚本和依赖`;

  await x.exec(`printf '${memoryEntry}' | x-memory add "Workspace项目" --description "AI创建的项目" --keyword workspace --stdin`);

  // 4. 初始提交
  await x.exec('git add .');
  await x.exec('git commit -m "初始化：创建项目框架"');

  // 5. 显示最终状态
  console.log('\n项目创建完成！');
  
  const wsStatus = await x.exec('ls -la $WORKSPACE_HOME');
  console.log('Workspace 内容:', wsStatus.stdout);

  const gitLog = await x.exec('git log --oneline');
  console.log('Git 提交历史:', gitLog.stdout);
}

createProjectInWorkspace().catch(console.error);
```

--------------------------------

### Example Usage of BootstrappableMountableFs

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/runtime/file-system.md

Demonstrates creating a BootstrappableMountableFs instance and performing basic file operations like creating a directory and writing a file within it.

```typescript
import { BootstrappableMountableFs } from "ai-sdk-x";
import { InMemoryFs } from "just-bash";

const base = new InMemoryFs();
const fs = new BootstrappableMountableFs({ base });

await fs.mkdir("/workspace", { recursive: true });
await fs.writeFile("/workspace/README.md", "# Demo\n");
```

--------------------------------

### Install AI SDK X Packages

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/quick-start.md

Install the necessary npm packages for AI SDK X, including the core SDK, the agent framework, and zod for validation.

```bash
npm install ai-sdk-x ai zod
```

--------------------------------

### Example Usage of SubpathFs

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/runtime/file-system.md

Demonstrates creating a subpath filesystem and reading a file from it, showing how it isolates content within a specified directory.

```typescript
import { createSubpathFs } from "ai-sdk-x";
import { InMemoryFs } from "just-bash";

const base = new InMemoryFs();
await base.mkdir("/projects/demo", { recursive: true });
await base.writeFile("/projects/demo/README.md", "hello");

const demoFs = createSubpathFs(base, "/projects/demo");

console.log(await demoFs.readFile("/README.md"));
```

--------------------------------

### InMemoryKVStore Usage Example

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/runtime/backend-storage.md

Demonstrates the usage of the default InMemoryKVStore implementation for basic set and get operations with a TTL. Suitable for tests, local demos, and ephemeral runtimes.

```typescript
import { InMemoryKVStore } from "ai-sdk-x";

const kv = new InMemoryKVStore({
  now: () => Date.now(),
});

await kv.set("answer", "42", 10_000);
console.log(await kv.get("answer"));
```

--------------------------------

### Example Usage of IndexedFs

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/runtime/file-system.md

Shows creating an IndexedFs with an in-memory source and cache, then performing operations like creating a directory and writing a file, followed by listing directory contents.

```typescript
import { IndexedFs, InMemoryKVStore } from "ai-sdk-x";
import { InMemoryFs } from "just-bash";

const source = new InMemoryFs();
const cache = new InMemoryKVStore();
const fs = new IndexedFs({
  fs: source,
  cache,
});

await fs.mkdir("/docs", { recursive: true });
await fs.writeFile("/docs/index.md", "# Docs\n");

console.log(await fs.readdir("/docs"));
```

--------------------------------

### Add File with x-patch

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/patch.md

Example of using the `x-patch` command to add a new file. Paths resolve relative to the command's current working directory.

```bash
x-patch <<'EOF'
*** Begin Patch
*** Add File: README.md
+# Example
*** End Patch
EOF
```

--------------------------------

### Create a Feature with Commands and Hooks

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/create-your-feature.md

Register a feature with a name, description, commands, and setup logic using `onExecStart` hook to create directories and set environment variables.

```typescript
const projectFeature: Feature = {
  name: "project",
  description: () =>
    "The `project-info` command prints information about the current project.",
  command: [projectInfoCommand],
  hooks: {
    async onExecStart(ctx) {
      await ctx.fs.mkdir("/home/user/project", { recursive: true });
      ctx.setEnv("PROJECT_HOME", "/home/user/project");
    },
  },
};

x.registerFeature(projectFeature);
```

--------------------------------

### Initialize AI SDK X and Run an Agent

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/quick-start.md

Initialize the AI SDK X Bash runtime and use it to create and run an agent that installs skills, implements a game, and summarizes its work.

```typescript
import { X } from "ai-sdk-x";
import { ToolLoopAgent, stepCountIs } from "ai";

const bash = X.init();
const tools = await bash.getTools();

const agent = ToolLoopAgent({
  model: "gpt-5.5",
  tools,
  stopWhen: stepCountIs(20),
});

await agent.generate({
  prompt: `
    First, search and install "frontend-design" Skills.

    Then, read it and implement a "Snake game" in the Workspace.

    Finally, summarise into Memory.`,
});
```

--------------------------------

### Update File with x-patch

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/patch.md

Example of using the `x-patch` command to update an existing file. Paths resolve relative to the command's current working directory.

```bash
x-patch <<'EOF'
*** Begin Patch
*** Update File: src/index.ts
@@
-console.log("old");
+console.log("new");
*** End Patch
EOF
```

--------------------------------

### Register Workspace Feature with Custom Filesystem

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/workspace.md

Example of registering the Workspace feature with a custom in-memory filesystem and a specific mount point.

```typescript
import { createWorkspaceFeature } from "ai-sdk-x";
import { InMemoryFs } from "just-bash";

const workspaceFs = new InMemoryFs();

x.registerFeature(
  createWorkspaceFeature({
    fs: workspaceFs,
    mountPoint: "/home/user/workspace",
  }),
);
```

--------------------------------

### Using Skills Feature Actions to Manage Skills

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/skills.md

Shows how to directly manage skills using the actions returned by `createSkillsFeature`. This example demonstrates listing skills and logging the output.

```typescript
const skills = createSkillsFeature();
x.registerFeature(skills);

const result = await skills.list?.(x.fs);
console.log(result?.stdout);
```

--------------------------------

### Example Usage of TransactionalFs

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/runtime/file-system.md

Shows how to use TransactionalFs to write a file, check its status, and then commit the changes. Use rollback() to discard changes instead of commit().

```typescript
import { TransactionalFs } from "ai-sdk-x";
import { InMemoryFs } from "just-bash";

const tx = new TransactionalFs({ fs: new InMemoryFs() });

await tx.writeFile("/draft.md", "draft");
console.log(await tx.stat("/draft.md"));

await tx.commit();
```

--------------------------------

### Skills Management Functions

Source: https://github.com/niapya/ai-sdk-x/blob/main/_autodocs/EXPORTS.md

Functions for managing skills, including creation, installation, listing, finding, searching, and removal.

```APIDOC
## createSkillsFeature

### Description
Creates a skills feature.

### Signature
`createSkillsFeature(option?: boolean | SkillsOptions): Feature`

## createSkillsFeatureDescription

### Description
Creates a description for the skills feature.

### Signature
`createSkillsFeatureDescription(ctx: FeatureSetupContext, mountPoint: string): Promise<string>`

## createSkillsCommand

### Description
Creates a command for skills operations.

### Signature
`createSkillsCommand(options: SkillsCommandOptions): Command`

## installSkill

### Description
Installs a skill.

### Signature
`installSkill(input: InstallSkillInput, ctx: CommandContext, options: SkillsCommandOptions): Promise<ExecResult>`

## addSkill

### Description
Adds a skill.

### Signature
`addSkill(input: AddSkillInput, ctx: CommandContext, options: SkillsCommandOptions): Promise<ExecResult>`

## importSkill

### Description
Imports a skill.

### Signature
`importSkill(input: ImportSkillInput, ctx: CommandContext, options: SkillsCommandOptions): Promise<ExecResult>`

## listSkills

### Description
Lists available skills.

### Signature
`listSkills(fs: IFileSystem, options: SkillsCommandOptions): Promise<SkillInfo[]>`

## findSkills

### Description
Finds skills based on input.

### Signature
`findSkills(input: string, fs: IFileSystem, options: SkillsCommandOptions): Promise<SkillInfo[]>`

## searchSkills

### Description
Searches for skills.

### Signature
`searchSkills(input: string, ctx: CommandContext, options: SkillsCommandOptions): Promise<ExecResult>`

## removeSkill

### Description
Removes a skill.

### Signature
`removeSkill(input: RemoveSkillInput, ctx: CommandContext, options: SkillsCommandOptions): Promise<ExecResult>`

## infoSkill

### Description
Retrieves information about a skill.

### Signature
`infoSkill(input: string, fs: IFileSystem, options: SkillsCommandOptions): Promise<SkillDetails>`

## parseSkillInstallTarget

### Description
Parses a skill installation target string.

### Signature
`parseSkillInstallTarget(target: string): SkillInstallTarget`

## createInstallSkillCommand

### Description
Creates a command definition for installing a skill.

### Signature
`createInstallSkillCommand(options: SkillsCommandOptions): CliCommandDefinition`

## createAddSkillCommand

### Description
Creates a command definition for adding a skill.

### Signature
`createAddSkillCommand(options: SkillsCommandOptions): CliCommandDefinition`

## createImportSkillCommand

### Description
Creates a command definition for importing a skill.

### Signature
`createImportSkillCommand(options: SkillsCommandOptions): CliCommandDefinition`

## createListSkillsCommand

### Description
Creates a command definition for listing skills.

### Signature
`createListSkillsCommand(options: SkillsCommandOptions): CliCommandDefinition`

## createRemoveSkillCommand

### Description
Creates a command definition for removing a skill.

### Signature
`createRemoveSkillCommand(options: SkillsCommandOptions): CliCommandDefinition`

## createFindSkillsCommand

### Description
Creates a command definition for finding skills.

### Signature
`createFindSkillsCommand(options: SkillsCommandOptions): CliCommandDefinition`

## createSearchSkillsCommand

### Description
Creates a command definition for searching skills.

### Signature
`createSearchSkillsCommand(options: SkillsCommandOptions): CliCommandDefinition`

## createUpdateSkillsCommand

### Description
Creates a command definition for updating skills.

### Signature
`createUpdateSkillsCommand(options: SkillsCommandOptions): CliCommandDefinition`

## createInfoSkillCommand

### Description
Creates a command definition for retrieving skill information.

### Signature
`createInfoSkillCommand(options: SkillsCommandOptions): CliCommandDefinition`
```

--------------------------------

### KVStorage Interface Definition

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/runtime/backend-storage.md

Defines the contract for key-value storage operations including list, get, set, and delete. Supports string values and optional time-to-live (TTL) for expiration.

```typescript
interface KVStorage {
  list(prefix?: string, limit?: number): string[] | Promise<string[]>;
  get(key: string): string | null | undefined | Promise<string | null | undefined>;
  set(key: string, value: string, ttl?: number): void | Promise<void>;
  delete(key: string): void | Promise<void>;
}
```

--------------------------------

### Skills Types and Interfaces

Source: https://github.com/niapya/ai-sdk-x/blob/main/_autodocs/EXPORTS.md

Defines types and interfaces for skill management, including installation targets, index entries, index structures, configuration options, and command options. These types provide the data structures used by the skills functions.

```typescript
export interface SkillInstallTarget {
  repoUrl: string;
  selector: string;
}

export interface SkillIndexEntry {
  createAt: number;
  description?: string;
  files: string[];
  frontmatter?: Record<string, string>;
  skillPath: string;
  source?: "git" | "local";
  updateAt: number;
  url?: string;
}

export interface SkillsIndex {
  skills: Record<string, SkillIndexEntry>;
  version: 1;
}

export interface SkillsConfig {
  readonly enabled: boolean;
  readonly fs?: IFileSystem;
  readonly lockfile: boolean;
  readonly mountPoint: string;
}

export interface SkillsCommandOptions {
  lockfile: boolean;
  mountPoint: string;
}

export type SkillsOptions = {
  fs?: IFileSystem;
  lockfile?: boolean;
  mountPoint?: string;
}

export const DEFAULT_SKILLS_MOUNT: "/home/user/skills"
```

--------------------------------

### Skills Feature Functions

Source: https://github.com/niapya/ai-sdk-x/blob/main/_autodocs/EXPORTS.md

Defines functions for managing skills, including creation, description, installation, addition, import, listing, searching, removal, and information retrieval. Some functions are asynchronous and require a context or file system.

```typescript
export function createSkillsFeature(
  option?: boolean | SkillsOptions
): Feature

export async function createSkillsFeatureDescription(
  ctx: FeatureSetupContext,
  mountPoint: string
): Promise<string>

export function createSkillsCommand(
  options: SkillsCommandOptions
): Command

export async function installSkill(
  input: InstallSkillInput,
  ctx: CommandContext,
  options: SkillsCommandOptions
): Promise<ExecResult>

export async function addSkill(
  input: AddSkillInput,
  ctx: CommandContext,
  options: SkillsCommandOptions
): Promise<ExecResult>

export async function importSkill(
  input: ImportSkillInput,
  ctx: CommandContext,
  options: SkillsCommandOptions
): Promise<ExecResult>

export async function listSkills(
  fs: IFileSystem,
  options: SkillsCommandOptions
): Promise<SkillInfo[]>

export async function findSkills(
  input: string,
  fs: IFileSystem,
  options: SkillsCommandOptions
): Promise<SkillInfo[]>

export async function searchSkills(
  input: string,
  ctx: CommandContext,
  options: SkillsCommandOptions
): Promise<ExecResult>

export async function removeSkill(
  input: RemoveSkillInput,
  ctx: CommandContext,
  options: SkillsCommandOptions
): Promise<ExecResult>

export async function infoSkill(
  input: string,
  fs: IFileSystem,
  options: SkillsCommandOptions
): Promise<SkillDetails>

export function parseSkillInstallTarget(
  target: string
): SkillInstallTarget

export function createInstallSkillCommand(options: SkillsCommandOptions): CliCommandDefinition
export function createAddSkillCommand(options: SkillsCommandOptions): CliCommandDefinition
export function createImportSkillCommand(options: SkillsCommandOptions): CliCommandDefinition
export function createListSkillsCommand(options: SkillsCommandOptions): CliCommandDefinition
export function createRemoveSkillCommand(options: SkillsCommandOptions): CliCommandDefinition
export function createFindSkillsCommand(options: SkillsCommandOptions): CliCommandDefinition
export function createSearchSkillsCommand(options: SkillsCommandOptions): CliCommandDefinition
export function createUpdateSkillsCommand(options: SkillsCommandOptions): CliCommandDefinition
export function createInfoSkillCommand(options: SkillsCommandOptions): CliCommandDefinition
```

--------------------------------

### Initialize X with KvEnvBackend

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/runtime/environment.md

Demonstrates initializing the AI SDK X runtime with a KvEnvBackend, using an in-memory key-value store for environment persistence.

```typescript
import { KvEnvBackend, InMemoryKVStore, X } from "ai-sdk-x";

const x = new X({
  envBackend: new KvEnvBackend({
    kv: new InMemoryKVStore(),
    key: "project:env",
  }),
});
```

--------------------------------

### Initialize Runtime with X.init() and In-Memory Filesystem

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/serverless-and-embedded.md

When using `X.init()`, pass the `fs` explicitly at the top level. Configure `bash.cwd` and `bash.network` as needed for your environment.

```typescript
import { InMemoryFs } from "just-bash";
import { X } from "ai-sdk-x";

const x = X.init({
  fs: new InMemoryFs(),
  bash: {
    cwd: "/home/user/workspace",
    network: false,
  },
});
```

--------------------------------

### Initialize X with Custom Options

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/custom-start.md

Use `new X()` to specify custom runtime options like Bash configurations and register features manually. This provides granular control over the X environment.

```typescript
import {
  X,
  createPatchFeature,
  createWorkspaceFeature,
} from "ai-sdk-x";

const x = new X({
  bash: {
    cwd: "/home/user/workspace",
    network: false,
  },
})
  .registerFeature(createPatchFeature())
  .registerFeature(
    createWorkspaceFeature({
      mountPoint: "/work",
    }),
  );

const result = await x.exec("echo $WORKSPACE_HOME");
console.log(result.stdout);
```

--------------------------------

### Initialize Skills Feature with Custom Filesystem

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/skills.md

Demonstrates how to create and register the Skills feature using an in-memory filesystem and specifying a mount point. The feature is then registered with the main application context 'x'.

```typescript
import { createSkillsFeature } from "ai-sdk-x";
import { InMemoryFs } from "just-bash";

const skillsFs = new InMemoryFs();

const skills = createSkillsFeature({
  fs: skillsFs,
  lockfile: true,
  mountPoint: "/home/user/skills",
});

x.registerFeature(skills);
```

--------------------------------

### Initialize and Use Bash Tool with AI SDK

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/use-with-ai-sdk.md

Pass the AI SDK X Bash tool to a model by initializing X and calling `getTools()`. This snippet demonstrates setting the working directory and network configuration for the Bash environment.

```typescript
import { generateText } from "ai";
import { openai } from "@ai-sdk/openai";
import { X } from "ai-sdk-x";

const x = X.init({
  bash: {
    cwd: "/home/user/workspace",
    network: false,
  },
});

const tools = await x.getTools();

const result = await generateText({
  model: openai("gpt-4.1"),
  tools,
  prompt: "Create a README with a short project description.",
});

console.log(result.text);
```

--------------------------------

### Initialize Runtime with In-Memory Filesystem

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/serverless-and-embedded.md

Use `InMemoryFs` when the platform lacks a persistent local disk. Pass `fs` explicitly when constructing the runtime for clarity in serverless code.

```typescript
import { InMemoryFs } from "just-bash";
import { X } from "ai-sdk-x";

const fs = new InMemoryFs();

const x = new X({
  fs,
});
```

--------------------------------

### Construct BootstrappableMountableFs

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/runtime/file-system.md

Instantiate BootstrappableMountableFs directly when you need a shared runtime filesystem for Bash and features, with mounted workspaces or storage, and the default shell bootstrap layout.

```typescript
import { BootstrappableMountableFs } from "ai-sdk-x";
import { InMemoryFs } from "just-bash";

const fs = new BootstrappableMountableFs({
  base: new InMemoryFs(),
});
```

--------------------------------

### Access Workspace Home and Find Files

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/workspace.md

Demonstrates how to access the WORKSPACE_HOME environment variable and find files within the workspace directory using Bash commands.

```bash
echo "$WORKSPACE_HOME"
find "$WORKSPACE_HOME" -maxdepth 2 -type f
```

--------------------------------

### Connect to runtime FS wrappers

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/mount-custom-storage.md

Mounts a transactional filesystem, enabling advanced semantics like indexing, caching, and transactions. This allows Bash commands to interact with a sophisticated filesystem layer.

```typescript
import {
  CachingFs,
  IndexedFs,
  TransactionalFs,
  InMemoryKVStore,
} from "ai-sdk-x";
import { InMemoryFs } from "just-bash";

const source = new InMemoryFs();
const cache = new InMemoryKVStore();

const indexed = new IndexedFs({ fs: source, cache });
const cached = new CachingFs({ fs: indexed, cache, ttlMs: 60_000 });
const transactional = new TransactionalFs({ fs: cached, cache });

x.registerFeature({
  name: "storage",
  hooks: {
    onExecStart(ctx) {
      ctx.fs.mount("/home/user/storage", transactional);
      ctx.setEnv("STORAGE_HOME", "/home/user/storage");
    },
  },
});
```

--------------------------------

### Build Runtime with In-Memory FS and KVEnvBackend

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/serverless-and-embedded.md

Construct the AI SDK X runtime with an `InMemoryFs` and a `KvEnvBackend` using an `InMemoryKVStore`. This is a basic shape for serverless functions.

```typescript
import { InMemoryFs } from "just-bash";
import { InMemoryKVStore, KvEnvBackend, X } from "ai-sdk-x";

const x = new X({
  fs: new InMemoryFs(),
  envBackend: new KvEnvBackend({
    kv: new InMemoryKVStore(),
    key: "project:env",
  }),
});
```

--------------------------------

### Workspace Directory Structure

Source: https://github.com/niapya/ai-sdk-x/blob/main/_autodocs/api-reference/Workspace.md

Recommended organization for a workspace directory, including source code, tests, documentation, and configuration files.

```shell
$WORKSPACE_HOME/
├── README.md              # 项目主文档
├── PROGRESS.md           # 任务进度
├── src/                  # 源代码
│   ├── index.js
│   ├── utils.js
│   └── components/
├── tests/                # 测试文件
├── docs/                 # 文档
├── assets/               # 资源文件
├── config/               # 配置文件
└── .gitignore           # Git 忽略文件
```

--------------------------------

### Mount a custom filesystem

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/mount-custom-storage.md

Mounts a provided filesystem at a specified mount point and sets the WORKSPACE_HOME environment variable. This is useful for providing custom project files to the runtime.

```typescript
import { X, createWorkspaceFeature } from "ai-sdk-x";
import { InMemoryFs } from "just-bash";

const projectFs = new InMemoryFs();
await projectFs.mkdir("/", { recursive: true });
await projectFs.writeFile("/README.md", "# Project\n");

const x = new X();

x.registerFeature(
  createWorkspaceFeature({
    fs: projectFs,
    mountPoint: "/home/user/workspace",
  }),
);

const result = await x.exec("cat $WORKSPACE_HOME/README.md");
console.log(result.stdout);
```

--------------------------------

### Register Lifecycle Hooks

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/custom-start.md

Implement `onExecStart` and `onExecEnd` hooks to intercept command execution. `onExecStart` allows environment variable manipulation before execution.

```typescript
x.registerHook({
  onExecStart(ctx) {
    ctx.setEnv("PROJECT_MODE", "docs");
  },
  onExecEnd(ctx) {
    console.log(ctx.result.exitCode);
  },
});
```

--------------------------------

### Custom KVStorage Backend Interface

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/serverless-and-embedded.md

Implement the `KVStorage` interface to provide a custom storage backend for cache and index data. This allows data to survive across invocations.

```typescript
import type { KVStorage } from "ai-sdk-x";

const storage: KVStorage = {
  async list(prefix = "") {
    return [];
  },
  async get(key) {
    return null;
  },
  async set(key, value, ttl) {
    void key;
    void value;
    void ttl;
  },
  async delete(key) {},
};
```

--------------------------------

### Memory Feature CLI Commands

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/memory.md

Demonstrates common `x-memory` CLI commands for managing memory. Use these to list, add, or find memory entries directly from the command line.

```shell
x-memory list

printf 'Use Bun for JS tasks.' |
  x-memory add project-style \
    --description 'Project command preference' \
    --keyword bun \
    --stdin

x-memory find bun
```

--------------------------------

### Create Skills Feature

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/skills.md

Instantiates the Skills feature with optional configuration. Use this to set up the feature with a custom filesystem, lockfile behavior, or mount point.

```typescript
createSkillsFeature(option?: boolean | SkillsOptions): SkillsFeature
```

--------------------------------

### Construct IndexedFs

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/runtime/file-system.md

Instantiate IndexedFs to manage directory listings and stat data in KVStorage, ideal for object storage backends where directory walking is expensive and listings come from an index.

```typescript
import { IndexedFs, InMemoryKVStore } from "ai-sdk-x";
import { InMemoryFs } from "just-bash";

const fs = new IndexedFs({
  fs: new InMemoryFs(),
  cache: new InMemoryKVStore(),
  manifestPrefix: "runtime-storage:index",
});
```

--------------------------------

### Custom EnvBackend Interface

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/serverless-and-embedded.md

Implement the `EnvBackend` interface to provide a custom environment backend. This allows persisting session state in platform storage instead of relying on process memory.

```typescript
import type { EnvBackend, EnvSnapshot } from "ai-sdk-x";

const envBackend: EnvBackend = {
  async load(): Promise<EnvSnapshot | null> {
    return null;
  },
  async save(snapshot: EnvSnapshot): Promise<void> {
    void snapshot;
  },
};
```

--------------------------------

### Define a CLI Command

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/create-your-feature.md

Use `defineCliCommand` to create a command definition with an ID, type, summary, usage, and a run function.

```typescript
import { createCommand, defineCliCommand } from "ai-sdk-x";

const commandDefinition = defineCliCommand({
  id: "project-info",
  type: "command",
  summary: "Print project information.",
  usage: "project-info",
  run: () => ({
    stdout: "AI SDK X project\n",
    stderr: "",
    exitCode: 0,
  }),
});

const projectInfoCommand = createCommand(commandDefinition);
```

--------------------------------

### WorkspaceOptions Interface

Source: https://github.com/niapya/ai-sdk-x/blob/main/_autodocs/api-reference/Workspace.md

Defines the options available when initializing or configuring a workspace, including file system and mount point.

```typescript
interface WorkspaceOptions {
  fs?: IFileSystem;
  mountPoint?: string;
}
```

--------------------------------

### Use Tool Description in System Prompt

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/use-with-ai-sdk.md

Configure the Bash tool to use a detailed description in the system prompt instead of tool metadata. This is useful for models that perform better with explicit guidance. Set `enableDescription: false` to use a fallback description for the tool schema.

```typescript
const system = await x.createToolDescription();
const tools = await x.getTools({ enableDescription: false });

const result = await generateText({
  model: openai("gpt-4.1"),
  system,
  tools,
  prompt: "Inspect the workspace and summarize it.",
});
```

--------------------------------

### Workspace Types and Interfaces

Source: https://github.com/niapya/ai-sdk-x/blob/main/_autodocs/EXPORTS.md

Defines types for workspace options and configuration, including file system and mount point properties. Also exports a default mount point constant.

```typescript
export interface WorkspaceOptions {
  fs?: IFileSystem;
  mountPoint?: string;
}

export interface WorkspaceConfig {
  readonly enabled: boolean;
  readonly fs?: IFileSystem;
  readonly mountPoint: string;
}

export const DEFAULT_WORKSPACE_MOUNT: "/home/user/workspace"
```

--------------------------------

### EnvBackend Interface Definition

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/runtime/environment.md

Defines the adapter interface for loading and saving environment snapshots, separating persistence logic from the core runtime.

```typescript
interface EnvBackend {
  load(): EnvSnapshot | null | Promise<EnvSnapshot | null>;
  save(snapshot: EnvSnapshot): void | Promise<void>;
}
```

--------------------------------

### Mount storage from a custom feature

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/mount-custom-storage.md

Mounts custom storage at a specified path and sets an environment variable to point to it. This allows features to expose their own storage to the runtime.

```typescript
import type { Feature } from "ai-sdk-x";
import { InMemoryFs } from "just-bash";

const docsFs = new InMemoryFs();
await docsFs.mkdir("/", { recursive: true });
await docsFs.writeFile("/index.md", "# Internal docs\n");

const docsFeature: Feature = {
  name: "docs",
  description: () => "Internal docs are mounted at $DOCS_HOME.",
  hooks: {
    onExecStart(ctx) {
      ctx.fs.mount("/home/user/docs", docsFs);
      ctx.setEnv("DOCS_HOME", "/home/user/docs");
    },
  },
};

x.registerFeature(docsFeature);
```

--------------------------------

### Skills Feature Construction Parameters

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/skills.md

Defines the optional parameters for constructing the Skills feature, including filesystem, lockfile enablement, and the mount point within the Bash environment.

```typescript
interface SkillsOptions {
  fs?: IFileSystem;
  lockfile?: boolean;
  mountPoint?: string;
}
```

--------------------------------

### Add External Instructions and Limits to Bash Tool

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/use-with-ai-sdk.md

Provide application-specific Bash rules using `externalDescription`. Control tool output size with `maxLines` and `maxOutput` to limit the amount of data processed.

```typescript
const tools = await x.getTools({
  externalDescription:
    "Before making durable edits, inspect the target file with targeted commands.",
  maxLines: 400,
  maxOutput: 20_000,
});
```

--------------------------------

### Construct SubpathFs

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/runtime/file-system.md

Create a scoped filesystem using createSubpathFs to expose a directory as its own filesystem, ensuring features only see a project root and path resolution stays within a known subtree.

```typescript
import { createSubpathFs } from "ai-sdk-x";

const scopedFs = createSubpathFs(baseFs, "/home/user/workspace");
```

--------------------------------

### Execute Direct Bash Commands

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/quick-start.md

Run arbitrary Bash commands directly within the AI SDK X runtime to inspect its state or perform specific operations without involving a model.

```typescript
const result = await bash.exec("pwd && ls -la");
console.log(result.stdout);
```

--------------------------------

### WorkspaceConfig Interface

Source: https://github.com/niapya/ai-sdk-x/blob/main/_autodocs/api-reference/Workspace.md

Defines the configuration structure for a workspace, including its enabled state, file system, and mount point.

```typescript
interface WorkspaceConfig {
  readonly enabled: boolean;
  readonly fs?: IFileSystem;
  readonly mountPoint: string;
}
```

--------------------------------

### Construct TransactionalFs

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/runtime/file-system.md

Instantiate TransactionalFs to stage file changes in memory before committing them, useful for preparing edits without immediate persistence, inspecting changes, or controlled agent workflows.

```typescript
import { TransactionalFs } from "ai-sdk-x";
import { InMemoryFs } from "just-bash";

const tx = new TransactionalFs({
  fs: new InMemoryFs(),
});
```

--------------------------------

### Git Types and Interfaces

Source: https://github.com/niapya/ai-sdk-x/blob/main/_autodocs/EXPORTS.md

Defines types for Git options and configuration. GitOptions is an Omit type that excludes specific properties from JustGitOptions, tailoring them for the SDK's use.

```typescript
export type GitOptions = Omit<JustGitOptions, "cwd" | "fs" | "gitDir" | "objectStore" | "refStore">

export interface GitConfig extends GitOptions {
  readonly enabled: boolean;
}
```

--------------------------------

### Register a Custom Feature

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/custom-start.md

Define and register a feature that includes commands, descriptions, and lifecycle hooks. This allows for modular extension of X's capabilities.

```typescript
x.registerFeature({
  name: "project",
  description: () => "Project commands are available.",
  command: [helloCommand],
  hooks: {
    onExecStart(ctx) {
      ctx.setEnv("PROJECT_HOME", "/home/user/project");
    },
  },
});
```

--------------------------------

### Workspace Feature Functions

Source: https://github.com/niapya/ai-sdk-x/blob/main/_autodocs/EXPORTS.md

Exports functions for creating workspace features and their descriptions. Includes asynchronous functions for creating feature descriptions that require context and a mount point.

```typescript
export function createWorkspaceFeature(
  option?: boolean | WorkspaceOptions
): Feature

export async function createWorkspaceFeatureDescription(
  ctx: FeatureSetupContext,
  mountPoint: string
): Promise<string>
```

--------------------------------

### Workspace File Management Commands

Source: https://github.com/niapya/ai-sdk-x/blob/main/_autodocs/api-reference/Workspace.md

Common shell commands for managing files within the workspace, such as checking size, listing large files, cleaning temporary files, and counting files.

```typescript
// 定期检查工作区大小
const size = await x.exec('du -sh $WORKSPACE_HOME');

// 列出大文件
const large = await x.exec('find $WORKSPACE_HOME -type f -size +10M');

// 清理临时文件
await x.exec('find $WORKSPACE_HOME -name "*.tmp" -delete');

// 统计文件数量
const count = await x.exec('find $WORKSPACE_HOME -type f | wc -l');
```

--------------------------------

### Memory Feature Options

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/memory.md

Defines the configuration options for creating a Memory feature. You can provide a custom filesystem or specify a mount point for the memory storage.

```typescript
interface MemoryOptions {
  fs?: IFileSystem;
  mountPoint?: string;
}
```

--------------------------------

### Create Workspace Feature

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/workspace.md

Factory function to create a Workspace feature instance. It can be configured with a custom filesystem and mount point.

```typescript
createWorkspaceFeature(option?: boolean | WorkspaceOptions): Feature
```

--------------------------------

### Import Feature Type

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/create-your-feature.md

Import the `Feature` type from the `ai-sdk-x` library to define feature structures.

```typescript
import type { Feature } from "ai-sdk-x";
```

--------------------------------

### Workspace Management Functions

Source: https://github.com/niapya/ai-sdk-x/blob/main/_autodocs/EXPORTS.md

Functions for managing workspace features, including feature creation and description generation.

```APIDOC
## createWorkspaceFeature

### Description
Creates a workspace feature.

### Signature
`createWorkspaceFeature(option?: boolean | WorkspaceOptions): Feature`

## createWorkspaceFeatureDescription

### Description
Creates a description for the workspace feature.

### Signature
`createWorkspaceFeatureDescription(ctx: FeatureSetupContext, mountPoint: string): Promise<string>`
```

--------------------------------

### Create Memory Feature

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/memory.md

Instantiates the Memory feature. Use this to enable long-term memory storage for your AI application. It requires an optional filesystem and mount point.

```typescript
import { createMemoryFeature } from "ai-sdk-x";
import { InMemoryFs } from "just-bash";

const memoryFs = new InMemoryFs();

const memory = createMemoryFeature({
  fs: memoryFs,
  mountPoint: "/home/user/memory",
});

x.registerFeature(memory);
```

--------------------------------

### Define Feature with Custom Actions

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/create-your-feature.md

Create a feature that also exposes application-level actions, such as `writeNote`, in addition to standard feature properties.

```typescript
import type { CommandContext } from "just-bash";
import type { Feature } from "ai-sdk-x";

type ProjectFeature = Feature & {
  writeNote?: (title: string, body: string, ctx: CommandContext) => Promise<void>;
};

function createProjectFeature(): ProjectFeature {
  return {
    name: "project",
    hooks: {
      async onExecStart(ctx) {
        await ctx.fs.mkdir("/home/user/project", { recursive: true });
      },
    },
    writeNote: async (title, body, ctx) => {
      await ctx.fs.writeFile(`/home/user/project/${title}.md`, body);
    },
  };
}
```

--------------------------------

### Access Memory Actions Programmatically

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/memory.md

Shows how to use Memory feature actions directly within your application code. This allows for programmatic interaction with memory without invoking the CLI.

```typescript
const memory = createMemoryFeature();
x.registerFeature(memory);

const listResult = await memory.list?.(x.fs);
console.log(listResult?.stdout);
```

--------------------------------

### Resolved Memory Configuration

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/memory.md

Shows the structure of the final configuration object after creating a Memory feature. It includes whether the feature is enabled, the filesystem, and the mount point.

```typescript
interface MemoryConfig {
  readonly enabled: boolean;
  readonly fs?: IFileSystem;
  readonly mountPoint: string;
}
```

--------------------------------

### Define a Custom Bash Command

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/custom-start.md

Register a custom command object with `registerCommand()` to extend X's functionality. Commands registered this way are trusted by default.

```typescript
import type { Command } from "just-bash";

const helloCommand: Command = {
  name: "hello",
  execute: async () => ({
    stdout: "hello\n",
    stderr: "",
    exitCode: 0,
  }),
};

x.registerCommand(helloCommand);
```

--------------------------------

### Patch Feature Functions

Source: https://github.com/niapya/ai-sdk-x/blob/main/_autodocs/EXPORTS.md

Exports functions for creating patch features, descriptions, and commands, along with constants for description and command definitions. These are used for implementing patch-related functionality.

```typescript
export function createPatchFeature(
  option?: boolean | PatchOptions
): Feature

export function createPatchFeatureDescription(): string

export function createPatchCommand(
  options?: PatchCommandOptions
): Command

export const PATCH_DESCRIPTION: string
export const PATCH_COMMAND: CliCommandDefinition
```

--------------------------------

### Patch Management Functions

Source: https://github.com/niapya/ai-sdk-x/blob/main/_autodocs/EXPORTS.md

Functions for managing patches, including feature creation and command generation.

```APIDOC
## createPatchFeature

### Description
Creates a patch feature.

### Signature
`createPatchFeature(option?: boolean | PatchOptions): Feature`

## createPatchFeatureDescription

### Description
Creates a description for the patch feature.

### Signature
`createPatchFeatureDescription(): string`

## createPatchCommand

### Description
Creates a command for patch operations.

### Signature
`createPatchCommand(options?: PatchCommandOptions): Command`
```

--------------------------------

### Construct CachingFs

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/runtime/file-system.md

Instantiate CachingFs to implement a read-through cache for file contents and directory metadata, reducing repeated remote reads and invalidating cache on writes.

```typescript
import { CachingFs, InMemoryKVStore } from "ai-sdk-x";

const cachedFs = new CachingFs({
  fs: baseFs,
  cache: new InMemoryKVStore(),
  ttlMs: 30_000,
});
```

--------------------------------

### Git Management Functions

Source: https://github.com/niapya/ai-sdk-x/blob/main/_autodocs/EXPORTS.md

Functions for managing Git operations within the SDK.

```APIDOC
## createGitFeature

### Description
Creates a Git feature.

### Signature
`createGitFeature(option?: boolean | GitOptions): Feature`

## createGitFeatureDescription

### Description
Creates a description for the Git feature.

### Signature
`createGitFeatureDescription(): string`
```

--------------------------------

### Git Feature Functions

Source: https://github.com/niapya/ai-sdk-x/blob/main/_autodocs/EXPORTS.md

Exports functions for creating Git features and their descriptions. These are foundational for integrating Git-related operations within the SDK.

```typescript
export function createGitFeature(
  option?: boolean | GitOptions
): Feature

export function createGitFeatureDescription(): string
```

--------------------------------

### EnvSnapshot Interface Definition

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/runtime/environment.md

Defines the structure for persisting runtime environment state, including the current working directory and environment variables.

```typescript
interface EnvSnapshot {
  cwd: string;
  env: Record<string, string>;
}
```

--------------------------------

### Resolved Skills Feature Configuration

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/skills.md

Details the structure of the configuration object after it has been resolved by the Skills feature, including whether it's enabled and its specific settings.

```typescript
interface SkillsConfig {
  readonly enabled: boolean;
  readonly fs?: IFileSystem;
  readonly lockfile: boolean;
  readonly mountPoint: string;
}
```

--------------------------------

### Feature Interface Definition

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/guide/create-your-feature.md

Defines the structure of a feature, including its name, description, commands, and lifecycle hooks.

```typescript
interface Feature {
  readonly name: string;
  readonly description?: (ctx: FeatureSetupContext) => string | Promise<string>;
  readonly command?: Command[];
  readonly hooks?: ExecHook;
}
```

--------------------------------

### Create Patch Feature

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/patch.md

Factory function to create the Patch feature. Pass `false` to disable the feature.

```typescript
createPatchFeature(option?: boolean): Feature
```

--------------------------------

### Patch Types and Interfaces

Source: https://github.com/niapya/ai-sdk-x/blob/main/_autodocs/EXPORTS.md

Defines types for patch hunks, configuration, options, and command options. The Hunk type is a discriminated union representing different patch operations (add, delete, update).

```typescript
export type Hunk =
  | { type: 'add'; path: string; contents: string }
  | { type: 'delete'; path: string }
  | {
      type: 'update';
      path: string;
      chunks: Chunk[];
      movePath?: string
    }

export interface PatchConfig {
  readonly enabled: boolean;
}

export type PatchOptions = {}

export interface PatchCommandOptions {
  // 当前无特定属性
}
```

--------------------------------

### Register Patch Feature

Source: https://github.com/niapya/ai-sdk-x/blob/main/packages/docs/content/v1/features/patch.md

Registers the created Patch feature with the AI SDK X.

```typescript
import { createPatchFeature } from "ai-sdk-x";

x.registerFeature(createPatchFeature());
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.