@hadooppei/hwcode 0.2.0 → 0.2.4

package/.env.example

@@ -1,10 +1,5 @@
-# Keep real credentials outside version control.
-# Local provider credentials. Model addresses and capabilities live in
-# .pi/model-providers.json.
-PI_LOCAL_MODEL_API_KEY=local
-
-# Optional credential used as the default when logging in to the configurable
-# "hw" provider. Leave unset for a keyless local endpoint.
+# Keep real credentials outside version control. Set this value to provide the
+# required "hw" credential through the environment, or enter it through /login.
 # HW_API_KEY=
 
 # OPENAI_API_KEY=

package/.pi/extensions/cloud.ts

@@ -8,7 +8,11 @@ import { CURSOR_MARKER, Input, type Component, type TUI } from "@earendil-works/
 
 import { checkProviderCli, formatValidationFailure, prepareCloudExecution, validateCloudCredentials, type TemporaryCredentialStore } from "../lib/cloud/adapters.ts";
 import { runProcess, truncateOutput, type ProcessResult } from "../lib/cloud/process.ts";
-import { expandCloudPromptTemplate, listCloudPromptTemplates, saveCloudPromptTemplate, type CloudPromptTemplate } from "../lib/cloud/templates.ts";
+import {
+	cloudPromptTemplateSource, expandCloudPromptTemplate, listCloudPromptTemplates, saveCloudPromptTemplate, updateCloudPromptTemplate,
+	type CloudPromptTemplate,
+} from "../lib/cloud/templates.ts";
+import { saveCloudWorkflowTemplate } from "../lib/cloud/template-save.ts";
 import {
 	CLOUD_EXECUTABLES, CLOUD_PROVIDERS, classifyCloudOperation, containsCloudCommand,
 	getCloudProvider, inaccessibleCloudCliMessage, missingCloudCliMessage, redactCredentialValues,
@@ -22,7 +26,7 @@ import {
 import { canonicalizeWorkspaceRoot } from "../lib/workflow-guard.ts";
 import { modelConfigurationIssue } from "../lib/models/readiness.ts";
 import {
-	WORKFLOW_EXTERNAL_AUDIT_TYPE, WORKFLOW_STATE_TYPE, activeWorkflow, updateWorkflowState,
+	WORKFLOW_EXTERNAL_AUDIT_TYPE, WORKFLOW_STATE_TYPE, activeWorkflow, createCloudWorkflowState, updateWorkflowState,
 	type CloudWorkflowDetails, type WorkflowState,
 } from "../lib/workflows/state.ts";
 import { evaluateCommandArgumentsAccess } from "../lib/workspace/access-policy.ts";
@@ -82,6 +86,13 @@ function cloudDetails(state: WorkflowState): CloudWorkflowDetails | undefined {
 	return state.mode === "cloud" ? state.details : undefined;
 }
 
+function formatTemplateTime(value: string): string {
+	const date = new Date(value);
+	if (Number.isNaN(date.valueOf())) return value;
+	const pad = (part: number) => String(part).padStart(2, "0");
+	return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())} ${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`;
+}
+
 function restoreCloudWorkflow(ctx: ExtensionContext): WorkflowState | undefined {
 	const state = activeWorkflow(ctx.sessionManager.getEntries());
 	return state?.mode === "cloud" && state.details ? state : undefined;
@@ -121,18 +132,6 @@ function appendWorkflowState(pi: ExtensionAPI, state: WorkflowState): void {
 	pi.appendEntry<WorkflowState>(WORKFLOW_STATE_TYPE, state);
 }
 
-function createCloudWorkflowState(root: string, vendor: CloudVendorId, deploy: boolean, request: string): WorkflowState {
-	const now = new Date().toISOString();
-	return {
-		version: 2, status: "active", mode: "cloud", root, phase: "connected",
-		activatedAt: now, updatedAt: now,
-		details: {
-			vendor, deployCurrentProject: deploy, request, allowNonDeleteChanges: false,
-			failedApproaches: [], successfulSteps: [], terminalFailure: false,
-		},
-	};
-}
-
 async function secretInput(ctx: ExtensionContext, title: string): Promise<string | undefined> {
 	if (ctx.mode !== "tui") return undefined;
 	return ctx.ui.custom<string | undefined>((tui, theme, _keybindings, done) => new MaskedInput(tui, theme, title, done));
@@ -190,7 +189,10 @@ async function collectCredentials(vendor: CloudVendorId, root: string, ctx: Exte
 
 function activationPrompt(state: WorkflowState): string {
 	const details = cloudDetails(state)!;
-	return `/skill:hwcode-cloud HWCode Cloud workflow activated.\n\nLocked project root: ${state.root}\nCloud provider: ${getCloudProvider(details.vendor).label}\nDeploy current project: ${details.deployCurrentProject ? "yes" : "no"}\nUser objective and reusable guidance:\n${details.request}\n\nCredentials were validated and remain outside model context. Use hwcode_cloud_exec for every cloud or infrastructure command.`;
+	const guidance = details.templateGuidance
+		? `\n\nReusable template guidance (${details.sourceTemplate?.name ?? "saved template"}):\n${details.templateGuidance}`
+		: "";
+	return `/skill:hwcode-cloud HWCode Cloud workflow activated.\n\nLocked project root: ${state.root}\nCloud provider: ${getCloudProvider(details.vendor).label}\nDeploy current project: ${details.deployCurrentProject ? "yes" : "no"}\nUser objective:\n${details.request}${guidance}\n\nCredentials were validated and remain outside model context. Use hwcode_cloud_exec for every cloud or infrastructure command.`;
 }
 
 async function approveOperation(operation: CloudOperation, params: { command: string; args: string[]; intent: string }, state: WorkflowState, ctx: ExtensionContext): Promise<"allow" | "allow-session" | "deny"> {
@@ -263,11 +265,13 @@ export default function cloudExtension(pi: ExtensionAPI) {
 			notify(ctx, "还没有本地 Cloud Prompt Template。成功执行任务后使用 /hwcode-cloud-save-template 保存。", "warning");
 			return undefined;
 		}
+		const labels = templates.map((template) => `${template.name} · ${formatTemplateTime(template.updatedAt)}`);
 		const selected = await ctx.ui.select(
 			"选择已验证的 Cloud Prompt Template",
-			templates.map((template) => `${template.id} — ${template.description}`),
+			labels,
 		);
-		return templates.find((template) => selected?.startsWith(`${template.id} —`));
+		const selectedIndex = selected ? labels.indexOf(selected) : -1;
+		return selectedIndex >= 0 ? templates[selectedIndex] : undefined;
 	}
 
 	async function activate(args: string, ctx: ExtensionCommandContext, initialTemplate?: CloudPromptTemplate): Promise<void> {
@@ -307,6 +311,7 @@ export default function cloudExtension(pi: ExtensionAPI) {
 		let vendor: CloudVendorId;
 		let deployCurrentProject: boolean;
 		let request: string;
+		let templateGuidance: string | undefined;
 		if (resumedState) {
 			const details = cloudDetails(resumedState)!;
 			vendor = details.vendor;
@@ -315,7 +320,8 @@ export default function cloudExtension(pi: ExtensionAPI) {
 		} else if (template) {
 			vendor = template.vendor;
 			deployCurrentProject = template.deployCurrentProject;
-			request = expandCloudPromptTemplate(template, args);
+			request = template.objective || template.name;
+			templateGuidance = expandCloudPromptTemplate(template, args);
 		} else {
 			const label = await ctx.ui.select("选择需要对接的云计算厂商", CLOUD_PROVIDERS.map((provider) => provider.label));
 			if (!label) return;
@@ -378,7 +384,16 @@ export default function cloudExtension(pi: ExtensionAPI) {
 		);
 		cleanupCredentialDirectories();
 		activeCredentials = credentials;
-		activeState = resumedState ?? createCloudWorkflowState(root, vendor, deployCurrentProject, request);
+		activeState = resumedState ?? createCloudWorkflowState(
+			root,
+			vendor,
+			deployCurrentProject,
+			request,
+			template && templateGuidance ? {
+				source: cloudPromptTemplateSource(template),
+				guidance: templateGuidance,
+			} : undefined,
+		);
 		appendWorkflowState(pi, activeState);
 		notify(ctx, `${vendorLabel} 连接成功。凭据已加密保存，项目根目录锁定为 ${root}。`);
 		pi.sendUserMessage(activationPrompt(activeState), { expandPromptTemplates: true });
@@ -404,15 +419,42 @@ export default function cloudExtension(pi: ExtensionAPI) {
 				notify(ctx, "当前 Cloud workflow 还没有成功执行步骤，无法生成可复用模板。", "warning");
 				return;
 			}
-			const name = args.trim() || (await ctx.ui.input("模板名称", details.request.slice(0, 48)))?.trim();
-			if (!name) return;
-			const notes = (await ctx.ui.editor("补充成功经验、必要前置条件或易错点（可留空；不得包含凭据）", ""))?.trim();
-			const safeNotes = activeCredentials && notes ? redactCredentialValues(notes, activeCredentials) : notes;
-			const safeState = activeCredentials
-				? { ...activeState, details: { ...details, request: redactCredentialValues(details.request, activeCredentials) } }
-				: activeState;
-			const template = saveCloudPromptTemplate(name, safeState, undefined, safeNotes);
-			notify(ctx, `已保存模板 ${template.id} 到 ${template.path}。使用 /hwcode-cloud-template 可立即复用。`);
+
+			const result = await saveCloudWorkflowTemplate({
+				state: activeState,
+				requestedName: args,
+				redact: activeCredentials
+					? (value) => redactCredentialValues(value, activeCredentials!)
+					: undefined,
+				interaction: {
+					async chooseSourceAction(source) {
+						const updateLabel = `更新原模板「${source.name}」`;
+						const choice = await ctx.ui.select(
+							`当前会话关联模板「${details.sourceTemplate?.name ?? source.name}」`,
+							[updateLabel, "创建新模板", "取消"],
+						);
+						if (!choice || choice === "取消") return "cancel";
+						return choice === updateLabel ? "update" : "create";
+					},
+					inputName: (defaultName) => ctx.ui.input("模板名称", defaultName),
+					editNotes: (initialNotes) => ctx.ui.editor(
+						"补充必要前置条件、成功经验及必须避免的高消耗错误路径（可留空；不得包含凭据）",
+						initialNotes,
+					),
+					sourceMissing(sourceName) {
+						notify(ctx, `本次使用的原模板「${sourceName}」已不存在，将创建新模板。`, "warning");
+					},
+				},
+				store: {
+					list: () => listCloudPromptTemplates(),
+					create: (name, state, notes) => saveCloudPromptTemplate(name, state, undefined, notes),
+					update: (template, state, notes) => updateCloudPromptTemplate(template, state, notes),
+				},
+			});
+			if (result.status === "cancelled") return;
+			activeState = replaceDetails(activeState, result.details);
+			const action = result.action === "updated" ? "已更新" : "已创建";
+			notify(ctx, `${action}模板「${result.template.name}」（${formatTemplateTime(result.template.updatedAt)}）。使用 /hwcode-cloud-template 可立即复用。`);
 		},
 	});
 

package/.pi/lib/cloud/template-save.ts

@@ -0,0 +1,107 @@
+import type { CloudPromptTemplate } from "./templates.ts";
+import { cloudPromptTemplateSource } from "./templates.ts";
+import type { CloudWorkflowDetails, WorkflowState } from "../workflows/state.ts";
+
+export type CloudTemplateSourceAction = "update" | "create" | "cancel";
+export type CloudTemplateSaveStage = "source-action" | "name" | "notes";
+
+export interface CloudTemplateSaveInteraction {
+  chooseSourceAction(source: CloudPromptTemplate): Promise<CloudTemplateSourceAction | undefined>;
+  inputName(defaultName: string): Promise<string | undefined>;
+  editNotes(initialNotes: string): Promise<string | undefined>;
+  sourceMissing(sourceName: string): void | Promise<void>;
+}
+
+export interface CloudTemplateStore {
+  list(): CloudPromptTemplate[];
+  create(name: string, state: WorkflowState, notes: string): CloudPromptTemplate;
+  update(template: CloudPromptTemplate, state: WorkflowState, notes: string): CloudPromptTemplate;
+}
+
+export type CloudTemplateSaveResult =
+  | { status: "cancelled"; stage: CloudTemplateSaveStage }
+  | {
+    status: "saved";
+    action: "created" | "updated";
+    template: CloudPromptTemplate;
+    details: CloudWorkflowDetails;
+  };
+
+export interface SaveCloudWorkflowTemplateOptions {
+  state: WorkflowState;
+  requestedName?: string;
+  interaction: CloudTemplateSaveInteraction;
+  store: CloudTemplateStore;
+  redact?: (value: string) => string;
+}
+
+/**
+ * Coordinates the save/update decision without depending on Pi UI or filesystem APIs.
+ * Storage is invoked only after every interactive step succeeds, so cancellation and
+ * storage failures cannot partially change the workflow state.
+ */
+export async function saveCloudWorkflowTemplate(
+  options: SaveCloudWorkflowTemplateOptions,
+): Promise<CloudTemplateSaveResult> {
+  const { state, interaction, store } = options;
+  if (state.mode !== "cloud" || !state.details) throw new Error("Cloud workflow state is required");
+  if (state.details.successfulSteps.length === 0) {
+    throw new Error("No successful Cloud execution steps are available to summarize");
+  }
+
+  const details = state.details;
+  let target: CloudPromptTemplate | undefined;
+  if (details.sourceTemplate) {
+    target = store.list().find((template) => template.id === details.sourceTemplate?.id);
+    if (target) {
+      const sourceAction = await interaction.chooseSourceAction(target);
+      if (!sourceAction || sourceAction === "cancel") {
+        return { status: "cancelled", stage: "source-action" };
+      }
+      if (sourceAction === "create") target = undefined;
+    } else {
+      await interaction.sourceMissing(details.sourceTemplate.name);
+    }
+  }
+
+  let name = target?.name;
+  if (!name) {
+    const suppliedName = options.requestedName?.trim();
+    if (suppliedName) {
+      name = suppliedName;
+    } else {
+      const defaultName = details.sourceTemplate
+        ? `${details.sourceTemplate.name} 副本`
+        : details.request.slice(0, 48);
+      name = (await interaction.inputName(defaultName))?.trim();
+    }
+    if (!name) return { status: "cancelled", stage: "name" };
+  }
+
+  const notes = await interaction.editNotes(target?.notes ?? "");
+  if (notes === undefined) return { status: "cancelled", stage: "notes" };
+
+  const redact = options.redact ?? ((value: string) => value);
+  const safeName = redact(name);
+  const safeNotes = redact(notes.trim());
+  const safeState: WorkflowState = {
+    ...state,
+    details: {
+      ...details,
+      request: redact(details.request),
+      templateGuidance: details.templateGuidance === undefined
+        ? undefined
+        : redact(details.templateGuidance),
+    },
+  };
+  const template = target
+    ? store.update(target, safeState, safeNotes)
+    : store.create(safeName, safeState, safeNotes);
+
+  return {
+    status: "saved",
+    action: target ? "updated" : "created",
+    template,
+    details: { ...details, sourceTemplate: cloudPromptTemplateSource(template) },
+  };
+}

package/.pi/lib/cloud/templates.ts

@@ -1,20 +1,33 @@
-import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { basename, join } from "node:path";
+import { basename, dirname, join } from "node:path";
 
 import { getCloudProvider, isCloudVendorId, type CloudVendorId } from "../cloud-providers.ts";
-import type { WorkflowState } from "../workflows/state.ts";
+import type { CloudTemplateSource, WorkflowState } from "../workflows/state.ts";
 
 export interface CloudPromptTemplate {
   id: string;
+  name: string;
   description: string;
+  createdAt: string;
+  updatedAt: string;
   vendor: CloudVendorId;
   deployCurrentProject: boolean;
   objective: string;
+  notes: string;
   body: string;
   path: string;
 }
 
+export function cloudPromptTemplateSource(template: CloudPromptTemplate): CloudTemplateSource {
+  return {
+    id: template.id,
+    name: template.name,
+    createdAt: template.createdAt,
+    updatedAt: template.updatedAt,
+  };
+}
+
 export function defaultCloudPromptDirectory(home = homedir()): string {
   return join(home, ".hwcode", "cloud", "prompts");
 }
@@ -40,6 +53,22 @@ function frontmatterValue(text: string, key: string): string | undefined {
   }
 }
 
+function normalizeTimestamp(value: string | undefined, fallback: string): string {
+  if (!value) return fallback;
+  const date = new Date(value);
+  return Number.isNaN(date.valueOf()) ? fallback : date.toISOString();
+}
+
+function legacyTemplateName(id: string): string {
+  const words = id.replace(/^hwcloud-/u, "").split("-").filter(Boolean);
+  if (words.length === 0) return "Legacy Cloud Template";
+  return words.map((word) => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+
+function cleanTemplateName(value: string): string {
+  return value.replace(/[\r\n]+/gu, " ").replace(/\s+/gu, " ").trim().slice(0, 80);
+}
+
 export function parseCloudPromptTemplate(path: string): CloudPromptTemplate | undefined {
   const text = readFileSync(path, "utf8");
   const match = text.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/u);
@@ -48,12 +77,20 @@ export function parseCloudPromptTemplate(path: string): CloudPromptTemplate | un
   const vendorValue = frontmatterValue(metadata, "hwcode-cloud-vendor");
   if (!vendorValue || !isCloudVendorId(vendorValue)) return undefined;
   const id = basename(path, ".md");
+  const stats = statSync(path);
+  const modifiedAt = stats.mtime.toISOString();
+  const bornAt = stats.birthtimeMs > 0 ? stats.birthtime.toISOString() : modifiedAt;
+  const name = cleanTemplateName(frontmatterValue(metadata, "hwcode-cloud-name") ?? "") || legacyTemplateName(id);
   return {
     id,
-    description: frontmatterValue(metadata, "description") ?? id,
+    name,
+    description: frontmatterValue(metadata, "description") ?? name,
+    createdAt: normalizeTimestamp(frontmatterValue(metadata, "hwcode-cloud-created-at"), bornAt),
+    updatedAt: normalizeTimestamp(frontmatterValue(metadata, "hwcode-cloud-updated-at"), modifiedAt),
     vendor: vendorValue,
     deployCurrentProject: frontmatterValue(metadata, "hwcode-cloud-deploy") === "true",
     objective: frontmatterValue(metadata, "hwcode-cloud-objective") ?? "",
+    notes: frontmatterValue(metadata, "hwcode-cloud-notes") ?? "",
     body: match[2].trim(),
     path,
   };
@@ -67,7 +104,7 @@ export function listCloudPromptTemplates(
     .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
     .map((entry) => parseCloudPromptTemplate(join(directory, entry.name)))
     .filter((template): template is CloudPromptTemplate => Boolean(template))
-    .sort((left, right) => left.description.localeCompare(right.description));
+    .sort((left, right) => right.updatedAt.localeCompare(left.updatedAt) || left.name.localeCompare(right.name));
 }
 
 export function expandCloudPromptTemplate(template: CloudPromptTemplate, argumentsText: string): string {
@@ -79,6 +116,10 @@ function inlineCode(value: string): string {
   return value.replace(/[\r\n]+/gu, " ").replaceAll("`", "\\`");
 }
 
+function singleLine(value: string): string {
+  return value.replace(/[\r\n]+/gu, " ").replace(/\s+/gu, " ").trim();
+}
+
 export function renderCloudPromptTemplate(state: WorkflowState, notes = ""): string {
   if (state.mode !== "cloud" || !state.details) throw new Error("Cloud workflow state is required");
   const details = state.details;
@@ -87,62 +128,121 @@ export function renderCloudPromptTemplate(state: WorkflowState, notes = ""): str
   }
   const provider = getCloudProvider(details.vendor);
   const steps = details.successfulSteps.map((step, index) => (
-    `${index + 1}. [${step.operation}] ${step.intent}\n`
-      + `   - Approach: ${step.approach}\n`
-      + `   - Reference command: \`${inlineCode([step.command, ...step.args].join(" "))}\``
+    `${index + 1}. [${step.operation}] ${singleLine(step.intent)}\n`
+      + `   - Validated approach: ${singleLine(step.approach)}\n`
+      + `   - Known-good command and path: \`${inlineCode([step.command, ...step.args].join(" "))}\``
   )).join("\n");
