基于对nanoPencil架构的分析，我建议按以下框架决策：                                                                                                   
  🎯 核心判断标准                                                                                                                                      
  放进主项目 core/ 的条件（满足**任意2+**个）                                                                                                       
  
  ✅ 必需性 - 核心体验不可或缺
  // 例子：read/write/edit/bash工具
  - 没有它们，agent无法完成基本编码任务
  - 90%+用户会用到

  ✅ 紧密耦合 - 与核心状态深度交互
  // 例子：会话管理、模型切换
  - 需要访问AgentSession内部状态
  - 依赖compaction、session-manager等核心模块

  ✅ 配置驱动 - 需要全局配置管理
  // 例子：settings、model-registry
  - 需要在 ~/.nanopencil/agent/ 中持久化
  - 影响agent启动流程

  放进扩展 extensions/ 的条件（满足**任意1+**个）

  🔌 可选性 - 非核心功能
  // 例子：数据库操作、浏览器自动化
  - 特定场景使用（如测试需要爬虫）
  - 可以独立安装/卸载

  🎨 可替换性 - 多种实现方式
  // 例子：不同的MCP服务器
  - 可以有多个竞品实现
  - 用户可能偏好不同的方案

  🌐 外部依赖 - 引入重量级第三方库
  // 例子：puppeteer、sqlite
  - 会显著增加包体积
  - 不是所有用户都需要

  📊 决策流程图

  新功能需求
      │
      ├─ 是否是基础工具？
      │   ├─ YES → core/tools/ (read/write/bash)
      │   └─ NO  → 继续
      │
      ├─ 是否需要会话状态？
      │   ├─ YES → 检查耦合度
      │   │       ├─ 紧密 → core/ (session-manager, compaction)
      │   │       └─ 松散 → extensions/
      │   └─ NO  → 继续
      │
      ├─ 是否依赖外部服务/库？
      │   ├─ YES → extensions/ (mcp, integrations)
      │   └─ NO  → 继续
      │
      ├─ 用户群体是否<50%？
      │   ├─ YES → extensions/
      │   └─ NO  → 继续
      │
      └─ 默认扩展
          - 核心体验提升但可移除
          - 放在 extensions/ 但默认启用
          - 例: nanomem, nanosoul

  🎯 具体建议

  主项目 core/ 包含

  core/
  ├── tools/           # 基础工具（不可缺失）
  │   ├── read.ts
  │   ├── write.ts
  │   ├── edit.ts
  │   ├── bash.ts
  │   └── grep.ts
  ├── session-manager.ts  # 会话管理（核心状态）
  ├── compaction/         # 上下文管理（核心机制）
  ├── model-registry.ts   # 模型管理（配置驱动）
  └── extensions/         # 扩展系统本身（基础设施）

  扩展 extensions/ 包含

  extensions/
  ├── nanomem/        # 默认扩展（高级功能）
  ├── nanosoul/       # 默认扩展（个性系统）
  ├── mcp/            # MCP服务器集成
  ├── integrations/   # 第三方服务（GitHub, Jira等）
  └── community/      # 社区贡献

  💡 实战案例

  案例1：Git工具

  // ❌ 放进 core/tools/git.ts
  // 理由：依赖外部git命令，非所有用户需要

  // ✅ 放进 extensions/mcp/git.ts
  // 理由：已有MCP Git实现，可选功能

  案例2：测试运行器

  // ❌ 放进 extensions/test-runner.ts
  // 理由：与项目结构紧密相关，核心开发场景

  // ✅ 放进 core/tools/test.ts 或 core/testing/
  // 理由：开发调试的核心需求，需要解析项目配置

  案例3：数据库操作

  // ❌ 放进 core/tools/database.ts
  // 理由：引入sqlite依赖，场景特定

  // ✅ 放进 extensions/mcp/sqlite.ts
  // 理由：外部依赖，可选功能

  案例4：代码搜索增强

  // ❌ 放进 extensions/code-search.ts
  // 理由：grep的基础增强，核心功能

  // ✅ 放进 core/tools/search.ts
  // 理由：基于现有grep工具的自然扩展

  🚀 实施建议

  1. 创建扩展模板

  // extensions/template/my-extension.ts
  import { defineExtension } from '../../core/extensions/index.js';

  export default defineExtension({
    id: 'my-extension',

    hooks: {
      before_agent_start: async (context) => {
        // 初始化逻辑
      },
    },

    tools: [
      {
        name: 'my_tool',
        description: 'Tool description',
        execute: async (args) => {
          // 实现逻辑
        }
      }
    ],

    commands: [
      {
        name: 'my-command',
        description: 'Command description',
        handler: async (args) => {
          // 命令逻辑
        }
      }
    ]
  });

  2. 默认扩展管理

  // nanopencil-defaults.ts
  export const DEFAULT_EXTENSIONS = [
    'nanomem',      // 默认启用，可禁用
    'nanosoul',     // 默认启用，可禁用
    // 'mcp-puppeteer',  // 默认禁用，需手动启用
  ];

  3. 扩展发现机制

  # 内置扩展
  ~/.nanopencil/agent/extensions/
    ├── nanomem/
    └── nanosoul/

  # 用户扩展
  ~/.nanopencil/agent/extensions/community/
    ├── my-custom-tool/
    └── project-integration/

  # npm包扩展
  npm install @pencil-agent/ext-github

  📋 决策清单

  在添加新功能前，问自己：

  - 是否是基础工具（读/写/执行）？
  - 是否需要访问核心会话状态？
  - 是否会引入外部依赖？
  - 是否影响agent启动流程？
  - 是否<50%用户会使用？
  - 是否有多种实现方式？

  如果前3个都是YES → 主项目
  如果后3个都是YES → 扩展

  ---
  总结：核心是"最小主项目，最大扩展性"。主项目保持精简稳定，扩展提供灵活创新。这样既能保证核心质量，又能鼓励社区贡献。