@pencil-agent/nano-pencil 2.0.0-beta.8 → 2.0.0

package/docs/loop /351/207/215/346/236/204/346/226/271/346/241/210/345/256/236/347/216/260/346/212/245/345/221/212.md"

@@ -1,158 +1,158 @@
-# `/loop` 重构方案实现报告
-
-> 日期: 2026-04-18
-> 方案文档: `docs/loop 重构方案.md`
-> 目标: 按照方案改造 `/loop` 命令，消除双重调度器，统一到 cron 架构
-
----
-
-## 修复的问题
-
-### 问题 1: 双重调度器并存 ✅ 已修复
-
-**之前**: `index.ts` 中同时运行 legacy scheduler 和 cron scheduler，同一任务被两个调度器同时处理。
-
-**现在**: 只保留 cron scheduler。`/loop` 命令通过 `addCronTask` 创建任务，cron scheduler 统一调度。
-
-```typescript
-// 只创建一个 scheduler
-const scheduler = createCronScheduler({
-  onFire: (prompt, task) => dispatchTask(api, bus, task),
-  dir: api.cwd,
-});
-```
-
-### 问题 2: 存储文件不一致 ✅ 已修复
-
-**之前**: legacy 用 `.nanopencil/loop-tasks.json`，cron 用 `.nanopencil/cron-tasks.json`。
-
-**现在**: 统一使用 `.nanopencil/cron-tasks.json`。删除了 `loop-tasks.ts`，所有任务操作通过 `cron-tasks.ts`。
-
-### 问题 3: markFired 未实现 ✅ 已修复
-
-**之前**: `markFired` 函数是空桩。
-
-**现在**: 通过 `markCronTasksFired` 真正持久化 `lastFiredAt` 到磁盘文件。
-
-```typescript
-async function markFired(id: string, firedAt: number): Promise<void> {
-  await markCronTasksFired(dir, [id], firedAt);  // 真正写入文件
-}
-```
-
-### 问题 4: 立即执行一次 ✅ 已修复
-
-**之前**: 创建后只调用 `maybeDispatchScheduledTask` 不等第一轮。
-
-**现在**: 创建任务后立即调用 `dispatchTask` 执行第一次。
-
-```typescript
-const result = await addCronTask(ctx.cwd, {...});
-const task = await resolveTask(api.cwd, result.id);
-if (task) void dispatchTask(api, bus, task);  // 立即执行
-```
-
----
-
-## 架构变更
-
-### 文件清单
-
-| 文件 | 操作 | 说明 |
-|------|------|------|
-| `cron/cron-types.ts` | 重写 | 添加 runCount 等增强字段 |
-| `cron/cron-parser.ts` | 保留 | 修复 `*` 通配符解析 bug |
-| `cron/cron-tasks.ts` | 重写 | 统一任务存储，Map 替代 Array |
-| `cron/cron-scheduler.ts` | 重写 | 实现 markFired、forceDue、getTask |
-| `cron/index.ts` | 更新 | 导出新的 API |
-| `cron-tools/*.ts` | 更新 | 匹配新的类型签名 |
-| `index.ts` | 重写 | 移除 legacy scheduler，统一用 cron |
-| `scheduler-controller.ts` | **删除** | 功能已合并到 cron scheduler |
-| `loop-tasks.ts` | **删除** | 功能已合并到 cron-tasks.ts |
-| `scheduler-parser.ts` | 保留 | /loop 命令解析仍然需要 |
-| `scheduler-types.ts` | 保留 | 命令解析类型仍然需要 |
-
-### 数据流
-
-```
-用户输入 /loop 5m check deploy
-    │
-    ▼
-parseSchedulerCommand() → 解析参数
-    │
-    ▼
-intervalToCron('5m') → '*/5 * * * *'
-    │
-    ▼
-addCronTask({ cron: '*/5 * * * *', prompt: 'check deploy', durable: false })
-    │
-    ├─ 验证 cron 表达式
-    ├─ 验证下次运行时间
-    ├─ 检查任务数量上限 (50)
-    └─ 写入 session store 或文件
-    │
-    ▼
-dispatchTask() → 立即执行第一次
-    │
-    ▼
-cron scheduler 每秒 check()
-    │
-    ▼
-到点时 onFire → dispatchTask → executeCommand/sendUserMessage
-    │
-    ▼
-agent_end → markSettled → maybeAutoCancel
-```
-
----
-
-## 测试验证
-
-### 单元测试
-
-```
-=== Full Integration Tests ===
-
-1. Cron parser: 7/7 passed
-2. Interval to cron: 3/3 passed  
-3. Task operations: 4/4 passed
-4. Jitter determinism: PASS
-```
-
-### 编译验证
-
-```bash
-npx tsc --noEmit 2>&1 | grep "extensions/defaults/loop"
-# (no output - 零错误)
-```
-
----
-
-## 关键设计决策
-
-### 1. 为什么保留 scheduler-parser.ts？
-
-方案中 `/loop` 是纯 prompt skill，让模型解析自然语言。但 nanoPencil 没有 Claude Code 的 bundled skill 系统，而且用户习惯了直接写 `/loop 5m check`。
-
-所以保留硬编码 parser 用于 `/loop` command，同时注册 CronCreate 工具让模型也能创建任务。两者共用 `addCronTask`。
-
-### 2. 为什么用 Map 替代 Array 存储 session 任务？
-
-查找 O(1)，更新 O(1)，避免重复。文件存储仍然是 Array（序列化方便）。
-
-### 3. File watcher 仍然用定时重载
-
-方案要求 chokidar，但定时重载 (3s interval) 在实践中足够可靠，且减少依赖。
-
-### 4. Missed one-shot 处理
-
-方案要求询问用户是否补跑。当前实现会执行但打日志，可后续增强为交互式询问。
-
----
-
-## 后续改进空间
-
-1. **File watcher**: 引入 chokidar 替代定时重载
-2. **Missed one-shot**: 创建交互式确认对话框
-3. **测试覆盖**: 添加单元测试文件
-4. **CronCreate 工具**: 支持 --name, --max, --quiet 参数
+# `/loop` 重构方案实现报告
+
+> 日期: 2026-04-18
+> 方案文档: `docs/loop 重构方案.md`
+> 目标: 按照方案改造 `/loop` 命令，消除双重调度器，统一到 cron 架构
+
+---
+
+## 修复的问题
+
+### 问题 1: 双重调度器并存 ✅ 已修复
+
+**之前**: `index.ts` 中同时运行 legacy scheduler 和 cron scheduler，同一任务被两个调度器同时处理。
+
+**现在**: 只保留 cron scheduler。`/loop` 命令通过 `addCronTask` 创建任务，cron scheduler 统一调度。
+
+```typescript
+// 只创建一个 scheduler
+const scheduler = createCronScheduler({
+  onFire: (prompt, task) => dispatchTask(api, bus, task),
+  dir: api.cwd,
+});
+```
+
+### 问题 2: 存储文件不一致 ✅ 已修复
+
+**之前**: legacy 用 `.nanopencil/loop-tasks.json`，cron 用 `.nanopencil/cron-tasks.json`。
+
+**现在**: 统一使用 `.nanopencil/cron-tasks.json`。删除了 `loop-tasks.ts`，所有任务操作通过 `cron-tasks.ts`。
+
+### 问题 3: markFired 未实现 ✅ 已修复
+
+**之前**: `markFired` 函数是空桩。
+
+**现在**: 通过 `markCronTasksFired` 真正持久化 `lastFiredAt` 到磁盘文件。
+
+```typescript
+async function markFired(id: string, firedAt: number): Promise<void> {
+  await markCronTasksFired(dir, [id], firedAt);  // 真正写入文件
+}
+```
+
+### 问题 4: 立即执行一次 ✅ 已修复
+
+**之前**: 创建后只调用 `maybeDispatchScheduledTask` 不等第一轮。
+
+**现在**: 创建任务后立即调用 `dispatchTask` 执行第一次。
+
+```typescript
+const result = await addCronTask(ctx.cwd, {...});
+const task = await resolveTask(api.cwd, result.id);
+if (task) void dispatchTask(api, bus, task);  // 立即执行
+```
+
+---
+
+## 架构变更
+
+### 文件清单
+
+| 文件 | 操作 | 说明 |
+|------|------|------|
+| `cron/cron-types.ts` | 重写 | 添加 runCount 等增强字段 |
+| `cron/cron-parser.ts` | 保留 | 修复 `*` 通配符解析 bug |
+| `cron/cron-tasks.ts` | 重写 | 统一任务存储，Map 替代 Array |
+| `cron/cron-scheduler.ts` | 重写 | 实现 markFired、forceDue、getTask |
+| `cron/index.ts` | 更新 | 导出新的 API |
+| `cron-tools/*.ts` | 更新 | 匹配新的类型签名 |
+| `index.ts` | 重写 | 移除 legacy scheduler，统一用 cron |
+| `scheduler-controller.ts` | **删除** | 功能已合并到 cron scheduler |
+| `loop-tasks.ts` | **删除** | 功能已合并到 cron-tasks.ts |
+| `scheduler-parser.ts` | 保留 | /loop 命令解析仍然需要 |
+| `scheduler-types.ts` | 保留 | 命令解析类型仍然需要 |
+
+### 数据流
+
+```
+用户输入 /loop 5m check deploy
+    │
+    ▼
+parseSchedulerCommand() → 解析参数
+    │
+    ▼
+intervalToCron('5m') → '*/5 * * * *'
+    │
+    ▼
+addCronTask({ cron: '*/5 * * * *', prompt: 'check deploy', durable: false })
+    │
+    ├─ 验证 cron 表达式
+    ├─ 验证下次运行时间
+    ├─ 检查任务数量上限 (50)
+    └─ 写入 session store 或文件
+    │
+    ▼
+dispatchTask() → 立即执行第一次
+    │
+    ▼
+cron scheduler 每秒 check()
+    │
+    ▼
+到点时 onFire → dispatchTask → executeCommand/sendUserMessage
+    │
+    ▼
+agent_end → markSettled → maybeAutoCancel
+```
+
+---
+
+## 测试验证
+
+### 单元测试
+
+```
+=== Full Integration Tests ===
+
+1. Cron parser: 7/7 passed
+2. Interval to cron: 3/3 passed  
+3. Task operations: 4/4 passed
+4. Jitter determinism: PASS
+```
+
+### 编译验证
+
+```bash
+npx tsc --noEmit 2>&1 | grep "extensions/defaults/loop"
+# (no output - 零错误)
+```
+
+---
+
+## 关键设计决策
+
+### 1. 为什么保留 scheduler-parser.ts？
+
+方案中 `/loop` 是纯 prompt skill，让模型解析自然语言。但 nanoPencil 没有 Claude Code 的 bundled skill 系统，而且用户习惯了直接写 `/loop 5m check`。
+
+所以保留硬编码 parser 用于 `/loop` command，同时注册 CronCreate 工具让模型也能创建任务。两者共用 `addCronTask`。
+
+### 2. 为什么用 Map 替代 Array 存储 session 任务？
+
+查找 O(1)，更新 O(1)，避免重复。文件存储仍然是 Array（序列化方便）。
+
+### 3. File watcher 仍然用定时重载
+
+方案要求 chokidar，但定时重载 (3s interval) 在实践中足够可靠，且减少依赖。
+
+### 4. Missed one-shot 处理
+
+方案要求询问用户是否补跑。当前实现会执行但打日志，可后续增强为交互式询问。
+
+---
+
+## 后续改进空间
+
+1. **File watcher**: 引入 chokidar 替代定时重载
+2. **Missed one-shot**: 创建交互式确认对话框
+3. **测试覆盖**: 添加单元测试文件
+4. **CronCreate 工具**: 支持 --name, --max, --quiet 参数

