@pencil-agent/nano-pencil 2.0.1 → 2.0.3

package/docs/nanoPencil-/345/255/246/344/271/240/350/256/241/345/210/222.md

@@ -1,170 +0,0 @@
-# nanoPencil 学习计划
-
-> 一份循序渐进的学习路线，帮助寸哥系统掌握 nanoPencil 项目的架构与代码。
-
----
-
-## 📌 学习前置
-
-- 熟悉 TypeScript 基础
-- 了解 Node.js 运行时
-- 对 CLI / TUI 应用有基本概念
-- 对 Agent / LLM API 有基本了解
-
----
-
-## Phase 1：全局认知 — 项目是什么（1-2 天）
-
-**目标**：搞清楚 nanoPencil 是什么、能做什么、怎么跑起来。
-
-| # | 学习项 | 文件 / 命令 | 产出 |
-|---|--------|------------|------|
-| 1 | 阅读产品宪章 | `.PENCIL.md` | 理解产品性格、交互哲学 |
-| 2 | 阅读项目导航 | `AGENTS.md` | 理解架构拓扑、目录结构、三大模式 |
-| 3 | 安装与运行 | `npm install && npm run build`<br>`npx tsx cli.ts` | 能在终端启动 nanoPencil |
-| 4 | 体验三个模式 | 分别跑 interactive / print / rpc | 感受不同模式的使用场景 |
-| 5 | 体验斜杠命令 | `/model`, `/thinking`, `/fork`, `/compact` 等 | 熟悉内置命令 |
-
-**验收标准**：能向别人用一句话解释 nanoPencil 是什么，并演示 TUI 模式下的基本对话。
-
----
-
-## Phase 2：核心链路 — 一条消息的生命周期（2-3 天）
-
-**目标**：追踪从用户输入到 AI 回复的完整流程。
-
-| # | 学习项 | 文件 | 关键概念 |
-|---|--------|------|----------|
-| 1 | CLI 入口 | `cli.ts`, `main.ts` | 参数解析、模式选择 |
-| 2 | AgentSession 生命周期 | `core/runtime/agent-session.ts` | 会话创建、模型切换、工具执行 |
-| 3 | TUI 模式交互 | `modes/interactive/interactive-mode.ts` | 输入读取、输出渲染、事件循环 |
-| 4 | 工具执行链路 | `core/tools/` 目录 | ToolOrchestrator、bash/read/edit/write |
-| 5 | Prompt 构建 | `core/prompt/system-prompt.ts` | 系统提示词组装、上下文注入 |
-| 6 | 模型调用 | `core/lib/ai/` + `core/model/` | Provider 抽象、API 调用、流式响应 |
-
-**验收标准**：能画出从用户输入到模型返回的调用链，标注每个关键节点的职责。
-
----
-
-## Phase 3：扩展系统 — 能力如何生长（2-3 天）
-
-**目标**：理解 nanoPencil 的插件架构，学会写扩展。
-
-| # | 学习项 | 文件 | 关键概念 |
-|---|--------|------|----------|
-| 1 | Extension Host | `core/extensions-host/loader.ts`<br>`runner.ts`, `wrapper.ts` | 发现、加载、生命周期 |
-| 2 | 扩展事件钩子 | `core/extensions-host/types.ts` | before_agent_start, tool_call, context 等 |
-| 3 | 内置扩展源码 | `extensions/builtin/` | interview, loop, link-world, soul 等 |
-| 4 | Skill 系统 | `core/skills.ts` + `.agents/skills/` | Skill 定义、触发条件 |
-| 5 | MCP 集成 | `core/mcp/` 目录 | MCP 协议、客户端、适配器 |
-
-**动手任务**：写一个最小的自定义扩展（注册一个自定义工具或斜杠命令）。
-
-**验收标准**：能独立创建一个扩展，并在 nanoPencil 中加载运行。
-
----
-
-## Phase 4：会话管理 — 记忆与持久化（1-2 天）
-
-**目标**：理解对话如何保存、分支、压缩。
-
-| # | 学习项 | 文件 | 关键概念 |
-|---|--------|------|----------|
-| 1 | 会话持久化 | `core/session/session-manager.ts` | JSONL 格式、会话切换 |
-| 2 | 会话分支 | `core/session/branch-summarization.ts` | Fork、分支摘要 |
-| 3 | 上下文压缩 | `core/session/compaction/compaction.ts` | 窗口管理、Token 估算 |
-| 4 | 配置系统 | `core/platform/config/` | 全局+项目级设置、auth 存储 |
-
-**验收标准**：能解释会话 fork 和 compaction 的工作原理。
-
----
-
-## Phase 5：特色能力 — 差异化功能（2-3 天）
-
-**目标**：掌握 nanoPencil 区别于其他 Agent 的核心能力。
-
-| # | 学习项 | 文件 | 关键概念 |
-|---|--------|------|----------|
-| 1 | SubAgent 系统 | `core/sub-agent/` | Agent 工具、子进程隔离、结果提取 |
-| 2 | Git Worktree | `core/workspace/worktree-manager.ts` | 临时工作区、变更检测、Patch 生成 |
-| 3 | Soul / 人格系统 | `core/soul-integration.ts`<br>`packages/soul-core/` | AI 人格演化 |
-| 4 | Memory 系统 | `packages/mem-core/` | 持久化记忆、记忆检索 |
-| 5 | 联网能力 | `extensions/builtin/link-world/` | agent-reach、搜索、浏览器 |
-
-**验收标准**：能用一句话解释 SubAgent 和 Worktree 的设计意图。
-
----
-
-## Phase 6：架构深度 — 设计哲学与规范（2-3 天）
-
-**目标**：理解项目的设计哲学，为贡献代码做准备。
-
-| # | 学习项 | 文件 | 关键概念 |
-|---|--------|------|----------|
-| 1 | DIP 协议 | `AGENTS.md` §DIP Protocol | P1/P2/P3 文档层级、同构性 |
-| 2 | 特性工作流 | `.dev-docs/feature-workflow.md` | 四步循环、层级归属、验收门 |
-| 3 | 代码规范 | `AGENTS.md` §Code Standards | 语言策略、提交约定 |
-| 4 | 代码异味 | `AGENTS.md` §Code Smells | 识别和消除坏味道 |
-| 5 | 发布流程 | `AGENTS.md` §Release Process | 版本管理、CHANGELOG 生成 |
-| 6 | 对标分析 | `docs/对标Claude-Code.md` | 与竞品的差距与优势 |
-
-**验收标准**：能按照项目规范完成一次完整的 PR 流程（从创建分支到提交）。
-
----
-
-## Phase 7：实战演练（持续）
-
-| # | 任务 | 说明 |
-|---|------|------|
-| 1 | 修复一个 bug | 从 issue 或测试失败入手 |
-| 2 | 新增一个小功能 | 比如一个新工具或新命令 |
-| 3 | 写一篇扩展教程 | 帮助新人入门 |
-| 4 | 参与 Code Review | 用 `requesting-code-review` skill |
-
----
-
-## 🗂️ 学习资源索引
-
-### 核心文档
-| 文件 | 说明 |
-|------|------|
-| `AGENTS.md` | P1 根文档：架构、命令、规范 |
-| `.PENCIL.md` | 产品性格宪章 |
-| `core/AGENT.md` | P2 Core 模块地图 |
-| `modes/AGENT.md` | P2 模式模块地图 |
-| `extensions/AGENT.md` | P2 扩展模块地图 |
-
-### 设计文档
-| 文件 | 说明 |
-|------|------|
-| `docs/cc-agent-design.md` | Claude Code Agent 设计 |
-| `docs/cc-tui-design.md` | TUI 设计规范 |
-| `docs/planmode.md` | Plan Mode 设计 |
-| `docs/pi-design-philosophy.md` | PI 设计哲学 |
-| `docs/对标Claude-Code.md` | 竞品对标分析 |
-
-### 配置路径
-| 路径 | 说明 |
-|------|------|
-| `~/.pencils/agents/` | 全局配置根目录 |
-| `~/.pencils/agents/<id>/settings.json` | 用户偏好 |
-| `~/.pencils/agents/<id>/models.json` | 模型定义 |
-| `~/.pencils/agents/<id>/auth.json` | API 密钥 |
-| `~/.pencils/agents/<id>/sessions/` | 对话历史 |
-
----
-
-## 📅 建议节奏
-
-| 周次 | 阶段 | 时间投入 |
-|------|------|----------|
-| 第 1 周 | Phase 1-2 | 每天 1-2 小时 |
-| 第 2 周 | Phase 3-4 | 每天 1-2 小时 |
-| 第 3 周 | Phase 5-6 | 每天 1-2 小时 |
-| 第 4 周+ | Phase 7 | 按需实战 |
-
-> 蕾姆的建议：不用急着赶进度。每个阶段结束后，试着用自己的话总结一遍"这个部分解决了什么问题"。这样理解会更深。
-
----
-
-*这份计划由蕾姆为寸哥整理。*