@simonyea/holysheep-cli 2.1.49 → 2.1.51

package/dist/aionui-resources/assistant/planning-with-files/planning-with-files.zh-CN.md

@@ -0,0 +1,395 @@
+# Planning with Files - Manus 风格文件规划
+
+像 Manus（Meta 以 20 亿美元收购的 AI Agent）一样工作：使用持久化的 Markdown 文件作为"磁盘上的工作记忆"。
+
+## 核心原则
+
+```
+上下文窗口 = RAM（易失、有限）
+文件系统 = 磁盘（持久化、无限）
+
+→ 所有重要信息都写入磁盘。
+```
+
+## 3 文件模式
+
+对于每个复杂任务，在项目目录中创建三个文件：
+
+```
+task_plan.md      → 跟踪阶段和进度
+findings.md       → 存储研究和发现
+progress.md       → 会话日志和测试结果
+```
+
+**模板文件位置：** `assistant/planning-with-files/templates/`
+
+## 何时使用此模式
+
+**适用于：**
+
+- 多步骤任务（3+ 步骤）
+- 研究型任务
+- 构建/创建项目
+- 需要多次工具调用的任务
+- 任何需要组织的任务
+
+**不适用于：**
+
+- 简单问题
+- 单文件编辑
+- 快速查询
+
+## 关键时机规则
+
+这些规则模拟 hooks 以确保正确的工作流程：
+
+### 📌 任务开始时（SessionStart）
+
+**必须**在任何其他工作之前首先创建所有三个文件：
+
+1. 使用模板创建 `task_plan.md`
+2. 使用模板创建 `findings.md`
+3. 使用模板创建 `progress.md`
+4. 填写 task_plan.md 中的目标部分
+
+**原因：** 没有规划文件，在 50+ 次工具调用后你会忘记目标。
+
+### 📌 重大决策前（PreToolUse）
+
+**必须**在以下操作前重新阅读 `task_plan.md`：
+
+- 写入或编辑文件
+- 执行命令
+- 做架构决策
+- 实现功能
+
+**如何操作：** 使用 Read 工具刷新上下文中的计划。
+
+**原因：** 这使目标在注意力窗口中保持新鲜（Manus 的"注意力操控"）。
+
+### 📌 文件操作后（PostToolUse）
+
+**必须**在以下操作后立即更新状态：
+
+- 写入文件
+- 编辑文件
+- 完成任务阶段
+
+**如何操作：** 编辑 task_plan.md 更新阶段状态：
+
+```markdown
+- **Status:** pending → in_progress → complete
+```
+
+**原因：** 跟踪进度，防止忘记已完成的工作。
+
+### 📌 任务结束前（Stop）
+
+**必须**验证完成度：
+
+- 检查所有阶段是否标记为 `complete`
+- 审查交付物部分
+- 确保没有未解决的错误
+
+**原因：** 防止任务未完成就提前结束。
+
+## 6 条关键规则
+
+### 1. 先创建计划
+
+绝不在没有 `task_plan.md` 的情况下开始复杂任务。这是不可协商的。
+
+```markdown
+## 目标
+
+[一句话描述最终状态]
+
+## 当前阶段
+
+Phase 1
+
+## 阶段
+
+### Phase 1: 需求和发现
+
+- [ ] 理解用户意图
+- [ ] 识别约束条件
+- **Status:** in_progress
+```
+
+### 2. 2-Action 规则
+
+> "每 2 次查看/浏览/搜索操作后，立即将关键发现保存到 findings.md。"
+
+这防止视觉/多模态信息丢失。
+
+```markdown
+## 视觉/浏览器发现
+
+- 截图显示登录表单有邮箱和密码字段
+- API 文档指示 JSON 响应格式
+```
+
+### 3. 决策前先读
+
+在重大决策前，读取计划文件。这使目标保持在注意力窗口中。
+
+```bash
+# 在实现功能前：
+Read 工具 → task_plan.md
+# 现在继续实现
+```
+
+### 4. 行动后更新
+
+完成任何阶段后：
+
+- 标记阶段状态：`pending` → `in_progress` → `complete`
+- 记录遇到的任何错误
+- 注明创建/修改的文件
+
+```markdown
+## 遇到的错误
+
+| 错误              | 尝试次数 | 解决方案     |
+| ----------------- | -------- | ------------ |
+| FileNotFoundError | 1        | 创建默认配置 |
+```
+
+### 5. 记录所有错误
+
+每个错误都记入计划文件。这建立知识库并防止重复。
+
+### 6. 永不重复失败
+
+```
+if 操作失败:
+    下一个操作 != 相同操作
+```
+
+跟踪你尝试过的方法。改变策略。
+
+## 3 次尝试错误协议
+
+```
+尝试 1：诊断和修复
+  → 仔细阅读错误
+  → 识别根本原因
+  → 应用针对性修复
+
+尝试 2：替代方法
+  → 相同错误？尝试不同方法
+  → 不同工具？不同库？
+  → 绝不重复完全相同的失败操作
+
+尝试 3：更广泛的重新思考
+  → 质疑假设
+  → 搜索解决方案
+  → 考虑更新计划
+
+3 次失败后：上报用户
+  → 解释你尝试了什么
+  → 分享具体错误
+  → 寻求指导
+```
+
+## 文件用途
+
+| 文件           | 用途               | 何时更新     |
+| -------------- | ------------------ | ------------ |
+| `task_plan.md` | 阶段、进度、决策   | 每个阶段后   |
+| `findings.md`  | 研究、发现         | 任何发现后   |
+| `progress.md`  | 会话日志、测试结果 | 整个会话期间 |
+
+## 读取 vs 写入决策矩阵
+
+| 情况           | 操作             | 原因                     |
+| -------------- | ---------------- | ------------------------ |
+| 刚写入文件     | 不要读取         | 内容仍在上下文中         |
+| 查看了图像/PDF | 立即写入发现     | 多模态 → 文本，避免丢失  |
+| 浏览器返回数据 | 写入文件         | 截图不会持久化           |
+| 开始新阶段     | 读取计划/发现    | 如果上下文过时则重新定向 |
+| 发生错误       | 读取相关文件     | 需要当前状态来修复       |
+| 间隔后恢复     | 读取所有规划文件 | 恢复状态                 |
+
+## 5 问题重启测试
+
+如果你能回答这些问题，说明你的上下文管理很好：
+
+| 问题           | 答案来源                  |
+| -------------- | ------------------------- |
+| 我在哪里？     | task_plan.md 中的当前阶段 |
+| 我要去哪里？   | 剩余阶段                  |
+| 目标是什么？   | 计划中的目标陈述          |
+| 我学到了什么？ | findings.md               |
+| 我做了什么？   | progress.md               |
+
+## 模板结构
+
+### task_plan.md 模板
+
+```markdown
+# 任务计划：[简要描述]
+
+## 目标
+
+[一句话描述最终状态]
+
+## 当前阶段
+
+Phase 1
+
+## 阶段
+
+### Phase 1: 需求和发现
+
+- [ ] 理解用户意图
+- [ ] 识别约束和需求
+- [ ] 在 findings.md 中记录发现
+- **Status:** in_progress
+
+### Phase 2: 规划和结构
+
+- [ ] 定义技术方法
+- [ ] 如需要则创建项目结构
+- [ ] 记录决策及理由
+- **Status:** pending
+
+### Phase 3: 实现
+
+- [ ] 逐步执行计划
+- [ ] 执行前先将代码写入文件
+- [ ] 增量测试
+- **Status:** pending
+
+### Phase 4: 测试和验证
+
+- [ ] 验证所有需求已满足
+- [ ] 在 progress.md 中记录测试结果
+- [ ] 修复发现的任何问题
+- **Status:** pending
+
+### Phase 5: 交付
+
+- [ ] 审查所有输出文件
+- [ ] 确保交付物完整
+- [ ] 交付给用户
+- **Status:** pending
+
+## 关键问题
+
+1. [要回答的问题]
+2. [要回答的问题]
+
+## 已做决策
+
+| 决策 | 理由 |
+| ---- | ---- |
+|      |      |
+
+## 遇到的错误
+
+| 错误 | 尝试次数 | 解决方案 |
+| ---- | -------- | -------- |
+|      | 1        |          |
+```
+
+### findings.md 模板
+
+```markdown
+# 发现和决策
+
+## 需求
+
+## <!-- 从用户请求中捕获 -->
+
+## 研究发现
+
+## <!-- 探索期间的关键发现 -->
+
+## 技术决策
+
+<!-- 已做决策及理由 -->
+
+| 决策 | 理由 |
+| ---- | ---- |
+|      |      |
+
+## 遇到的问题
+
+<!-- 错误及其解决方式 -->
+
+| 问题 | 解决方案 |
+| ---- | -------- |
+|      |          |
+
+## 资源
+
+## <!-- URL、文件路径、API 引用 -->
+
+## 视觉/浏览器发现
+
+## <!-- 关键：每 2 次查看/浏览操作后更新 -->
+```
+
+### progress.md 模板
+
+```markdown
+# 进度日志
+
+## 会话：[日期]
+
+### Phase 1: [标题]
+
+- **Status:** in_progress
+- **开始时间：** [时间戳]
+- ## 采取的行动：
+- ## 创建/修改的文件：
+
+## 测试结果
+
+| 测试 | 输入 | 预期 | 实际 | 状态 |
+| ---- | ---- | ---- | ---- | ---- |
+|      |      |      |      |      |
+
+## 错误日志
+
+| 时间戳 | 错误 | 尝试次数 | 解决方案 |
+| ------ | ---- | -------- | -------- |
+|        |      | 1        |          |
+
+## 5 问题重启检查
+
+| 问题           | 答案           |
+| -------------- | -------------- |
+| 我在哪里？     | Phase X        |
+| 我要去哪里？   | 剩余阶段       |
+| 目标是什么？   | [目标陈述]     |
+| 我学到了什么？ | 见 findings.md |
+| 我做了什么？   | 见上文         |
+```
+
+## 反模式
+
+| 不要做                | 应该做                 |
+| --------------------- | ---------------------- |
+| 使用 TodoWrite 持久化 | 创建 task_plan.md 文件 |
+| 陈述一次目标就忘记    | 决策前重新读取计划     |
+| 隐藏错误并静默重试    | 将错误记录到计划文件   |
+| 所有内容塞进上下文    | 将大内容存储在文件中   |
+| 立即开始执行          | 首先创建计划文件       |
+| 重复失败的操作        | 跟踪尝试，改变方法     |
+
+## Manus 原则
+
+| 原则             | 实现                     |
+| ---------------- | ------------------------ |
+| 文件系统作为内存 | 存储在文件中，而非上下文 |
+| 注意力操控       | 决策前重新读取计划       |
+| 错误持久化       | 在计划文件中记录失败     |
+| 目标跟踪         | 复选框显示进度           |
+| 完成验证         | 停止前检查所有阶段       |
+
+---
+
+**记住：** 你在前期收集并写入磁盘的上下文越多，执行就会越好。文件是你的持久化记忆。

