# NanoPencil Monorepo Migration Guide

## 迁移状态

- ✅ 基础配置已创建 (pnpm-workspace.yaml, package.json, .npmrc)
- ✅ 共享 TypeScript 配置 (tsconfig.base.json)
- ✅ nanomem 包结构已创建
- ⏳ nanopencil 主包待迁移
- ⏳ simplify 扩展待迁移

## 目标结构

```
nanopencil-monorepo/
├── packages/
│   ├── nanopencil/          # 主包 - AI 编程助手
│   │   ├── src/
│   │   │   ├── cli.ts
│   │   │   ├── main.ts
│   │   │   ├── core/
│   │   │   ├── modes/
│   │   │   ├── extensions/
│   │   │   │   └── simplify/
│   │   │   └── ...
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   └── README.md
│   │
│   ├── nanomem/             # 记忆引擎 (独立包)
│   │   ├── src/
│   │   │   ├── engine.ts
│   │   │   ├── extension.ts
│   │   │   ├── types.ts
│   │   │   └── ...
│   │   ├── package.json
│   │   ├── tsconfig.json
│   │   └── README.md
│   │
│   └── simplify/            # 代码简化扩展 (可选)
│       ├── src/
│       │   └── index.ts
│       ├── package.json
│       └── README.md
│
├── pnpm-workspace.yaml
├── package.json
├── tsconfig.base.json
├── .npmrc
└── 单体仓库迁移指南.md
```

## 依赖关系

```
nanopencil
    ↓ depends on
nanomem (workspace: *)
    ↓
(主机无关核心)

simplify (可选扩展)
    ↓
nanopencil
```

## 包说明

### @nanopencil/nanomem

**独立发布的记忆引擎包**
- 主机无关设计，可用于任何 AI agent
- 包含核心记忆功能：提取、评分、巩固、洞察
- 无外部框架依赖
- 可作为独立 npm 包使用

**依赖**: 无

### @pencil-agent/nano-pencil

**主 AI 编程助手包**
- CLI 工具和 TUI 界面
- 集成 nanomem 作为内置扩展
- 完整的工具系统 (read, bash, edit, write, grep, find)
- 多模型支持 (DashScope, OpenAI, Anthropic, Ollama)

**依赖**:
- `@nanopencil/nanomem@workspace:*` - 记忆引擎
- `@mariozechner/pi-*` - 核心 AI 框架

### @nanopencil/simplify (可选)

**代码简化扩展包**
- Claude Code 风格的 `/simplify` 命令
- 基于模式的重构（卫语句、表达式折叠等）
- 测试验证集成

**依赖**:
- `@pencil-agent/nano-pencil` - 主包类型

## 迁移步骤

### 步骤 1: 安装 pnpm

```bash
npm install -g pnpm
```

### 步骤 2: 安装依赖

```bash
pnpm install
```

### 步骤 3: 构建所有包

```bash
pnpm build
```

### 步骤 4: 开发模式

```bash
# 启动 nanopencil
pnpm dev

# 监听 nanomem 变化
pnpm dev:nanomem
```

### 步骤 5: 发布

```bash
# 使用 changesets 管理版本
pnpm changeset
pnpm version
pnpm release
```

## 工作空间命令

```bash
# 在所有包中运行命令
pnpm -r <command>

# 在特定包中运行命令
pnpm --filter <package-name> <command>

# 示例
pnpm -r build              # 构建所有包
pnpm -r clean              # 清理所有包
pnpm --filter nanomem build # 只构建 nanomem
pnpm --filter nanopencil dev # 启动 nanopencil

# 包含依赖的构建
pnpm -r --filter './packages/**' build
```

## 版本管理

使用 [Changesets](https://github.com/changesets/changesets) 管理 monorepo 版本:

```bash
# 添加 changeset
pnpm changeset

# 更新版本
pnpm changeset version

# 发布
pnpm changeset publish
```

## 优势

### 1. 统一版本管理
- 所有包在同一仓库中，版本协调更容易
- Changesets 自动处理相互依赖的包版本更新

### 2. 共享配置
- 统一的 TypeScript 配置
- 共享的开发依赖
- 一致的代码风格

### 3. 原子提交
- 跨包的更改可以在单个 PR 中完成
- 确保所有包保持同步

### 4. 本地开发
- workspace 协议 (`workspace:*`) 自动链接本地包
- 无需手动 `npm link`

### 5. 独立发布
- nanomem 可以作为独立包发布到 npm
- 其他项目可以单独使用 nanomem

### 6. 更快的 CI/CD
- 增量构建（只构建变化的包）
- 并行测试

## 下一步

1. ✅ 创建 monorepo 基础结构
2. ⏳ 迁移 nanopencil 主包代码
3. ⏳ 更新 nanopencil 的 package.json
4. ⏳ 迁移 simplify 扩展
5. ⏳ 测试 workspace 依赖
6. ⏳ 配置 CI/CD
7. ⏳ 首次发布

## 注意事项

1. **导入路径更新**
   - nanopencil 中对 nanomem 的引用需要更新
   - 从 `../../core/extensions/nanomem` 到 `@nanopencil/nanomem`

2. **构建顺序**
   - nanomem 必须先于 nanopencil 构建
   - 使用 `pnpm -r --filter './packages/**' build` 确保正确顺序

3. **扩展路径**
   - 内置扩展路径从 `extensions/` 变为相对于新包结构
   - 需要更新 `pencil-mem-integration.ts`

4. **环境变量**
   - `NANOMEM_MEMORY_DIR` 在 monorepo 中仍然有效
   - 建议为开发设置独立的测试目录

## 参考资源

- [pnpm workspace](https://pnpm.io/workspaces)
- [Changesets](https://github.com/changesets/changesets)
- [TypeScript Project References](https://www.typescriptlang.org/docs/handbook/project-references.html)
