@pencil-agent/nano-pencil 2.0.0 → 2.0.1

package/docs/loop-usage-examples.md

@@ -1,215 +1,215 @@
-# Loop Extension Usage Examples
-
-## Basic Usage
-
-### Session-Scoped Loops (Default)
-
-Session-scoped loops are cleared when you close the session.
-
-```bash
-# Check the build every 10 minutes (default)
-/loop check the build
-
-# Run a command every 5 minutes
-/loop 5m /grub status
-
-# Check PR reviews every 20 minutes
-/loop every 20m Review test failures
-
-# Remind to drink water every 30 minutes
-/loop Drink water every 30m --name hydrate --max 8 --quiet
-```
-
-### Durable Loops (Persistent Across Sessions)
-
-Durable loops are saved to `.nanopencil/loop-tasks.json` and resume when you reopen the project.
-
-```bash
-# Monitor build status every 5 minutes, persists across sessions
-/loop Check build status every 5m --durable
-
-# Check for new commits every hour
-/loop 1h Check for new commits --durable
-
-# Daily status check at 9 AM
-/loop Daily status check --durable --name daily-check
-```
-
-## Managing Loops
-
-### List All Loops
-
-```bash
-/loop list
-```
-
-Output:
-```
-[Loop] 3 scheduled tasks:
-- build-monitor (abc123) every 5m next in 3m [durable] Check build status
-- hydrate (def456) every 30m next in 15m [quiet, max 2/8] Drink water every 30m
-- ghi789 every 10m next in 8m /grub status
-```
-
-### Get Loop Status
-
-```bash
-/loop status build-monitor
-```
-
-Output:
-```
-[Loop] build-monitor (abc123) — scheduled
-Every: 5m
-Kind: prompt (durable)
-Next run: Sat Apr 18 2025 01:05:00 GMT+0800 (in 3m)
-Last run: Sat Apr 18 2025 01:00:00 GMT+0800
-Run count: 5
-Input: Check build status
-Last output: Build is green
-```
-
-### Pause and Resume
-
-```bash
-/loop pause build-monitor
-/loop resume build-monitor
-```
-
-### Run Immediately
-
-```bash
-/loop run build-monitor
-```
-
-### Cancel a Loop
-
-```bash
-/loop cancel build-monitor
-# or by ID
-/loop cancel abc123
-```
-
-### Clear All Loops
-
-```bash
-/loop clear
-```
-
-## Advanced Features
-
-### Named Loops
-
-```bash
-/loop Check build every 5m --name build-monitor
-/loop pause build-monitor
-```
-
-### Maximum Runs
-
-```bash
-/loop Drink water every 30m --name hydrate --max 8 --quiet
-```
-
-### Quiet Mode
-
-Suppresses per-tick UI messages (errors and terminal events still surface):
-
-```bash
-/loop 5m Check system status --quiet
-```
-
-### Combining Flags
-
-```bash
-/loop Check build every 5m --name build-monitor --durable --quiet
-```
-
-## Durable vs Session-Scoped Loops
-
-| Feature | Session-Scoped | Durable |
-|---------|---------------|---------|
-| Persistence | Lost when session closes | Saved to disk |
-| Multi-process safety | N/A (per-process) | Protected by lock |
-| Use case | Temporary tasks | Long-running monitoring |
-| Storage | In-memory | `.nanopencil/loop-tasks.json` |
-
-## Real-World Examples
-
-### Development Workflow
-
-```bash
-# Monitor build status while developing
-/loop npm run build --name build-check
-
-# Run tests every time you save
-/loop npm test --name test-checker --quiet
-
-# Check for linting errors
-/loop npm run lint --name linter --durable
-```
-
-### Project Monitoring
-
-```bash
-# Check for new git commits
-/loop git pull --name git-update --durable
-
-# Monitor dependencies
-/loop npm outdated --name deps-check --durable
-
-# Check server health
-/loop curl http://localhost:3000/health --name health-check --durable
-```
-
-### Productivity
-
-```bash
-# Take breaks
-/loop Take a break every hour --name break-reminder --max 4
-
-# Daily standup reminder
-/loop Daily standup every 24h --name standup --durable
-
-# Code review reminder
-/loop Review pending PRs every 2h --name pr-review --durable
-```
-
-## Troubleshooting
-
-### Loop Not Running
-
-1. Check if loop is paused: `/loop status <name>`
-2. Check if max runs reached: look at run count in status
-3. Check if session is idle: loops only run when agent is idle
-
-### Durable Loop Not Persisting
-
-1. Check if `.nanopencil/loop-tasks.json` exists
-2. Verify you used `--durable` flag
-3. Check file permissions on project directory
-
-### Multiple Instances Triggering Same Loop
-
-The scheduler lock prevents this. If you see multiple triggers:
-1. Check if lock file exists: `.nanopencil/loop-scheduler.lock`
-2. Manually remove lock file if necessary
-3. Restart nanoPencil
-
-## File Locations
-
-```
-<nanopencil>
-├── .nanopencil/
-│   ├── loop-tasks.json          # Durable loop storage
-│   └── loop-scheduler.lock      # Scheduler lock file
-```
-
-## Best Practices
-
-1. **Use meaningful names**: `--name` makes it easier to manage loops
-2. **Set appropriate intervals**: Don't poll too frequently (minimum 1m)
-3. **Use durable for long-running tasks**: `--durable` for tasks that should survive session restarts
-4. **Use max runs for finite tasks**: `--max` for tasks that should auto-cancel
-5. **Use quiet for frequent tasks**: `--quiet` reduces UI noise
+# Loop Extension Usage Examples
+
+## Basic Usage
+
+### Session-Scoped Loops (Default)
+
+Session-scoped loops are cleared when you close the session.
+
+```bash
+# Check the build every 10 minutes (default)
+/loop check the build
+
+# Run a command every 5 minutes
+/loop 5m /grub status
+
+# Check PR reviews every 20 minutes
+/loop every 20m Review test failures
+
+# Remind to drink water every 30 minutes
+/loop Drink water every 30m --name hydrate --max 8 --quiet
+```
+
+### Durable Loops (Persistent Across Sessions)
+
+Durable loops are saved to `.nanopencil/loop-tasks.json` and resume when you reopen the project.
+
+```bash
+# Monitor build status every 5 minutes, persists across sessions
+/loop Check build status every 5m --durable
+
+# Check for new commits every hour
+/loop 1h Check for new commits --durable
+
+# Daily status check at 9 AM
+/loop Daily status check --durable --name daily-check
+```
+
+## Managing Loops
+
+### List All Loops
+
+```bash
+/loop list
+```
+
+Output:
+```
+[Loop] 3 scheduled tasks:
+- build-monitor (abc123) every 5m next in 3m [durable] Check build status
+- hydrate (def456) every 30m next in 15m [quiet, max 2/8] Drink water every 30m
+- ghi789 every 10m next in 8m /grub status
+```
+
+### Get Loop Status
+
+```bash
+/loop status build-monitor
+```
+
+Output:
+```
+[Loop] build-monitor (abc123) — scheduled
+Every: 5m
+Kind: prompt (durable)
+Next run: Sat Apr 18 2025 01:05:00 GMT+0800 (in 3m)
+Last run: Sat Apr 18 2025 01:00:00 GMT+0800
+Run count: 5
+Input: Check build status
+Last output: Build is green
+```
+
+### Pause and Resume
+
+```bash
+/loop pause build-monitor
+/loop resume build-monitor
+```
+
+### Run Immediately
+
+```bash
+/loop run build-monitor
+```
+
+### Cancel a Loop
+
+```bash
+/loop cancel build-monitor
+# or by ID
+/loop cancel abc123
+```
+
+### Clear All Loops
+
+```bash
+/loop clear
+```
+
+## Advanced Features
+
+### Named Loops
+
+```bash
+/loop Check build every 5m --name build-monitor
+/loop pause build-monitor
+```
+
+### Maximum Runs
+
+```bash
+/loop Drink water every 30m --name hydrate --max 8 --quiet
+```
+
+### Quiet Mode
+
+Suppresses per-tick UI messages (errors and terminal events still surface):
+
+```bash
+/loop 5m Check system status --quiet
+```
+
+### Combining Flags
+
+```bash
+/loop Check build every 5m --name build-monitor --durable --quiet
+```
+
+## Durable vs Session-Scoped Loops
+
+| Feature | Session-Scoped | Durable |
+|---------|---------------|---------|
+| Persistence | Lost when session closes | Saved to disk |
+| Multi-process safety | N/A (per-process) | Protected by lock |
+| Use case | Temporary tasks | Long-running monitoring |
+| Storage | In-memory | `.nanopencil/loop-tasks.json` |
+
+## Real-World Examples
+
+### Development Workflow
+
+```bash
+# Monitor build status while developing
+/loop npm run build --name build-check
+
+# Run tests every time you save
+/loop npm test --name test-checker --quiet
+
+# Check for linting errors
+/loop npm run lint --name linter --durable
+```
+
+### Project Monitoring
+
+```bash
+# Check for new git commits
+/loop git pull --name git-update --durable
+
+# Monitor dependencies
+/loop npm outdated --name deps-check --durable
+
+# Check server health
+/loop curl http://localhost:3000/health --name health-check --durable
+```
+
+### Productivity
+
+```bash
+# Take breaks
+/loop Take a break every hour --name break-reminder --max 4
+
+# Daily standup reminder
+/loop Daily standup every 24h --name standup --durable
+
+# Code review reminder
+/loop Review pending PRs every 2h --name pr-review --durable
+```
+
+## Troubleshooting
+
+### Loop Not Running
+
+1. Check if loop is paused: `/loop status <name>`
+2. Check if max runs reached: look at run count in status
+3. Check if session is idle: loops only run when agent is idle
+
+### Durable Loop Not Persisting
+
+1. Check if `.nanopencil/loop-tasks.json` exists
+2. Verify you used `--durable` flag
+3. Check file permissions on project directory
+
+### Multiple Instances Triggering Same Loop
+
+The scheduler lock prevents this. If you see multiple triggers:
+1. Check if lock file exists: `.nanopencil/loop-scheduler.lock`
+2. Manually remove lock file if necessary
+3. Restart nanoPencil
+
+## File Locations
+
+```
+<nanopencil>
+├── .nanopencil/
+│   ├── loop-tasks.json          # Durable loop storage
+│   └── loop-scheduler.lock      # Scheduler lock file
+```
+
+## Best Practices
+
+1. **Use meaningful names**: `--name` makes it easier to manage loops
+2. **Set appropriate intervals**: Don't poll too frequently (minimum 1m)
+3. **Use durable for long-running tasks**: `--durable` for tasks that should survive session restarts
+4. **Use max runs for finite tasks**: `--max` for tasks that should auto-cancel
+5. **Use quiet for frequent tasks**: `--quiet` reduces UI noise
 6. **Monitor loops**: Regularly check `/loop list` to ensure loops are working as expected

