# ai-codespec 用户使用指南

本文面向 `@ai/ai-codespec` 的普通使用者，说明如何安装、更新和清理团队 AI 编程助手资产。

| AI 编程助手 | 支持状态 | 说明 |
|---|---|---|
| Windsurf | 已支持 | 当前可安装和更新全局 skills、workflows。 |
| Qoder | 待接入 | 后续接入后会补充安装路径和使用说明。 |

## 零、快速安装（推荐）

提供两种安装方式，二选一即可。完整说明见 [install-guide.md](./install-guide.md)。

### 方式一：手动安装

打开飞书 Wiki 上的《ai-codespec 安装指南》（含团队只读 Token）：

> <https://vvcazjv268.feishu.cn/wiki/FINPwzI7liiRF5kw5IEc0RsmnGe>

复制文档底部整段命令到终端运行即可（已包含 registry / token / 安装 / 同步资产）。

### 方式二：通过 AI Agent 安装（推荐）

把下面提示词发给你的 AI 助手（Claude Code / Codex / Cursor / Windsurf / Trae 等），它会自动完成所有步骤：

```text
帮我安装 ai-codespec：https://vvcazjv268.feishu.cn/wiki/FINPwzI7liiRF5kw5IEc0RsmnGe
```

> 如果本机没有 Node 18+，请先按团队《Node.js 环境安装指南》安装：<https://vvcazjv268.feishu.cn/wiki/I0KywUlJNiYH0RkZ3hmc1nzZnIf>

如果你只想看每一步的细节，请继续阅读下文。

## 一、前置条件

