@lmzhen/dsh-evolution-commands 0.32.3 → 0.32.5

package/README.md

@@ -1,34 +1,23 @@
 # @lmzhen/dsh-evolution-commands
 
-Human commands for the evolution family: it registers the `/evolution …` command surface
-and its help text, and drives the other rows from a command. It adds no automatic
-background behaviour of its own.
+> `/evolution` 命令入口。
 
-## Model surface
+## 你会看到
 
-- **Model-visible:** two direct tokens, both injected as user messages in this session — the `/evolution learn` injection (the full learning guidance) and the `maintain handoff` injection (a one-line POINTER to a finished maintenance report plus a report-only protocol: read the file, report per item, change nothing until the operator approves). **Command output never reaches model history**: `/evolution maintain` and every other subcommand answer in the client only. Everything else adds no tokens.
-- **Prompt prefix / KV cache:** independent of request-prefix construction — it does not alter the assembled prompt or tool list; family rules: `packages/README.md` §"Model-visible prompt prefix and the KV cache".
-- **Mount it?** yes — the `evolution-commands` row, carried by the `evolution-host`, `evolution-all` and `evolution-preset` bundles.
+`/evolution doctor`、`pending`、`curator`、`merge`、`skill history` 等。
 
-## Command reference
+## 什么时候会用到
 
-The full `/evolution` subcommand table is single-sourced in the family README's **Command reference** section (`packages/README.md` in the source repository; it is named here instead of linked because a repo-relative markdown link out of this package would be dead inside the npm published tree). It is rendered from the subcommand registry (`src/registry.ts`, the same single source as the `/evolution` input-declaration hint and the bare-command help output), and `tests/registry.spec.ts` (T-WD2) pins that rendered table byte-for-byte.
+日常管理和排障时。
 
-## Known limitations
+## 默认 / 前提
 
-- No known durable consumer gaps at this time. Runtime contracts are covered by package and boundary tests.
-- **`/evolution maintain` runs in the BACKGROUND (0.19.0).** The command answers with a run id and the scan keeps working: read it with `/evolution maintain report [<id>]` (a run that produced nothing answers "no result" instead of an empty plan) or `/evolution maintain status [<id>]` (in flight plus the recent terminal states). Since 0.20.0 the id may be **omitted** on `report`, `cancel` and `handoff`: it then means the newest run in this home, and an unreadable `runs.json` answers "the run index is not readable" for that form rather than guessing. The run's lifetime belongs to this plugin through `evolution-core`'s run registry, **not** to the request that started it: the desktop shell ends a request at ~305 s (measured four times) while the same scan completes in 949.7 s on the web plane, and `maintainTimeoutMs` (default 600000) bounds the run itself. **Cancelling the request no longer stops the scan** — use `/evolution maintain cancel <id>`, or unmount the row. The plan is written once at settle to `<evolutionHome>/reports/maintain-<runId>.{json,md}`, under the same per-home reports window the curator's reports use.
-- **`maintain handoff` is a SOFT gate (0.20.0, accepted).** The injected protocol asks the model to report and wait for the user's reply, and "what was approved" lives only in that conversation — the family keeps no approval record of its own. Escalate to the existing `evolution-approval` channel when unattended bulk skill edits, a multi-person audit trail, or non-repudiation become requirements.
-- **`maintain handoff` reports a run whose state is not `succeeded` as "ready" when a report file exists (0.20.0, accepted).** A failed or cancelled run writes the same `.json`/`.md` pair (the failure text is the report), so the injection fires and the protocol's first line — read the file — is what tells the model what happened. Tightening it to `succeeded` only is a behavior choice, not a defect fix.
-- **The injected pointer names the `.md` digest without re-probing it (0.20.0, accepted).** `reportDigestPath` swaps the `.json` suffix; the writer emits both files in one settle, so a hand-deleted `.md` beside a live `.json` would name a missing file.
-- **The id-less forms repeat the same resolve skeleton three times (0.20.0, recorded).** `report`, `cancel` and `handoff` each run `syncRuns` → id-less `newestRun` → three-state error reporting; the wording is shared through `unreadableIndex`/`unreadableForId`, the skeleton is not. Extracting one resolver is the next batch's refactor.
-- **Cross-plane run state is eventual, and the shared index is the truth for runs this process does not own (0.19.1).** Two hosts sharing one `DSH_HOME` (the desktop app and a `dsh web` plane) read and write `evolution/runs.json` together. `begin()` resolves only after its row is in that index, so a plane reading the answer "started" finds the run; a run another plane owns is re-read at this plane's **next** read, and it stops being live in exactly two ways — its owner settled it (that terminal state is adopted) or its owner died (converged to `failed(orphan)`, with the reason spelled out). Runs this process owns keep memory as the truth. No timer and no heartbeat sits behind this: 0.19.0 skipped ids it already knew, which left an observing plane reporting `running` forever and refusing its own `maintain` until it restarted. The rule is monotonic on BOTH sides (0.19.2): the read side adopts a terminal row, and the write side never puts a row this process does not own back to `running` over the terminal state its owner wrote — so a settled run cannot be resurrected by this plane's own later write. Two hosts sharing one home must be on the SAME machine: `isProcessAlive(pid)` does not cross machines. Structurally (0.19.3) a row has **exactly one writer — the process that started it**: this process's rows live in its own map, every other row is whatever the index says (rebuilt on each read), and a settled row is **never** shown as running again — a stale writer that puts `running` back is refused on read and repaired on the next write.
-- **① variant form: the `/evolution …` command face is visible in every session** (accepted, not fixed). Commands are registered in scope layers, and the family registers once on the host plane, so a session on a platform original preset still lists the management-only subcommands even though no automatic family behaviour reaches it. The difference and its reasoning are single-sourced in `INSTALL.md` ("Known difference").
+随 all/host/preset 安装自动注册。
 
