From bbde757fcade50772f5cac9c1183fd12bf7fe959 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Yishun=20Tang=20=C2=B7=20CrazyAnt?= Date: Thu, 3 Sep 2026 21:53:46 +0800 Subject: [PATCH] fix: point a new install at the map instead of at CI MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Every documented route out of `init` ended in a CI round trip: commit, push, wait for the run, download the artifact, unzip it, serve the folder. The one command that puts the map on screen was listed only as a suggested package.json script, where nothing says it opens a viewer. So a person could install the tool, finish setup, and never once see the map it exists to draw. `init` now closes by naming that command on both paths — plain and `--github` — in both languages. It goes last deliberately: it is the only instruction that ends with something on screen, and the `--github` path otherwise signs off on a round trip through CI. The README (both languages) now opens its usage section with the same one command and links to it from the header. The Action keeps its section directly below, which is where it belongs: it answers "keep this current", not "show me the thing". Co-Authored-By: Claude Opus 5 --- CHANGELOG.md | 13 +++++++++++++ README.md | 20 +++++++++++++++++--- README.zh-CN.md | 20 ++++++++++++++++---- packages/cli/src/continuous.ts | 9 +++++++-- packages/cli/src/i18n.ts | 7 +++++++ tests/i18n.test.ts | 15 ++++++++++++++- 6 files changed, 74 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 75842c9..7505a57 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,19 @@ All notable changes are documented here. +## Unreleased + +### Changed + +- `init` now ends by naming the one command that puts the map on screen + (`npx agent-runtime-map watch .`), in both languages and on both the plain and + `--github` paths. Every route out of `init` previously ended in a CI round trip + — commit, push, wait, download the artifact, serve it — so someone could finish + setup without ever seeing the map the tool exists to draw. +- The README (both languages) opens the usage section with that same one-command + run instead of the GitHub Action, and the header links to it. The Action stays + documented right below it as the way to keep the map current. + ## 0.9.1 - 2026-09-03 ### Fixed diff --git a/README.md b/README.md index 104b708..e1df089 100644 --- a/README.md +++ b/README.md @@ -12,6 +12,7 @@

Open the live demo + · Map your own project · Install in a repository · npm

@@ -113,11 +114,24 @@ frames, edge-state tokens, and boundary measurement helpers for embedding the same map in another product. See [Visual Components](docs/VISUAL_COMPONENTS.md) for the component contract and integration example. +## Start here: your own map, one command + +Point it at a project and the interactive map opens in your browser. Nothing to +configure, no commit, no CI: + +```bash +npx agent-runtime-map@latest . +``` + +That is the whole first run. Add `watch` instead to keep the map live while you +edit, or `--no-open` to skip the browser. Once you have seen your own map, set up +the section below so it stays current without you asking. + ## Set it up once, GitHub keeps the map current -The primary way to use Agent Runtime Map: install it, run one init, commit the -workflow it generates — and from then on every push and pull request rebuilds the -map on GitHub automatically. +For continuous updates: install it, run one init, commit the workflow it +generates — and from then on every push and pull request rebuilds the map on +GitHub automatically. ```bash npm install --save-dev agent-runtime-map diff --git a/README.zh-CN.md b/README.zh-CN.md index 7725574..a1b1d0b 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -12,7 +12,8 @@

打开在线 Demo - · 接入仓库 + · 一条命令看到自己的图 + · 接入仓库 · npm