package/dist/aionui-resources/assistant/planning-with-files/templates/findings.md

@@ -0,0 +1,106 @@
+# Findings & Decisions
+
+<!--
+  WHAT: Your knowledge base for the task. Stores everything you discover and decide.
+  WHY: Context windows are limited. This file is your "external memory" - persistent and unlimited.
+  WHEN: Update after ANY discovery, especially after 2 view/browser/search operations (2-Action Rule).
+-->
+
+## Requirements
+
+<!--
+  WHAT: What the user asked for, broken down into specific requirements.
+  WHY: Keeps requirements visible so you don't forget what you're building.
+  WHEN: Fill this in during Phase 1 (Requirements & Discovery).
+  EXAMPLE:
+    - Command-line interface
+    - Add tasks
+    - List all tasks
+    - Delete tasks
+    - Python implementation
+-->
+
+## <!-- Captured from user request -->
+
+## Research Findings
+
+<!--
+  WHAT: Key discoveries from web searches, documentation reading, or exploration.
+  WHY: Multimodal content (images, browser results) doesn't persist. Write it down immediately.
+  WHEN: After EVERY 2 view/browser/search operations, update this section (2-Action Rule).
+  EXAMPLE:
+    - Python's argparse module supports subcommands for clean CLI design
+    - JSON module handles file persistence easily
+    - Standard pattern: python script.py <command> [args]
+-->
+
+## <!-- Key discoveries during exploration -->
+
+## Technical Decisions
+
+<!--
+  WHAT: Architecture and implementation choices you've made, with reasoning.
+  WHY: You'll forget why you chose a technology or approach. This table preserves that knowledge.
+  WHEN: Update whenever you make a significant technical choice.
+  EXAMPLE:
+    | Use JSON for storage | Simple, human-readable, built-in Python support |
+    | argparse with subcommands | Clean CLI: python todo.py add "task" |
+-->
+<!-- Decisions made with rationale -->
+
+| Decision | Rationale |
+| -------- | --------- |
+|          |           |
+
+## Issues Encountered
+
+<!--
+  WHAT: Problems you ran into and how you solved them.
+  WHY: Similar to errors in task_plan.md, but focused on broader issues (not just code errors).
+  WHEN: Document when you encounter blockers or unexpected challenges.
+  EXAMPLE:
+    | Empty file causes JSONDecodeError | Added explicit empty file check before json.load() |
+-->
+<!-- Errors and how they were resolved -->
+
+| Issue | Resolution |
+| ----- | ---------- |
+|       |            |
+
+## Resources
+
+<!--
+  WHAT: URLs, file paths, API references, documentation links you've found useful.
+  WHY: Easy reference for later. Don't lose important links in context.
+  WHEN: Add as you discover useful resources.
+  EXAMPLE:
+    - Python argparse docs: https://docs.python.org/3/library/argparse.html
+    - Project structure: src/main.py, src/utils.py
+-->
+
+## <!-- URLs, file paths, API references -->
+
+## Visual/Browser Findings
+
+<!--
+  WHAT: Information you learned from viewing images, PDFs, or browser results.
+  WHY: CRITICAL - Visual/multimodal content doesn't persist in context. Must be captured as text.
+  WHEN: IMMEDIATELY after viewing images or browser results. Don't wait!
+  EXAMPLE:
+    - Screenshot shows login form has email and password fields
+    - Browser shows API returns JSON with "status" and "data" keys
+-->
+<!-- CRITICAL: Update after every 2 view/browser operations -->
+
+## <!-- Multimodal content must be captured as text immediately -->
+
+---
+
+<!--
+  REMINDER: The 2-Action Rule
+  After every 2 view/browser/search operations, you MUST update this file.
+  This prevents visual information from being lost when context resets.
+-->
+
+_Update this file after every 2 view/browser/search operations_
+_This prevents visual information from being lost_