-**Runtime invariant:** No companion is published. The platform auto-assembles nothing and the family mounts no `<pkg>/invariant` cordis row, so a companion here would never execute (v37 S2.1 / I-3).
+## 边界
 
-## Notes and history
+没有 `commands` 服务时整条命令不存在。
 
-- P2-22 (v11) correction: this package's direct model-visible tokens are the `/evolution learn` injection (the full learning guidance) and — since 0.20.0 — the `maintain handoff` injection (a report pointer plus the report-only protocol). Both are injected as user messages in this session; see **Model surface** above for the current count.
-- **① variant form: the `/evolution …` command face is visible in every session** (accepted, not fixed: 0.3.78).
-- The injection goes through the agent's waking primitive (`followup`, falling back to `inject` when the host lacks it), **called on the agent instance**: the platform's `Agent.followup` is a prototype method (`this.send(...)`), so a detached reference throws and queues nothing (0.3.73 fix; the same shape is pinned by rule N13b in `packages/scripts/verify-arch-guards.mjs`, which masks comments and string literals before matching and self-tests its detector at startup).
+分层/variant 的命令面差异单源在 [INSTALL.md](../INSTALL.md)。
+
+> 旧的 consolidate 已从用户面退役；合并请用 `merge`。

package/lib/index.js

