From 4e7f40382dfb564225f12c7f406f200ecadd50ec Mon Sep 17 00:00:00 2001 From: Turtle Date: Wed, 12 Aug 2026 14:23:07 +0800 Subject: [PATCH] docs: clarify source build prerequisite --- .../2026-08-12-separate-source-launch-from-build.i18n.yaml | 4 ++-- .../2026-08-12-separate-source-launch-from-build.md | 2 +- .../2026-08-12-separate-source-launch-from-build.zh.md | 2 +- apps/cli/reference/README.i18n.yaml | 4 ++-- apps/cli/reference/README.md | 2 +- apps/cli/reference/README.zh.md | 2 +- docs/development.i18n.yaml | 4 ++-- docs/development.md | 6 ++++++ docs/development.zh.md | 6 ++++++ 9 files changed, 22 insertions(+), 10 deletions(-) diff --git a/.agents/notes/implemented/simplification/2026-08-12-separate-source-launch-from-build.i18n.yaml b/.agents/notes/implemented/simplification/2026-08-12-separate-source-launch-from-build.i18n.yaml index 34d2f04d87..d3d7a7f7b4 100644 --- a/.agents/notes/implemented/simplification/2026-08-12-separate-source-launch-from-build.i18n.yaml +++ b/.agents/notes/implemented/simplification/2026-08-12-separate-source-launch-from-build.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-12-separate-source-launch-from-build.md -2026-08-12-separate-source-launch-from-build.md: 6cd5d7e3e0757a9a748df59ea0897ee59e3627cc -2026-08-12-separate-source-launch-from-build.zh.md: d5c0dc79f8274029c1626310ea5cb97db8421d72 +2026-08-12-separate-source-launch-from-build.md: 2562ee2b0c91c9eb805f409c8d2da0c6dcb8253b +2026-08-12-separate-source-launch-from-build.zh.md: ea33c3815fc4cf02047e09bf9590d3aa6b35da09 diff --git a/.agents/notes/implemented/simplification/2026-08-12-separate-source-launch-from-build.md b/.agents/notes/implemented/simplification/2026-08-12-separate-source-launch-from-build.md index 6cd5d7e3e0..2562ee2b0c 100644 --- a/.agents/notes/implemented/simplification/2026-08-12-separate-source-launch-from-build.md +++ b/.agents/notes/implemented/simplification/2026-08-12-separate-source-launch-from-build.md @@ -14,7 +14,7 @@ Source modules reached through tsx and browser modules reached through built bun The root `dsh` script only runs `node --import tsx/esm apps/cli/src/bin.ts`. `pnpm run build` remains the separate operation that generates package and frontend artifacts. Source users run the build before the first production-like launch and whenever frontend or client-plugin artifacts need refreshing. -Missing frontend and client-plugin artifacts fail at startup with diagnostics that direct the user to `pnpm run build`. The launcher does not validate artifact freshness: existing stale frontend or client-plugin bundles are accepted and can run older browser code until the next build. During client-plugin development, `pnpm run dev:web` keeps those bundles current and activates their hot-reload path. +Missing TypeRT host artifacts fail profile boot through module-resolution errors without a build instruction. Once those host artifacts exist, missing frontend and client-plugin artifacts fail at startup with diagnostics that direct the user to `pnpm run build`. The launcher does not validate artifact freshness: existing stale frontend or client-plugin bundles are accepted and can run older browser code until the next build. After package Node halves have been built once, `pnpm run dev:web` rebuilds only packages that declare `dsh.client`; it keeps client-plugin bundles current and activates their hot-reload path, but does not rebuild the frontend shell. This decision owns build scheduling only. The [tsx ESM source-launch decision](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md) owns TypeScript transformation and workspace resolution, the [source-run decision](2026-08-10-source-run-without-managed-installer.md) owns repository scripts as the supported checkout entry points, and the [personal-config decision](../feature/2026-07-20-dsh-cli-personal-config.md) owns the machine-level configuration layer. diff --git a/.agents/notes/implemented/simplification/2026-08-12-separate-source-launch-from-build.zh.md b/.agents/notes/implemented/simplification/2026-08-12-separate-source-launch-from-build.zh.md index d5c0dc79f8..ea33c3815f 100644 --- a/.agents/notes/implemented/simplification/2026-08-12-separate-source-launch-from-build.zh.md +++ b/.agents/notes/implemented/simplification/2026-08-12-separate-source-launch-from-build.zh.md @@ -14,7 +14,7 @@ TypeScript 源码启动器无需在每次调用前完成整个仓库的构建。 根目录的 `dsh` 脚本只运行 `node --import tsx/esm apps/cli/src/bin.ts`。`pnpm run build` 仍是生成包与前端产物的独立操作。源码用户在首次进行类生产启动前运行构建，并在前端或 Client plugin 产物需要刷新时再次运行。 -前端与 Client plugin 产物缺失时，启动会失败，诊断信息会指示用户运行 `pnpm run build`。启动器不会验证产物是否为最新：已有的过期前端或 Client plugin 组合包仍会被接受，并可能继续运行旧版浏览器代码，直至下次构建。开发 Client plugin 时，`pnpm run dev:web` 会保持这些组合包为最新状态，并启用其热重载路径。 +TypeRT Host 产物缺失时，profile 启动会因不含构建指引的模块解析错误而失败。这些 Host 产物存在后，如果前端或 Client plugin 产物缺失，启动会失败，诊断信息会指示用户运行 `pnpm run build`。启动器不会验证产物是否为最新：已有的陈旧前端或 Client plugin 组合包仍会被接受，并可能继续运行旧版浏览器代码，直至下次构建。各包的 Node 半侧至少构建过一次后，`pnpm run dev:web` 只重建声明了 `dsh.client` 的包；它会保持 Client plugin 组合包为最新状态并启用其热重载路径，但不会重建前端 shell。 本决策仅规定构建调度。[tsx ESM 源码启动决策](../architecture/2026-07-29-dsh-source-launch-tsx-esm.md)规定 TypeScript 转换与 workspace 解析，[源码运行决策](2026-08-10-source-run-without-managed-installer.md)规定以仓库脚本作为受支持的检出入口，[个人配置决策](../feature/2026-07-20-dsh-cli-personal-config.md)规定机器级配置层。 diff --git a/apps/cli/reference/README.i18n.yaml b/apps/cli/reference/README.i18n.yaml index 52208bab8b..4d832a6d47 100644 --- a/apps/cli/reference/README.i18n.yaml +++ b/apps/cli/reference/README.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write apps/cli/reference/README.md -README.md: 811842ba6b30b485b313c8498a1c728bbb9cfc5a -README.zh.md: 43a6599525548ef9b3b4d67c05e1af34cf8f893d +README.md: e8bc99f7b2b15f0679ec268a8e778e815758c00f +README.zh.md: c75c487caa7e2ffd7ca5c4b16f3c6243f0a86f3e diff --git a/apps/cli/reference/README.md b/apps/cli/reference/README.md index 811842ba6b..e8bc99f7b2 100644 --- a/apps/cli/reference/README.md +++ b/apps/cli/reference/README.md @@ -81,4 +81,4 @@ Install external plugin bundles through `dsh plugin --profile add `. The `package.json` script launches `apps/cli/src/bin.ts` with `node --import tsx/esm` without building and forwards every argument. Missing frontend or client-plugin bundles fail at startup with an instruction to run `pnpm run build`; the launcher does not check freshness, so existing stale bundles can run older browser code until rebuilt. The process inherits the launch environment; set `NODE_USE_ENV_PROXY=1` when a supporting Node version must honor `HTTP_PROXY` and `HTTPS_PROXY`. The installed form launches the built `apps/cli/lib/bin.js` without rebuilding the repository. +From the repository root, run `pnpm run build` separately after a fresh checkout and whenever artifacts need updating, then use `pnpm dsh `. The `package.json` script launches `apps/cli/src/bin.ts` with `node --import tsx/esm` without building and forwards every argument. Missing TypeRT host artifacts fail profile boot through module-resolution errors without a build instruction. Once those host artifacts exist, missing frontend or client-plugin bundles fail at startup with an instruction to run `pnpm run build`. The launcher does not check freshness, so existing stale bundles can run older browser code until rebuilt. The process inherits the launch environment; set `NODE_USE_ENV_PROXY=1` when a supporting Node version must honor `HTTP_PROXY` and `HTTPS_PROXY`. The installed form launches the built `apps/cli/lib/bin.js` without rebuilding the repository. diff --git a/apps/cli/reference/README.zh.md b/apps/cli/reference/README.zh.md index 43a6599525..c75c487caa 100644 --- a/apps/cli/reference/README.zh.md +++ b/apps/cli/reference/README.zh.md @@ -81,4 +81,4 @@ dsh web --help ## 源码执行 -请在仓库根目录中，于产物需要更新时单独运行 `pnpm run build`，然后使用 `pnpm dsh `。`package.json` 中的脚本不会构建，而是通过 `node --import tsx/esm` 启动 `apps/cli/src/bin.ts`，并转发所有参数。前端或 Client plugin 组合包缺失时，启动会失败并提示运行 `pnpm run build`；启动器不会检查产物是否为最新，因此已有的过期组合包可能继续运行旧版浏览器代码，直至重新构建。该进程会继承启动环境；当支持环境代理的 Node 版本必须遵循 `HTTP_PROXY` 和 `HTTPS_PROXY` 时，请设置 `NODE_USE_ENV_PROXY=1`。安装形式会直接启动构建后的 `apps/cli/lib/bin.js`，不会重新构建仓库。 +请在仓库根目录中，于全新 checkout 之后及产物需要更新时单独运行 `pnpm run build`，然后使用 `pnpm dsh `。`package.json` 中的脚本不会构建，而是通过 `node --import tsx/esm` 启动 `apps/cli/src/bin.ts`，并转发所有参数。TypeRT Host 产物缺失时，profile 启动会因不含构建指引的模块解析错误而失败。这些 Host 产物存在后，如果前端或 Client plugin 组合包缺失，启动会失败并提示运行 `pnpm run build`。启动器不会检查产物是否为最新，因此已有的陈旧组合包可能继续运行旧版浏览器代码，直至重新构建。该进程会继承启动环境；当支持环境代理的 Node 版本必须遵循 `HTTP_PROXY` 和 `HTTPS_PROXY` 时，请设置 `NODE_USE_ENV_PROXY=1`。安装形式会直接启动构建后的 `apps/cli/lib/bin.js`，不会重新构建仓库。 diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml index 24d78bf62d..aa2566a34b 100644 --- a/docs/development.i18n.yaml +++ b/docs/development.i18n.yaml @@ -2,5 +2,5 @@ # side as of the last confirmed-consistent state. Both languages carry equal authority; # after editing either side, bring the other along and re-record with: # pnpm run verify-translation-pairing --write docs/development.md -development.md: d5bd18f83f6f2f8fd3d507ec133eea4d4e06abef -development.zh.md: 0725cfaad74ec2aa3e52f6523a1dbdbdd9da8a39 +development.md: 8d79756c50f82a840d412f52ee980cb0b505f6f1 +development.zh.md: 285bc0309212694d11077fa590edd199b895fe10 diff --git a/docs/development.md b/docs/development.md index d5bd18f83f..8d79756c50 100644 --- a/docs/development.md +++ b/docs/development.md @@ -126,6 +126,12 @@ The root [contributor instructions](../AGENTS.md#commands) summarize common comm ### Demos +Run the repository build separately before using these source-checkout demos: + +```sh +pnpm run build +``` + The one-shot Headless coding agent needs `DEEPSEEK_API_KEY` in the environment or repo-root `.env`: ```sh diff --git a/docs/development.zh.md b/docs/development.zh.md index 0725cfaad7..285bc03092 100644 --- a/docs/development.zh.md +++ b/docs/development.zh.md @@ -126,6 +126,12 @@ keyless [CI 工作流](../.github/workflows/ci.yml) 将独立门禁分组到若 ### 演示 +从源码 checkout 运行这些演示前，请单独执行仓库构建： + +```sh +pnpm run build +``` + 单次运行的 Headless coding agent 需要环境变量或仓库根目录 `.env` 中的 `DEEPSEEK_API_KEY`： ```sh