@@ -80,10 +81,21 @@ Viewer 采用开源的工程蓝图视觉系统：细密网格画布、图标型 后台可以复用节点、分区边框、链路状态 token 和自动边界计算工具。组件接口和 嵌入示例见 [Visual Components](docs/VISUAL_COMPONENTS.md)。 -## 一次设置，GitHub 持续更新（主路径） +## 从这里开始：一条命令看到自己的图 -主用法：安装、执行一次 init、提交它生成的 workflow——之后每次 push 和 Pull -Request 都会在 GitHub 上自动重建地图。 +指向任意项目，交互式地图就在浏览器里打开。无需配置、无需提交、不用等 CI： + +```bash +npx agent-runtime-map@latest . +``` + +第一次就这一步。想让地图随代码改动一直刷新，把命令换成 `watch`；不想自动开 +浏览器，加 `--no-open`。看过自己的图之后，再按下一节配置持续更新。 + +## 一次设置，GitHub 持续更新 + +需要持续更新时：安装、执行一次 init、提交它生成的 workflow——之后每次 push 和 +Pull Request 都会在 GitHub 上自动重建地图。 ```bash npm install --save-dev agent-runtime-map diff --git a/packages/cli/src/continuous.ts b/packages/cli/src/continuous.ts index 87949dd..51657b0 100644 --- a/packages/cli/src/continuous.ts +++ b/packages/cli/src/continuous.ts @@ -39,7 +39,12 @@ export async function runInit( .map(([name, command]) => ` "${name}": "${command}"`) .join("\n"); process.stdout.write(`${text.initScripts(scripts)}\n`); - if (!options.github) return 0; + // The view hint goes last on both paths: it is the one instruction that ends with + // the map on screen, and `init --github` otherwise closes on a CI round trip. + if (!options.github) { + process.stdout.write(`${text.initViewHint}\n`); + return 0; + } try { const workflow = await initGithubWorkflow(projectPath, { force: options.force }); @@ -50,7 +55,7 @@ export async function runInit( : workflow.outcome === "overwritten" ? text.githubWorkflowOverwritten(workflow.workflowFile) : text.githubWorkflowUpdated(workflow.workflowFile); - process.stdout.write(`${line}\n${text.githubNextSteps}\n`); + process.stdout.write(`${line}\n${text.githubNextSteps}\n${text.initViewHint}\n`); return 0; } catch (error) { if (error instanceof WorkflowModifiedError) { diff --git a/packages/cli/src/i18n.ts b/packages/cli/src/i18n.ts index 12e06a5..8a01cd2 100644 --- a/packages/cli/src/i18n.ts +++ b/packages/cli/src/i18n.ts @@ -26,6 +26,7 @@ export interface CliText { initUnchanged(file: string): string; initScripts(scripts: string): string; initIgnored(rule: string, file: string): string; + initViewHint: string; configWarning(warning: string): string; buildUpdated(dir: string, buildId: string, ms: number): string; buildUnchanged(buildId: string): string; @@ -84,6 +85,11 @@ const TEXT: Record = { githubWorkflowUnchanged: (file) => `${file} is already current; nothing changed.`, githubWorkflowModified: (file) => `${file} exists and has local modifications, so it was NOT touched. Re-run with --force to overwrite it.`, githubNextSteps: `Next: commit agent-runtime-map.config.json and .github/workflows/agent-runtime-map.yml.\nEvery push, pull request, and a weekly schedule will then rebuild the map on GitHub:\nthe run's Summary shows what changed, and the full map (report.html) is attached as an artifact.`, + // Init is the moment someone has just installed and is still at the terminal. + // Without this line every documented path from here ends in CI: commit, push, + // wait, download an artifact, serve it — so a new user can finish setup having + // never once seen the map. The viewer is a single command away; say so here. + initViewHint: `To see the map right now, without committing or waiting for CI:\n npx agent-runtime-map watch .\nThat analyzes this project, opens the interactive viewer in your browser, and keeps\nboth current as you edit. Use \`build .\` for the files alone, without a viewer.`, forceRequiresGithub: "--force is only meaningful together with init --github", }, "zh-CN": { @@ -126,6 +132,7 @@ const TEXT: Record = { githubWorkflowUnchanged: (file) => `${file} 已是最新，未做修改。`, githubWorkflowModified: (file) => `${file} 已存在且包含你的手动修改，因此没有改动它。如需覆盖，请使用 --force 重新执行。`, githubNextSteps: `下一步：提交 agent-runtime-map.config.json 和 .github/workflows/agent-runtime-map.yml。\n之后每次 push、Pull Request 以及每周一次的定时任务都会在 GitHub 上自动重建地图：\n运行的 Summary 会显示变更摘要，完整地图（report.html）会作为 artifact 附在运行结果里。`, + initViewHint: `想立刻看到地图，无需提交、也不用等 CI：\n npx agent-runtime-map watch .\n该命令会分析当前项目，在浏览器中打开交互式界面，并随你改代码自动刷新。\n只要产物文件、不需要界面时，用 \`build .\`。`, forceRequiresGithub: "--force 只能与 init --github 一起使用", }, }; diff --git a/tests/i18n.test.ts b/tests/i18n.test.ts index 67e8e72..66d6c5f 100644 --- a/tests/i18n.test.ts +++ b/tests/i18n.test.ts @@ -3,7 +3,7 @@ import { fileURLToPath } from "node:url"; import { describe, expect, it } from "vitest"; import { analyzeTypeScriptProject } from "@agent-runtime-map/typescript"; import { compileLogicGraph } from "@agent-runtime-map/logic-compiler"; -import { helpText, localizedViewerUrl, resolveCliLocale } from "../packages/cli/src/i18n.js"; +import { cliText, helpText, localizedViewerUrl, resolveCliLocale } from "../packages/cli/src/i18n.js"; import { localizeDiagnostic, localizeFeatureLabel, @@ -25,6 +25,19 @@ describe("localization", () => { expect(localizedViewerUrl("http://127.0.0.1:4173", "zh-CN")).toBe("http://127.0.0.1:4173/?locale=zh-CN"); }); + it("tells a freshly initialized project how to open the viewer, in both languages", () => { + // Every other path out of init ends in CI — commit, push, wait, download an + // artifact, serve it — so without this line a user can finish setup having + // never seen the map. The command has to be runnable as printed. + for (const locale of ["en", "zh-CN"] as const) { + const hint = cliText(locale).initViewHint; + expect(hint).toContain("npx agent-runtime-map watch ."); + // A hint that does not promise a viewer does not fix the problem it exists for. + expect(hint).toMatch(locale === "en" ? /viewer/i : /界面/); + } + expect(cliText("zh-CN").initViewHint).not.toBe(cliText("en").initViewHint); + }); + it("localizes generated graph semantics while preserving code-backed metadata", async () => { const raw = await analyzeTypeScriptProject(fixture); const graph = compileLogicGraph(raw, { maxNodes: 40 });