package/docs/models.md

@@ -1,27 +1,27 @@
----
-name: models
-description: Use when the user asks how to add, select, or configure models.
-surface: TODO  # user entry points: /command, --flag, config key, file location
-owner: core/model-registry.ts  # DIP P2 anchor — read its AGENT.md member list to find code
-status: draft
----
-
-# Models
-
-> TODO: one line — what this feature does for the user.
-
-## When to use
-TODO: the user intents that should pull this doc (mirrors the frontmatter `description`).
-
-## Usage
-TODO: commands / flags / config keys / file locations, with one minimal example.
-
-## Behavior & defaults
-TODO: default on/off, side effects, opt-in/opt-out.
-
-## Code map → DIP
-- Owner: `core/model-registry.ts` — read its DIP **P2 member list** (the nearest `AGENT.md`) to locate files.
-- Then follow **P3** file headers (WHO / FROM / TO / HERE) to navigate. Do **not** duplicate code paths here.
-
-## Related
-[[custom-provider]] [[providers]]
+---
+name: models
+description: Use when the user asks how to add, select, or configure models.
+surface: TODO  # user entry points: /command, --flag, config key, file location
+owner: core/model-registry.ts  # DIP P2 anchor — read its AGENT.md member list to find code
+status: draft
+---
+
+# Models
+
+> TODO: one line — what this feature does for the user.
+
+## When to use
+TODO: the user intents that should pull this doc (mirrors the frontmatter `description`).
+
+## Usage
+TODO: commands / flags / config keys / file locations, with one minimal example.
+
+## Behavior & defaults
+TODO: default on/off, side effects, opt-in/opt-out.
+
+## Code map → DIP
+- Owner: `core/model-registry.ts` — read its DIP **P2 member list** (the nearest `AGENT.md`) to locate files.
+- Then follow **P3** file headers (WHO / FROM / TO / HERE) to navigate. Do **not** duplicate code paths here.
+
+## Related
+[[custom-provider]] [[providers]]

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

@@ -0,0 +1,170 @@
+# 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 | 按需实战 |
+
+> 蕾姆的建议：不用急着赶进度。每个阶段结束后，试着用自己的话总结一遍"这个部分解决了什么问题"。这样理解会更深。
+
+---
+
+*这份计划由蕾姆为寸哥整理。*