+  const failedPaths = details.failedApproaches.length > 0
+    ? details.failedApproaches.map((failure, index) => (
+      `${index + 1}. **DO NOT RETRY:** ${singleLine(failure.approach)}\n`
+        + `   - Recorded failure: ${singleLine(failure.reason)}`
+    )).join("\n")
+    : "No failed execution paths were recorded for this run.";
   return [
-    "Execute a reusable HWCode Cloud task based on a previously successful run.",
+    "Execute this HWCode Cloud task from a layered record of a previously successful run.",
+    "",
+    "## Layer 1 — Stable intent and boundaries",
     "",
     `Preferred provider: ${provider.label}`,
     `Deploy current project: ${details.deployCurrentProject ? "yes" : "no"}`,
     `Objective pattern: ${details.request}`,
     "",
-    "Known successful execution sequence (reference only; re-check current account state before reuse):",
+    "Preserve the objective, provider boundary, credential isolation, resource approvals, and deletion confirmations. Adapt only environment-specific values.",
+    "",
+    "## Layer 2 — Preconditions and operator knowledge",
+    "",
+    "Start with read-only discovery. Re-check the active account, region, project, resource state, tool versions, and workspace paths before making changes.",
+    ...(notes ? ["", "Validated prerequisites, lessons, and expensive pitfalls:", notes] : []),
+    "",
+    "## Layer 3 — Preferred validated execution path",
+    "",
+    "Use this path first and preserve its order unless read-only evidence requires an adaptation. The commands and paths below are the known-good reference; do not replace them with speculative alternatives.",
+    "",
     steps,
     "",
-    ...(notes ? ["Validated-run notes and pitfalls:", notes, ""] : []),
-    "Start with read-only discovery and adapt account, region, project, resource names, versions, and paths to the current environment. Present the plan and obtain all normal HWCode Cloud approvals. Never copy credentials or assume resources from the previous run still exist.",
+    "## Layer 4 — Expensive failed paths to avoid",
+    "",
+    "Do not retry any path below, including renamed or parameter-only variants. Reconsider one only when the user explicitly directs it after reviewing the recorded failure.",
+    "",
+    failedPaths,
+    "",
+    "## Layer 5 — Execution contract",
+    "",
+    "Present the adapted plan and obtain all normal HWCode Cloud approvals. Never copy credentials, assume old resources still exist, or skip current-state verification.",
     "If HWCode Cloud is not active, do not run cloud commands directly; ask the user to start this template through /hwcode-cloud-template.",
     "",
     "Additional instructions: ${@:-Use the objective and successful sequence above.}",
   ].join("\n");
 }
 
