feat: migrate to golang

AGENTS.md

@@ -2,75 +2,61 @@
 
 ## Overview
 
-This document describes the autonomous agents, subagents, and their roles within the scientific-surfing project.
+This document describes the internal "agents" (manager components) of the
+scientific-surfing (`ss`) CLI and their roles. The CLI is a single Go binary
+(`cmd/ss`); each agent below is a package under `internal/`.
 
 ---
 
 ## Agent List
 
-### 1. SubscriptionManager Agent
-- **Purpose:** Handles all subscription-related operations, including adding, refreshing, deleting, renaming, and activating subscriptions.
-- **Key Methods:**
-  - `add_subscription`
-  - `refresh_subscription`
-  - `delete_subscription`
-  - `rename_subscription`
-  - `set_subscription_url`
-  - `activate_subscription`
-  - `list_subscriptions`
+### 1. Subscription Manager (`internal/subscription`)
+- **Purpose:** Handles all subscription-related operations, including adding, refreshing, deleting, renaming, and activating subscriptions. Also parses `ss://`/`trojan://`/`vless://` links and base64-encoded link lists into Clash proxy YAML.
+- **Key Methods:** `AddSubscription`, `RefreshSubscription`, `DeleteSubscription`, `RenameSubscription`, `SetSubscriptionURL`, `GetSubscriptionURL`, `ActivateSubscription`, `ListSubscriptions`, `ShowStorageInfo`
 - **Notes:** Supports backup option on refresh.
 
-### 2. StorageManager Agent
-- **Purpose:** Manages persistent storage for configuration and subscription data.
-- **Key Methods:**
-  - `load_subscriptions`
-  - `save_subscriptions`
-  - `load_config`
-  - `get_storage_info`
+### 2. Storage Manager (`internal/storage`)
+- **Purpose:** Manages persistent storage for configuration and subscription data as YAML files under the per-user config directory (`$SF_CONFIG_DIR` or `~/basicfiles/cli/ss`).
+- **Key Methods:** `LoadSubscriptions`, `SaveSubscriptions`, `LoadConfig`, `SaveConfig`, `GetStorageInfo`
 
-### 3. CoreConfigManager Agent
-- **Purpose:** Handles core configuration management, including import/export, editing, resetting, and applying configuration.
-- **Key Methods:**
-  - `import_config`
-  - `export_config`
-  - `edit_config`
-  - `reset_config`
-  - `show_config`
-  - `apply`
+### 3. Core Config Manager (`internal/corecfg`)
+- **Purpose:** Handles core (mihomo) configuration management, including import/export, editing, resetting, and applying a subscription to produce the final generated config file. Also executes post-apply hook scripts.
+- **Key Methods:** `ImportConfig`, `ExportConfig`, `EditConfig`, `ResetConfig`, `ShowConfig`, `Apply`
 
-### 4. CoreManager Agent
-- **Purpose:** Manages core components and system service operations (install, uninstall, start, stop, restart, reload, status, update).
-- **Key Methods:**
-  - `install_service`
-  - `uninstall_service`
-  - `start_service`
-  - `stop_service`
-  - `restart_service`
-  - `reload_service`
-  - `get_service_status`
-  - `update`
+### 4. Core Manager (`internal/core`)
+- **Purpose:** Manages the mihomo core binary (download/update from GitHub releases) and delegates system service operations to the Service Manager.
+- **Key Methods:** `Update`, `InstallService`, `UninstallService`, `StartService`, `StopService`, `RestartService`, `GetServiceStatus`, `ReloadService`
 
-### 5. HookManager Agent
-- **Purpose:** Manages hook scripts for automation and customization.
-- **Key Methods:**
-  - `init`
-  - `list_hooks`
-  - `edit`
-  - `rm`
+### 5. Service Manager (`internal/service`)
+- **Purpose:** Cross-platform system service integration — systemd on Linux, launchd on macOS, and a native Windows Service (via `golang.org/x/sys/windows/svc`) on Windows. On macOS and Windows, this same `ss` binary is what the generated service definition invokes (hidden `service run-macos` / `service run-windows` commands), rather than a separate wrapper process.
+- **Key Methods:** `Install`, `Uninstall`, `Start`, `Stop`, `Restart`, `Status`
+
+### 6. Hook Manager (`internal/hook`)
+- **Purpose:** Manages hook scripts for automation and customization, initialized from templates embedded in the binary.
+- **Key Methods:** `Init`, `ListHooks`, `Edit`, `Rm`
+
+### 7. Model (`internal/model`)
+- **Purpose:** Persisted data structures — `Subscription`, `SubscriptionsData`, `Config` — plus a `Time` wrapper that tolerates both this implementation's own timestamps and legacy timezone-naive timestamps.
+
+### 8. YAML Util (`internal/yamlutil`)
+- **Purpose:** A duplicate-mapping-key-tolerant YAML `Unmarshal`, since real-world mihomo/clash configs are frequently hand-merged and contain duplicate keys that the underlying YAML library rejects by default.
+
+### 9. Editor (`internal/editor`)
+- **Purpose:** Opens a file in the user's configured (`$EDITOR`/`$VISUAL`) or best-guess system editor.
 
 ---
 
 ## Agent Interactions
-- The CLI acts as the orchestrator, parsing user commands and delegating tasks to the appropriate agent.
-- Agents interact via method calls and shared data models.
+- The CLI (`internal/cli`) acts as the orchestrator, parsing user commands (via cobra) and delegating tasks to the appropriate agent.
+- Agents interact via direct method calls and shared data models (`internal/model`); there is no message-passing or independent agent lifecycle — everything runs synchronously within a single CLI invocation.
 
 ---
 
 ## Extending Agents
-- To add a new agent, implement a new manager class and update the CLI to route commands.
+- To add a new agent, implement a new package under `internal/`, wire it into `internal/cli/root.go`'s `newManagers`, and add cobra subcommands under `internal/cli/`.
 - Document new agents and their responsibilities in this file.
 
 ---
 
 ## Last updated
-May 26, 2026
+2026-07-19