Skill: yangwenyu2/agent-memento (version 2.0.15)

--- clawdbot: emoji: 🧠 requires: bins: - bash - openclaw - node - npm - git env: [] --- # Agent Memento v0.2 — Complete Skill Specification ```markdown --- name: agent-memento description: Tick-Driven Autonomous Production Factory for LLMs. A framework for long-running agents using Cron/Heartbeats and physical Markdown checklists to prevent OOM and context decay. metadata: {"clawdbot":{"emoji":"🧠","requires":{"bins":["bash","openclaw"],"env":[]}}} --- # Agent Memento v0.2 (Tick-Driven Autonomous Execution) > "Don't build AI that tries to remember everything. Build systems that make AI read the blueprint anew every 5 minutes." 当我们在聊天框里让大模型"写一个游戏"时，开头总是美好的。但随着代码超过 2000 行，模型开始： - **失忆症 (Amnesia)**：忘记了自己定义的接口，开始凭空捏造。 - **幻觉重构 (Hallucination)**：自信满满地输出一堆根本没有跑过的"完美"代码。 - **上下文核爆 (Resource Overload)**：为了修一个小 Bug，强行覆盖整个大文件，导致内存耗尽 (OOM)。 **核心原则：把"全知全能的超级 Agent"降级为无数个"只有 5 分钟记忆的、无情的 Tick 机器"。** --- ## Quick Start (30 秒上手) 1. 初始化项目： ```bash bash skills/agent-memento/scripts/init_memento.sh MyProject ``` 2. 在主对话中让 Architect 填写 `MASTER_PLAN.md` 和 `PROJECT_MAP.md` 3. 启动自动执行： ```bash crontab -e # 添加：*/5 * * * * /path/to/MyProject/scripts/memento_tick.sh ``` 4. （可选）启动 Dashboard 看板监控： ```bash bash scripts/dashboard.sh ``` 5. 去刷手机。回来看 Dashboard 或 `docs/TICK_STATUS.md` 查看进度。 ## 一、系统架构总览 ``` ┌─────────────────────────────────────────────────────────┐ │ Human (You) │ │ Discord / 飞书 / Dashboard Panel │ └──────────────┬──────────────────────────┬───────────────┘ │ 自然语言交互 │ 面板批注/干预 ▼ ▼ ┌─────────────────────────────────────────────────────────┐ │ Main Agent (Architect) │ │ LLM 本体 · 长对话 Session │ │ │ │ 职责： │ │ - 与人类讨论需求，翻译为结构化任务 │ │ - 编辑 MASTER_PLAN.md（增/删/改/重排任务） │ │ - 编辑 PROJECT_MAP.md（维护项目认知地图） │ │ - 读取 TICK_STATUS.md 和 Dashboard 批注 │ │ - 根据反馈调整计划（自主决策 or 请示人类） │ └──────────────┬──────────────────────────────────────────┘ │ 写入物理文件 ▼ ┌─────────────────────────────────────────────────────────┐ │ Physical State Layer (磁盘) │ │ │ │ docs/MASTER_PLAN.md ← 唯一真相源，结构化任务清单 │ │ docs/PROJECT_MAP.md ← 项目认知地图 / 文件索引 │ │ docs/TICK_STATUS.md ← Tick 执行状态流水账 │ │ docs/HUMAN_NOTES.md ← 人类批注通道（面板写入） │ │ logs/tick_*.log ← 每个 Tick 的完整执行日志 │ └──────────────┬──────────────────────────────────────────┘ │ 读取（每次从零开始） ▼ ┌─────────────────────────────────────────────────────────┐ │ Tick Worker (Bricklayer) │ │ Cron 唤醒 · 短命进程 · 无状态 · 无情 │ │ │ │ 生命周期： │ │ 1. 醒来 → 读 MASTER_PLAN.md │ │ 2. 找到当前可执行任务 │ │ 3. 读 PROJECT_MAP.md 确定上下文范围 │ │ 4. 读 HUMAN_NOTES.md 检查人类批注 │ │ 5. 执行任务 → 物理验证 │ │ 6. 写结果到 TICK_STATUS.md │ │ 7. 成功则标 [x]，失败则记录 → 死亡 │ │ 8. 自动 git commit │ └─────────────────────────────────────────────────────────┘ ``` --- ## 二、The Methodology：三层智能分工 ### Layer 1：人类（方向盘） - 在 Discord/飞书/Dashboard 中用自然语言描述需求和反馈 - 通过 Dashboard 面板随时插入批注、暂停/恢复流水线 - **不需要逐条审核**——只在 Agent 请求帮助或自己想介入时参与 ### Layer 2：Architect（主 Agent / 翻译官） - 与人类的主对话 Session - 将模糊需求翻译为 `MASTER_PLAN.md` 中的结构化任务 - 持续维护 `PROJECT_MAP.md`（项目认知地图） - 监控 `TICK_STATUS.md`，根据执行情况自主调整计划 - 遇到阻塞性决策时才请示人类 ### Layer 3：Tick Worker（子 Agent / 泥瓦匠） - Cron 唤醒的短命进程，每次从零启动 - 绝对服从 `MASTER_PLAN.md`，不做创造性决策 - 执行 → 验证 → 汇报 → 死亡 --- ## 三、物理状态文件规范 ### 3.1 MASTER_PLAN.md — 唯一真相源 ```markdown # MASTER_PLAN: <ProjectName> ## Meta - created: 2025-01-15 - last_architect_edit: 2025-01-15T14:30:00 - tick_mode: auto <!-- auto | paused | stopped --> - max_retries: 3 <!-- 单任务最大重试次数 --> - max_tasks_per_tick: 2 <!-- 快任务时允许单 Tick 连续处理上限 --> - max_diff_lines: 200 <!-- diff size guard 阈值 --> - stale_lock_timeout: 15min <!-- [~] 僵尸锁重置阈值 --> - circuit_breaker_threshold: 5 <!-- 连续失败多少次触发熔断 --> - clean_strategy: git-clean <!-- 三阶段防爆清理机制 --> - clean_ignore: .memento_cleanignore - status_max_entries: 50 <!-- TICK_STATUS.md 最大条目数，超出自动归档 --> - status_archive_dir: logs/status_archive/ - total_ticks: 0 <!-- 自动递增的 Tick 计数器 --> - total_tasks: 15 <!-- 自动维护 --> - completed_tasks: 0 <!-- 自动维护 --> --- ## Phase 1: Foundation <!-- parallel: true --> <!-- depends: none --> - [ ] `T-101` [MODULE:database] Setup PostgreSQL schema - verify: `cd src && npm test -- --grep "db-schema" && echo PASS` - context_files: [src/db/schema.ts, src/db/migrations/] - guard_files: [src/auth/*] - estimate: 5min - retries: 0 - [ ] `T-102` [MODULE:auth] Implement JWT token generation - verify: `cd src && npm test -- --grep "jwt" && echo PASS` - context_files: [src/auth/jwt.ts, tests/auth/jwt.test.ts] - guard_files: [src/db/*] - estimate: 5min - retries: 0 ## Phase 2: Integration <!-- parallel: false --> <!-- depends: Phase 1 --> - [ ] `T-201` [MODULE:auth] Connect auth middleware to database - verify: `cd src && npm run test:integration && echo PASS` - context_files: [src/auth/middleware.ts, src/db/queries.ts] - guard_files: [src/db/schema.ts] - estimate: 10min - retries: 0 ## Phase 3: Polish <!-- parallel: true --> <!-- depends: Phase 2 --> - [ ] `T-301` [MODULE:docs] Generate API documentation - verify: `test -f docs/api.md && echo PASS` - context_files: [src/routes/*.ts] - guard_files: [] - estimate: 3min - retries: 0 ``` **任务字段说明：** | 字段 | 必须 | 说明 | |------|------|------| | `T-XXX` | ✅ | 任务唯一 ID，用于日志追踪和跨文件引用 | | `[MODULE:xxx]` | ✅ | 模块标签，帮助 Worker 理解领域边界 | | `verify` | ✅ | 验收命令，Exit Code 0 = 通过。**没有这个字段，任务不合法** | | `context_files` | ✅ | Worker 允许加载的文件白名单，防止上下文爆炸 | | `guard_files` | 推荐 | 禁止修改的文件列表，硬约束 | | `estimate` | 推荐 | 预估耗时，用于 Tick 调度决策 | | `retries` | 自动 | 由 Tick Worker 自动递增，Architect 可重置 | **任务状态标记：** | 标记 | 含义 | |------|------| | `[ ]` | 待执行 | | `[x]` | 已完成（verify 通过） | | `[!]` | 已阻塞（超过 max_retries） | | `[~]` | 执行中（Tick Worker 正在处理，防止并发冲突） | | `[-]` | 已跳过（Architect 主动标记为不需要） | **Phase 级元数据：** | 字段 | 说明 | |------|------| | `parallel: true/false` | 该 Phase 内的任务是否可并发执行 | | `depends: Phase X` / `none` | Phase 级前置依赖 | ### 3.2 PROJECT_MAP.md — 项目认知地图 > Worker 的 GPS。不读全部源码，先读地图，再按 `context_files` 精准加载。 ```markdown # PROJECT MAP: <ProjectName> ## Architecture Overview Single-page game using Canvas API. No framework. Vanilla TypeScript. ## Module Registry ### [MODULE:database] - Purpose: PostgreSQL connection and schema management - Entry: src/db/index.ts - Key interfaces: `DbConnection`, `UserRecord`, `SessionRecord` - Notes: Uses connection pooling via pg-pool ### [MODULE:auth] - Purpose: JWT-based authentication - Entry: src/auth/index.ts - Key interfaces: `AuthToken`, `AuthMiddleware` - Dependencies: [MODULE:database] - Notes: Tokens expire in 24h, refresh flow not yet implemented ### [MODULE:routes] - Purpose: Express route handlers - Entry: src/routes/index.ts - Dependencies: [MODULE:auth], [MODULE:database] ## File Tree (auto-maintained) <!-- Architect 应在项目结构变动时更新此区块 --> src/ ├── db/ │ ├── index.ts # DB connection pool │ ├── schema.ts # Table definitions │ └── migrations/ # SQL migration files ├── auth/ │ ├── index.ts # Auth module entry │ ├── jwt.ts # Token generation/validation │ └── middleware.ts # Express middleware └── routes/ ├── index.ts # Route registry └── users.ts # User CRUD endpoints ## Conventions - All tests in `tests/` mirror `src/` structure - Config via environment variables (see .env.example) - Error handling: all async handlers wrapped in try/catch, errors go to src/utils/errors.ts ``` **维护规则：** - Architect 在创建/调整计划时同步更新 - Tick Worker **只读不写** PROJECT_MAP.md - 如果 Worker 发现 MAP 与实际不符，在 TICK_STATUS.md 中报告，由 Architect 修正 ### 3.3 TICK_STATUS.md — 执行状态流水账 ```markdown # TICK STATUS LOG --- ## [2025-01-15T14:35:00] Tick #012 - **Task**: T-101 [MODULE:database] Setup PostgreSQL schema - **Status**: ✅ SUCCESS - **Verify Output**: `PASS` (exit code 0) - **Duration**: 2m18s - **Files Modified**: src/db/schema.ts (+45 -0), src/db/migrations/001_init.sql (+23 -0) - **Diff Size**: 68 lines - **Git Commit**: `a3f7b2c` — "memento: complete T-101 database schema setup" --- ## [2025-01-15T14:35:00] Tick #012 (continued, tasks_this_tick: 2/2) - **Task**: T-102 [MODULE:auth] Implement JWT token generation - **Status**: ✅ SUCCESS - **Verify Output**: `PASS` (exit code 0) - **Duration**: 3m41s - **Files Modified**: src/auth/jwt.ts (+67 -0), tests/auth/jwt.test.ts (+34 -0) - **Diff Size**: 101 lines - **Git Commit**: `b8e2d1f` — "memento: complete T-102 JWT token generation" --- ## [2025-01-15T14:40:00] Tick #013 - **Task**: T-201 [MODULE:auth] Connect auth middleware to database - **Status**: ❌ FAILED (retry 2/3) - **Verify Output**: `TypeError: pool.query is not a function` (exit code 1) - **Duration**: 4m52s - **Error Analysis**: DB module exports `pool` but middleware imports `connection`. Interface mismatch. - **Files Modified**: (rolled back) - **Git Commit**: (none — rollback) --- ## [2025-01-15T14:45:00] Tick #014 - **Task**: T-201 [MODULE:auth] Connect auth middleware to database - **Status**: 🚫 BLOCKED (retry 3/3 — max_retries exceeded) - **Verify Output**: Same error as Tick #013 - **Error Analysis**: Recurring interface mismatch. Likely needs Architect to update MODULE:database exports or redefine task scope. - **Escalation**: ⚠️ NEEDS ARCHITECT ATTENTION - **Files Modified**: (rolled back) --- ``` ### 3.4 HUMAN_NOTES.md — 人类批注通道 > Dashboard 面板写入此文件。Tick Worker 每次启动时检查。Architect 也会读取。 ```markdown # HUMAN NOTES <!-- 格式：每条批注带时间戳和目标（global / 具体 Task ID） --> <!-- Worker 执行完相关批注后，将 [NOTE] 改为 [NOTE:READ] --> <!-- Architect 处理完后可归档到底部的 Archive 区 --> ## Active Notes ### [NOTE] 2025-01-15T15:00:00 → T-201 改用 Redis 做 session 存储而不是 PostgreSQL。连接配置参考项目根目录的 redis.conf。 ### [NOTE] 2025-01-15T15:10:00 → global 暂停 Phase 3 的所有任务，等 Phase 2 全部稳定再说。 ### [NOTE:READ] 2025-01-15T14:00:00 → T-102 JWT secret 从环境变量 `JWT_SECRET` 读取，别硬编码。 --- ## Archive <!-- Architect 把已处理的批注移到这里 --> ``` --- ## 四、Tick 调度引擎规范 ### 4.1 任务拾取算法 Tick Worker 醒来后执行以下逻辑： ``` 1. 读取 MASTER_PLAN.md 的 Meta 区 - 如果 tick_mode != "auto"，写一行 "Tick skipped: mode={mode}" 到 TICK_STATUS.md，退出 2. 读取 HUMAN_NOTES.md - 缓存所有 [NOTE]（非 [NOTE:READ]）条目，按 target 分组备用 3. 按 Phase 顺序扫描： FOR each Phase: a. 检查 depends 条件 - 依赖的 Phase 内是否所有任务都是 [x] 或 [-]？ - 如果有 [ ] 或 [~] 或 [!]，则该 Phase 不可进入，跳过 b. 在当前 Phase 内扫描任务： - 跳过 [x] [!] [-] [~] - 对于 [ ]：检查 retries < max_retries - 如果 parallel: false，只取第一个符合条件的 [ ] - 如果 parallel: true，取第一个符合条件的 [ ]（单 Worker 场景） c. 找到目标任务后，break 4. 如果没有找到任何可执行任务： - 检查是否所有任务都是 [x] 或 [-] → 写 "🎉 ALL TASKS COMPLETE" 到 TICK_STATUS.md - 检查是否存在 [!] 阻塞 → 写 "⚠️ PIPELINE BLOCKED" 到 TICK_STATUS.md - 退出 5. 将目标任务标记为 [~]（执行中） 6. 执行任务（详见 4.2） 7. tasks_completed_this_tick++ 如果 tasks_completed_this_tick < max_tasks_per_tick 且剩余任务 estimate 合理： 回到步骤 3 继续拾取 否则退出 ``` ### 4.2 单任务执行流程 ``` 1. 读取任务的 context_files 列表 - 通过 PROJECT_MAP.md 理解模块上下文 - 加载 context_files 中声明的文件内容 - 检查是否有针对该 Task ID 的 HUMAN_NOTES，如有，纳入上下文 2. 执行实际工作 - 遵循铁血纪律（见第五节） - 生成精确 diff，不做全文件覆写 3. 运行 guard_files 检查 - diff 中是否触及了 guard_files 列表中的文件？ - 如果是 → 自动回滚 → 标记失败 → 原因写 "guard file violation" 4. 运行 diff size 检查 - 单次修改是否超过 200 行？（可配置） - 如果是 → 自动回滚 → 标记失败 → 原因写 "diff too large, possible full-file rewrite" 5. 运行 verify 命令 - 捕获 stdout/stderr 和 exit code - Exit Code 0 → SUCCESS - Exit Code != 0 → FAILED 6. 写结果到 TICK_STATUS.md 7. 如果 SUCCESS： - 任务标记 [ ] → [x] - retries 保持不变 - git add + git commit（message 格式：`memento: complete {TASK_ID} {简述}`） 8. 如果 FAILED： - 回滚所有文件修改（git checkout 或备份恢复） - retries += 1 - 任务保持 [ ]，清除 [~] - 如果 retries >= max_retries： - 标记 [!] - TICK_STATUS 中添加 "⚠️ NEEDS ARCHITECT ATTENTION" ``` ### 4.3 并发安全 当 parallel Phase 中可能有多个 Worker 并行时（高级场景）： - `[~]` 标记充当简易锁 —— Worker 拾取任务时先标 `[~]`，其他 Worker 看到 `[~]` 就跳过 - 如果检测到 `[~]` 标记超过 15 分钟未更新（Worker 可能崩溃），将其重置为 `[ ]` - 在 MVP 阶段，建议单 Worker 串行执行，并发作为未来扩展 --- ## 五、铁血纪律 (Execution Sandbox) 作为一个被 Memento 唤醒的 Tick Worker，你**必须**遵循： ### 纪律 1：防爆底线 (Surgical Edits Only) - ❌ 严禁输出完整文件内容要求覆写 - ✅ 必须通过精准定位工具进行增量修改 - 硬约束：diff size guard 会物理阻断超大修改 ### 纪律 2：拒绝脑内验算 (Evidence-Based Audit) - ❌ 不许在脑中模拟运行然后宣称"应该没问题" - ✅ 跑 verify 命令看真实退出码 - 没有 `Exit Code 0`，不许标 `[x]` ### 纪律 3：不要静默空转 (No Silent Ghosting) - ❌ 遇到问题不许沉默退出 - ✅ 把死亡原因、错误日志、分析完整写入 `TICK_STATUS.md` - 卡死了就大声喊出来，让 Architect 看到 ### 纪律 4：恪守边界 (Stay in Your Lane) - ❌ 不许修改 guard_files 中的文件 - ❌ 不许修改 MASTER_PLAN.md 的任务定义（只能改 checkbox 状态和 retries） - ❌ 不许修改 PROJECT_MAP.md - ✅ 只能读写 context_files 中声明的文件 + TICK_STATUS.md ### 纪律 5：原子提交 (Atomic Commits) - 每完成一个任务，立即 `git commit` - 每失败一个任务，立即 `git checkout` 回滚 - 确保任意时刻 `git log` 都是干净的、可追溯的 --- ## 六、Dashboard 面板设计 ### 6.1 设计理念 Dashboard 是人类与 Memento 流水线之间的**异步交互界面**。不是实时聊天，而是**留言板 + 监控台**。人类不需要一直盯着，但打开就能在 5 秒内知道一切。 ### 6.2 面板布局 ``` ┌─────────────────────────────────────────────────────────────┐ │ 🧠 Agent Memento Dashboard [ProjectName] │ │ Status: ● RUNNING Uptime: 2h 35m Next tick: 2m 14s │ │ ┌──────────────────┐ ┌──────────────────────────────────┐ │ │ │ Controls │ │ Progress │ │ │ │ │ │ │ │ │ │ [▶ Resume] │ │ ████████████░░░░░░░░░ 23/47 │ │ │ │ [⏸ Pause ] │ │ Phase 1 ████████████ 100% │ │ │ │ [⏹ Stop ] │ │ Phase 2 ████████░░░░ 67% │ │ │ │ │ │ Phase 3 ░░░░░░░░░░░░ 0% │ │ │ │ Tick interval: │ │ │ │ │ │ [5] min ▼ │ │ Blocked: 2 ⚠️ │ │ │ │ │ │ Est. remaining: ~1h 20m │ │ │ └──────────────────┘ └──────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────┤ │ │ Task List Filter: All │ │ │ │ │ │ ✅ T-101 [database] Setup PostgreSQL schema 2m18s │ │ │ ✅ T-102 [auth] JWT token generation 3m41s │ │ │ 🚫 T-201 [auth] Connect auth to DB BLOCKED │ │ │ └─ retries: 3/3 · "Interface mismatch" │ │ │ └─ 💬 [Add Note] │ │ │ ⬜ T-202 [auth] Password hashing waiting │ │ │ ⬜ T-301 [docs] Generate API docs Phase 3 │ │ │ │ │ └──────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────────────────────────────────────────────┤ │ │ Tick Timeline Latest first │ │ │ │ │ │ 14:45 Tick #014 · T-201 · 🚫 BLOCKED │ │ │ │ "Interface mismatch — needs Architect attention" │ │ │ │ [View Full Log] │ │ │ │ │ │ │ 14:40 Tick #013 · T-201 · ❌ FAILED (retry 2/3) │ │ │ │ "TypeError: pool.query is not a function" │ │ │ │ [View Full Log] │ │ │ │ │ │ │ 14:35 Tick #012 · T-101 + T-102 · ✅✅ │ │ │ │ 2 tasks completed in 5m59s │ │ │ │ [View Full Log] [View Diff] │ │ │ │ │ └──────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────────────────────────────────────────────┤ │ │ 📝 Notes │ │ │ │ │ │ ┌─────────────────────────────────────────────────────┐ │ │ │ │ Target: [T-201 ▼] or [global ▼] │ │ │ │ │ │ │ │ │ │ 改用 Redis 做 session 存储，连接配置见 redis.conf │ │ │ │ │ │ │ │ │ │ [Send Note 📤] │ │ │ │ └─────────────────────────────────────────────────────┘ │ │ │ │ │ │ Active Notes: │ │ │ • 15:10 → global: "暂停 Phase 3..." ⏳ pending │ │ │ • 15:00 → T-201: "改用 Redis..." ⏳ pending │ │ │ • 14:00 → T-102: "JWT_SECRET 环境变量..." ✅ read │ │ │ │ │ └──────────────────────────────────────────────────────────┘ └─────────────────────────────────────────────────────────────┘ ``` ### 6.3 面板功能规范 #### 控制区 (Controls) | 操作 | 行为 | |------|------| | Resume | 将 `MASTER_PLAN.md` 的 `tick_mode` 改为 `auto` | | Pause | 将 `tick_mode` 改为 `paused`（当前 Tick 执行完后停止） | | Stop | 将 `tick_mode` 改为 `stopped`（建议同时移除 crontab） | | Tick interval | 修改 crontab 的执行频率 | #### 进度区 (Progress) - 数据源：解析 `MASTER_PLAN.md` 的所有 checkbox 状态 - 实时计算各 Phase 完成百分比 - 基于已完成任务的平均耗时 × 剩余任务数，估算剩余时间 #### 任务列表 (Task List) - 数据源：`MASTER_PLAN.md` - 每个任务可展开查看：最近一次执行结果、错误信息、重试次数 - 支持过滤：All / Pending / Completed / Blocked - 每个任务旁有 `[Add Note]` 按钮，快速针对该任务添加批注 - 支持手动操作： - 对 `[!]` 任务点击 `[Reset Retries]` → 将 retries 重置为 0，状态改回 `[ ]` - 对任务点击 `[Skip]` → 标记为 `[-]` #### 时间线 (Tick Timeline) - 数据源：`TICK_STATUS.md` - 倒序展示每个 Tick 的执行摘要 - 可展开查看完整日志（链接到 `logs/tick_*.log`） - 可查看该 Tick 的 Git diff #### 批注区 (Notes) - 写入目标：`HUMAN_NOTES.md` - 支持选择 target（global 或具体 Task ID） - 显示所有 Active Notes 及其状态（pending / read） - Read 后的 notes 自动折叠但不删除 ### 6.4 面板技术建议 - **轻量优先**：纯静态页面 + 文件系统轮询（每 5~10s 读取 Markdown 文件）即可 - 数据层：直接 parse Markdown 文件，不需要数据库 - 可选方案 A：本地 HTTP server（Python/Node），serve 一个 SPA，通过 API 读写 Markdown 文件 - 可选方案 B：Terminal UI（blessed/ink），不离开终端 --- ## 七、错误恢复与自愈机制 ### 7.1 单任务失败 → 自动重试 ``` 失败 → retries++ → 保持 [ ] → 下个 Tick 重试 ↓ retries >= max_retries ↓ 标记 [!] → 写入 TICK_STATUS "NEEDS ARCHITECT ATTENTION" ↓ 跳过该任务，继续执行后续可执行任务 ``` ### 7.2 Phase 阻塞 → 智能跳转 ``` Phase 2 中 T-201 被标记 [!] ↓ Phase 2 depends 未完全满足（存在非 [x]/[-] 的任务） ↓ Phase 3 无法启动 ↓ 如果 Phase 2 中还有其他 [ ] 任务 → 继续执行它们 如果 Phase 2 所有任务都是 [x]/[-]/[!] → 整条流水线 BLOCKED ↓ TICK_STATUS: "⚠️ PIPELINE BLOCKED — Phase 2 has unresolved [!] tasks" ``` ### 7.3 Worker 崩溃 → 防腐检测 - 如果 `[~]` 标记存在超过 15 分钟（可配置），下一个 Tick Worker 将： - 重置该任务为 `[ ]` - 在 TICK_STATUS 中记录 "Stale [~] detected on {TASK_ID}, reset to [ ]" - 如果存在未提交的文件修改，执行 `git checkout` 清理 ### 7.4 全局熔断 在以下情况下自动暂停流水线（`tick_mode → paused`）： - 连续 5 个 Tick 全部失败（无一次 SUCCESS） - 阻塞任务数超过总任务数的 30% - 磁盘空间不足 / git 操作异常 在 TICK_STATUS 中写入：`🔴 CIRCUIT BREAKER TRIGGERED — reason: {reason}` --- ## 八、Architect 工作规范 当 Main Agent 处于 Architect 态时（与人类直接对话的 Session 中），遵循以下规范： ### 8.1 创建计划 1. 与人类讨论项目需求，理解全貌 2. 设计模块划分，写入 `PROJECT_MAP.md` 3. 将需求分解为原子任务，写入 `MASTER_PLAN.md` 4. 每个任务必须有 `verify` 命令 —— **没有验证命令的任务不配存在** 5. 合理划分 Phase，声明 parallel 和 depends ### 8.2 监控与调整 1. 定期读取 `TICK_STATUS.md`（可由人类触发，或在对话中主动查看） 2. 对于 `[!]` 阻塞任务： - 分析失败原因 - 修改任务定义（调整 verify、context_files、拆分子任务） - 或修改 PROJECT_MAP（更新接口定义） - 重置 retries 为 0，状态改回 `[ ]` 3. 对于 `HUMAN_NOTES.md` 中的批注： - 读取并理解 - 将批注转化为 MASTER_PLAN 的具体修改 - 处理完后归档 ### 8.3 计划变更原则 - 新增任务：追加到合适的 Phase，保持 ID 唯一 - 删除任务：标记 `[-]` 并注释原因，不要真的删掉行 - 拆分任务：将原任务标记 `[-] (拆分为 T-XXX, T-XXY)`，新增子任务 - 重排 Phase：更新 depends 关系，确保 DAG 无环 --- ## 九、初始化与部署 ### 9.1 初始化命令 ```bash bash skills/agent-memento/scripts/init_memento.sh <ProjectName> ``` 该脚本执行： 1. 在项目目录下创建 `docs/` 目录 2. 生成 `MASTER_PLAN.md` 模板（含 Meta 区和示例 Phase） 3. 生成 `PROJECT_MAP.md` 模板 4. 生成 `TICK_STATUS.md`（空） 5. 生成 `HUMAN_NOTES.md`（空） 6. 创建 `logs/` 目录 7. 生成 `scripts/memento_tick.sh` —— Tick Worker 的入口脚本 8. 生成 `.memento_ignore`（排除 `node_modules/`, `.git/`, `logs/` 等） 9. 生成 `scripts/tick_worker_system_prompt.md` —— 注入给 Worker 的全套纪律法则和 Output 规范。 10. 生成 `.memento_cleanignore`（保护 `node_modules/`, `.env`, `vendor/` 等） 11. 输出提示：“请将以下行添加到 crontab 以启动自动执行” ### 9.1.1 Tick Worker System Prompt 模板 (tick_worker_system_prompt.md) 以下是 `init_memento.sh` 应生成的 `scripts/tick_worker_system_prompt.md` 的完整内容： ```markdown # Memento Tick Worker — System Prompt You are a Memento Tick Worker: a short-lived, stateless, disciplined execution agent. You have no memory of previous ticks. You start fresh every time. ## Your Lifecycle (execute in this exact order) 1. Read `docs/MASTER_PLAN.md`. Parse the Meta section for configuration. 2. Read `docs/HUMAN_NOTES.md`. Note any `[NOTE]` entries (ignore `[NOTE:READ]`). 3. Scan Phases in order. For each Phase: - Check `depends`: all tasks in depended Phase must be `[x]` or `[-]`. - Find the first task marked `[ ]` with `retries < max_retries`. 4. If no executable task found: - If all tasks are `[x]`/`[-]`: write "🎉 ALL TASKS COMPLETE" to TICK_STATUS.md. - If any `[!]` exists: write "⚠️ PIPELINE BLOCKED" to TICK_STATUS.md. - Exit. 5. Mark the target task `[~]` in MASTER_PLAN.md. 6. Read `docs/PROJECT_MAP.md` for module context. 7. Load ONLY the files listed in the task's `context_files`. 8. If there are `[NOTE]` entries targeting this task ID or `global`, incorporate them. 9. Perform the work using surgical, targeted edits. NEVER output a full file. 10. Verify: - Check: did you modify any file listed in `guard_files`? If yes → rollback → fail. - Check: is your total diff > `max_diff_lines`? If yes → rollback → fail. - Run the task's `verify` command. Capture exit code, stdout, stderr. 11. Write a TICK_STATUS.md entry (format below). 12. If verify exit code == 0: - Mark task `[x]`. Run `git add -A && git commit -m "memento: complete {TASK_ID} {description}"`. - If `tasks_completed_this_tick < max_tasks_per_tick`, go to step 3 for next task. 13. If verify exit code != 0: - Rollback: `git checkout -- .` - Increment `retries` in MASTER_PLAN.md. - If `retries >= max_retries`: mark task `[!]`, add "⚠️ NEEDS ARCHITECT ATTENTION" to status. - Clear `[~]` back to `[ ]` (or `[!]`). 14. Exit. ## TICK_STATUS.md Entry Format ## [{timestamp}] Tick #{tick_number} - **Task**: {TASK_ID} [MODULE:{module}] {description} - **Status**: ✅ SUCCESS | ❌ FAILED (retry {n}/{max}) | 🚫 BLOCKED - **Verify Output**: {first 5 lines of stdout/stderr} (exit code {n}) - **Duration**: {time} - **Error Analysis**: {your diagnosis of what went wrong — FAILED/BLOCKED only} - **Files Modified**: {file (+lines -lines)} | (rolled back) - **Diff Size**: {total lines changed} - **Git Commit**: {hash} — "{message}" | (none — rollback) - **Outputs**: {key interfaces/exports created — SUCCESS only, optional but encouraged} ## Iron Disciplines (violation = immediate failure) 1. **SURGICAL EDITS ONLY**: Never output a complete file. Use precise, targeted modifications. 2. **EVIDENCE-BASED**: Run `verify`. No exit code 0 = no `[x]`. No exceptions. 3. **NO SILENT GHOSTING**: If stuck, write full error + analysis to TICK_STATUS.md. Never exit silently. 4. **STAY IN YOUR LANE**: Only modify files in `context_files`. Never touch `guard_files`. Never edit task definitions in MASTER_PLAN.md (only checkbox state + retries). Never edit PROJECT_MAP.md. 5. **ATOMIC COMMITS**: `git commit` on success. `git checkout` on failure. Always. ## What You Are NOT - You are NOT an architect. Do not redesign, re-plan, or question the task definition. - You are NOT creative. Execute exactly what is specified. - You are NOT persistent. After this tick, you will cease to exist. ``` ### 9.2 Tick 入口脚本模板 (memento_tick.sh) ```bash #!/usr/bin/env bash set -euo pipefail PROJECT_DIR="$(cd "$(dirname "$0")/.." && pwd)" PLAN="$PROJECT_DIR/docs/MASTER_PLAN.md" STATUS="$PROJECT_DIR/docs/TICK_STATUS.md" LOG_DIR="$PROJECT_DIR/logs" TIMESTAMP=$(date +%Y-%m-%dT%H:%M:%S) TICK_LOG="$LOG_DIR/tick_${TIMESTAMP}.log" # 防撞车：确保同一时间只有一个 Tick Worker 运行 LOCK_FILE="$PROJECT_DIR/.memento.lock" exec 200>"$LOCK_FILE" if ! flock -n 200; then echo "[$TIMESTAMP] Tick skipped: previous tick still running" >> "$STATUS" exit 0 fi # 检查 tick_mode TICK_MODE=$(grep -oP 'tick_mode:\s*\K\w+' "$PLAN" || echo "stopped") if [[ "$TICK_MODE" != "auto" ]]; then echo "[$TIMESTAMP] Tick skipped: mode=$TICK_MODE" >> "$STATUS" exit 0 fi # 调用 LLM Agent 执行 Tick SYSTEM_PROMPT="$(cat "$PROJECT_DIR/scripts/tick_worker_system_prompt.md")" openclaw agent \ --system-prompt "$SYSTEM_PROMPT" \ --prompt "Read $PLAN, find the first executable task, complete it following the Memento Tick Worker protocol. Write results to $STATUS." \ --context-files "$PLAN" "$PROJECT_DIR/docs/PROJECT_MAP.md" "$PROJECT_DIR/docs/HUMAN_NOTES.md" \ 2>&1 | tee "$TICK_LOG" # 后处理：三阶段防爆清理 cd "$PROJECT_DIR" if [[ -n $(git status --porcelain) ]]; then echo "[$TIMESTAMP] WARNING: Dirty workspace detected. Running 3-phase cleanup." >> "$STATUS" # Phase 1: 恢复已追踪文件 git checkout -- . # Phase 2: 清理未追踪文件（排除保护列表） if [[ -f ".memento_cleanignore" ]]; then git clean -fd --exclude-from=.memento_cleanignore else git clean -fd fi # Phase 3: 兜底——如果还是脏的，紧急 stash if [[ -n $(git status --porcelain) ]]; then git stash --include-untracked -m "memento-emergency-stash-$TIMESTAMP" echo "[$TIMESTAMP] CRITICAL: Emergency stash created. Manual inspection required." >> "$STATUS" fi fi # 日志轮转 MAX_ENTRIES=$(grep -oP 'status_max_entries:\s*\K\d+' "$PLAN" || echo "50") CURRENT_ENTRIES=$(grep -c '^\## \[' "$STATUS" || true) if [[ $CURRENT_ENTRIES -gt $MAX_ENTRIES ]]; then ARCHIVE_DIR="$PROJECT_DIR/logs/status_archive" mkdir -p "$ARCHIVE_DIR" mv "$STATUS" "$ARCHIVE_DIR/TICK_STATUS_$(date +%Y%m%d_%H%M%S).md" echo "# TICK STATUS LOG" > "$STATUS" echo "" >> "$STATUS" echo "<!-- Rotated at $TIMESTAMP. Previous entries archived. -->" >> "$STATUS" fi # 告警检测 BLOCKED_COUNT=$(grep -c '\[!\]' "$PLAN" || true) CIRCUIT_BROKEN=$(grep -c 'CIRCUIT BREAKER' "$STATUS" || true) if [[ $BLOCKED_COUNT -gt 0 || $CIRCUIT_BROKEN -gt 0 ]]; then cat > "$PROJECT_DIR/.memento_alert" << EOF_INNER timestamp: $TIMESTAMP blocked_tasks: $BLOCKED_COUNT circuit_breaker: $([[ $CIRCUIT_BROKEN -gt 0 ]] && echo "TRIGGERED" || echo "OK") message: Pipeline needs attention. $BLOCKED_COUNT task(s) blocked. EOF_INNER fi # 如果一切正常且之前有告警，清除告警 if [[ $BLOCKED_COUNT -eq 0 && $CIRCUIT_BROKEN -eq 0 && -f "$PROJECT_DIR/.memento_alert" ]]; then rm -f "$PROJECT_DIR/.memento_alert" fi ``` ### 9.3 Cron 配置 ```bash # 每 5 分钟执行一次 */5 * * * * /path/to/project/scripts/memento_tick.sh >> /path/to/project/logs/cron.log 2>&1 ``` --- ## 十、完整工作流示例 ``` 人类："我想做一个带用户系统的 REST API" │ ▼ Architect（主 Session）： ├─ 与人类讨论确认：PostgreSQL + JWT + Express ├─ 写入 PROJECT_MAP.md（模块划分） ├─ 写入 MASTER_PLAN.md（15 个任务，3 个 Phase） └─ "计划已就绪，运行 init 脚本后添加 crontab 即可启动" │ ▼ 人类：添加 crontab，开始刷手机 │ ▼ Tick #001 → T-101 数据库初始化 → ✅ Tick #001 → T-102 JWT 模块 → ✅ （同一 Tick 内连续完成 2 个快任务） Tick #002 → T-103 密码哈希 → ✅ Tick #003 → T-201 连接中间件 → ❌ (retry 1/3) Tick #004 → T-201 → ❌ (retry 2/3) Tick #005 → T-201 → 🚫 BLOCKED │ ▼ 人类打开 Dashboard，看到 T-201 阻塞 ├─ 在 Notes 区写："别用 pg-pool 了，直接用 prisma" └─ 继续刷手机 │ ▼ Architect（读取 HUMAN_NOTES + TICK_STATUS）： ├─ 更新 PROJECT_MAP.md（MODULE:database 改为 Prisma） ├─ 修改 T-201 的 context_files 和 verify ├─ 新增 T-105 "安装并配置 Prisma"（插入 Phase 1） ├─ 重置 T-201 retries → 0，状态 [!] → [ ] └─ 归档 HUMAN_NOTES 中的批注 │ ▼ Tick #006 → T-105 安装 Prisma → ✅ Tick #007 → T-201 连接中间件（Prisma 版）→ ✅ Tick #008 → T-202 ... → ✅ │ ... 持续推进 ... │ ▼ Tick #031 → 🎉 ALL TASKS COMPLETE │ ▼ 人类打开 Dashboard："哦，做完了。" 移除 crontab。 ``` --- ## Security & Transparency ### Data Access — Exactly What Is Read - Reads `<project-dir>/docs/MASTER_PLAN.md` to determine the current task - Reads `<project-dir>/docs/PROJECT_MAP.md` for project structure awareness - Reads `<project-dir>/docs/HUMAN_NOTES.md` for human annotations - Reads source code files listed in each task's `context_files` only ### Data Written - Creates project scaffolding (`MASTER_PLAN.md`, `PROJECT_MAP.md`, `TICK_STATUS.md`, `HUMAN_NOTES.md`, `memento_tick.sh`) - Updates checkbox states in `MASTER_PLAN.md` (Tick Worker: only `[ ]`↔`[x]`/`[!]`/`[~]`) - Edits source files within the target project directory, limited to declared `context_files` - Writes execution logs to `logs/tick_*.log` - Creates git commits for successful task completions ### Hard Safety Guards - **Diff size limit**: Rejects changes > 200 lines per task (configurable) - **Guard files**: Physically prevents modification of declared protected files - **Auto-rollback**: Failed tasks are rolled back via `git checkout` - **Circuit breaker**: Auto-pauses pipeline on sustained failures ### Persistence & Autonomous Scheduling - The `init_memento.sh` script generates a bash script intended to be run via `cron` - The user must manually add this to their crontab to enable autonomous execution - Stop at any time by removing the crontab entry or setting `tick_mode: stopped` ### Credentials - Operates entirely locally - Relies on `openclaw agent` with the system's existing LLM configurations - No new keys are requested or stored ### Network Access - No outbound network access by framework scripts - Network access may occur only when user-defined `verify` commands require it (e.g., `npm install`) ``` --- ## 附录：文件结构总览 ``` <project>/ ├── docs/ │ ├── MASTER_PLAN.md # 唯一真相源 │ ├── PROJECT_MAP.md # 项目认知地图 │ ├── TICK_STATUS.md # 执行状态流水账 │ └── HUMAN_NOTES.md # 人类批注通道 ├── logs/ │ ├── cron.log # cron 调度日志 │ ├── tick_2025-01-15T14:35:00.log │ └── tick_2025-01-15T14:40:00.log ├── scripts/ │ └── memento_tick.sh # Tick Worker 入口 ├── .memento_ignore # 上下文排除规则 └── src/ # 实际项目代码 └── ... ```


Security scan verdicts — ClawScan: suspicious | static analysis: suspicious | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)