cicy-desktop 2.1.237 → 2.1.239

package/.kiro/steering/dev-workflow.md

@@ -1,166 +0,0 @@
----
-inclusion: always
----
-
-# Git 开发工作流程 - Git Development Workflow
-
-## ⚠️ 开发前必读
-
-**在开始任何开发任务前，必须完整阅读本文档并严格遵循所有规范。**
-
-违反规范将导致：
-- ❌ 代码被拒绝合并
-- ❌ 浪费时间重做
-- ❌ 影响项目质量
-
-## 🚨 核心原则（必须遵守）
-
-1. **开发前必读本文档** - 不要凭记忆或猜测
-2. **严格遵循每个阶段** - 不要跳过任何步骤
-3. **遇到问题先分析** - 不要盲目重试
-4. **测试驱动开发** - 一功能一测试
-5. **全部测试通过才提交** - npm test 必须 100% 通过
-
-## 新功能/Bug修复标准流程
-
-当收到开发新功能或修复bug的请求时，严格遵循以下流程：
-
-### 阶段1：需求分析
-1. **用户提出需求**
-2. **AI 制定可行方案**
-   - 分析技术实现路径
-   - 评估工作量和风险
-   - 提出具体实现方案
-3. **询问用户是否有补充**
-4. **等待用户确认"开始"**
-
-### 阶段2：环境准备（用户说"开始"后执行）
-```bash
-# 分支命名规范：
-# - 新功能：feat-MMDD-功能简述
-# - Bug修复：fix-MMDD-问题简述
-
-# 1. 直接在工作目录克隆并创建分支
-mkdir -p ~/projects/cicy-desktop/branches/
-git clone -b origin/main git@github.com:cicy-ai/cicy-desktop.git ~/projects/cicy-desktop/branches/<branch-name>
-sudo ln -s /<branch-name> ~/projects/cicy-desktop/branches/<branch-name>
-cd /<branch-name>
-git fetch origin
-git checkout -b <branch-name> origin/main
-
-# 2. 安装依赖
-npm install
-```
-
-### 阶段3：需求文档化
-在工作目录创建 `task/task-<branch-name>.md` 文档，包含：
-
-```markdown
-# 任务：[功能/Bug简述]
-
-## 需求描述
-[用户原始需求]
-
-## 实现方案
-[技术方案详细说明]
-
-## TODO 清单
-- [ ] 任务1
-- [ ] 任务2
-- [ ] 任务3
-
-## 验收标准
-- [ ] 功能正常工作
-- [ ] 所有测试通过
-- [ ] 代码符合规范
-- [ ] 文档已更新
-```
-
-### 阶段4：开发实现
-```bash
-# 在工作目录进行开发
-cd /<branch-name>
-
-# ⚠️ 必须遵循：一功能一测试
-# ❌ 禁止：写完所有代码再测试
-# ✅ 正确：每完成一个功能立即测试
-
-# 实时更新 TASK.md 中的完成状态
-```
-
-**核心原则：增量开发，持续验证**
-
-### 阶段5：本地测试（❗强制要求）
-```bash
-# ⚠️ 必须运行完整测试套件
-npm test
-
-# ❌ 如果测试失败，绝对不能提交
-# ✅ 必须所有测试通过才能进入下一阶段
-# ✅ 验证所有验收标准
-```
-
-**⚠️ 警告：如果跳过此步骤直接提交，视为严重违规！**
-
-**遇到测试失败时：**
-1. ❌ 不要盲目重试
-2. ✅ 仔细阅读错误信息
-3. ✅ 分析失败原因（依赖缺失？代码错误？环境问题？）
-4. ✅ 总结问题根源
-5. ✅ 制定修复方案
-6. ✅ 修复后再次测试
-
-### 阶段6：提交和推送
-```bash
-# 提交更改
-git add .
-git commit -m "feat/fix: 简要描述更改内容"
-
-# 推送到远程
-git push origin <branch-name>
-```
-
-### 阶段7：创建 Pull Request
-```bash
-# 使用 GitHub CLI 创建 PR
-gh pr create --base main --head <branch-name> --title "标题" --body "详细描述"
-
-# 或手动在 GitHub 网页创建 PR
-```
-
-## 分支命名示例
-
-### 新功能
-- `feat-0206-add-cdp-scroll`
-- `feat-0206-multi-account-support`
-- `feat-0206-network-monitor`
-
-### Bug修复
-- `fix-0206-window-close-crash`
-- `fix-0206-screenshot-memory-leak`
-- `fix-0206-test-timeout`
-
-## 工作目录结构
-```
-~/
-├── projects/
-│   └── cicy-desktop/main             # 主仓库
-└── projects/cicy-desktop/branches/
-    ├── feat-0206-feature1/
-    ├── fix-0206-bug1/
-    └── feat-0206-feature2/
-```
-
-## 核心原则
-- ✅ 始终基于 `origin/main` 创建新分支
-- ✅ 使用独立工作目录避免污染主仓库
-- ✅ **本地测试必须全部通过才能提交（npm test）**
-- ✅ **一功能一测试，不要全写完再测试**
-- ✅ 分支名称包含日期和清晰的功能/问题描述
-- ✅ 提交信息遵循 conventional commits 规范
-- ❌ **禁止跳过测试直接提交代码**
-- ❌ **禁止一次性写完所有代码**
-
----
-**制定时间：2026-02-06**
-**适用项目：cicy-desktop**