- 已安装 Node.js 18 或更高版本。Node 环境安装参考：[Node.js 环境安装指南](https://vvcazjv268.feishu.cn/wiki/I0KywUlJNiYH0RkZ3hmc1nzZnIf)。
- 已配置公司 GitLab npm Registry 访问权限。
- 内部访问通常由团队统一配置只读 npm token；如果安装失败，再联系软件团队维护者确认权限。

## 二、配置 npm Registry

```powershell
npm config set "@ai:registry" "https://git.manifoldtech.cn/api/v4/projects/ai%2Fai-codespec/packages/npm/"
```

如果你的机器尚未配置团队 npm token，可使用维护者提供的只读 token 配置一次：

```powershell
npm config set "//git.manifoldtech.cn/api/v4/projects/ai%2Fai-codespec/packages/npm/:_authToken" "glpat-WoFFcrVOCrrkz_DEjiVpNm86MQp1OjIwCA.01.0y16dsfbm"
```

安装使用者的 token 只需要读取权限：

- `read_api`
- `read_registry`

## 三、全局安装 CLI

```powershell
npm install -g @ai/ai-codespec
```

安装完成后验证：

```powershell
ai-codespec --version
ai-codespec --help
```

## 四、首次安装团队资产

默认 agent 是 `windsurf`，所以可以直接执行：

```powershell
ai-codespec install
```

也可以显式指定：

```powershell
ai-codespec install windsurf
```

当前 Windsurf 会同步：

- skills
- workflows

当前不会写入或修改：

```text
%USERPROFILE%\.codeium\windsurf\memories\global_rules.md
```

## 五、内置 Skills 清单

安装后，以下 skills 会同步到 Windsurf 全局 skills 目录，供 AI 助手在对应任务场景下自动调用或按名称显式调用。

| Skill | 作用 | 典型使用场景 |
|---|---|---|
| `mt-code-review` | 系统化进行代码审查，覆盖逻辑、边界条件、安全、性能和可维护性问题。 | 让 AI review PR、提交 diff、某段代码或某个模块。 |
| `mt-debugging` | 按“复现、定位、假设、收集信息、最小修复、验证”的流程排查 bug。 | 处理报错、异常行为、测试失败、线上问题复盘。 |
| `mt-frontend-design` | 生成更有设计感的前端页面、组件和交互，避免默认化 AI 风格。 | 创建网页、后台页面、落地页、React/Vue 组件。 |
| `mt-go-init` | 基于 `gin + gorm + redis + zap + mix-go/xcli` 的 Go 后端项目结构与模块生成规范。 | 初始化 Go API 项目，或在既有 Go 项目中新增 controller、service、model、route、cron command。 |
| `mt-refactoring` | 在不改变行为的前提下重构代码，提高可读性、可维护性或性能。 | 拆分大函数、消除重复逻辑、整理遗留代码、改善命名。 |
| `mt-skill-creator` | 创建、优化和评估 AI skills，支持编写测试 prompt、跑评估和迭代改进。 | 新增团队 skill，或优化已有 skill 的触发描述和执行效果。 |
| `mt-test-generation` | 为目标代码生成单元测试、集成测试或端到端测试。 | 补充 Jest、PyTest、Go test 等测试用例，覆盖 happy path 和边界场景。 |

### 使用 skills

Skills 通常由 Windsurf 根据用户请求自动匹配。也可以在对话中明确点名，例如：

```text
使用 mt-code-review 帮我 review 当前改动
使用 mt-debugging 帮我排查这个报错
使用 mt-go-init 按团队规范初始化一个 Go API 项目
```

## 六、内置 Workflows 清单

安装后，以下 workflows 会同步到 Windsurf 全局 workflows 目录，可通过 Windsurf 的 workflow 入口或 slash command 使用。

| Workflow | Slash command | 作用 |
|---|---|---|
| `mt-git-commit.md` | `/mt-git-commit` | 标准化提交代码：检查变更、暂存文件、按 Conventional Commits 编写提交信息。 |
| `mt-git-feature.md` | `/mt-git-feature` | 启动新功能开发：理解需求、检查环境、制定计划、创建功能分支并搭建基础结构。 |
| `mt-git-release.md` | `/mt-git-release` | 创建新版本发布：检查变更、更新版本号、准备 changelog、提交并打 tag。 |
| `mt-review.md` | `/mt-review` | 审查当前代码变更，重点发现 bug、安全风险、边界条件和可维护性问题。 |

### 使用 workflows

在 Windsurf 中输入对应 slash command，例如：

```text
/mt-git-commit
/mt-git-feature
/mt-git-release
/mt-review
```

## 七、更新团队资产

日常更新推荐使用：

```powershell
ai-codespec update
```

显式指定 Windsurf：

```powershell
ai-codespec update windsurf
```

更新会覆盖当前包内的同名团队资产。覆盖前会自动备份，且同一资产最多保留最近 3 个备份。

备份统一存放在：

```text
%USERPROFILE%\.codeium\windsurf\.ai-codespec-backups\
```

示例：

```text
%USERPROFILE%\.codeium\windsurf\.ai-codespec-backups\skills\mt-code-review\2026-05-24T10-30-00-000Z\
%USERPROFILE%\.codeium\windsurf\.ai-codespec-backups\global_workflows\mt-review.md\2026-05-24T10-30-00-000Z
```

## 八、更新并清理旧资产

如果团队资产发生过改名或删除，推荐使用：

```powershell
ai-codespec update --clean
```

或：

```powershell
ai-codespec update windsurf --clean
```

`--clean` 会清理本机已不在当前包内的旧团队资产：

- `mt-*` skill 目录
- `mt-*.md` workflow 文件

`--clean` 不会删除非 `mt-*` 的个人资产。

## 九、只同步某类资产

只同步 skills：

```powershell
ai-codespec update --only skills
```

只同步 workflows：

```powershell
ai-codespec update --only workflows
```

只同步并清理 skills：

```powershell
ai-codespec update --only skills --clean
```

只同步并清理 workflows：

```powershell
ai-codespec update --only workflows --clean
```

## 十、查看可安装资产

```powershell
ai-codespec list
```

或：

```powershell
ai-codespec list windsurf
```

## 十一、查看本机安装状态

```powershell
ai-codespec status
```

或：

```powershell
ai-codespec status windsurf
```

状态文件位置：

```text
%USERPROFILE%\.codeium\windsurf\.ai-codespec.json
```

## 十二、卸载或删除资产

卸载 CLI：

```powershell
npm uninstall -g @ai/ai-codespec
```

卸载 CLI 不会自动删除已经同步到 Windsurf 的 assets。

如果需要手动删除团队 skills：

```powershell
Remove-Item -Recurse -Force "$env:USERPROFILE\.codeium\windsurf\skills\mt-*"
```

如果需要手动删除团队 workflows：

```powershell
Remove-Item -Force "$env:USERPROFILE\.codeium\windsurf\global_workflows\mt-*.md"
```

请不要直接删除整个 Windsurf 配置目录，因为其中可能包含个人配置和个人资产。

## 十三、常见问题

### 1. Windsurf 提示 skill name 不匹配怎么办？

通常是本机残留了旧目录，例如：

```text
mt-code_review
mt-test_generation
```

执行清理更新：

```powershell
ai-codespec update --only skills --clean
```

### 2. `npm install -g` 返回 401 怎么办？

检查 npm Registry 是否配置正确：

```powershell
npm config get @ai:registry
```

如果 registry 正确但仍报错，请联系维护者确认团队只读 token 是否有效，并确认 token 具备读取权限：

- `read_api`
- `read_registry`

### 3. 更新后没有生效怎么办？

建议重启 Windsurf，或重新执行：

```powershell
ai-codespec update --clean
```

### 4. 会不会覆盖个人 skills？

不会主动覆盖非 `mt-*` 的个人 assets。

团队分发的 skills 和 workflows 都以 `mt-` 开头，清理逻辑也只处理 `mt-*` 团队资产。