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

tools/scripts/README.md

@@ -0,0 +1,184 @@
+# Scripts
+
+This directory is reserved for repository scripts such as:
+
+- build helpers
+- packaging helpers
+- code generation entrypoints
+- validation tasks
+
+Current examples include:
+
+- `dev-gui.sh` for checking local prerequisites, preparing workspace
+  dependencies, downloading and building the development `tuttid` binary, and
+  launching the desktop GUI with `TUTTID_BIN`; the renderer dev server warms
+  its reachable module graph before Electron opens. Agent Extensions use their
+  configured signed remote releases by default. The command clears inherited
+  Kimi Code package overrides so stale shell or launchd state cannot shadow the
+  release used by the shipped product; set `DEV_GUI_KIMI_CODE_PACKAGE_DIR` to
+  an explicit unpacked package path only when testing a local package. When the
+  package comes from the standard Kimi Extension repository layout, the script
+  also discovers its local account-usage Helper so an unpublished development
+  package can exercise API billing without weakening the production install
+  contract. `DEV_GUI_KIMI_CODE_ACCOUNT_USAGE_EXECUTABLE` selects an explicit
+  Helper when the layout differs. The standard layout points at the Helper's
+  self-contained `dist/cli.cjs` build. The script canonicalizes these paths and
+  fails before launch when an account-usage profile declares a Helper but its
+  executable build is missing
+- `renderer-dev-warmup.mjs` for moving cold Vite and React Compiler transforms
+  ahead of the Electron launch during desktop development
+- `setup-dev.mjs` for checking local developer prerequisites such as pinned lint tooling
+- `setup-dev.mjs --install=golangci-lint` for installing the pinned Go lint tool
+- `generate-defaults.mjs` for generating shared Go and desktop TypeScript defaults from `config/tutti.defaults.json`
+- `generate-openapi.mjs` for generating Go and TypeScript API contract artifacts from `services/tuttid/api/openapi/tuttid.v1.yaml`
+- `smoke-desktop-transport.mjs` for daemon transport smoke validation
+- `push-checked.mjs` for fetching the current branch, stopping before
+  `check:full` when the remote branch already has new commits, then pushing
+  with an explicit `--force-with-lease` against the fetched remote head
+- `check-i18n.mjs` for desktop locale parity, placeholder parity, i18n key references, and hardcoded user-visible copy candidates
+- `check-electron-runtime-boundaries.mjs` for Electron `main`/`preload` runtime import graph checks that catch React/TSX leaks and externalized workspace packages that resolve to raw source files
+- `check-ui-boundaries.mjs` for shared UI boundary enforcement across imports, CSS, SVG usage, and desktop Tailwind `@source` coverage for workspace packages that declare `tutti.tailwindSourceRoot`
+- `build-tutti-app-release.mjs` for packaging an external Tutti app into a zip plus `release.json` and `latest.json`
+- `build-tutti-app-catalog.mjs` for merging app `release.json` files into the App Center remote catalog
+- `build-tutti-app-runtime-catalog.mjs` for merging managed app runtime artifact metadata into the runtime download catalog
+- `apps/desktop/scripts/vendor-managed-posix-shell.mjs` for assembling the
+  pinned minimal managed POSIX shell used by packaged Windows Desktop adapters;
+  CI downloads and verifies the archive from
+  `config/tutti.managed-posix-shell.lock.json`, while local packaging may set
+  `TUTTI_MSYS2_BASE_ARCHIVE` to an already downloaded matching archive
+  (the caller passes the target platform explicitly)
+- `capture-electron-trace.mjs` for recording desktop Electron performance
+  traces through CDP stream mode without opening the DevTools Performance export
+  UI
+- `run-agent-gui-performance.mjs` for starting an isolated Desktop from a
+  consistent backup of the developer database, running a selected AgentGUI or
+  window interaction, capturing its exact trace window, and generating
+  report-only JSON and Markdown summaries. It reuses a fresh production
+  Desktop bundle when available, so each run starts the isolated Electron
+  process directly instead of starting a new Vite renderer dev server.
+- `lark-log-tool.mjs` for fetching Feishu/Lark message file attachments or Base bug-record attachments with `lark-cli`, extracting Tutti log bundles, summarizing repeated log failures around an anchor time, and optionally watching appended warn/error lines in real time
+
+  ```bash
+  pnpm lark:logs -- fetch --url '<feishu-applink>' --issue 'interactive request is no longer live' --analyze
+  pnpm lark:logs -- fetch --base-url '<feishu-base-url>' --record-url '<feishu-record-url>' --issue 'cannot submit reply' --analyze
+  pnpm lark:logs -- fetch --record-url '<feishu-record-url>' --base-token '<base-token>' --table-id '<table-id-or-name>' --issue 'cannot submit reply' --analyze
+  pnpm lark:logs -- fetch --record-url '<feishu-record-url>' --issue 'cannot submit reply' --analyze
+  pnpm lark:logs -- analyze /path/to/tutti-logs.zip --anchor '2026-06-05 20:17' --issue 'event stream mismatch'
+  ```
+
+  The short `--record-url` form reads defaults from the first existing config:
+  - `./.tutti-logger-fetcher.json`
+  - `~/.config/tutti-logger-fetcher/config.json`
+  - `~/.codex/skills/tutti-logger-fetcher/config.json`
+
+  Example:
+
+  ```json
+  {
+    "bugRecord": {
+      "baseToken": "app_xxx",
+      "tableId": "tbl_xxx",
+      "viewId": "vew_xxx",
+      "attachmentField": "日志",
+      "recordTimeField": "反馈时间"
+    }
+  }
+  ```
+
+Core product behavior should graduate into Go services or first-class tools rather than remain in shell scripts indefinitely.
+
+## Agent Session Replay recording
+
+This repository owns the generic Electron record/replay runner. QA case
+metadata, scenario modules, fixtures, Cassettes, and evidence live in the
+separate `tutti-agent-session-replay-cases` repository.
+
+Record mode receives the case-owned module explicitly:
+
+```bash
+pnpm e2e:agent-gui -- \
+  --record .tmp/cassettes/c01_codex \
+  --scenario c01 \
+  --scenario-file ../tutti-agent-session-replay-cases/cases/c01/scenario.mjs
+```
+
+`run-agent-session-replay.mjs` owns CLI mode selection and record/replay
+orchestration. It validates that the external module's exported scenario ID
+matches `--scenario`. Cassette validation and artifacts, isolated runtime
+setup, and recording project preparation remain in
+`agent-session-replay-runner/`.
+
+Example desktop trace capture:
+
+```bash
+TUTTI_ELECTRON_REMOTE_DEBUGGING_PORT=9223 \
+TUTTI_ELECTRON_JS_FLAGS=--max-old-space-size=8192 \
+make dev-gui
+
+pnpm trace:desktop -- --duration 15
+```
+
+Automated AgentGUI performance reports:
+
+```bash
+pnpm perf:agent-gui
+pnpm perf:agent-gui -- --list-scenarios
+pnpm perf:agent-gui -- --scenario session-switch
+pnpm perf:agent-gui -- --scenario virtualized-streaming
+pnpm perf:agent-gui -- --scenario composer-input
+pnpm perf:agent-gui -- --scenario provider-status-focus-refresh --all-process-time-profile
+```
+
+The command reads `~/.tutti-dev/tuttid.db` by default and uses SQLite online
+backup to create a temporary copy. It never writes the source database. The
+copy keeps projects, sessions, and rail data, but clears recoverable operation
+queues and the selected AgentGUI session before starting an isolated daemon and
+Electron `userData` directory. This prevents the diagnostic run from resuming a
+real provider session while avoiding a schema-sensitive fixture.
+All scenarios run with invisible, non-activating Electron windows while keeping
+the real renderer, compositor, and CDP trace pipeline active. Native pointer
+events pass through those windows; scenario interaction is injected through
+CDP.
+
+Outputs are stored under
+`.tmp/perf/agent-gui/<scenario>/<timestamp>/`: `trace.json`,
+`report.json`, `report.md`, and `desktop.log`. Metric values are report-only;
+only infrastructure, scenario, trace, or analysis failures return a non-zero
+exit code. Available scenarios also cover deterministic streaming into an
+already virtualized transcript, fresh-scope Rail reveal, hero composer
+prompt-tip layout measurement during resize, per-character composer input,
+IME composition, `@` panel keyboard navigation in a restored dock composer,
+internal Workbench window lifecycle, and native Electron window state changes.
+The streaming scenario rewrites only the isolated snapshot and shadows
+`cursor-agent` only inside the isolated Desktop process, so it cannot send input
+to an installed Agent provider. The native window scenarios are currently
+macOS-only. Use `--source-db`,
+`--from-target-id`, or `--to-target-id` to override the defaults.
+
+The `provider-status-focus-refresh` scenario dispatches a second synthetic
+workspace focus and observes the page for one second, then proves neither focus
+starts a provider-status request. On macOS,
+`--all-process-time-profile` additionally writes `time-profile.trace` for all
+processes, including `tuttid` and short-lived provider CLIs that are outside the
+Chromium trace.
+
+The Markdown report contains scenario assertions, observed milestone phases,
+renderer-main `RunTask`/layout/paint metrics, React component fanout, and static
+repository declaration links for components that resolve unambiguously. It
+reports `ungraded` without a comparable baseline; it does not turn raw duration
+or render counts into a pass/fail verdict. Source links are ownership hints,
+not runtime stack attribution.
+
+`analyze-electron-trace.mjs` is marker- and scenario-neutral. Interactive
+automation lives in scenario modules registered by
+`agent-gui-performance-scenarios.mjs`; each owns preparation, execution,
+milestones, completion, and assertions. New scenarios should reuse the runner
+and analyzer through that boundary. Native close/reopen is intentionally not
+mixed into the renderer-marked native-window scenario because it destroys the
+renderer that owns the start/end markers.
+
+SQLite migrations are forward-only. If the developer database was last opened
+by a newer checkout with incompatible Agent target migrations, the command
+reports them before starting Desktop. Use the matching checkout or provide a
+compatible snapshot through `--source-db`; the runner does not downgrade the
+source.