package/dist/aionui-resources/assistant/planning-with-files/templates/progress.md

@@ -0,0 +1,126 @@
+# Progress Log
+
+<!--
+  WHAT: Your session log - a chronological record of what you did, when, and what happened.
+  WHY: Answers "What have I done?" in the 5-Question Reboot Test. Helps you resume after breaks.
+  WHEN: Update after completing each phase or encountering errors. More detailed than task_plan.md.
+-->
+
+## Session: [DATE]
+
+<!--
+  WHAT: The date of this work session.
+  WHY: Helps track when work happened, useful for resuming after time gaps.
+  EXAMPLE: 2026-01-15
+-->
+
+### Phase 1: [Title]
+
+<!--
+  WHAT: Detailed log of actions taken during this phase.
+  WHY: Provides context for what was done, making it easier to resume or debug.
+  WHEN: Update as you work through the phase, or at least when you complete it.
+-->
+
+- **Status:** in_progress
+- **Started:** [timestamp]
+<!--
+  STATUS: Same as task_plan.md (pending, in_progress, complete)
+  TIMESTAMP: When you started this phase (e.g., "2026-01-15 10:00")
+-->
+- Actions taken:
+  <!--
+    WHAT: List of specific actions you performed.
+    EXAMPLE:
+      - Created todo.py with basic structure
+      - Implemented add functionality
+      - Fixed FileNotFoundError
+  -->
+  -
+- Files created/modified:
+  <!--
+    WHAT: Which files you created or changed.
+    WHY: Quick reference for what was touched. Helps with debugging and review.
+    EXAMPLE:
+      - todo.py (created)
+      - todos.json (created by app)
+      - task_plan.md (updated)
+  -->
+  -
+
+### Phase 2: [Title]
+
+<!--
+  WHAT: Same structure as Phase 1, for the next phase.
+  WHY: Keep a separate log entry for each phase to track progress clearly.
+-->
+
+- **Status:** pending
+- ## Actions taken:
+- ## Files created/modified:
+
+## Test Results
+
+<!--
+  WHAT: Table of tests you ran, what you expected, what actually happened.
+  WHY: Documents verification of functionality. Helps catch regressions.
+  WHEN: Update as you test features, especially during Phase 4 (Testing & Verification).
+  EXAMPLE:
+    | Add task | python todo.py add "Buy milk" | Task added | Task added successfully | ✓ |
+    | List tasks | python todo.py list | Shows all tasks | Shows all tasks | ✓ |
+-->
+
+| Test | Input | Expected | Actual | Status |
+| ---- | ----- | -------- | ------ | ------ |
+|      |       |          |        |        |
+
+## Error Log
+
+<!--
+  WHAT: Detailed log of every error encountered, with timestamps and resolution attempts.
+  WHY: More detailed than task_plan.md's error table. Helps you learn from mistakes.
+  WHEN: Add immediately when an error occurs, even if you fix it quickly.
+  EXAMPLE:
+    | 2026-01-15 10:35 | FileNotFoundError | 1 | Added file existence check |
+    | 2026-01-15 10:37 | JSONDecodeError | 2 | Added empty file handling |
+-->
+<!-- Keep ALL errors - they help avoid repetition -->
+
+| Timestamp | Error | Attempt | Resolution |
+| --------- | ----- | ------- | ---------- |
+|           |       | 1       |            |
+
+## 5-Question Reboot Check
+
+<!--
+  WHAT: Five questions that verify your context is solid. If you can answer these, you're on track.
+  WHY: This is the "reboot test" - if you can answer all 5, you can resume work effectively.
+  WHEN: Update periodically, especially when resuming after a break or context reset.
+
+  THE 5 QUESTIONS:
+  1. Where am I? → Current phase in task_plan.md
+  2. Where am I going? → Remaining phases
+  3. What's the goal? → Goal statement in task_plan.md
+  4. What have I learned? → See findings.md
+  5. What have I done? → See progress.md (this file)
+-->
+<!-- If you can answer these, context is solid -->
+
+| Question             | Answer           |
+| -------------------- | ---------------- |
+| Where am I?          | Phase X          |
+| Where am I going?    | Remaining phases |
+| What's the goal?     | [goal statement] |
+| What have I learned? | See findings.md  |
+| What have I done?    | See above        |
+
+---
+
+<!--
+  REMINDER:
+  - Update after completing each phase or encountering errors
+  - Be detailed - this is your "what happened" log
+  - Include timestamps for errors to track when issues occurred
+-->
+
+_Update after completing each phase or encountering errors_