@@ -73,7 +73,7 @@ const RUNTIME_LABELS = {
 */
 const FORM_WORDS = Object.freeze({
 	M1: "完整功能包",
-	M2: "后台自动化包",
+	M2: "人工审批包",
 	M3: "会话预设包",
 	M4: "分层安装"
 });
@@ -238,7 +238,7 @@ function runtimeOf(inputs) {
 			label: RUNTIME_LABELS.runs ?? "运行登记",
 			status: "warn",
 			detail: "running=" + String(inputs.runs.running) + "，orphaned=" + String(inputs.runs.orphaned),
-			remedy: "运行 /evolution runs 收敛遗留运行。"
+			remedy: "运行 /evolution maintain status 查看并收敛遗留运行。"
 		} : {
 			key: "runs",
 			label: RUNTIME_LABELS.runs ?? "运行登记",
@@ -392,9 +392,10 @@ async function assembleDoctorInputs(ctx, extras = {}) {
 	const hasPreset = bundles.some((name) => name.endsWith("dsh-evolution-preset"));
 	const hasHost = bundles.some((name) => name.endsWith("dsh-evolution-host"));
 	const hasFamilyPreset = listed.some((entry) => typeof entry.id === "string" && EVOLUTION_PRESET_IDS.includes(entry.id));
+	const humanGated = get("evolutionApproval")?.isEnabled === true;
 	const detectedForm = hasAll || hasPreset ? {
-		id: "M1",
-		evidence: [hasAll ? "bundle dsh-evolution-all installed" : "bundle dsh-evolution-preset installed"],
+		id: humanGated ? "M2" : "M1",
+		evidence: [hasAll ? "bundle dsh-evolution-all installed" : "bundle dsh-evolution-preset installed", ...humanGated ? ["approval.enabled: true"] : []],
 		confidence: "declared"
 	} : hasHost ? hasFamilyPreset ? {
 		id: "M4",
@@ -1446,8 +1447,9 @@ async function diagnose(ctx, options = {}) {
 		pendingCount = null;
 		executingCount = null;
 	}
-	const installForm = full ? "full" : preset ? "preset" : layered ? "layered" : host ? "host" : presetDirInstalled ? "preset-only" : "none";
-	const deploymentForm = installForm === "layered" ? "variant" : installForm === "full" || installForm === "preset" ? "attach" : installForm === "host" ? "host-only" : installForm === "preset-only" ? "preset-only" : "none";
+	const humanGated = ctx.get("evolutionApproval")?.isEnabled === true;
+	const installForm = full || preset ? humanGated ? "human-gated" : full ? "full" : "preset" : layered ? "layered" : host ? "host" : presetDirInstalled ? "preset-only" : "none";
+	const deploymentForm = installForm === "layered" ? "variant" : installForm === "full" || installForm === "preset" || installForm === "human-gated" ? "attach" : installForm === "host" ? "host-only" : installForm === "preset-only" ? "preset-only" : "none";
 	const mountConflicts = conflicts.filter((row) => !row.includes("DEGRADED"));
 	const undecidable = mountConflicts.length !== conflicts.length;
 	const scopedProbe = {
@@ -1483,7 +1485,7 @@ async function diagnose(ctx, options = {}) {
 		if (row.status !== "differs") continue;
 		actions.push(`Preset row for base "${row.base}" in ${row.destination} DIFFERS from a fresh generation — it is an install-time snapshot; re-run the installer (/evolution preset install) to regenerate`);
 	}
-	const view = buildDoctorView(await assembleDoctorInputs(ctx));
+	const view = buildDoctorView(await assembleDoctorInputs(ctx, options.runs === void 0 ? {} : { runs: options.runs }));
 	const merge = await mergeDoctorLine(ctx);
 	if (merge.status !== "ok" && merge.remedy !== void 0) actions.push("合并行：" + merge.remedy);
 	return {
@@ -2270,7 +2272,10 @@ function parseCommand(defs, argv) {
 		help: true
 	};
 	const candidates = defs.filter((item) => item.words.includes(verb));
-	const def = candidates.find((item) => rest.filter((token) => token.startsWith("--")).every((token) => item.flags.some((flag) => flag.name === token.slice(2)))) ?? candidates[0];
+	const def = candidates.find((item) => rest.filter((token) => token.startsWith("--")).every((token) => {
+		const name = token.slice(2).split("=")[0] ?? "";
+		return item.flags.some((flag) => flag.name === name);
+	})) ?? candidates[0];
 	if (def === void 0) return {
 		ok: false,
 		code: "usage",
@@ -2284,15 +2289,27 @@ function parseCommand(defs, argv) {
 			positional.push(token);
 			continue;
 		}
-		const name = token.slice(2);
+		const eq = token.indexOf("=");
+		const name = (eq < 0 ? token : token.slice(0, eq)).slice(2);
+		const inline = eq < 0 ? void 0 : token.slice(eq + 1);
 		const flag = def.flags.find((item) => item.name === name);
 		if (flag === void 0) return {
 			ok: false,
 			code: "usage",
 			message: "unknown flag: --" + name
 		};
-		if (flag.kind === "boolean") values[name] = true;
-		else {
+		if (flag.kind === "boolean") {
+			if (inline !== void 0) return {
+				ok: false,
+				code: "usage",
+				message: "flag does not take a value: --" + name
+			};
+			values[name] = true;
+		} else {
+			if (inline !== void 0) {
+				values[name] = inline;
+				continue;
+			}
 			const value = rest[index + 1];
 			if (value === void 0 || value.startsWith("--")) return {
 				ok: false,
@@ -2573,7 +2590,7 @@ function apply(ctx, rawConfig = {}) {
 			};
 			const approval = ctx.get("evolutionApproval");
 			const pendingParsed = parseSubcommand(input);
-			if (!isParseFailure(pendingParsed) && pendingParsed.name === "pending") {
+			if (!isParseFailure(pendingParsed) && pendingParsed.name === "pending" && pendingParsed.positionals.length === 0 && [...pendingParsed.flags.keys()].every((flag) => flag === "detail")) {
 				if (!approval) return err(errorText("e-301-approval-service-not-mounted"));
 				const listed = [...await approval.list("pending"), ...await approval.list("executing")];
 				const pending = [...new Map(listed.map((row) => [row.id, row])).values()];
@@ -3331,7 +3348,7 @@ function apply(ctx, rawConfig = {}) {
 				return ok(replay.compare().report);
 			}
 			const paramsParsed = parseSubcommand(input);
-			if (!isParseFailure(paramsParsed) && paramsParsed.name === "params") {
+			if (!isParseFailure(paramsParsed) && paramsParsed.name === "params" && paramsParsed.positionals.length === 0 && [...paramsParsed.flags.keys()].every((flag) => flag === "group" || flag === "json")) {
 				const provider = ctx.get("settings");
 				const sections = /* @__PURE__ */ new Map();
 				if (provider?.describe !== void 0) try {
@@ -3446,7 +3463,8 @@ function apply(ctx, rawConfig = {}) {
 				} };
 				const report = await diagnose(ctx, {
 					home: evolutionRoot(),
-					...mounted
+					...mounted,
+					runs: doctorRuns()
 				});
 				if (input === "doctor --json") return ok(JSON.stringify(report.view, null, 2));
 				return ok(renderDoctorText(report));

package/lib/types/doctor.d.ts

@@ -73,7 +73,7 @@ export interface DoctorReport {
      * per-session install reported `none` and the action ladder advised
      * installing `all` — which double-mounts the preset's model rows (the
      * exact conflict this report flags). */
-    installForm: 'full' | 'host' | 'preset' | 'layered' | 'preset-only' | 'none';
+    installForm: 'full' | 'human-gated' | 'host' | 'preset' | 'layered' | 'preset-only' | 'none';
     /** The PRODUCT form the install form implies (0.3.77, C axis). `variant` =
      * session-level opt-in: the model tools live in the Evolution preset, so a
      * session on any platform original preset carries none of the family and the
@@ -166,6 +166,10 @@ export declare function diagnose(ctx: {
 }, options?: {
     home?: string;
     mounted?: MountedProfile;
+    runs?: {
+        readonly running: number;
+        readonly orphaned: number;
+    };
 }): Promise<DoctorReport>;
 /**
  * W8-S7: the doctor's text face, VIEW-FIRST.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lmzhen/dsh-evolution-commands",
   "description": "Human commands for the evolution family (/evolution pending|curator|maintain|doctor) (community build)",
-  "version": "0.32.3",
+  "version": "0.32.5",
   "publishConfig": {
     "access": "public"
   },
@@ -27,13 +27,13 @@
   "license": "MIT",
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.5",
-    "@lmzhen/dsh-evolution-approval": "^0.32.3",
-    "@lmzhen/dsh-evolution-core": "^0.32.3",
-    "@lmzhen/dsh-evolution-maintenance": "^0.32.3",
-    "@lmzhen/dsh-evolution-state-storage": "^0.32.3"
+    "@lmzhen/dsh-evolution-approval": "^0.32.5",
+    "@lmzhen/dsh-evolution-core": "^0.32.5",
+    "@lmzhen/dsh-evolution-maintenance": "^0.32.5",
+    "@lmzhen/dsh-evolution-state-storage": "^0.32.5"
   },
   "optionalDependencies": {
-    "@lmzhen/dsh-evolution-agent-preset": "^0.32.3"
+    "@lmzhen/dsh-evolution-agent-preset": "^0.32.5"
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.5",