GenericAgent Framework

The frontends/desktop/packaging/ directory contains materials for desktop releases. Most files in this directory are for reference only and are not included in the final release package.

Only the contents of the scripts/ directory are consumed by the CI process (.github/workflows/desktop-release-package.yml). The CI copies the platform-specific installation and uninstallation scripts from scripts/ into the portable release artifacts for each platform.

Directory Structure:

• scripts/windows/: Contains install_windows.ps1, uninstall.bat, and uninstall_windows.ps1.
• scripts/linux/: Contains install_linux.sh and uninstall.sh.
• scripts/macos/: Contains install_macos.sh and uninstall.command.
• CHECKLIST.md and TODO.md: Functional testing checklists and platform testing plans (used by testers, not included in builds).

frontends/desktop/packaging/
├── README.md            # This documentation
├── CHECKLIST.md         # Pre-release functional test checklist
├── TODO.md              # Platform testing tasks and plans
└── scripts/             # ← ONLY content consumed by CI
    ├── windows/
    │   ├── install_windows.ps1     # Environment preparation
    │   ├── uninstall.bat           # Uninstallation entry point
    │   └── uninstall_windows.ps1
    ├── linux/
    │   ├── install_linux.sh
    │   └── uninstall.sh
    └── macos/
        ├── install_macos.sh
        └── uninstall.command

Morphling is a project-level capability absorption or replacement pattern. The goal is to take an existing target project, extract its objectives and test cases, and then decide whether to call, rewrite, or discard specific components. The final output (either the original agent or a new product) must match or exceed the target's performance on the same test cases.

The Core Triad

To execute Morphling, you must define three elements:

1. Target: What problem is being solved, who is it for, and what is its core value? This can be a full project or a deliverable subsystem of a larger project.
2. Tests: The benchmarks, demos, CI, leaderboards, or user task lists the target claims to pass. If no tests exist, you must first construct a minimal set of observable test cases.
3. Actions: For every component, you must decide whether to Call, Rewrite, or Discard. Avoid using "replicate/copy" as a default behavior.

Output Types

• Call-based morphling: Incorporates the target's capability into your own toolchain. The result is "a stronger version of yourself."
• Rewrite-based morphling: Understands the core logic and implements a better version from scratch. The result is a new repository, tool, or product that can independently replace the original.
• Hybrid morphling: Handles components differently within the same project (e.g., calling complex low-level dependencies while rewriting differentiated core logic and discarding redundant modules).

The Goal Hive Master acts as the central design and coordination department of a Hive. Its primary responsibility is to decompose sub-tasks, judge results, and aggregate outputs to ensure core deliverables reach the user within a given timeframe.

Core Principles

• Role Limitation: The Master does not produce deliverables itself. It only performs Decomposition (拆) and Aggregation (汇) by scheduling workers. It has no authority to stop itself and must not design its own termination conditions.
• Control Theory Model: The process is treated as a controlled system where the goal is to minimize the error $e = J^* - y$ (where $J^$ is the target value/user need and $y$ is the current product). The objective is to make $y$ monotonically approach $J^$ through iterative cycles.
• The Anchor Method: Always maintain a "current optimal accepted version" as an anchor. Every iteration must perform incremental changes on this anchor. Only merge changes if they increase the value $J$; if a change makes the product worse, roll back to the previous anchor.
• Termination: The cycle continues until the budget is exhausted. At that point, deliver the current best anchor version.

The Iterative Cycle

One full cycle consists of: Probing (探测) $\rightarrow$ Designing (设计) $\rightarrow$ Executing (执行) $\rightarrow$ Checking (检查) $\rightarrow$ (Repeat SOP).

When OCR or Vision-based detection fails to identify icons (like 'More' or 'Edit' buttons), use the macOS Accessibility (AX) API. This is more stable than coordinate-based clicking.

Recommended Approaches:

1. Native pyobjc (Preferred): Use macljqCtrl.AXElements(pid/bundle_id/app_name) to enumerate the control tree. This provides metadata like role, description, title, and enabled status. Use AXFind to filter and AXClick(node) to interact.
2. AppleScript (Fallback): Use osascript with System Events to recursively enumerate entire contents of every window.