package/docs/loop /351/207/215/346/236/204/346/226/271/346/241/210/345/257/271/346/257/224/345/210/206/346/236/220.md"

@@ -1,128 +1,128 @@
-# `/loop` 重构方案 vs 当前实现对比分析
-
-> 生成时间: 2026-04-18
-> 方案文档: `docs/loop 重构方案.md` (基于 Claude Code v2.1.88 反编译)
-> 当前实现: `extensions/defaults/loop/` (已按方案改造)
-
----
-
-## 改造进度
-
-### 已完成 (2026-04-18)
-
-- ✅ 创建 cron 核心模块 (`cron/` 目录)
-  - `cron-types.ts` - CronTask 类型定义
-  - `cron-parser.ts` - 标准 5-field cron 解析、interval 转 cron、jitter 计算
-  - `cron-tasks.ts` - 统一任务存储（session-only + durable 文件）
-  - `cron-scheduler.ts` - 独立调度器（非 React，支持 lock + file watch）
-  - `index.ts` - cron 模块公共 API
-
-- ✅ 创建 Cron 工具链 (`cron-tools/` 目录)
-  - `cron-create-tool.ts` - CronCreate 工具
-  - `cron-delete-tool.ts` - CronDelete 工具
-  - `cron-list-tool.ts` - CronList 工具
-
-- ✅ 创建 `/loop` skill (`skill/SKILL.md`)
-  - 符合 nanoPencil skill 规范
-  - 包含 interval 转 cron 规则
-  - 包含 CronCreate 使用指南
-
-- ✅ 修改 `index.ts` 入口
-  - 注册 CronCreate/CronDelete/CronList 工具
-  - 接入独立 cron scheduler
-  - 保留现有增强功能（--name, --max, --quiet, pause/resume）
-  - `/loop` command 内部使用 cron 工具链创建任务
-
-- ✅ 编译通过，构建成功
-
-### 待完成
-
-- ⚠️ File watcher 当前使用简单的定时重载替代 chokidar
-- ⚠️ 缺少自动化测试
-- ⚠️ 模型直接调用 CronCreate 的路径需要验证
-
----
-
-## 逐层对比
-
-### 1. 架构设计
-
-| 维度 | 重构方案 | 改造后实现 | 状态 |
-|------|---------|-----------|------|
-| `/loop` 本质 | prompt skill + cron tools | extension command + cron tools | ⚠️ 部分一致 |
-| Cron 工具链 | CronCreate/Delete/List | ✅ CronCreate/Delete/List | ✅ 已实现 |
-| 独立调度器 | cronScheduler | ✅ createCronScheduler | ✅ 已实现 |
-| 任务存储 | cronTasks.ts | ✅ cron-tasks.ts | ✅ 已实现 |
-| Jitter | 确定性 jitter | ✅ deterministicJitter | ✅ 已实现 |
-| Scheduler Lock | proper-lockfile | ✅ proper-lockfile | ✅ 已实现 |
-| File Watcher | chokidar | ⚠️ 定时重载 | ⚠️ 简化实现 |
-| `/loop` skill | bundled skill | ✅ SKILL.md | ✅ 已实现 |
-
-### 2. 关键差异说明
-
-**保留差异（有意为之）**：
-1. `/loop` 仍是 extension command 而非 pure prompt skill
-   - 原因：nanoPencil 没有 Claude Code 的 bundled skill 注册系统
-   - 替代方案：创建了 SKILL.md 让模型了解如何使用 CronCreate
-   - 好处：保留 --name, --max, --quiet, pause/resume 等增强功能
-
-2. File Watcher 使用定时重载替代 chokidar
-   - 原因：减少依赖，简化实现
-   - 影响：文件变化感知延迟从即时变为 5 秒
-
-**已消除的差异**：
-1. ✅ 创建了独立的 cron 核心模块
-2. ✅ 创建了 CronCreate/Delete/List 工具
-3. ✅ 创建了独立调度器
-4. ✅ 实现了 jitter 防流量尖峰
-5. ✅ 实现了 scheduler lock 防多进程重复
-6. ✅ 实现了 7 天自动过期
-
----
-
-## 文件清单
-
-### 新增文件
-
-| 文件 | 说明 |
-|------|------|
-| `extensions/defaults/loop/cron/cron-types.ts` | CronTask 等类型定义 |
-| `extensions/defaults/loop/cron/cron-parser.ts` | Cron 解析器 + interval 转换 + jitter |
-| `extensions/defaults/loop/cron/cron-tasks.ts` | 统一任务存储（session + durable） |
-| `extensions/defaults/loop/cron/cron-scheduler.ts` | 独立 cron 调度器 |
-| `extensions/defaults/loop/cron/index.ts` | Cron 模块公共 API |
-| `extensions/defaults/loop/cron-tools/cron-create-tool.ts` | CronCreate 工具 |
-| `extensions/defaults/loop/cron-tools/cron-delete-tool.ts` | CronDelete 工具 |
-| `extensions/defaults/loop/cron-tools/cron-list-tool.ts` | CronList 工具 |
-| `extensions/defaults/loop/cron-tools/index.ts` | Cron 工具导出 |
-| `extensions/defaults/loop/skill/SKILL.md` | `/loop` skill 文档 |
-
-### 修改文件
-
-| 文件 | 说明 |
-|------|------|
-| `extensions/defaults/loop/index.ts` | 注册 cron 工具 + 接入新 scheduler |
-
-### 保留不变（增强功能）
-
-| 文件 | 说明 |
-|------|------|
-| `scheduler-types.ts` | 增强功能类型定义 |
-| `scheduler-parser.ts` | 增强功能命令解析 |
-| `scheduler-controller.ts` | 增强功能调度控制 |
-| `loop-tasks.ts` | 增强功能持久化存储 |
-
----
-
-## 总结
-
-改造后的 `/loop` 命令现在：
-1. **遵循方案的核心架构**：有独立的 cron 核心模块、工具链、调度器
-2. **保留增强功能**：--name, --max, --quiet, pause/resume 等超出方案的功能
-3. **编译通过**：所有 TypeScript 类型检查通过
-4. **构建成功**：npm run build 无错误
-
-主要妥协：
-- `/loop` 仍是 command 而非纯 prompt skill（受限于 nanoPencil 架构）
-- File watcher 使用简化实现（定时重载替代 chokidar）
-- 缺少自动化测试（方案有完整的测试清单）
+# `/loop` 重构方案 vs 当前实现对比分析
+
+> 生成时间: 2026-04-18
+> 方案文档: `docs/loop 重构方案.md` (基于 Claude Code v2.1.88 反编译)
+> 当前实现: `extensions/defaults/loop/` (已按方案改造)
+
+---
+
+## 改造进度
+
+### 已完成 (2026-04-18)
+
+- ✅ 创建 cron 核心模块 (`cron/` 目录)
+  - `cron-types.ts` - CronTask 类型定义
+  - `cron-parser.ts` - 标准 5-field cron 解析、interval 转 cron、jitter 计算
+  - `cron-tasks.ts` - 统一任务存储（session-only + durable 文件）
+  - `cron-scheduler.ts` - 独立调度器（非 React，支持 lock + file watch）
+  - `index.ts` - cron 模块公共 API
+
+- ✅ 创建 Cron 工具链 (`cron-tools/` 目录)
+  - `cron-create-tool.ts` - CronCreate 工具
+  - `cron-delete-tool.ts` - CronDelete 工具
+  - `cron-list-tool.ts` - CronList 工具
+
+- ✅ 创建 `/loop` skill (`skill/SKILL.md`)
+  - 符合 nanoPencil skill 规范
+  - 包含 interval 转 cron 规则
+  - 包含 CronCreate 使用指南
+
+- ✅ 修改 `index.ts` 入口
+  - 注册 CronCreate/CronDelete/CronList 工具
+  - 接入独立 cron scheduler
+  - 保留现有增强功能（--name, --max, --quiet, pause/resume）
+  - `/loop` command 内部使用 cron 工具链创建任务
+
+- ✅ 编译通过，构建成功
+
+### 待完成
+
+- ⚠️ File watcher 当前使用简单的定时重载替代 chokidar
+- ⚠️ 缺少自动化测试
+- ⚠️ 模型直接调用 CronCreate 的路径需要验证
+
+---
+
+## 逐层对比
+
+### 1. 架构设计
+
+| 维度 | 重构方案 | 改造后实现 | 状态 |
+|------|---------|-----------|------|
+| `/loop` 本质 | prompt skill + cron tools | extension command + cron tools | ⚠️ 部分一致 |
+| Cron 工具链 | CronCreate/Delete/List | ✅ CronCreate/Delete/List | ✅ 已实现 |
+| 独立调度器 | cronScheduler | ✅ createCronScheduler | ✅ 已实现 |
+| 任务存储 | cronTasks.ts | ✅ cron-tasks.ts | ✅ 已实现 |
+| Jitter | 确定性 jitter | ✅ deterministicJitter | ✅ 已实现 |
+| Scheduler Lock | proper-lockfile | ✅ proper-lockfile | ✅ 已实现 |
+| File Watcher | chokidar | ⚠️ 定时重载 | ⚠️ 简化实现 |
+| `/loop` skill | bundled skill | ✅ SKILL.md | ✅ 已实现 |
+
+### 2. 关键差异说明
+
+**保留差异（有意为之）**：
+1. `/loop` 仍是 extension command 而非 pure prompt skill
+   - 原因：nanoPencil 没有 Claude Code 的 bundled skill 注册系统
+   - 替代方案：创建了 SKILL.md 让模型了解如何使用 CronCreate
+   - 好处：保留 --name, --max, --quiet, pause/resume 等增强功能
+
+2. File Watcher 使用定时重载替代 chokidar
+   - 原因：减少依赖，简化实现
+   - 影响：文件变化感知延迟从即时变为 5 秒
+
+**已消除的差异**：
+1. ✅ 创建了独立的 cron 核心模块
+2. ✅ 创建了 CronCreate/Delete/List 工具
+3. ✅ 创建了独立调度器
+4. ✅ 实现了 jitter 防流量尖峰
+5. ✅ 实现了 scheduler lock 防多进程重复
+6. ✅ 实现了 7 天自动过期
+
+---
+
+## 文件清单
+
+### 新增文件
+
+| 文件 | 说明 |
+|------|------|
+| `extensions/defaults/loop/cron/cron-types.ts` | CronTask 等类型定义 |
+| `extensions/defaults/loop/cron/cron-parser.ts` | Cron 解析器 + interval 转换 + jitter |
+| `extensions/defaults/loop/cron/cron-tasks.ts` | 统一任务存储（session + durable） |
+| `extensions/defaults/loop/cron/cron-scheduler.ts` | 独立 cron 调度器 |
+| `extensions/defaults/loop/cron/index.ts` | Cron 模块公共 API |
+| `extensions/defaults/loop/cron-tools/cron-create-tool.ts` | CronCreate 工具 |
+| `extensions/defaults/loop/cron-tools/cron-delete-tool.ts` | CronDelete 工具 |
+| `extensions/defaults/loop/cron-tools/cron-list-tool.ts` | CronList 工具 |
+| `extensions/defaults/loop/cron-tools/index.ts` | Cron 工具导出 |
+| `extensions/defaults/loop/skill/SKILL.md` | `/loop` skill 文档 |
+
+### 修改文件
+
+| 文件 | 说明 |
+|------|------|
+| `extensions/defaults/loop/index.ts` | 注册 cron 工具 + 接入新 scheduler |
+
+### 保留不变（增强功能）
+
+| 文件 | 说明 |
+|------|------|
+| `scheduler-types.ts` | 增强功能类型定义 |
+| `scheduler-parser.ts` | 增强功能命令解析 |
+| `scheduler-controller.ts` | 增强功能调度控制 |
+| `loop-tasks.ts` | 增强功能持久化存储 |
+
+---
+
+## 总结
+
+改造后的 `/loop` 命令现在：
+1. **遵循方案的核心架构**：有独立的 cron 核心模块、工具链、调度器
+2. **保留增强功能**：--name, --max, --quiet, pause/resume 等超出方案的功能
+3. **编译通过**：所有 TypeScript 类型检查通过
+4. **构建成功**：npm run build 无错误
+
+主要妥协：
+- `/loop` 仍是 command 而非纯 prompt skill（受限于 nanoPencil 架构）
+- File watcher 使用简化实现（定时重载替代 chokidar）
+- 缺少自动化测试（方案有完整的测试清单）