package/AGENTS.md

@@ -1,275 +0,0 @@
-# AGENTS.md
-
-This file provides guidelines for AI agents working on this codebase.
-
-## Build, Lint, and Test Commands
-
-### Core Commands
-
-```bash
-# Start the MCP server (runs Electron app with MCP endpoint)
-npm start
-
-# Start with specific port
-npm start -- --port=8102
-
-# Start with URL and single window mode
-npm start -- --url=http://example.com --one-window
-
-# Run all tests (Jest with forceExit to handle Electron processes)
-npm test
-
-# Run a single test file
-npm test -- api.ping.test.js
-
-# Run tests matching a pattern
-npm test -- --testNamePattern="ping"
-
-# Format code with Prettier
-npm run format
-
-# Check formatting
-npm run format:check
-
-# Build distributables
-npm run build
-```
-
-### Test Configuration
-
-- Tests are in `tests/` directory with pattern `*.test.js`
-- Jest runs with `--runInBand` (serial execution) due to Electron's single-process nature
-- Tests use supertest for HTTP API testing
-- Tests spawn actual Electron processes on dynamic ports
-- Auth token loaded from `~/global.json`
-- Test utilities in `tests/test-utils.js`
-
-## Code Style Guidelines
-
-### Language
-
-- **CommonJS** only - use `require()` not ES modules
-- Plain JavaScript - no TypeScript
-- ES6+ features: async/await, arrow functions, template literals
-
-### File Organization
-
-```
-src/
-  main.js              # Main entry: Electron + Express + MCP server
-  config.js            # Configuration constants
-  tools/               # MCP tool implementations
-    ping.js
-    window-tools.js
-    cdp-tools.js
-    exec-js.js
-  utils/               # Utility modules
-    window-utils.js
-    window-monitor.js
-    cdp-utils.js
-    snapshot-utils.js
-    auth.js
-tests/                 # Test files
-  test-utils.js        # Shared test utilities
-  *.test.js            # Individual test files
-```
-
-### Imports Order
-
-```javascript
-// 1. Built-in Node modules
-const fs = require("fs");
-const path = require("path");
-
-// 2. External dependencies
-const { BrowserWindow } = require("electron");
-const { z } = require("zod");
-const express = require("express");
-
-// 3. Internal modules
-const { config } = require("../config");
-const { createWindow } = require("../utils/window-utils");
-```
-
-### Naming Conventions
-
-- **Classes**: PascalCase (`AuthManager`, `BrowserWindow`)
-- **Functions/variables**: camelCase (`getWindows`, `registerTool`)
-- **Constants**: SCREAMING_SNAKE_CASE (`PORT`, `LOGS_DIR`)
-- **Tool names**: snake_case (`open_window`, `get_windows`)
-- **File names**: kebab-case for tests (`api.ping.test.js`)
-
-### Error Handling
-
-All tool handlers must return structured MCP responses:
-
-```javascript
-try {
-  // ... operation
-  return {
-    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
-  };
-} catch (error) {
-  return {
-    content: [{ type: "text", text: `Error: ${error.message}` }],
-    isError: true,
-  };
-}
-```
-
-### Tool Registration Pattern
-
-```javascript
-const { z } = require("zod");
-
-function registerTools(registerTool) {
-  registerTool(
-    "tool_name",
-    "Description of what the tool does",
-    z.object({
-      win_id: z.number().optional().default(1).describe("Window ID"),
-      param: z.string().describe("Required parameter"),
-    }),
-    async ({ win_id, param }) => {
-      try {
-        // Implementation
-        return { content: [{ type: "text", text: "result" }] };
-      } catch (error) {
-        return { content: [{ type: "text", text: `Error: ${error.message}` }], isError: true };
-      }
-    },
-    { tag: "Category" } // OpenAPI grouping tag
-  );
-}
-
-module.exports = registerTools;
-```
-
-### Response Formats
-
-```javascript
-// Text response
-return { content: [{ type: "text", text: "message" }] };
-
-// JSON response
-return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
-
-// Image response (NativeImage from Electron)
-return {
-  content: [
-    { type: "text", text: `Image: ${width}x${height}` },
-    { type: "image", data: base64String, mimeType: "image/png" },
-  ],
-};
-
-// Error response
-return { content: [{ type: "text", text: "error message" }], isError: true };
-```
-
-### Common Patterns
-
-#### Window Lookup
-
-```javascript
-const win = BrowserWindow.fromId(win_id);
-if (!win) throw new Error(`Window ${win_id} not found`);
-```
-
-#### JSON Serialization with BigInt
-
-```javascript
-JSON.stringify(result, (key, value) => (typeof value === "bigint" ? value.toString() : value), 2);
-```
-
-#### NativeImage Handling
-
-```javascript
-if (result?.constructor.name === "NativeImage") {
-  const size = result.getSize();
-  const base64 = result.toPNG().toString("base64");
-  return {
-    content: [
-      { type: "text", text: `Image: ${size.width}x${size.height}` },
-      { type: "image", data: base64, mimeType: "image/png" },
-    ],
-  };
-}
-```
-
-### Testing Patterns
-
-```javascript
-const { setPort, setupTest, teardownTest, sendRequest } = require("./test-utils");
-
-describe("Feature Test Suite", () => {
-  beforeAll(async () => {
-    setPort(8102); // Set test port
-    await setupTest(); // Start Electron + establish SSE
-  }, 30000);
-
-  afterAll(async () => {
-    await teardownTest(); // Cleanup
-  });
-
-  test("should do something", async () => {
-    const response = await sendRequest("tools/call", {
-      name: "tool_name",
-      arguments: { param: "value" },
-    });
-    expect(response.result).toBeDefined();
-  });
-});
-```
-
-### Logging
-
-Use electron-log with consistent format:
-
-```javascript
-const log = require("electron-log");
-log.info("[MCP] Server starting");
-log.error("[MCP] Error:", error);
-```
-
-### Security
-
-- Never log secrets or API keys
-- Validate all inputs with Zod schemas
-- Return structured errors without internal details
-- Auth token loaded from `~/global.json`
-
-### Electron Best Practices
-
-- Use `electronApp.whenReady()` for initialization
-- Handle `window-all-closed` event properly
-- Enable remote debugging with `--remote-debugging-port`
-- Use `nodeIntegration: false` and `contextIsolation: true`
-- Multi-account support via `partition: persist:sandbox-{accountIdx}`
-
-## Master/Worker Cluster Commands
-
-```bash
-# Start Master server (port 8100)
-npm run start:master
-
-# Start Worker registered to Master
-MASTER_TOKEN=$(jq -r '.api_token' ~/global.json)
-PORT=8101 CICY_MASTER_URL="http://127.0.0.1:8100" CICY_MASTER_TOKEN="$MASTER_TOKEN" npm start
-
-# Master API endpoints
-curl http://127.0.0.1:8100/api/ping
-curl http://127.0.0.1:8100/api/workers
-curl http://127.0.0.1:8100/api/agents
-
-# Worker direct API (requires auth token from ~/global.json)
-curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:8101/rpc/tools
-curl -H "Authorization: Bearer $TOKEN" -X POST http://127.0.0.1:8101/rpc/tools/call \
-  -H "Content-Type: application/json" \
-  -d '{"name":"ping","arguments":{}}'
-```
-
-### Master Token
-
-- Token stored in `~/global.json` as `api_token`
-- Token file created automatically on first startup if missing
-- Token passed to workers via `CICY_MASTER_TOKEN` env var