Critical Notes:

• Window Scope: Popups and detail cards are often independent sub-windows. Do not rely on front window; you must iterate through every window.
• Coordinate Conversion: AX returns logical coordinates. You must convert these to physical coordinates (e.g., multiplying by 2 on Retina displays) if you fall back to ljqCtrl.Click.
• Activation: Use osascript tell application "<App>" to activate to ensure the target app is truly in the foreground before interacting.

The scheduling system follows this lifecycle:

1. Polling: scheduler.py (located in reflect/) polls sche_tasks/*.json every 60 seconds.
2. Condition Check: A task triggers only if enabled=true, the current time is $\ge$ schedule, and the cooldown period has passed (determined by checking the timestamp of the latest report in ../sche_tasks/done/).
3. Prompt Injection: When triggered, the system constructs a prompt that includes the expected report path: ../sche_tasks/done/YYYY-MM-DD_task_name.md.
4. Agent Checkpoint: Upon receiving a task, the agent must first call update_working_checkpoint to record the target report file path. This prevents the agent from losing track of the output during long-running tasks.
5. Completion: Once finished, the agent writes the report to the injected path. The scheduler uses the existence of this file to determine if the task has been completed for the current period.

Task Planning Mode is a specialized state used when no pending tasks exist in the local TODO.txt. Instead of executing tasks, the agent focuses exclusively on strategic planning to ensure high-value future actions.

Core Logic:

• Trigger: If TODO.txt in the current working directory (cwd) contains entries, the agent skips planning and enters Execution Mode.
• Goal: Generate high-value tasks based on the formula: (Value of information not covered by AI training data) × (Long-term benefit for future collaboration). The primary output is memory updates.
• Constraint: The agent is strictly forbidden from self-reviewing its own TODOs. Every task must be reviewed and scored by a subagent before it is considered valid for execution.

The Planning Workflow:

1. Checkpoint: Call update_working_checkpoint with a status indicating planning mode is active and that tasks require subagent review.
2. History Analysis: Critically read history.txt to identify and avoid "low-value patterns" (e.g., shallow verification, repetitive exploration, or basic tool usage).
3. Memory Review: Analyze existing reports in ls autonomous_reports/ and the ../memory directory to find opportunities for optimization.
4. TODO Generation: Write 5-7 tasks to TODO.txt using the format: [ ] Type(Output/Surfing/Environment) | One-sentence goal | Acceptance criteria.
5. Subagent Review: Submit the TODO list to a subagent with the prompt: "Read the memory library and this SOP yourself to judge, score each item 1-10, and briefly state the reason.". Do not provide prior information.
6. Iteration: Delete or replace items that receive low scores. If the review fails, retry the planning process.
7. Termination: Once TODOs are reviewed and written, the agent must immediately end the current session to allow the next autonomous action to enter Execution Mode.

When planning tasks, follow these principles:

1. Decomposition: Break goals into sub-tasks that are unrelated and can be executed in parallel. Use cl.add() for these.
2. Serial Tasks: If Task B depends on the result of Task A, do not split them into parallel sub-tasks; execute them serially.
3. Task Granularity: Use short sentences for tasks. Detailed information should only be added during the dispatch phase.

Examples of effective task decomposition:

• Parallel Web Tasks: To download all files from a directory, first run a webscan to get the list, then create one task per file: `cl.add(["Download A.exe", "Download B.zip", "Download C.zip"])

• Multi-dimensional Checks: To check a PDF for grammar, style, and format, treat them as independent: `cl.add(["Check grammar", "Check style", "Check format"])

• Multi-stage (MapReduce) Workflow: To upgrade VPS versions:

  1. Round 1 (Map): Create one task per machine to check the version: cl.add(["Check node03 version", "Check node09 version"]).
  2. Reduce: The Master filters the results to find machines with version < 22.
  3. Round 2 (Map): Create tasks only for the machines that need upgrading: `cl.add(["Upgrade node03 to 24", "Upgrade Dell to 24"])