# Monorepo 结构可视化

## 当前状态

```
nanoPencil/
├── packages/
│   └── nanomem/              ✅ 已完成
│       ├── src/
│       │   ├── cli.ts
│       │   ├── config.ts
│       │   ├── consolidation.ts
│       │   ├── engine.ts
│       │   ├── eviction.ts
│       │   ├── extension.ts
│       │   ├── extraction.ts
│       │   ├── i18n.ts
│       │   ├── index.ts
│       │   ├── insights-html.ts
│       │   ├── linking.ts
│       │   ├── privacy.ts
│       │   ├── scoring.ts
│       │   ├── store.ts
│       │   ├── types.ts
│       │   └── update.ts
│       ├── package.json      ✅ 已创建
│       ├── tsconfig.json     ✅ 已创建
│       ├── README.md         ✅ 已创建
│       └── CLAUDE.md
│
├── nanopencil/               ⏳ 待迁移
│   ├── cli.ts
│   ├── main.ts
│   ├── core/
│   │   ├── agent-session.ts
│   │   ├── auth-storage.ts
│   │   ├── bash-executor.ts
│   │   ├── compaction/
│   │   ├── defaults.ts
│   │   ├── diagnostics.ts
│   │   ├── event-bus.ts
│   │   ├── exec.ts
│   │   ├── export-html/
│   │   ├── extensions/
│   │   │   ├── index.ts
│   │   │   ├── loader.ts
│   │   │   ├── runner.ts
│   │   │   ├── types.ts
│   │   │   └── wrapper.ts
│   │   ├── footer-data-provider.ts
│   │   ├── index.ts
│   │   ├── keybindings.ts
│   │   ├── messages.ts
│   │   ├── model-registry.ts
│   │   ├── model-resolver.ts
│   │   ├── package-manager.ts
│   │   ├── prompt-templates.ts
│   │   ├── resolve-config-value.ts
│   │   ├── resource-loader.ts
│   │   ├── sdk.ts
│   │   ├── session-manager.ts
│   │   ├── settings-manager.ts
│   │   ├── skills.ts
│   │   ├── slash-commands.ts
│   │   ├── system-prompt.ts
│   │   ├── timings.ts
│   │   └── tools/
│   │       ├── bash.ts
│   │       ├── edit-diff.ts
│   │       ├── edit.ts
│   │       ├── find.ts
│   │       ├── grep.ts
│   │       ├── index.ts
│   │       ├── ls.ts
│   │       ├── path-utils.ts
│   │       ├── read.ts
│   │       ├── truncate.ts
│   │       └── write.ts
│   ├── modes/
│   │   ├── interactive/
│   │   ├── print-mode.ts
│   │   ├── rpc/
│   │   └── index.ts
│   ├── cli/
│   │   ├── args.ts
│   │   ├── config-selector.ts
│   │   ├── file-processor.ts
│   │   ├── list-models.ts
│   │   └── session-picker.ts
│   ├── utils/
│   │   └── ...
│   ├── extensions/
│   │   └── simplify/
│   │       └── index.ts
│   ├── migrations.ts
│   ├── nanopencil-defaults.ts
│   ├── pencil-mem-integration.ts
│   ├── config.ts
│   ├── index.ts
│   └── package.json
│
├── simplify/                 ⏳ 待迁移
│   └── src/
│       └── index.ts
│
├── pnpm-workspace.yaml       ✅ 已创建
├── package.json              ✅ 已更新 (根)
├── .npmrc                    ✅ 已创建
├── tsconfig.base.json        ✅ 已创建
├── 单体仓库迁移指南.md     ✅ 已创建
├── 迁移总结.md      ✅ 已创建
└── 单体仓库自述.md        ✅ 已创建
```

## 依赖关系图

```
┌─────────────────────────────────────────────────────────┐
│                    用户 / CLI                           │
└─────────────────────┬───────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│              @pencil-agent/nano-pencil                  │
│                                                         │
│  ┌──────────────────────────────────────────────────┐  │
│  │  • CLI 入口 (cli.ts)                             │  │
│  │  • 主循环 (main.ts)                              │  │
│  │  • Agent 会话管理                                │  │
│  │  • 工具系统 (read, bash, edit, write, grep)      │  │
│  │  • 扩展系统                                       │  │
│  └──────────────────────────────────────────────────┘  │
│                        │                               │
│                        ▼                               │
│  ┌──────────────────────────────────────────────────┐  │
│  │         Extension System                         │  │
│  │  ┌────────────────────────────────────────────┐  │  │
│  │  │ @nanopencil/nanomem (workspace:*)          │  │  │
│  │  │  • 持久记忆引擎                             │  │  │
│  │  │  • 会话巩固                                 │  │  │
│  │  │  • 评分与召回                               │  │  │
│  │  │  • 洞察报告                                 │  │  │
│  │  └────────────────────────────────────────────┘  │  │
│  │  ┌────────────────────────────────────────────┐  │  │
│  │  │ @nanopencil/simplify (可选)                │  │  │
│  │  │  • 代码简化                                 │  │  │
│  │  │  • 重构模式                                 │  │  │
│  │  │  • 测试验证                                 │  │  │
│  │  └────────────────────────────────────────────┘  │  │
│  └──────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────┐
│            @mariozechner/pi-* (外部依赖)                │
│  • @mariozechner/pi-agent-core                          │
│  • @mariozechner/pi-ai                                 │
│  • @mariozechner/pi-tui                                │
└─────────────────────────────────────────────────────────┘
```