package/CLAUDE_HANDOFF.md

@@ -1,168 +0,0 @@
-# Claude Code Handoff
-
-Please read this file first, then read `AGENTS.md`, and then inspect the codebase.
-
-## Project Summary
-
-`cicy-desktop` is an Electron-based desktop automation host. It is not just a normal desktop app; it acts as a:
-
-- Electron runtime
-- browser/desktop automation host
-- MCP + HTTP RPC + admin UI control plane
-- evolving master/worker distributed desktop platform
-
-## Read These Files First
-
-Start with these files in this order:
-
-1. `AGENTS.md`
-2. `src/main.js`
-3. `src/master/master-main.js`
-4. `src/master/master-routes.js`
-5. `src/cluster/worker-client.js`
-6. `src/cluster/worker-identity.js`
-7. `src/server/tool-registry.js`
-8. `src/utils/window-utils.js`
-9. `src/utils/window-monitor.js`
-10. `src/tools/window-tools.js`
-11. `docs/feature-distributed-multi-agent.md`
-
-## Architecture Overview
-
-### Worker Runtime
-- Main worker entry: `src/main.js`
-- Exposes:
-  - MCP SSE endpoints
-  - HTTP RPC endpoints
-  - admin/UI routes
-  - Electron IPC bridge
-- Registers tools from `src/tools/*`
-- Manages BrowserWindow lifecycle
-- Supports automation, screenshots, CDP, DOM actions, downloads, requests, logs, and system window operations
-
-### Master Runtime
-- Main master entry: `src/master/master-main.js`
-- API routes in `src/master/master-routes.js`
-- Tracks workers, agents, tasks, and session affinity
-- Exposes worker/task/agent APIs and RPC forwarding
-
-### Tool Registry
-- Central registration point: `src/server/tool-registry.js`
-- Tool modules live in `src/tools/*`
-- Tool handlers are reused across protocols
-
-### Window/Agent Foundation
-- Window lifecycle core: `src/utils/window-utils.js`
-- Monitoring/telemetry core: `src/utils/window-monitor.js`
-- A BrowserWindow is effectively the current agent runtime unit
-- Multi-account/session isolation uses Electron partitioning
-
-## Current Distributed State
-
-The repository already contains early master/worker support.
-
-### Already Implemented
-- Worker identity generation
-- Worker client registration flow
-- Worker heartbeat flow
-- Master worker registry
-- Agent index
-- Task store
-- Session affinity store
-- Master RPC forwarding to workers
-- Master admin HTML/UI routes
-
-### Main Endpoints
-
-#### Master
-- `GET /api/ping`
-- `POST /api/workers/register`
-- `POST /api/workers/heartbeat`
-- `GET /api/workers`
-- `GET /api/agents`
-- `GET /api/tasks`
-- `POST /api/rpc/:toolName`
-- `GET /master`
-
-#### Worker
-- `GET /rpc/tools`
-- `POST /rpc/tools/call`
-- `POST /rpc/:toolName`
-- `GET /ui`
-- `GET /docs`
-
-## Known Operational Facts
-
-### Master Start
-```bash
-cd /Users/ton/projects/cicy-desktop
-npm run start:master
-```
-
-### Worker Start
-```bash
-MASTER_TOKEN=$(jq -r '.api_token' ~/global.json)
-PORT=8101 CICY_MASTER_URL="http://127.0.0.1:8100" CICY_MASTER_TOKEN="$MASTER_TOKEN" npm start
-```
-
-### Important Runtime Requirements
-Worker registration to master fails if any of the following are wrong:
-
-1. `CICY_MASTER_URL` is missing
-2. `CICY_MASTER_TOKEN` is missing
-3. worker port (for example `8101`) is already occupied
-4. wrong Node runtime is used
-
-### Node Version Note
-This project runs better with Node 22 in this environment. Node 19 caused startup/runtime issues.
-
-## Recently Confirmed Issue
-
-A worker previously failed to appear in master because:
-- port `8101` was already in use by another Electron process
-- worker startup environment was not consistently correct
-
-After killing the conflicting process and starting the worker with:
-- Node 22
-- `CICY_MASTER_URL`
-- `CICY_MASTER_TOKEN`
-
-registration succeeded.
-
-## What This Project Is Right Now
-
-Best current description:
-
-> A mature single-node Electron automation worker runtime with early but working master/worker distributed plumbing.
-
-It is **not yet** a fully mature distributed desktop cluster, but it already has the first working pieces.
-
-## What Is Still Missing / Incomplete
-
-Likely gaps still needing work:
-- richer agent abstraction beyond raw BrowserWindow
-- stronger task lifecycle orchestration
-- worker health/resource reporting polish
-- clearer worker startup/desktop launch flow
-- better master UI observability for workers/agents/tasks
-- more robust retry/error handling in master-to-worker forwarding
-
-## What To Do First
-
-Before changing code:
-1. Read the files listed above
-2. Summarize current architecture in your own words
-3. Explain what master/worker currently implements
-4. Identify the most important missing pieces
-5. Propose the next incremental step before editing code
-
-## Expected First Response
-
-Please start by answering:
-
-1. What is the current architecture?
-2. What exactly is already implemented for master/worker?
-3. What is missing or fragile?
-4. What should be the next priority?
-
-Do not start editing immediately. Read first, then propose a plan.