-export function saveCloudPromptTemplate(
-  requestedName: string,
+function renderTemplateFile(
+  name: string,
   state: WorkflowState,
-  directory = defaultCloudPromptDirectory(),
-  notes = "",
-): CloudPromptTemplate {
+  notes: string,
+  createdAt: string,
+  updatedAt: string,
+): string {
   if (state.mode !== "cloud" || !state.details) throw new Error("Cloud workflow state is required");
-  const idBase = `hwcloud-${slugify(requestedName || state.details.request)}`;
   const body = renderCloudPromptTemplate(state, notes);
-  const description = `Reuse successful ${getCloudProvider(state.details.vendor).label} workflow: ${state.details.request.slice(0, 80)}`;
-  const content = [
+  return [
     "---",
-    `description: ${JSON.stringify(description)}`,
+    `description: ${JSON.stringify(name)}`,
     'argument-hint: "[additional instructions]"',
+    `hwcode-cloud-name: ${JSON.stringify(name)}`,
+    `hwcode-cloud-created-at: ${JSON.stringify(createdAt)}`,
+    `hwcode-cloud-updated-at: ${JSON.stringify(updatedAt)}`,
     `hwcode-cloud-vendor: ${JSON.stringify(state.details.vendor)}`,
     `hwcode-cloud-deploy: ${state.details.deployCurrentProject}`,
     `hwcode-cloud-objective: ${JSON.stringify(state.details.request)}`,
+    `hwcode-cloud-notes: ${JSON.stringify(notes)}`,
     "---",
     body,
     "",
   ].join("\n");
+}
 
+function writeTemplateFile(path: string, content: string): void {
+  const directory = dirname(path);
   mkdirSync(directory, { recursive: true, mode: 0o700 });
   chmodSync(directory, 0o700);
+  const temporaryPath = `${path}.${process.pid}.tmp`;
+  writeFileSync(temporaryPath, content, { encoding: "utf8", mode: 0o600 });
+  chmodSync(temporaryPath, 0o600);
+  renameSync(temporaryPath, path);
+  chmodSync(path, 0o600);
+}
+
+export function saveCloudPromptTemplate(
+  requestedName: string,
+  state: WorkflowState,
+  directory = defaultCloudPromptDirectory(),
+  notes = "",
+  savedAt = new Date(),
+): CloudPromptTemplate {
+  if (state.mode !== "cloud" || !state.details) throw new Error("Cloud workflow state is required");
+  const name = cleanTemplateName(requestedName);
+  if (!name) throw new Error("Cloud Prompt Template name is required");
+  const idBase = `hwcloud-${slugify(name)}`;
+  const timestamp = savedAt.toISOString();
+  const content = renderTemplateFile(name, state, notes, timestamp, timestamp);
   let id = idBase;
   let path = join(directory, `${id}.md`);
   for (let suffix = 2; existsSync(path); suffix++) {
     id = `${idBase}-${suffix}`;
     path = join(directory, `${id}.md`);
   }
-  const temporaryPath = `${path}.${process.pid}.tmp`;
-  writeFileSync(temporaryPath, content, { encoding: "utf8", mode: 0o600 });
-  chmodSync(temporaryPath, 0o600);
-  renameSync(temporaryPath, path);
-  chmodSync(path, 0o600);
+  writeTemplateFile(path, content);
   return parseCloudPromptTemplate(path)!;
 }
+
+export function updateCloudPromptTemplate(
+  template: CloudPromptTemplate,
+  state: WorkflowState,
+  notes = template.notes,
+  updatedAt = new Date(),
+): CloudPromptTemplate {
+  const timestamp = updatedAt.toISOString();
+  const content = renderTemplateFile(template.name, state, notes, template.createdAt, timestamp);
+  writeTemplateFile(template.path, content);
+  return parseCloudPromptTemplate(template.path)!;
+}

package/.pi/lib/models/provider-config.ts

@@ -1,7 +1,7 @@
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-import { loadReplacingResource } from "../runtime/config.ts";
+import { readJsonObject } from "../runtime/config.ts";
 
 export type ModelInput = "text" | "image";
 export interface ConfiguredModel { id: string; name?: string; reasoning?: boolean; input?: ModelInput[]; contextWindow?: number; maxTokens?: number; }
@@ -42,9 +42,9 @@ function validateModel(providerId: string, model: ConfiguredModel): void {
   if (model.maxTokens !== undefined && !isPositiveNumber(model.maxTokens)) throw new Error(`Model "${model.id}" has an invalid maxTokens`);
 }
 
-export function loadModelProvidersConfig(cwd = process.cwd()): ModelProvidersConfig {
+export function loadModelProvidersConfig(): ModelProvidersConfig {
   const source = "model-providers.json";
-  const config = loadReplacingResource<ModelProvidersConfig & Record<string, unknown>>(cwd, source, BUNDLED_CONFIG_PATH);
+  const config = readJsonObject(BUNDLED_CONFIG_PATH) as ModelProvidersConfig & Record<string, unknown>;
   if (!Array.isArray(config.providers) || config.providers.length === 0) throw new Error(`${source} must contain a non-empty providers array`);
   const providerIds = new Set<string>();
   for (const provider of config.providers) {

package/.pi/lib/workflow-guard.ts

@@ -11,6 +11,8 @@ export interface ExternalPathReference {
 	resolved: string;
 }
 
+const APPROVAL_FREE_EXTERNAL_PATHS = new Set(["/dev/null"]);
+
 function realpathWithMissingTail(path: string): string {
 	const tail: string[] = [];
 	let cursor = resolve(path);
@@ -41,6 +43,11 @@ export function isPathInsideRoot(root: string, candidate: string): boolean {
 	return relation === "" || (!relation.startsWith(`..${sep}`) && relation !== ".." && !isAbsolute(relation));
 }
 
+export function isPathAllowedWithoutApproval(root: string, candidate: string): boolean {
+	const resolved = realpathWithMissingTail(candidate);
+	return APPROVAL_FREE_EXTERNAL_PATHS.has(resolved) || isPathInsideRoot(root, resolved);
+}
+
 function stripTrailingShellPunctuation(value: string): string {
 	return value.replace(/[\]}),;]+$/g, "");
 }
@@ -52,7 +59,7 @@ function addExternalReference(
 	resolved: string,
 ): void {
 	const cleanResolved = realpathWithMissingTail(stripTrailingShellPunctuation(resolved));
-	if (!isPathInsideRoot(root, cleanResolved)) {
+	if (!isPathAllowedWithoutApproval(root, cleanResolved)) {
 		result.set(`${raw}\0${cleanResolved}`, { raw, resolved: cleanResolved });
 	}
 }

package/.pi/lib/workflows/state.ts

@@ -21,6 +21,13 @@ export interface CloudExecutionStep {
   completedAt: string;
 }
 
+export interface CloudTemplateSource {
+  id: string;
+  name: string;
+  createdAt: string;
+  updatedAt: string;
+}
+
 export interface CloudWorkflowDetails {
   vendor: "aws" | "azure" | "gcp" | "huawei" | "alibaba" | "tencent";
   deployCurrentProject: boolean;
@@ -29,6 +36,8 @@ export interface CloudWorkflowDetails {
   failedApproaches: FailedApproach[];
   successfulSteps: CloudExecutionStep[];
   terminalFailure: boolean;
+  templateGuidance?: string;
+  sourceTemplate?: CloudTemplateSource;
 }
 
 export interface WorkflowState {
@@ -52,6 +61,15 @@ interface LegacyWorkflowState {
   deactivatedAt?: string;
 }
 
+function isCloudTemplateSource(value: unknown): value is CloudTemplateSource {
+  if (!value || typeof value !== "object") return false;
+  const data = value as Record<string, unknown>;
+  return typeof data.id === "string"
+    && typeof data.name === "string"
+    && typeof data.createdAt === "string"
+    && typeof data.updatedAt === "string";
+}
+
 function isCloudDetails(value: unknown): value is CloudWorkflowDetails {
   if (!value || typeof value !== "object") return false;
   const data = value as Record<string, unknown>;
@@ -61,7 +79,9 @@ function isCloudDetails(value: unknown): value is CloudWorkflowDetails {
     && typeof data.allowNonDeleteChanges === "boolean"
     && Array.isArray(data.failedApproaches)
     && Array.isArray(data.successfulSteps)
-    && typeof data.terminalFailure === "boolean";
+    && typeof data.terminalFailure === "boolean"
+    && (data.templateGuidance === undefined || typeof data.templateGuidance === "string")
+    && (data.sourceTemplate === undefined || isCloudTemplateSource(data.sourceTemplate));
 }
 
 export function decodeWorkflowState(value: unknown): WorkflowState | undefined {
@@ -124,6 +144,38 @@ export function createWorkflowState(
   };
 }
 
+export function createCloudWorkflowState(
+  root: string,
+  vendor: CloudWorkflowDetails["vendor"],
+  deployCurrentProject: boolean,
+  request: string,
+  template?: { source: CloudTemplateSource; guidance: string },
+): WorkflowState {
+  const now = new Date().toISOString();
+  return {
+    version: 2,
+    status: "active",
+    mode: "cloud",
+    root,
+    phase: "connected",
+    activatedAt: now,
+    updatedAt: now,
+    details: {
+      vendor,
+      deployCurrentProject,
+      request,
+      allowNonDeleteChanges: false,
+      failedApproaches: [],
+      successfulSteps: [],
+      terminalFailure: false,
+      ...(template ? {
+        templateGuidance: template.guidance,
+        sourceTemplate: template.source,
+      } : {}),
+    },
+  };
+}
+
 export function updateWorkflowState(
   state: WorkflowState,
   changes: Partial<Omit<WorkflowState, "version" | "mode" | "root" | "activatedAt">>,

package/.pi/lib/workspace/access-policy.ts

@@ -2,7 +2,7 @@ import { homedir, tmpdir } from "node:os";
 
 import {
   findExternalPathReferences,
-  isPathInsideRoot,
+  isPathAllowedWithoutApproval,
   resolveToolPath,
   type ExternalPathReference,
 } from "../workflow-guard.ts";
@@ -21,7 +21,7 @@ export function evaluateToolPathAccess(
 ): ExternalPathReference[] {
   if (FILE_PATH_TOOLS.has(request.toolName) && typeof request.input.path === "string") {
     const resolved = resolveToolPath(root, request.input.path, homedir());
-    return isPathInsideRoot(root, resolved)
+    return isPathAllowedWithoutApproval(root, resolved)
       ? []
       : [{ raw: request.input.path, resolved }];
   }

package/.pi/model-providers.json

@@ -1,53 +1,14 @@
 {
   "providers": [
-    {
-      "id": "local",
-      "name": "Qwen3 VL (8081)",
-      "baseUrl": "http://127.0.0.1:8081",
-      "apiKeyEnv": "PI_LOCAL_MODEL_API_KEY",
-      "modelDefaults": {
-        "contextWindow": 1000000,
-        "maxTokens": 8192
-      },
-      "models": [
-        {
-          "id": "qwen3-VL:2b",
-          "name": "Qwen3 VL 2B",
-          "input": ["text", "image"],
-          "contextWindow": 1000000,
-          "maxTokens": 8192
-        }
-      ]
-    },
-    {
-      "id": "local-8080",
-      "name": "Qwen3.5 9B (8080)",
-      "baseUrl": "http://127.0.0.1:8080",
-      "apiKeyEnv": "PI_LOCAL_MODEL_API_KEY",
-      "modelDefaults": {
-        "contextWindow": 1000000,
-        "maxTokens": 8192
-      },
-      "models": [
-        {
-          "id": "Qwen3.5-9B-Q4_K_M",
-          "name": "Qwen3.5 9B Q4_K_M",
-          "input": ["text"],
-          "contextWindow": 1000000,
-          "maxTokens": 8192
-        }
-      ]
-    },
     {
       "id": "hw",
       "name": "Huawei MaaS",
-      "baseUrl": "http://127.0.0.1:8080/v1",
       "apiKeyEnv": "HW_API_KEY",
       "login": {
         "enabled": true,
         "promptBaseUrl": true,
         "promptApiKey": true,
-        "apiKeyRequired": false,
+        "apiKeyRequired": true,
         "catalogPath": "models",
         "timeoutMs": 15000
       },
@@ -55,16 +16,7 @@
         "input": ["text"],
         "contextWindow": 1000000,
         "maxTokens": 8192
-      },
-      "models": [
-        {
-          "id": "Qwen3.5-9B-Q4_K_M",
-          "name": "Qwen3.5 9B Q4_K_M",
-          "input": ["text"],
-          "contextWindow": 1000000,
-          "maxTokens": 8192
-        }
-      ]
+      }
     }
   ]
 }

package/README.md

@@ -21,10 +21,11 @@ hwcode
 Run `hwcode --help` for the HWCode command reference, including model,
 session, tool, and workflow options.
 
-`npx @hadooppei/hwcode` is also supported without a global installation. HWCode loads a
-project's `.env` file when present and keeps Pi's normal user-level auth and
-session storage. Project-local `.pi` resources continue to load alongside the
-built-in HWCode profile.
+`npx @hadooppei/hwcode` is also supported without a global installation. HWCode
+loads a project's `.env` file when present and keeps Pi's normal user-level auth
+and session storage. Project-local Pi resources continue to load alongside the
+built-in HWCode profile, except for HWCode's package-scoped model-provider
+definition described below.
 
 ## Repository setup
 
@@ -38,45 +39,31 @@ On first launch, review and accept Pi's project-trust prompt so it can load the
 
 ## Model providers
 
-OpenAI-compatible providers are declared in `.pi/model-providers.json`.
-Static providers list their models directly:
+The published `.pi/model-providers.json` is package-scoped and is not replaced
+by a file in the current project. It registers the configurable `hw` provider
+without shipping a machine-specific endpoint or a pre-populated model catalog.
+Use Pi's native `/login` flow, select `Huawei MaaS`, and enter the endpoint and
+API key. The key can instead come from `HW_API_KEY`. HWCode then discovers every model exposed by the
+OpenAI-compatible endpoint and Pi stores the selected endpoint, credential, and
+dynamic catalog in its user-level stores.
 
-```json
-{
-  "id": "local-example",
-  "name": "Local example",
-  "baseUrl": "http://127.0.0.1:8082",
-  "apiKeyEnv": "PI_LOCAL_MODEL_API_KEY",
-  "models": [
-    {
-      "id": "model-id",
-      "input": ["text", "image"],
-      "contextWindow": 32768,
-      "maxTokens": 8192
-    }
-  ]
-}
-```
-
-Login providers use Pi's native `/login` flow and discover every model exposed
-by an OpenAI-compatible model endpoint:
+The published provider is equivalent to:
 
 ```json
 {
   "id": "hw",
-  "name": "hw",
-  "baseUrl": "http://127.0.0.1:8080/v1",
+  "name": "Huawei MaaS",
   "apiKeyEnv": "HW_API_KEY",
   "login": {
     "enabled": true,
     "promptBaseUrl": true,
     "promptApiKey": true,
-    "apiKeyRequired": false,
+    "apiKeyRequired": true,
     "catalogPath": "models"
   },
   "modelDefaults": {
     "input": ["text"],
-    "contextWindow": 32768,
+    "contextWindow": 1000000,
     "maxTokens": 8192
   }
 }
@@ -84,12 +71,14 @@ by an OpenAI-compatible model endpoint:
 
 `id` is the stable credential and cache key; `name` is the configurable label
 shown alongside other providers in `/login`. A login authenticates the whole
-provider and publishes its complete model catalog to `/model`. Entries in a
-login provider's `models` array are optional metadata overrides for discovered
-IDs, which is where vision support should be declared with
-`"input": ["text", "image"]`. Unknown models default to text-only. Keep real
-API keys in `.env` or enter them through `/login`; Pi stores entered credentials
-in its own auth store rather than the project configuration.
+provider and publishes its complete model catalog to `/model`. Unknown models
+default to text-only. Keep real API keys in `.env` or enter them through
+`/login`; Pi stores entered credentials in its own auth store rather than the
+package configuration.
+
+Repository maintainers can refer to `.pi/model-providers.json.template` for the
+previous local static-provider examples, including multimodal metadata. The
+template is not loaded at runtime and is explicitly excluded from npm packages.
 
 ## Welcome screen
 
@@ -111,8 +100,9 @@ Start one of the project workflows from the Pi input:
 
 Both commands first confirm the current directory and lock project work to that
 root for the session. In-root operations run normally; each tool call that names
-an external path asks for separate approval. `/hwcode-vibe` uses short iterative
-build-and-verify loops. `/hwcode-sdd` additionally requires the current directory
+an external path asks for separate approval. The non-storage sink `/dev/null` is
+approval-free even when used by shell redirection. `/hwcode-vibe` uses short
+iterative build-and-verify loops. `/hwcode-sdd` additionally requires the current directory
 to be the Git repository root, inventories the codebase, resolves requirement
 questions, and persists approved artifacts under
 `.hwcode/specs/<requirement-slug>/` before test-first implementation begins.
@@ -149,13 +139,19 @@ remaining resources, and local changes instead of attempting a fourth approach.
 
 After at least one cloud command succeeds, run
 `/hwcode-cloud-save-template [name]` to save the objective, validated execution
-sequence, and optional lessons learned as a local Prompt Template. Templates are
-stored under `~/.hwcode/cloud/prompts/` with user-only permissions. Credential
-values are excluded and redacted before steps are persisted.
+sequence, failed approaches, prerequisites, and optional lessons learned as a
+local Prompt Template. Each template records its user-facing name plus creation
+and update timestamps. Its prompt is layered into stable intent, prerequisites,
+the preferred known-good path, expensive failed paths that must not be retried,
+and the guarded execution contract. Templates are stored under
+`~/.hwcode/cloud/prompts/` with user-only permissions. Credential values are
+excluded and redacted before steps are persisted.
 
 Use `/hwcode-cloud-template [additional instructions]` to select and start a
-saved template immediately. `/hwcode-cloud` also offers saved templates when it
-starts without an inline request. The files use a Pi-compatible
+saved template by name and last-updated time. `/hwcode-cloud` also offers saved
+templates when it starts without an inline request. If a session started from a
+template, saving again asks whether to update that source template or create a
+new one. The files use a Pi-compatible
 Markdown/frontmatter format, but HWCode intentionally keeps them out of Pi
 resource discovery so each saved template does not become another slash
 command. Templates are extension-private resources and always run through the
@@ -174,9 +170,9 @@ commands, tools, and UI. Reusable behavior lives under `.pi/lib/`:
 - `context/` and `models/` own compaction and provider-configuration policy.
 
 `settings.json` is layered as defaults → profile → project for settings such as
-context and hidden commands. `welcome.json` and `model-providers.json` use a
-single replacing resource, preferring project, then profile, then the bundled
-default. This keeps configuration precedence consistent across extensions.
+context and hidden commands. `welcome.json` uses a single replacing resource.
+`model-providers.json` is deliberately package-scoped so a project cannot
+silently replace login providers or reintroduce machine-local defaults.
 
 ## Working directory
 
@@ -204,8 +200,9 @@ HWCode defaults locally configured and dynamically discovered models to a
 1,000,000-token context window and caps configured or provider-reported values
 at that limit. If an OpenAI-compatible model catalog reports a smaller
 `context_window`, `context_length`, `max_context_length`, `max_model_len`, or
-`n_ctx`, the smaller server value wins. Per-model `contextWindow` values in
-`.pi/model-providers.json` can also select a smaller limit.
+`n_ctx`, the smaller server value wins. The package-scoped provider's
+`modelDefaults.contextWindow` can also select a smaller limit for dynamically
+discovered models.
 
 The default context policy is configured under `hwcode.context` in
 `.pi/settings.json`:

package/bin/hwcode.js

@@ -82,7 +82,7 @@ HWCode 交互命令:
   hwcode -p "总结当前代码库"
   hwcode @README.md "检查文档是否完整"
 
-项目中的 .env 会自动加载；项目本地 .pi 资源会与 HWCode 内置配置共同生效。`;
+项目中的 .env 会自动加载；模型 Provider 使用 HWCode 发布配置，其余项目本地 .pi 资源照常生效。`;
 }
 
 if (userArgs[0] === "--help" || userArgs[0] === "-h") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hadooppei/hwcode",
-  "version": "0.2.0",
+  "version": "0.2.4",
   "description": "A customizable terminal coding agent with local-model support and HWCode workflows.",
   "type": "module",
   "bin": {
@@ -26,7 +26,7 @@
     "pi": "node --env-file-if-exists=.env ./bin/hwcode.js",
     "test": "node --test .pi/lib/*.test.ts",
     "test:workflows": "npm test",
-    "prepack": "npm test"
+    "prepack": "npm test && node scripts/audit-package.mjs"
   },
   "engines": {
     "node": ">=22.19.0"