From 2618460ffdabf76720baa802a764f2bf07b6a2e7 Mon Sep 17 00:00:00 2001 From: vczh Date: Mon, 1 Jun 2026 15:08:10 -0700 Subject: [PATCH] Sync Copilot context --- .github/Guidelines/Running-GacUI.md | 32 ++++++++++++++++++++++----- .github/KnowledgeBase/Learning.md | 5 +++++ .github/prompts/investigate.prompt.md | 6 +++-- 3 files changed, 35 insertions(+), 8 deletions(-) diff --git a/.github/Guidelines/Running-GacUI.md b/.github/Guidelines/Running-GacUI.md index f70a1184..5e635865 100644 --- a/.github/Guidelines/Running-GacUI.md +++ b/.github/Guidelines/Running-GacUI.md @@ -8,18 +8,38 @@ You are strongly recommended to attach a debugger when running any GacUI application. Because some runtime exceptions are silently consumed by Windows causing the application not to crash, covering issues if no debugger is attached. -When `StartWindowsHttpAutomationService` is used during startup up a GacUI application, it listens to `http://localhost:/Automation//...`: -- GET `.../Controls` and `.../ControlsVerbose`, for GacUI applications, exposing all visible windows and popups. - - Read `GuiSharedAutomationService_Controls.h` for the schema. +### Automation Service via HTTP + +This is a very useful way for coding agent to debug GacUI applications. +Computer use via UI Automation may not work when the computer screen is locked. + +When `StartWindowsHttpAutomationService` is used during startup up a GacUI application: +- It listens to `http://localhost:/Automation//...`. +- GET `.../Controls`, for GacUI applications, exposing all visible windows and popups. + - Read comment for `DumpWindowClientArea` for the schema. - GET `.../Dom`, for remote protocol renderer, exposing the DOM tree. - - IRead `GuiSharedAutomationService.h` for the schema. + - Read comment for DumpRemoteProtocolRenderingDom` for the schema. - POST `.../IO` or `IO/` - - IRead `GuiSharedAutomationService.h` for the schema. - - `` is the window id returning from `.../Controls` or `.../ControlsVerbose`. + - IRead comment for `RunIOCommandOnNativeWindow` for the schema. + - `` is the window id returning from `.../Controls`. - The window ID can be comitted for the main window. - The window ID must be omitted for GacUI applications with hosted mode or remote protocol core side. - In this case all sub windows or popups behaves like controls in the main window. +When remote protocol is in use: +- Core side exposes UI in window-control tree concept. +- Renderer side exposes UI in DOM tree concept. +- Both supports IO operations: + - When performing IO via renderer, remote protocol events are used to pass IO operations to core. + - When performing IO via core, renderer only receives UI updates and redraw. + - Core and renderer should sync in the same UI state afterwards. + - Performaning IO via no matter renderer or core should result in the same UI state. +- If GacJS connects to the core side, automation service only works on core. + +### UI Automation + +GacUI does not support UI Automation so far, but this situation will be changed very soon. + ## Linux Specific NOT SUPPORTED diff --git a/.github/KnowledgeBase/Learning.md b/.github/KnowledgeBase/Learning.md index de8981b4..25ca1342 100644 --- a/.github/KnowledgeBase/Learning.md +++ b/.github/KnowledgeBase/Learning.md @@ -34,6 +34,7 @@ - Use 2-space indentation in embedded XML/JSON literals [1] - `collections::List` has deleted copy constructor; use `std::move()` for structs with `List` members [1] - Compare type descriptors by pointer when descriptor identity is available [1] +- Parse and validate before queuing asynchronous work [1] # Refinements @@ -194,3 +195,7 @@ When a failure is part of the public or script-visible semantics and tests are e ## Compare type descriptors by pointer when descriptor identity is available `GetTypeDescriptor()` and `GetTypeDescriptor(typeName)` guarantee one descriptor instance per type in a loaded type manager, so prefer direct `ITypeDescriptor*` pointer comparison over comparing type-name strings. Use `TypeInfo::content.typeName` only where the type manager cannot be loaded yet; if a name lookup is unavoidable, resolve the descriptor once and compare pointers inside hot or repeated paths. + +## Parse and validate before queuing asynchronous work + +When an API needs to report syntax or validation errors synchronously but execute accepted work asynchronously, split those phases explicitly. Parse and validate the request on the caller/transport path, return errors immediately, then queue only a parsed command object for main-thread or background execution. This keeps modal or blocking work off the response path without hiding malformed input behind an async boundary. diff --git a/.github/prompts/investigate.prompt.md b/.github/prompts/investigate.prompt.md index c1ccdb11..cc5ad430 100644 --- a/.github/prompts/investigate.prompt.md +++ b/.github/prompts/investigate.prompt.md @@ -12,8 +12,10 @@ - Your goal is to finish an investigation document in `Copilot_Investigate.md` to address a problem. - You are recommended to modify unit tests, build, run, and debug to understand the problem, or verify your root cause analysis while tracing a bug. -- **SUPER IMPORTANT** Your should always follow the coding convention when coding: `REPO-ROOT/.github/Guidelines/Coding.md`. - DO NOT ASK ANY QUESTION, you are going to complete the work to the end, I am not wathcing you in realtime. Unless you are explicitly instructed to ask questions. +- **SUPER IMPORTANT**: + - Your should always follow the coding convention when coding: `REPO-ROOT/.github/Guidelines/Coding.md`. + - When the request is separated by multiple tasks like `## Task N` or `## Task TITLE`, you should strictly follow `## Additional Instructions` to complete tasks in its order, and git commit and push after every single task, it is designed to simplify and work. ## Copilot_Investigate.md Structure @@ -173,7 +175,7 @@ Propose any solution you can think of and write them down in the document, you m ## Additional Instructions - `git commit` and `git push` all local changes to the current branch, unless there are explicit instructions to override this. -- When the request is separated by multiple tasks like `## Task N`, it is important to do task one by one strictly, by me designing tasks in this way, we can achieve: +- When the request is separated by multiple tasks like `## Task N` or `## Task TITLE`, it is important to do task one by one strictly, by me designing tasks in this way, we can achieve: - Easy-to-understand commits for file changing that is easy to review. - Limit side effects so that you don't have to deal with massive of issues at the same time. - `git commit` and `git push` should happen after every single task, unless there are explicit instructions to override this.