package/DESIGN.md

@@ -1,66 +0,0 @@
-# CiCy Desktop Design
-
-## Product Thesis
-
-CiCy Desktop is not a generic admin panel.
-It is a runtime cockpit for a desktop automation node.
-
-The UI should answer three operator questions:
-
-1. What is the node doing right now?
-2. What session or profile am I acting on?
-3. What is the next action I want to take?
-
-Everything else is secondary.
-
-## Core Model
-
-The product has two runtimes:
-
-- Electron sessions
-- Chrome profiles
-
-Both runtimes follow the same operator loop:
-
-1. `Operate`
-   Focus the current thing.
-   Example: live preview, current profile state.
-2. `Launch`
-   Start or switch to a target.
-   Example: open ChatGPT, open a profile.
-3. `Tune`
-   Configure, inspect, or do destructive actions.
-   Example: bounds, capture settings, proxy, close all.
-
-The main screen should show only one of these loops at a time.
-
-## Layout Rules
-
-- Left rail: identity + runtime switch + session/profile selection.
-- Main stage: one dominant task surface only.
-- No permanent debug sidebars.
-- No explanatory paragraphs in the main operating surface.
-- Advanced controls belong in `Tune`, not next to the live workspace.
-
-## Interaction Principles
-
-- Default landing state is `Operate`.
-- Switching runtime resets the workspace mode to `Operate`.
-- Selection should be sticky across refreshes.
-- Dangerous actions must be visually separated and confirmation-backed.
-- Keyboard forwarding must only happen in live operation mode, never while editing local inputs.
-
-## Visual Direction
-
-- Dark industrial control-room aesthetic, not SaaS dashboard chrome.
-- One restrained accent color.
-- Large stage, low copy density, high information contrast.
-- Rounded panels are acceptable, but panel count should stay low.
-- Motion should only reinforce state change, never decorate.
-
-## Anti-Patterns
-
-- Do not put all controls on screen at once.
-- Do not mix launch, observe, and configure in one canvas.
-- Do not use marketing copy inside the operator workspace.
-- Do not make Chrome and Electron feel like unrelated products.