## Workspace 配置

### pnpm-workspace.yaml

```yaml
packages:
  - 'packages/*'
```

### 依赖声明示例

**nanopencil/package.json**:

```json
{
  "name": "@pencil-agent/nano-pencil",
  "dependencies": {
    "@nanopencil/nanomem": "workspace:*",  // ← 本地链接
    "@mariozechner/pi-agent-core": "^0.55.3"
  }
}
```

**发布时自动替换为**:

```json
{
  "dependencies": {
    "@nanopencil/nanomem": "^0.2.0",  // ← 实际版本
    "@mariozechner/pi-agent-core": "^0.55.3"
  }
}
```

## 构建流程

```
pnpm build
    │
    ├─→ pnpm -r build
    │       │
    │       ├─→ packages/nanomem (先构建，无依赖)
    │       │       └─→ tsc → dist/
    │       │
    │       ├─→ packages/simplify (依赖 nanopencil 类型)
    │       │       └─→ tsc → dist/
    │       │
    │       └─→ packages/nanopencil (依赖 nanomem)
    │               └─→ tsc → dist/
    │
    └─→ 完成！所有包构建完毕
```

## 开发工作流

### 日常开发

```bash
# 1. 安装依赖
pnpm install

# 2. 启动开发模式（监听所有包）
pnpm -r --parallel dev

# 3. 只启动 nanopencil
pnpm dev

# 4. 只监听 nanomem 变化
pnpm dev:nanomem
```

### 添加新功能

```bash
# 1. 修改 nanomem 源码
vim packages/nanomem/src/engine.ts

# 2. 自动重新编译 (watch 模式)
# → 输出到 packages/nanomem/dist/

# 3. nanopencil 自动检测变化 (workspace 链接)
# → 无需重新安装，直接生效
```

### 发布流程

```bash
# 1. 添加 changeset
pnpm changeset
# > 选择要发布的包 (nanomem 或 nanopencil)
# > 填写变更摘要

# 2. 更新版本号
pnpm changeset version
# > 自动更新 package.json 版本
# > 自动更新 workspace 依赖版本

# 3. 构建
pnpm build

# 4. 发布
pnpm changeset publish
# > 按顺序发布所有有变更的包
```

## 优势对比

### ❌ 旧结构 (单一仓库)

```
nanoPencil/
├── core/extensions/nanomem/  (嵌入子目录)
├── core/
├── modes/
└── ...

问题：
• nanomem 无法独立使用
• 无法单独版本管理
• 测试和构建耦合
```

### ✅ 新结构 (Monorepo)

```
packages/
├── nanomem/        (独立包)
├── nanopencil/     (主包)
└── simplify/       (可选扩展)

优势：
✓ nanomem 可独立发布和使用
✓ 清晰的包边界和职责
✓ 灵活的版本管理
✓ 独立的测试和构建
✓ workspace 自动链接
✓ 原子提交 (跨包更改)
```

## 命令速查

```bash
# 构建所有包
pnpm build

# 构建特定包
pnpm --filter nanomem build

# 启动开发模式
pnpm dev

# 清理所有构建产物
pnpm clean

# 运行测试
pnpm test

# 添加依赖到特定包
pnpm --filter nanopencil add lodash

# 添加 workspace 依赖
pnpm --filter nanopencil add -D @nanopencil/nanomem@workspace:*

# 发布
pnpm changeset
pnpm changeset version
pnpm changeset publish
```

## 下一步

1. ✅ 基础 monorepo 结构已创建
2. ✅ nanomem 包已迁移完成
3. ⏳ 迁移 nanopencil 主包
4. ⏳ 迁移 simplify 扩展
5. ⏳ 测试 workspace 依赖
6. ⏳ 配置 CI/CD
7. ⏳ 首次发布
