# szyjiyi MCP 使用教程

> szyjiyi 是一个轻量级 MCP Server，为 AI 编程助手提供跨会话持久记忆能力。
>
> 本文档教你如何在各种 IDE 中配置 MCP 连接 + 导入 Steering 规范，让 AI 自动管理记忆。
>
> 配置完成后，AI 会在每次对话中自动加载历史记忆、记录踩坑、跟踪问题、保存会话。

---

## 目录

- [快速开始](#快速开始)
- [各 IDE 手动配置](#各-ide-手动配置)
  - [Kiro](#kiro)
  - [Cursor](#cursor)
  - [Claude Code](#claude-code)
  - [VS Code (GitHub Copilot)](#vs-code-github-copilot)
  - [Windsurf](#windsurf)
  - [Trae](#trae)
  - [OpenCode](#opencode)
  - [Claude Desktop](#claude-desktop)
- [Steering 规范（核心）](#steering-规范核心)
- [Web 看板](#web-看板)
- [常见问题](#常见问题)

---

## 快速开始

### 第一步：安装 szyjiyi

三种方式任选其一：

```bash
# 推荐：pipx 安装（隔离环境，不污染全局）
pipx install szyjiyi

# 或：pip 安装
pip install szyjiyi

# 升级到最新版
pip install --upgrade szyjiyi

# 或：uvx 免安装运行（每次拉最新版，无需安装）
# 后续 MCP 配置中 command 改为 uvx，见下方说明
```

### 第二步：自动配置（推荐）

在你的项目根目录运行：

```bash
szyjiyi install
# 或
python -m szyjiyi install
```

会交互式让你选择 IDE，自动完成：
1. 写入 MCP 配置文件
2. 生成 Steering 规范文件
3. 配置 Hooks（如果 IDE 支持）

**如果自动配置成功，后面的手动配置可以跳过，直接看 [Steering 规范](#steering-规范核心) 部分。**

---

## 各 IDE 手动配置

> 每个 IDE 需要配置两样东西：
> 1. **MCP 配置** — 告诉 IDE 如何启动 szyjiyi server
> 2. **Steering 规范** — 告诉 AI 什么时候、怎么调用 szyjiyi 的 8 个工具

### 运行方式说明

MCP 配置中的 `command` 和 `args` 取决于你的安装方式：

| 安装方式 | command | args |
|---------|---------|------|
| pip/pipx | `"python"` | `["-m", "szyjiyi", "--project-dir", "${workspaceFolder}"]` |
| uvx | `"uvx"` | `["szyjiyi@latest", "--project-dir", "${workspaceFolder}"]` |

> `${workspaceFolder}` 是 IDE 的工作区变量，会自动替换为当前项目路径。
> 部分 IDE（如 Claude Code、OpenCode）不支持此变量，用 `"."` 代替。

---

### Kiro

Kiro 支持两级 MCP 配置，workspace 级优先于 user 级：

| 级别 | 配置文件路径 | 作用范围 |
|------|------------|---------|
| Workspace | `.kiro/settings/mcp.json`（项目根目录） | 仅当前项目 |
| User（全局） | `~/.kiro/settings/mcp.json` | 所有项目 |

#### 1. MCP 配置

**Workspace 级**（推荐，项目根目录下）：

```json
{
  "mcpServers": {
    "szyjiyi": {
      "command": "python",
      "args": ["-m", "szyjiyi", "--project-dir", "${workspaceFolder}"],
      "autoApprove": ["remember", "recall", "forget", "status", "track", "task", "readme", "auto_save"],
      "disabled": false
    }
  }
}
```

**User 级**（全局，所有项目生效）：

```json
{
  "mcpServers": {
    "szyjiyi": {
      "command": "python",
      "args": ["-m", "szyjiyi"],
      "autoApprove": ["remember", "recall", "forget", "status", "track", "task", "readme", "auto_save"]
    }
  }
}
```

> 全局配置不传 `--project-dir`，szyjiyi 会自动检测当前工作目录。

配置属性说明：

| 属性 | 类型 | 说明 |
|------|------|------|
| `autoApprove` | Array | 自动批准的工具名列表，无需每次手动确认。可用 `"*"` 批准所有工具 |
| `disabled` | Boolean | 临时禁用此 server（默认 false） |
| `disabledTools` | Array | 禁用特定工具（从 Agent 调用中排除） |

#### 2. Steering 规范

Kiro 支持两级 Steering，workspace 级优先于 global 级：

| 级别 | 路径 | 作用范围 |
|------|------|---------|
| Workspace | `.kiro/steering/szyjiyi.md` | 仅当前项目 |
| Global | `~/.kiro/steering/szyjiyi.md` | 所有项目 |

将 [Steering 规范](#steering-规范核心) 完整内容复制到对应路径。建议放在 global 级别，所有项目自动生效。

Steering 文件支持 inclusion modes（在文件头部添加 YAML front matter）：

```yaml
---
inclusion: always    # always（默认）| fileMatch | manual | auto
---
```

szyjiyi 的 steering 建议使用 `always`（默认），确保每次对话都加载。

#### 3. 验证

打开 Kiro，在对话中输入任意内容，观察 AI 是否在对话开头调用了 `status` 和 `recall` 工具。如果调用了，说明配置成功。

---

### Cursor

#### 1. MCP 配置

创建文件 `.cursor/mcp.json`（项目根目录下）：

```json
{
  "mcpServers": {
    "szyjiyi": {
      "command": "python",
      "args": ["-m", "szyjiyi", "--project-dir", "${workspaceFolder}"]
    }
  }
}
```

#### 2. Steering 规范

创建文件 `.cursor/rules/szyjiyi.md`，将 [Steering 规范](#steering-规范核心) 完整内容复制进去。

#### 3. 验证

在 Cursor 的 AI 对话中开始新会话，AI 应该会自动调用 `status` → `recall` 加载记忆。

---

### Claude Code

#### 1. MCP 配置

创建文件 `.mcp.json`（项目根目录下）：

```json
{
  "mcpServers": {
    "szyjiyi": {
      "command": "python",
      "args": ["-m", "szyjiyi", "--project-dir", "."]
    }
  }
}
```

> 注意：Claude Code 不支持 `${workspaceFolder}`，使用 `"."` 表示当前目录。

#### 2. Steering 规范

将 [Steering 规范](#steering-规范核心) 完整内容追加到项目根目录的 `CLAUDE.md` 文件中。如果文件不存在则创建。

#### 3. 工具名前缀

Claude Code 会自动给工具名加 `mcp_szyjiyi_` 前缀，例如：
- `remember` → `mcp_szyjiyi_remember`
- `recall` → `mcp_szyjiyi_recall`

这是正常的，Steering 规范中写短名即可，AI 会自动匹配。

---

### VS Code (GitHub Copilot)

#### 1. MCP 配置

创建文件 `.vscode/mcp.json`（项目根目录下）：

```json
{
  "mcpServers": {
    "szyjiyi": {
      "command": "python",
      "args": ["-m", "szyjiyi", "--project-dir", "${workspaceFolder}"]
    }
  }
}
```

#### 2. Steering 规范

将 [Steering 规范](#steering-规范核心) 完整内容追加到 `.github/copilot-instructions.md` 文件中。如果文件不存在则创建。

---

### Windsurf

#### 1. MCP 配置

创建文件 `.windsurf/mcp.json`（项目根目录下）：

```json
{
  "mcpServers": {
    "szyjiyi": {
      "command": "python",
      "args": ["-m", "szyjiyi", "--project-dir", "${workspaceFolder}"]
    }
  }
}
```

#### 2. Steering 规范

创建文件 `.windsurf/rules/szyjiyi.md`，将 [Steering 规范](#steering-规范核心) 完整内容复制进去。

---

### Trae

#### 1. MCP 配置

创建文件 `.trae/mcp.json`（项目根目录下）：

```json
{
  "mcpServers": {
    "szyjiyi": {
      "command": "python",
      "args": ["-m", "szyjiyi", "--project-dir", "${workspaceFolder}"]
    }
  }
}
```

#### 2. Steering 规范

创建文件 `.trae/rules/szyjiyi.md`，将 [Steering 规范](#steering-规范核心) 完整内容复制进去。

---

### OpenCode

#### 1. MCP 配置

创建文件 `opencode.json`（项目根目录下）：

```json
{
  "mcp": {
    "szyjiyi": {
      "command": "python",
      "args": ["-m", "szyjiyi", "--project-dir", "."]
    }
  }
}
```

> 注意：OpenCode 的 MCP 配置格式是 `"mcp"` 而非 `"mcpServers"`。

#### 2. Steering 规范

将 [Steering 规范](#steering-规范核心) 完整内容追加到项目根目录的 `AGENTS.md` 文件中。

---

### Claude Desktop

#### 1. MCP 配置（全局）

编辑全局配置文件：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "szyjiyi": {
      "command": "python",
      "args": ["-m", "szyjiyi"]
    }
  }
}
```

> Claude Desktop 为全局配置，不支持项目级 Steering 规范文件。
> 你可以在对话开头手动告诉 AI 使用 szyjiyi 工具的规范。

---

## Steering 规范（核心）

> 以下是完整的 Steering 规范内容。将它复制到你 IDE 对应的 Steering 文件中。
> 这是让 AI 正确使用 szyjiyi 8 个工具的核心，没有它 AI 不知道什么时候该调用什么工具。

---

### 复制以下全部内容 ↓

```markdown
# szyjiyi - 跨会话持久记忆

本项目已配置 szyjiyi MCP Server，提供 8 个工具。请在合适的时机主动调用。

---

## 会话生命周期

### 会话开始（强制）

每次新会话的第一个动作，按顺序执行：

1. 调用 `status`（不传参数）→ 读取上次工作状态、阻塞、待处理
2. 调用 `recall`（tags: ["项目知识"], scope: "project", top_k: 50）→ 加载项目知识
3. 调用 `recall`（tags: ["preference"], scope: "user", top_k: 20）→ 加载用户偏好
4. 如果 status 返回 is_blocked: true → 向用户汇报阻塞原因，等待确认后再行动

### 工作过程

| 时机 | 操作 |
|------|------|
| 修改代码前 | `recall`（query: 功能关键词, tags: ["踩坑"]）查历史踩坑 |
| 遇到踩坑/技术要点 | `remember`（content: 具体内容, tags: ["踩坑"], scope: "project"） |
| 发现 bug/待处理事项 | `track`（action: "create"）记录问题 |
| 修复问题后 | `track`（action: "update"）更新排查内容和结论 |
| 问题关闭 | `track`（action: "archive"）归档 |
| 任务进度变化 | `status`（传 state 参数）更新当前任务、进度、最近修改 |
| 代码修改完成后 | `remember`（content: "[CODE_MOD] 功能名\n文件: path:行号\n变更: 具体内容", tags: ["代码修改"]） |

### 会话结束（强制）

调用 `auto_save`，保存本次对话中发现的用户偏好：

| 字段 | 内容 | scope |
|------|------|-------|
| preferences | 用户表达的技术偏好（编码风格、工具选择等） | user（跨项目通用） |
| extra_tags | 额外标签（可选） | — |

规则：每条必须具体可追溯，没有的传空数组，不编造。

---

## 工具速查

| 工具 | 用途 | 关键参数 |
|------|------|----------|
| `remember` | 存入记忆 | content, tags, scope(project/user) |
| `recall` | 语义搜索记忆 | query, tags, scope, top_k, source, brief |
| `forget` | 删除记忆 | memory_id / memory_ids / tags |
| `status` | 会话状态管理 | state(不传=读取, 传=更新) |
| `track` | 问题跟踪 | action(create/update/archive/list/delete) |
| `task` | 任务管理 | action(batch_create/update/list/delete/archive), feature_id |
| `auto_save` | 自动保存偏好 | preferences, extra_tags |
| `readme` | README 生成 | action(generate/diff), lang, sections |

---

## 工具详细参数

### remember - 存入记忆

```json
{
  "content": "记忆内容，Markdown 格式",
  "tags": ["标签1", "标签2"],
  "scope": "project"
}
```

- scope: "project"（项目级，默认）或 "user"（跨项目通用）
- 自动去重：相似度 > 0.95 时更新已有记忆而非新建

### recall - 语义搜索记忆

```json
{
  "query": "搜索内容（语义搜索，用自然语言描述即可）",
  "tags": ["按标签过滤（可选）"],
  "scope": "all",
  "top_k": 5,
  "source": "manual",
  "brief": true
}
```

- scope: "project" / "user" / "all"（默认）
- 无 query 时走纯标签精确查询
- 语义搜索：即使用词不同也能找到相关记忆
- source: "manual" / "auto_save" 过滤记忆来源
- brief: true 精简模式，只返回 content+tags，节省上下文

### forget - 删除记忆

```json
// 删除单条
{ "memory_id": "记忆ID" }

// 批量删除
{ "memory_ids": ["ID1", "ID2"] }

// 按标签批量删除
{ "tags": ["要删除的标签"], "scope": "project" }
```

### status - 会话状态管理

读取当前状态（不传参数）：

```json
{}
```

更新状态：

```json
{
  "state": {
    "is_blocked": false,
    "block_reason": "",
    "current_task": "当前正在做的事",
    "next_step": "下一步计划",
    "progress": ["已完成步骤1", "已完成步骤2"],
    "recent_changes": ["修改了 src/foo.py"],
    "pending": ["待处理事项"]
  }
}
```

阻塞状态规则：
- 提出方案等用户确认 → `is_blocked: true, block_reason: "方案待用户确认"`
- 修复完成等验证 → `is_blocked: true, block_reason: "修复完成等待验证"`
- 用户明确确认后 → `is_blocked: false`
- "确认"判定：只有明确肯定词（"执行"/"可以"/"好的"/"去做吧"）才算
- 反问句、质疑句、模糊回复不算确认
- 新会话中上一会话的确认不延续，必须重新确认

### track - 问题跟踪

创建问题：

```json
{
  "action": "create",
  "title": "问题标题",
  "content": "问题描述（必填，简述问题现象和背景）",
  "date": "2026-02-27"
}
```

更新问题（排查后必填 investigation + root_cause，修复后必填 solution + files_changed + test_result）：

```json
{
  "action": "update",
  "issue_id": 1,
  "content": "排查过程和结论",
  "status": "in_progress"
}
```

归档/删除问题：

```json
{ "action": "archive", "issue_id": 1 }
{ "action": "delete", "issue_id": 1 }
```

查看问题列表：

```json
{ "action": "list", "include_archived": false }
```

### task - 任务管理

批量创建任务（支持子任务）：

```json
{
  "action": "batch_create",
  "feature_id": "feature-name",
  "tasks": [
    { "title": "任务1", "subtasks": ["子任务1", "子任务2"] },
    { "title": "任务2" }
  ]
}
```

更新任务状态（自动同步关联问题状态）：

```json
{ "action": "update", "task_id": 1, "status": "completed" }
```

查看/归档/删除：

```json
{ "action": "list", "feature_id": "feature-name" }
{ "action": "archive", "feature_id": "feature-name" }
{ "action": "delete", "task_id": 1 }
```

- 通过 feature_id 关联 track 问题，update 自动同步问题状态
- archive 归档功能组所有任务到 tasks_archive 表

### auto_save - 自动保存偏好

```json
{
  "preferences": ["用户偏好简洁代码风格"],
  "extra_tags": ["可选额外标签"]
}
```

- preferences 固定 scope=user（跨项目通用）
- 每次对话结束自动提取并存储用户偏好，智能去重

### readme - README 生成

```json
{ "action": "generate", "lang": "en", "sections": ["header", "tools", "deps"] }
{ "action": "diff" }
```

- 从 TOOL_DEFINITIONS / pyproject.toml 自动生成 README 内容
- 支持多语言：en / zh-TW / ja / de / fr / es

---

## 代码修改记忆格式

修改代码后，用 remember 记录，格式如下：

```
[CODE_MOD] 功能名称
文件: relative/path/to/file.ext:行号
变更: 具体修改内容描述
```

示例：

```
[CODE_MOD] 用户认证
文件: src/auth/login.py:45
变更: 新增 JWT token 刷新逻辑，过期前 5 分钟自动续期
```
```

### 复制以上全部内容 ↑

---

## Web 看板

szyjiyi 内置 Web 看板，可视化查看和管理所有记忆数据：

```bash
szyjiyi web
# 或
python -m szyjiyi web
```

默认访问 http://localhost:9473

功能包括：
- 按项目查看所有记忆
- 3D 向量可视化
- 问题跟踪看板
- 标签管理
- 数据导入/导出

---

## 数据存储

所有数据存储在 `~/.szyjiyi/memory.db`（SQLite），包括：
- 记忆内容和向量嵌入
- 会话状态
- 问题跟踪记录
- 项目注册信息

数据完全本地，不上传任何云端。

---

## 常见问题

**Q: 自动配置和手动配置有什么区别？**
A: 没有区别。`szyjiyi install` 只是帮你自动创建了 MCP 配置文件和 Steering 规范文件，内容和手动配置完全一样。

**Q: 多个项目共享记忆吗？**
A: `scope: "project"` 的记忆按项目目录隔离，`scope: "user"` 的记忆跨项目共享（如用户偏好）。

**Q: IDE 中工具名带前缀怎么办？**
A: 部分 IDE 会自动加前缀（如 Claude Code 加 `mcp_szyjiyi_`，Kiro 加 `szyjiyi_`），这是 MCP 客户端的行为，不影响使用。Steering 规范中写短名即可。

**Q: 如何迁移旧版 aivectormemory 的数据？**
A: 将 `~/.aivectormemory/memory.db` 复制到 `~/.szyjiyi/memory.db` 即可。

**Q: 支持哪些嵌入模型？**
A: 默认使用本地轻量嵌入模型（intfloat/multilingual-e5-small），无需 API Key，完全离线可用。

**Q: 需要 Python 什么版本？**
A: Python >= 3.10。

**Q: uvx 方式和 pip 方式有什么区别？**
A: uvx 每次运行时自动拉取最新版本，无需手动更新；pip/pipx 需要手动 `pip install --upgrade szyjiyi` 更新。

**Q: 如何查看当前版本？**
A:
```bash
szyjiyi --version
# 或
python -m szyjiyi --version
```
