建立開發助手

本指南會教你建立一個結合所有 Workspace 功能的完整開發助手：

用於檔案管理的檔案系統
用於執行程式碼的 Sandbox
用於編程標準的 Skill
用於尋找範例的搜尋

你會設定一個包含範例項目的 Workspace，並以 Skill 形式加入編程標準。然後，你會建立一個按照 TDD 實務編寫程式碼的 Agent。完成後，Agent 可以讀取現有程式碼並編寫新的實作，接着在 Sandbox 中執行測試，再根據結果反覆改進。

前置要求
前置要求的直接連結

已安裝 Node.js v22.13.0 或更新版本
已取得支援的 Model Provider 所提供的 API 金鑰
已有 Mastra 項目（請按照安裝指南設定新項目）

安裝 vitest
安裝 vitest 的直接連結

開發助手會使用 Vitest 在 Workspace Sandbox 內執行測試。請在項目中將它安裝為開發依賴套件：

npm
pnpm
Yarn
Bun

npm install -D vitest

pnpm add -D vitest

yarn add --dev vitest

bun add --dev vitest

設定 Workspace
設定 Workspace 的直接連結

Workspace 使用本機檔案系統管理文件檔案。Agent 會在 Workspace 目錄內讀寫檔案。在 src/mastra/index.ts 檔案中，匯入 Workspace、LocalFilesystem 和 LocalSandbox 類別。

此外，啟用 BM25 搜尋索引，並從 skills 目錄載入 Skill。

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { resolve } from 'node:path'
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: resolve(import.meta.dirname, '../../workspace') }),
  sandbox: new LocalSandbox({ workingDirectory: resolve(import.meta.dirname, '../../workspace') }),
  skills: ['skills'],
  bm25: true,
  autoIndexPaths: ['docs', 'src'],
})

export const mastra = new Mastra({
  workspace,
})

在項目根目錄建立名為 workspace 的新資料夾。所有檔案都會儲存於此，並由 Agent 管理。

加入範例項目檔案
加入範例項目檔案的直接連結

Workspace 使用以下資料夾結構：

workspace/src/：範例項目的原始碼
workspace/tests/：測試檔案
workspace/docs/：項目文件
workspace/skills/：以 Agent Skills 形式提供的編程標準和指引

首先建立含有一些實用函式的 workspace/src/utils/string-helpers.ts 檔案，以及對應的測試檔案 workspace/tests/string-helpers.test.ts。

workspace/src/utils/string-helpers.ts
export function capitalize(str: string): string {
  if (!str) return str
  return str.charAt(0).toUpperCase() + str.slice(1)
}

export function slugify(str: string): string {
  return str
    .toLowerCase()
    .replace(/[^\w\s-]/g, '')
    .replace(/\s+/g, '-')
}

workspace/tests/string-helpers.test.ts
import { describe, it, expect } from 'vitest'
import { capitalize, slugify } from '../src/utils/string-helpers'

describe('String Helpers', () => {
  describe('capitalize', () => {
    it('capitalizes first letter', () => {
      expect(capitalize('hello')).toBe('Hello')
    })
  })

  describe('slugify', () => {
    it('converts to lowercase and replaces spaces', () => {
      expect(slugify('Hello World')).toBe('hello-world')
    })
  })
})

在 workspace/skills/coding-standards/SKILL.md 建立 Skill 定義。這會告訴 Agent 如何編寫及測試程式碼：

workspace/skills/coding-standards/SKILL.md
---
name: coding-standards
description: Project coding standards and testing guidelines
---

# Coding Standards

## Code quality

- Functions under 50 lines
- Use descriptive variable names
- Always add TypeScript types

## Testing

- Test all exported functions
- Use AAA pattern: Arrange, Act, Assert
- Cover happy paths and edge cases

## Before committing

1. Write implementation
2. Write comprehensive tests
3. Run tests: `npm test`
4. All tests must pass

在 workspace/skills/coding-standards/references/testing-guide.md 建立包含詳細測試模式的參考檔案：

workspace/skills/coding-standards/references/testing-guide.md
# Testing Guide

## AAA pattern

```typescript
it('descriptive test name', () => {
  // Arrange: Set up test data
  const input = 'test'

  // Act: Execute the function
  const result = doSomething(input)

  // Assert: Verify the result
  expect(result).toBe('expected')
})
```

## What to test

- Happy paths (normal inputs)
- Edge cases (empty, null, boundary values)
- Error cases (invalid inputs, exceptions)