源码快照 @ 2026-09-01 (source-only, 剔除非源码素材)

docs/computer-use-provenance.md

@@ -0,0 +1,135 @@
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# Computer Use provenance
+
+Maka's Computer Use surface was built against other people's work in three
+materially different ways. They are separated here because the obligations
+differ: redistribution under a license, adaptation or reference use of licensed
+source, and inspection of a proprietary implementation for compatibility.
+
+At a high level, Maka's Computer Use implementation was informed by the
+MIT-licensed `trycua/cua` and `iFurySt/open-codex-computer-use` projects and by
+comparison with Codex Desktop's implementation and externally visible
+behavior. Maka integrated and adjusted those inputs through its own testing,
+safety boundaries, and product requirements.
+
+That summary does not collapse the source categories below. Licensed source,
+behavior observations, exact facts recovered from a binary, and Maka-authored
+work remain separate because their evidence and release-review obligations are
+different.
+
+Paths are Maka's unless they carry the upstream repository name, as in
+`open-codex-computer-use/...`.
+
+Every entry names what was taken, where it landed, and what the evidence was.
+When you add or change a borrowed design, add the row here and put the same
+statement in the file that carries it — an in-file comment answers "why is this
+constant 200?" at the moment someone asks it, and this file answers "what did we
+build on?" for the project as a whole.
+
+## 1. Redistributed under license
+
+Ships inside the Maka artifact. Requires the license text and copyright notice
+to travel with it.
+
+| Component | License | Where the notice lives |
+|---|---|---|
+| npm dependencies | various | `apps/desktop/resources/licenses/npm/`, generated by `scripts/generate-third-party-notices.mjs` and byte-checked at build by `scripts/check-third-party-notices.mjs` |
+
+Maka has one Computer Use executor, `maka-cu`. It is built from Maka's own
+source by the `prepare` command in `scripts/computer-use.mjs` and pinned by digest in
+`apps/desktop/bundled-tools.json`. It is not signed, so it is not distributed:
+its `distributionReady` is false and `scripts/verify-macos-arm64-dmg.mjs`
+forbids its path in a packaged build. Nothing third-party ships inside the Maka
+artifact for Computer Use, which is why the table above has one row.
+
+The third-party executor Maka used to run, cua-driver, was removed along with
+its vendored notice. Nothing in this tree spawns it or links against it.
+
+`maka-cu` is itself a fork of MIT-licensed `iFurySt/open-codex-computer-use`
+(§2), so when it does ship, that notice travels with it.
+
+## 2. Licensed source adapted or read as reference
+
+MIT-licensed source was used both as an implementation starting point and as a
+design reference. The rows below distinguish adaptation from reference-only
+use.
+
+### trycua/cua
+
+MIT. The original Maka cursor renderer was a TypeScript adaptation of the
+public `cursor-overlay` crate, introduced in Maka commit
+`025d0c628a2162d0a7daf49e97d104c36a4431c6`. The fixed upstream source recorded
+by Maka's bundled cua-driver manifest was commit
+`8c921b2b3bf13494724ead4f0a814d80c56a7e8b`.
+
+Maka later replaced and extended the planner, timing, hotspot, rendering, and
+presentation lifecycle. The current source remains in that documented lineage
+even though the old cua-driver executable and its vendored notice no longer
+ship.
+
+### iFurySt/open-codex-computer-use, and its fork QwenLM/open-computer-use
+
+Both MIT, © 2026 Leo. An independent reimplementation of Codex's Computer Use
+as an MCP server.
+
+For the rows below, no source code was copied into this repository; what was
+taken is a format, a decision, or an archived measurement. Attribution is given
+because it was load-bearing, not because MIT compels it for ideas.
+
+| Taken | Landed in | Notes |
+|---|---|---|
+| An archived capture of Codex's real `get_app_state` result | `packages/runtime/src/computer-use-tools.ts` | Their `open-codex-computer-use/artifacts/tool-comparisons/20260417-focus-behavior/`. This is what turned Maka's model of Codex's observation format from inference into an observed sample. |
+| The one-line-per-element observation shape: indentation for containment, states written only when not the default | same file | Maka's version keeps `observation_id` in the header (frame binding is protocol here, prose there) and keeps element geometry (Codex has no coordinate action surface to need it; Maka's is disabled by default rather than absent). |
+| Writing only the informative half of a state — `disabled`, never `enabled` | same file | Their `summarizeTraits`. |
+| Filtering `AXPress` out of an element's advertised action list, because pressing is what `click` does | not yet landed — waits on `trycua/cua#2622` exposing per-element AX actions | Their `meaningfulActions`. |
+| The permission-onboarding pattern: anchor a guidance panel to the System Settings window, track it, and distinguish grants that need an app relaunch | not yet landed — for the `feat/permission-onboarding` work | Their `open-codex-computer-use/apps/OpenComputerUse/Sources/OpenComputerUse/PermissionOnboardingApp.swift`. |
+| Archiving side-by-side tool captures in-repo as evidence | practice, not code | Worth adopting for Maka's own Codex comparisons. |
+| Private SkyLight synthetic-focus/background click recipe | Maka's `maka-cu` executor, pinned in `apps/desktop/bundled-tools.json` | Derived independently from the same MIT cua-driver/yabai recipe; the executor keeps its attribution and notice. The WebContent path uses the host window and a single private post rather than the general dual-post compatibility route. |
+
+Removing the cua-driver binary from this tree changes nothing about that path:
+what was borrowed was a published recipe, not the artifact or proprietary Codex
+implementation.
+
+## 3. Proprietary implementation inspected for compatibility
+
+The signed Codex Desktop Computer Use executable was statically inspected. No
+OpenAI source code or executable is included or redistributed by Maka, but
+specific geometry, numeric constants, and control-flow facts recovered from the
+binary were transcribed into the cursor implementation. This is a claim about
+the listed facts, not a claim that the Computer Use implementation as a whole
+was derived from the binary.
+
+This inspection provides evidence, not a license grant. Pull requests #1255 and
+#1883 accurately recorded most of the listed binary-recovered inputs, but #1883's
+"term-for-term" phrase was broader than the current mixed scorer. The detailed
+artifact, retained facts, and Maka-authored divergences are recorded in
+`docs/computer-use-cursor-provenance.md`.
+
+| Binary-recovered or observed fact | Informed area |
+|---|---|
+| Exact cursor geometry, center hotspot, motion configuration, close-enough thresholds, path measurement, and core scoring weights | `apps/desktop/src/renderer/computer-use-overlay/engine/cursor-engine.ts` |
+| Overlay level policy — an occluded target raises the cursor rather than hiding it | same file, and `apps/desktop/src/main/computer-use/cursor-overlay-window.ts` |
+| The observation text shape | `packages/runtime/src/computer-use-tools.ts`, corroborated by the archived capture in §2 |
+| OOP WebContent targeting, retained-element unique refetch, and renderer-generation fencing | Reimplemented in the pinned `maka-cu` source; this repository records the exact source commit and binary digest in `apps/desktop/bundled-tools.json` |
+| Stable AX ids across revisions, ordered no-change/remove/insert/update presentation, and full-tree fallback | Reimplemented in the pinned `maka-cu` source and `packages/runtime/src/computer-use-observation-text.ts`; the complete current tree remains authoritative and dispatch still uses fresh snapshot tokens |
+
+Where Maka deliberately diverges, the divergence is stated at the point of
+divergence rather than here, so it is read by whoever is changing that code.