svharness 0.14.17 → 0.14.18

package/README.md

@@ -733,11 +733,13 @@ svharness start-agent --work-dir ~/projects/my-app
 
 #### 平台说明
 
-| 平台 | spawn 模式 | 右键菜单 |
-|------|------------|----------|
+| 平台 | spawn 模式 | 右键菜单 / PowerShell 别名 |
+|------|------------|----------------------------|
 | Windows | `shell: true` | 支持（`svharness shell`） |
 | Linux / macOS | `shell: false` | 不支持 |
 
+Windows 下首次 `start-agent` 会**尽力**写入 PowerShell `codechat` 函数（与 `shell install` 相同逻辑）；若未全局安装 svharness，可手动执行 `svharness shell install`。
+
 ### 无需 svharness：独立 PowerShell 启动器
 
 未安装 npm / svharness 时，可拷贝 [`templates/codechat/Start-CodeChat.ps1`](templates/codechat/Start-CodeChat.ps1) 到项目 `.claude\`，实现相同的 env 同步与 `run.bat` 解析（含 Android Studio / IDEA 插件路径）：
@@ -745,7 +747,12 @@ svharness start-agent --work-dir ~/projects/my-app
 ```powershell
 Copy-Item .\templates\codechat\Start-CodeChat.ps1 .\.claude\
 .\.claude\Start-CodeChat.ps1                              # 启动
-.\.claude\Start-CodeChat.ps1 -Action InstallMenu          # 可选：独立右键菜单
+.\.claude\Start-CodeChat.ps1 -Action Install              # 可选：独立右键 + 别名
+.\.claude\Start-CodeChat.ps1 -Action InstallMenu          # 仅右键
+.\.claude\Start-CodeChat.ps1 -Action InstallAlias         # 仅别名
+.\.claude\Start-CodeChat.ps1 -Action UninstallMenu        # 反注册独立右键
+.\.claude\Start-CodeChat.ps1 -Action UninstallAlias       # 反注册独立别名
+.\.claude\Start-CodeChat.ps1 -Action Status
 ```
 
 右键菜单使用注册表键 `CodeChatStandaloneAgent`，**不与** `svharness shell install` 冲突；可与 svharness 菜单并存。
@@ -762,24 +769,74 @@ launch_codechat_cli D:\projects\my-app    # Windows
 launch_codechat_cli ~/projects/my-app     # Linux
 ```
 
-### `shell` —— Windows 右键菜单（v0.16+，仅 win32）
+### `shell` —— Windows 右键菜单与 PowerShell 别名（v0.16+，仅 win32）
+
+在资源管理器**文件夹空白处**与**文件夹图标**右键增加「在此启动 CodeChat Agent」，并在 PowerShell `$PROFILE` 写入 `codechat` 函数（等价于 `launch_codechat_cli [workdir]`）。**注册与反注册**对右键菜单、本地 stub、PowerShell 别名**一并**处理。
 
-在资源管理器**文件夹空白处**与**文件夹图标**右键增加「在此启动 CodeChat Agent」，点击后打开 **PowerShell** 窗口并启动 Agent。
+#### 注册
 
 ```bash
-svharness shell install      # 注册（幂等）
-svharness shell uninstall    # 移除
-svharness shell status       # 查看 stub / 注册表状态
-svharness shell uninstall
-npm uninstall -g svharness
+svharness shell install      # 注册右键 + 安装 codechat 别名（幂等）
+svharness shell status       # 查看是否已完整安装
 ```
 
-`npm install -g svharness` 在 Windows 上 **默认自动** `shell install`。跳过：
+注册时会写入：
+
+| 项 | 路径 / 键 |
+|----|-----------|
+| 空白处右键 | `HKCU\Software\Classes\Directory\Background\shell\SvharnessLaunchCodeChatAgent` |
+| 文件夹右键 | `HKCU\Software\Classes\Directory\shell\SvharnessLaunchCodeChatAgent` |
+| 启动 stub | `%LOCALAPPDATA%\svharness\bin\launch_codechat_cli.ps1` |
+| 菜单图标 | `%LOCALAPPDATA%\svharness\bin\codechat-agent.ico` |
+| PowerShell 别名 | 当前用户 `$PROFILE` 内 `# >>> codechat >>>` … `# <<< codechat <<<` 块 |
+
+`npm install -g svharness` 在 Windows 上 **默认自动** 执行上述注册。跳过：
 
 ```bash
 SVHARNESS_SKIP_SHELL=1 npm install -g svharness
 ```
 
+**PowerShell 别名用法**（注册后需**新开** PowerShell 窗口才生效）：
+
+```powershell
+codechat                       # 当前目录启动
+codechat D:\projects\my-app    # 指定项目根
+```
+
+#### 反注册
+
+```bash
+svharness shell uninstall    # 移除右键、stub、图标与 profile 中的 codechat 块
+svharness shell status       # 确认「右键菜单完整 / codechat 别名」均为否
+```
+
+反注册时会删除：
+
+| 项 | 说明 |
+|----|------|
+| 上述两个 HKCU 注册表键 | 资源管理器右键菜单项消失（无需重启 Explorer） |
+| `%LOCALAPPDATA%\svharness\bin\` | 删除 stub `.ps1` 与 `.ico` |
+| `$PROFILE` 中的 codechat 块 | 移除 `# >>> codechat >>>` … `# <<< codechat <<<` 整段；**不**删除 profile 文件本身 |
+
+全局卸载 npm 包时，`preuninstall` 会**尽力**自动反注册（与 `shell uninstall` 相同范围）：
+
+```bash
+npm uninstall -g svharness
+```
+
+若自动反注册失败，可手动执行 `svharness shell uninstall`（包仍在时），或自行检查：
+
+- 注册表：`reg query HKCU\Software\Classes\Directory\Background\shell\SvharnessLaunchCodeChatAgent` 应报错「找不到」
+- 目录：`%LOCALAPPDATA%\svharness\bin\` 应不存在或为空
+- profile：打开 `$PROFILE`，确认无 `# >>> codechat >>>` 标记块
+
+**注意**：`shell uninstall` **仅**移除 svharness 注册的菜单（键名 `SvharnessLaunchCodeChatAgent`）。若曾用独立脚本 [`Start-CodeChat.ps1`](templates/codechat/Start-CodeChat.ps1) 注册过菜单（键名 `CodeChatStandaloneAgent`），需单独反注册：
+
+```powershell
+.\.claude\Start-CodeChat.ps1 -Action UninstallMenu    # 独立右键
+.\.claude\Start-CodeChat.ps1 -Action UninstallAlias   # 独立别名（若曾 Install / InstallAlias）
+```
+
 ---
 
 ## 架构模板

package/dist/commands/shell-integration.js

@@ -3,9 +3,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveLaunchScriptPath = void 0;
 exports.resolveShellMenuIconSourcePath = resolveShellMenuIconSourcePath;
 exports.installShellMenuIcon = installShellMenuIcon;
-exports.resolveLaunchScriptPath = resolveLaunchScriptPath;
 exports.resolveWindowsTerminalPath = resolveWindowsTerminalPath;
 exports.runShellInstall = runShellInstall;
 exports.runShellUninstall = runShellUninstall;
@@ -18,6 +18,9 @@ const os_1 = __importDefault(require("os"));
 const child_process_1 = require("child_process");
 const logger_1 = require("../utils/logger");
 const win_registry_1 = require("../lib/win-registry");
+const ps_codechat_alias_1 = require("../lib/ps-codechat-alias");
+const launch_script_path_1 = require("../lib/launch-script-path");
+Object.defineProperty(exports, "resolveLaunchScriptPath", { enumerable: true, get: function () { return launch_script_path_1.resolveLaunchScriptPath; } });
 const STUB_DIR = path_1.default.join(process.env.LOCALAPPDATA ?? path_1.default.join(os_1.default.homedir(), 'AppData', 'Local'), 'svharness', 'bin');
 const STUB_PATH = path_1.default.join(STUB_DIR, 'launch_codechat_cli.ps1');
 const LEGACY_STUB_PATH = path_1.default.join(STUB_DIR, 'launch_codechat_cli.cmd');
@@ -64,22 +67,6 @@ async function installShellMenuIcon() {
     await fs_extra_1.default.copy(source, ICON_STUB_PATH, { overwrite: true });
     return `${ICON_STUB_PATH},0`;
 }
-/**
- * Resolve absolute path to bin/launch-codechat-cli.js in the installed package.
- */
-function resolveLaunchScriptPath() {
-    // dist/commands/shell-integration.js → ../../bin/launch-codechat-cli.js
-    const fromDist = path_1.default.resolve(__dirname, '..', '..', 'bin', 'launch-codechat-cli.js');
-    if (fs_extra_1.default.existsSync(fromDist)) {
-        return fromDist;
-    }
-    // fallback: package root from scripts/postinstall.js context
-    const fromCwd = path_1.default.resolve(__dirname, '..', '..', '..', 'bin', 'launch-codechat-cli.js');
-    if (fs_extra_1.default.existsSync(fromCwd)) {
-        return fromCwd;
-    }
-    throw new Error(`未找到 launch-codechat-cli.js（预期：${fromDist}）`);
-}
 function canAccessExecutable(filePath) {
     try {
         fs_extra_1.default.accessSync(filePath, fs_extra_1.default.constants.F_OK);
@@ -162,7 +149,7 @@ async function runShellInstall(opts = {}) {
     // Avoid duplicate menu entries: overwrite standalone menu if present.
     (0, win_registry_1.regDeleteKey)(STANDALONE_MENU_KEY_BG);
     (0, win_registry_1.regDeleteKey)(STANDALONE_MENU_KEY_DIR);
-    const launchScriptPath = resolveLaunchScriptPath();
+    const launchScriptPath = (0, launch_script_path_1.resolveLaunchScriptPath)();
     await fs_extra_1.default.ensureDir(STUB_DIR);
     await writeStubFile(launchScriptPath);
     if (await fs_extra_1.default.pathExists(LEGACY_STUB_PATH)) {
@@ -182,6 +169,7 @@ async function runShellInstall(opts = {}) {
     if (wtPath) {
         logInfo(`  wt:   ${wtPath}`, opts.silent);
     }
+    await (0, ps_codechat_alias_1.installCodechatAlias)({ silent: opts.silent });
 }
 /**
  * Remove HKCU context menus and stub file.
@@ -199,7 +187,8 @@ async function runShellUninstall(opts = {}) {
     if (await fs_extra_1.default.pathExists(LEGACY_STUB_PATH)) {
         await fs_extra_1.default.remove(LEGACY_STUB_PATH);
     }
-    logSuccess('Windows 右键菜单已卸载', opts.silent);
+    await (0, ps_codechat_alias_1.uninstallCodechatAlias)({ silent: opts.silent });
+    logSuccess('Windows 右键菜单与 PowerShell 别名已卸载', opts.silent);
 }
 /**
  * Report shell integration installation state.
@@ -208,7 +197,7 @@ function getShellStatus() {
     assertWin32();
     let launchScriptPath = '';
     try {
-        launchScriptPath = resolveLaunchScriptPath();
+        launchScriptPath = (0, launch_script_path_1.resolveLaunchScriptPath)();
     }
     catch {
         launchScriptPath = '(未找到)';
@@ -217,6 +206,7 @@ function getShellStatus() {
     const directoryMenu = (0, win_registry_1.regKeyExists)(win_registry_1.SHELL_MENU_KEY_DIR);
     const stubExists = fs_extra_1.default.existsSync(STUB_PATH);
     const wtPath = resolveWindowsTerminalPath();
+    const aliasStatus = (0, ps_codechat_alias_1.getCodechatAliasStatus)();
     return {
         installed: backgroundMenu && directoryMenu && stubExists,
         stubPath: STUB_PATH,
@@ -224,24 +214,28 @@ function getShellStatus() {
         directoryMenu,
         launchScriptPath,
         viaWindowsTerminal: wtPath !== null,
+        aliasInstalled: aliasStatus.installed,
+        profilePath: aliasStatus.profilePath,
     };
 }
 function printShellStatus() {
     const status = getShellStatus();
-    logger_1.logger.section('Windows 右键菜单状态');
-    logger_1.logger.plain(`  已完整安装: ${status.installed ? '是' : '否'}`);
-    logger_1.logger.plain(`  stub 路径:   ${status.stubPath}`);
-    logger_1.logger.plain(`  空白处菜单:  ${status.backgroundMenu ? '已注册' : '未注册'}`);
-    logger_1.logger.plain(`  文件夹菜单:  ${status.directoryMenu ? '已注册' : '未注册'}`);
-    logger_1.logger.plain(`  启动脚本:    ${status.launchScriptPath}`);
-    logger_1.logger.plain(`  经 WT 启动:  ${status.viaWindowsTerminal ? '是（install 时检测到 wt.exe）' : '否'}`);
+    logger_1.logger.section('Windows shell 集成状态');
+    logger_1.logger.plain(`  右键菜单完整: ${status.installed ? '是' : '否'}`);
+    logger_1.logger.plain(`  stub 路径:     ${status.stubPath}`);
+    logger_1.logger.plain(`  空白处菜单:    ${status.backgroundMenu ? '已注册' : '未注册'}`);
+    logger_1.logger.plain(`  文件夹菜单:    ${status.directoryMenu ? '已注册' : '未注册'}`);
+    logger_1.logger.plain(`  启动脚本:      ${status.launchScriptPath}`);
+    logger_1.logger.plain(`  经 WT 启动:    ${status.viaWindowsTerminal ? '是（install 时检测到 wt.exe）' : '否'}`);
+    logger_1.logger.plain(`  codechat 别名: ${status.aliasInstalled ? '已安装' : '未安装'}`);
+    logger_1.logger.plain(`  profile 路径:  ${status.profilePath}`);
 }
 async function runShellInstallSafe(opts = {}) {
     try {
         await runShellInstall(opts);
     }
     catch (err) {
-        logWarn(`自动注册 Windows 右键菜单失败：${err.message}\n` +
+        logWarn(`自动注册 Windows shell 集成失败：${err.message}\n` +
             `  可稍后手动执行：svharness shell install`);
     }
 }

package/dist/index.js

@@ -492,10 +492,10 @@ function main() {
     });
     const shellCmd = program
         .command('shell')
-        .description('Windows 资源管理器右键菜单管理（仅 win32）');
+        .description('Windows 右键菜单与 PowerShell codechat 别名（仅 win32）');
     shellCmd
         .command('install')
-        .description('注册 HKCU 右键菜单「在此启动 CodeChat CLI」')
+        .description('注册 HKCU 右键菜单，并在 $PROFILE 安装 codechat 函数（幂等）')
         .action(async () => {
         try {
             await (0, shell_integration_1.runShellInstall)();
@@ -507,7 +507,7 @@ function main() {
     });
     shellCmd
         .command('uninstall')
-        .description('移除右键菜单与本地 stub')
+        .description('移除右键菜单、本地 stub 与 PowerShell codechat 别名')
         .action(async () => {
         try {
             await (0, shell_integration_1.runShellUninstall)();
@@ -519,7 +519,7 @@ function main() {
     });
     shellCmd
         .command('status')
-        .description('查看右键菜单安装状态')
+        .description('查看右键菜单与 PowerShell codechat 别名状态')
         .action(() => {
         try {
             (0, shell_integration_1.printShellStatus)();

package/dist/lib/agent-launcher.js

@@ -14,6 +14,7 @@ const child_process_1 = require("child_process");
 const logger_1 = require("../utils/logger");
 const validate_args_1 = require("../utils/validate-args");
 const codechat_runner_resolver_1 = require("./codechat-runner-resolver");
+const ps_codechat_alias_1 = require("./ps-codechat-alias");
 const SUPPORTED_START_AGENTS = ['codechat'];
 const DEFAULT_ENV_TEMPLATE = 'default-claude.env';
 function homePath(...segments) {
@@ -160,27 +161,6 @@ async function ensureUserEnv(workdir, config, syncEnv) {
     await copyEnvToUserOnly(defaultTemplate, userEnv);
     logger_1.logger.info(`已写入内置默认 env 到用户目录（未写入项目）→ ${userEnv}`);
 }
-function warnIfNotHarnessProject(workdir) {
-    const hints = [];
-    if (fs_extra_1.default.existsSync(path_1.default.join(workdir, 'CLAUDE.md')))
-        hints.push('CLAUDE.md');
-    if (fs_extra_1.default.existsSync(path_1.default.join(workdir, 'AGENTS.md')))
-        hints.push('AGENTS.md');
-    if (fs_extra_1.default.existsSync(path_1.default.join(workdir, '.he-harness')))
-        hints.push('.he-harness/');
-    try {
-        const entries = fs_extra_1.default.readdirSync(workdir);
-        if (entries.some((e) => e.endsWith('-harness') && fs_extra_1.default.statSync(path_1.default.join(workdir, e)).isDirectory())) {
-            hints.push('*-harness/');
-        }
-    }
-    catch {
-        // ignore
-    }
-    if (hints.length === 0) {
-        logger_1.logger.warn(`当前目录可能不是 harness 项目根（未找到 CLAUDE.md / AGENTS.md / *-harness/ / .he-harness/）：\n  ${workdir}`);
-    }
-}
 function buildRunnerArgs(config, workdir, skipPermissions) {
     const envFile = resolveUserEnvPath(config);
     const args = [
@@ -205,6 +185,9 @@ async function runStartAgent(opts) {
         workDir: opts.workDir,
         positionalWorkdir: opts.positionalWorkdir,
     });
+    if (process.platform === 'win32') {
+        await (0, ps_codechat_alias_1.ensureCodechatAliasSafe)({ silent: true });
+    }
     const config = getCodechatEnvConfig();
     const syncEnv = opts.syncEnv !== false;
     const skipPermissions = opts.skipPermissions !== false;
@@ -216,7 +199,6 @@ async function runStartAgent(opts) {
             `请提供 ${path_1.default.join(workdir, config.envSyncFromRel)}，或确保内置模板 templates/default-claude.env 可访问。`);
     }
     await verifyUserEnvWritten(userEnvFile);
-    warnIfNotHarnessProject(workdir);
     const args = buildRunnerArgs(config, workdir, skipPermissions);
     logger_1.logger.info(`CodeChat CLI: ${runner} (${formatRunnerSourceLog(source, label)})`);
     logger_1.logger.info(`启动 CodeChat Agent（workdir: ${workdir}）`);

package/dist/lib/launch-script-path.js

@@ -0,0 +1,24 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveLaunchScriptPath = resolveLaunchScriptPath;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+/**
+ * Resolve absolute path to bin/launch-codechat-cli.js in the installed package.
+ */
+function resolveLaunchScriptPath() {
+    // dist/lib/launch-script-path.js → ../../bin/launch-codechat-cli.js
+    const fromDist = path_1.default.resolve(__dirname, '..', '..', 'bin', 'launch-codechat-cli.js');
+    if (fs_extra_1.default.existsSync(fromDist)) {
+        return fromDist;
+    }
+    // fallback: package root from scripts/postinstall.js context
+    const fromCwd = path_1.default.resolve(__dirname, '..', '..', '..', 'bin', 'launch-codechat-cli.js');
+    if (fs_extra_1.default.existsSync(fromCwd)) {
+        return fromCwd;
+    }
+    throw new Error(`未找到 launch-codechat-cli.js（预期：${fromDist}）`);
+}

package/dist/lib/ps-codechat-alias.js

@@ -0,0 +1,183 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPowerShellProfilePath = getPowerShellProfilePath;
+exports.installCodechatAlias = installCodechatAlias;
+exports.uninstallCodechatAlias = uninstallCodechatAlias;
+exports.getCodechatAliasStatus = getCodechatAliasStatus;
+exports.printCodechatAliasStatus = printCodechatAliasStatus;
+exports.ensureCodechatAliasSafe = ensureCodechatAliasSafe;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const logger_1 = require("../utils/logger");
+const launch_script_path_1 = require("./launch-script-path");
+const START_MARKER = /^#\s*>>>\s*codechat\s*>>>/;
+const END_MARKER = /^#\s*<<<\s*codechat\s*<<</;
+function assertWin32() {
+    if (process.platform !== 'win32') {
+        throw new Error('PowerShell codechat 别名仅支持 Windows');
+    }
+}
+/**
+ * Resolve the current user's PowerShell $PROFILE path.
+ */
+function getPowerShellProfilePath() {
+    assertWin32();
+    const out = (0, child_process_1.execFileSync)('powershell.exe', ['-NoProfile', '-Command', 'Write-Output $PROFILE'], { encoding: 'utf8', windowsHide: true }).trim();
+    if (!out) {
+        throw new Error('无法解析 PowerShell $PROFILE 路径');
+    }
+    return out;
+}
+function normalizePathForCompare(value) {
+    return path_1.default.resolve(value).replace(/\\/g, '/').toLowerCase();
+}
+function stripCodechatBlock(content) {
+    const lines = content.split(/\r?\n/);
+    const clean = [];
+    let hadBlock = false;
+    let inBlock = false;
+    for (const line of lines) {
+        if (START_MARKER.test(line)) {
+            hadBlock = true;
+            inBlock = true;
+            continue;
+        }
+        if (inBlock) {
+            if (END_MARKER.test(line)) {
+                inBlock = false;
+            }
+            continue;
+        }
+        clean.push(line);
+    }
+    const joined = clean.join('\n').replace(/\n+$/, '');
+    return { clean: joined ? `${joined}\n` : '', hadBlock };
+}
+function buildAliasSnippet(launchScriptPath) {
+    const escapedPath = launchScriptPath.replace(/'/g, "''");
+    return `
+
+# >>> codechat >>>
+function codechat {
+    param([string]$Path)
+    if (-not $Path) { $Path = (Get-Location).Path }
+    & node '${escapedPath}' $Path
+}
+# <<< codechat <<<
+
+`;
+}
+function profileHasSvharnessAlias(content, launchScriptPath) {
+    if (!START_MARKER.test(content)) {
+        return false;
+    }
+    const needle = normalizePathForCompare(launchScriptPath);
+    return normalizePathForCompare(content).includes(needle);
+}
+/**
+ * Install or refresh the PowerShell `codechat` function in $PROFILE (idempotent).
+ * Ported from templates/codechat/Start-CodeChat.ps1 Install-CodeChatAlias.
+ */
+async function installCodechatAlias(opts = {}) {
+    assertWin32();
+    const profilePath = getPowerShellProfilePath();
+    const launchScriptPath = (0, launch_script_path_1.resolveLaunchScriptPath)();
+    const existing = (await fs_extra_1.default.pathExists(profilePath))
+        ? await fs_extra_1.default.readFile(profilePath, 'utf8')
+        : '';
+    if (profileHasSvharnessAlias(existing, launchScriptPath)) {
+        if (!opts.silent) {
+            logger_1.logger.info(`PowerShell 别名 codechat 已存在：${profilePath}`);
+        }
+        return;
+    }
+    await fs_extra_1.default.ensureDir(path_1.default.dirname(profilePath));
+    if (!(await fs_extra_1.default.pathExists(profilePath))) {
+        await fs_extra_1.default.writeFile(profilePath, '', 'utf8');
+    }
+    const { clean, hadBlock } = stripCodechatBlock(existing);
+    const snippet = buildAliasSnippet(launchScriptPath);
+    await fs_extra_1.default.writeFile(profilePath, `${clean}${snippet}`, 'utf8');
+    if (!opts.silent) {
+        if (hadBlock) {
+            logger_1.logger.success(`已更新 PowerShell 别名 codechat → ${launchScriptPath}`);
+        }
+        else {
+            logger_1.logger.success(`已安装 PowerShell 别名 codechat → ${profilePath}`);
+        }
+        logger_1.logger.info('  新开 PowerShell 窗口后可直接运行：codechat [项目路径]');
+    }
+}
+/**
+ * Remove the codechat block from $PROFILE.
+ */
+async function uninstallCodechatAlias(opts = {}) {
+    assertWin32();
+    const profilePath = getPowerShellProfilePath();
+    if (!(await fs_extra_1.default.pathExists(profilePath))) {
+        if (!opts.silent) {
+            logger_1.logger.info("PowerShell 别名 codechat 未安装（profile 不存在）");
+        }
+        return;
+    }
+    const existing = await fs_extra_1.default.readFile(profilePath, 'utf8');
+    const { clean, hadBlock } = stripCodechatBlock(existing);
+    if (!hadBlock) {
+        if (!opts.silent) {
+            logger_1.logger.info("PowerShell 别名 codechat 未安装");
+        }
+        return;
+    }
+    await fs_extra_1.default.writeFile(profilePath, clean, 'utf8');
+    if (!opts.silent) {
+        logger_1.logger.success(`已从 ${profilePath} 移除 PowerShell 别名 codechat`);
+    }
+}
+function getCodechatAliasStatus() {
+    assertWin32();
+    const profilePath = getPowerShellProfilePath();
+    let launchScriptPath = '';
+    try {
+        launchScriptPath = (0, launch_script_path_1.resolveLaunchScriptPath)();
+    }
+    catch {
+        launchScriptPath = '(未找到)';
+    }
+    let installed = false;
+    if (fs_extra_1.default.existsSync(profilePath) && launchScriptPath !== '(未找到)') {
+        try {
+            const content = fs_extra_1.default.readFileSync(profilePath, 'utf8');
+            installed = profileHasSvharnessAlias(content, launchScriptPath);
+        }
+        catch {
+            installed = false;
+        }
+    }
+    return { profilePath, installed, launchScriptPath };
+}
+function printCodechatAliasStatus() {
+    const status = getCodechatAliasStatus();
+    logger_1.logger.section('PowerShell codechat 别名状态');
+    logger_1.logger.plain(`  已安装:     ${status.installed ? '是' : '否'}`);
+    logger_1.logger.plain(`  profile:    ${status.profilePath}`);
+    logger_1.logger.plain(`  启动脚本:   ${status.launchScriptPath}`);
+}
+/**
+ * Best-effort alias install; never throws (warn only).
+ */
+async function ensureCodechatAliasSafe(opts = {}) {
+    if (process.platform !== 'win32') {
+        return;
+    }
+    try {
+        await installCodechatAlias({ silent: opts.silent ?? true });
+    }
+    catch (err) {
+        logger_1.logger.warn(`自动安装 PowerShell 别名 codechat 失败：${err.message}\n` +
+            `  可稍后手动执行：svharness shell install`);
+    }
+}

package/docs/standalone-codechat-ps1.md

@@ -23,9 +23,10 @@ cd D:\projects\my-app
 # 3. 可选：注册 Explorer 右键（独立菜单项）
 .\.claude\Start-CodeChat.ps1 -Action InstallMenu
 
-# 4. 状态 / 卸载右键
+# 4. 状态 / 反注册
 .\.claude\Start-CodeChat.ps1 -Action Status
 .\.claude\Start-CodeChat.ps1 -Action UninstallMenu
+.\.claude\Start-CodeChat.ps1 -Action UninstallAlias
 ```
 
 ## 子命令 `-Action`
@@ -33,8 +34,11 @@ cd D:\projects\my-app
 | Action | 说明 |
 |--------|------|
 | `Start`（默认） | 同步 env → 解析 `run.bat` → 启动 CodeChat |
+| `Install` | 注册 Explorer 右键 **并** 安装 PowerShell `codechat` 别名 |
 | `InstallMenu` | 复制脚本到 `%LOCALAPPDATA%\codechat-standalone\` 并注册 HKCU 右键 |
 | `UninstallMenu` | 删除独立注册表键与 `%LOCALAPPDATA%\codechat-standalone\` |
+| `InstallAlias` | 在 `$PROFILE` 安装 `codechat` 函数 |
+| `UninstallAlias` | 从 `$PROFILE` 移除 `codechat` 函数块 |
 | `Status` | 打印 runner / env / 菜单注册状态 |
 
 ## Start 参数

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "svharness",
-  "version": "0.14.17",
+  "version": "0.14.18",
   "description": "CLI scaffolder for SDD-Driven Agent-Agnostic Coding Framework (harness)",
   "bin": {
     "svharness": "./bin/cli.js",

package/scripts/postinstall.js

@@ -1,7 +1,7 @@
 'use strict';
 
 /**
- * postinstall: global install on Windows registers Explorer context menu.
+ * postinstall: global install on Windows registers Explorer context menu + PowerShell codechat alias.
  * Skip: SVHARNESS_SKIP_SHELL=1 npm install -g svharness
  */
 if (process.platform !== 'win32') {
@@ -20,7 +20,7 @@ if (process.env.SVHARNESS_SKIP_SHELL === '1') {
     await runShellInstallSafe({ silent: false });
   } catch (err) {
     console.warn(
-      '[svharness postinstall] 注册 Windows 右键菜单失败：',
+      '[svharness postinstall] 注册 Windows shell 集成失败：',
       err && err.message ? err.message : err,
     );
     console.warn('[svharness postinstall] 可稍后手动执行：svharness shell install');

package/scripts/preuninstall.js

@@ -55,3 +55,48 @@ regDeleteKey('HKCU\\Software\\Classes\\Directory\\shell\\svharness_codechat');
 
 // Stub files + icon under %LOCALAPPDATA%\svharness
 removeDirRecursive(STUB_DIR);
+
+function stripCodechatAliasFromProfile(profilePath) {
+  if (!profilePath || !fs.existsSync(profilePath)) {
+    return;
+  }
+  try {
+    const content = fs.readFileSync(profilePath, 'utf8');
+    const lines = content.split(/\r?\n/);
+    const clean = [];
+    let inBlock = false;
+    let hadBlock = false;
+    for (const line of lines) {
+      if (/^#\s*>>>\s*codechat\s*>>>/.test(line)) {
+        hadBlock = true;
+        inBlock = true;
+        continue;
+      }
+      if (inBlock) {
+        if (/^#\s*<<<\s*codechat\s*<<</.test(line)) {
+          inBlock = false;
+        }
+        continue;
+      }
+      clean.push(line);
+    }
+    if (!hadBlock) {
+      return;
+    }
+    const joined = clean.join('\n').replace(/\n+$/, '');
+    fs.writeFileSync(profilePath, joined ? `${joined}\n` : '', 'utf8');
+  } catch {
+    // best effort
+  }
+}
+
+try {
+  const profilePath = execFileSync(
+    'powershell.exe',
+    ['-NoProfile', '-Command', 'Write-Output $PROFILE'],
+    { encoding: 'utf8', windowsHide: true },
+  ).trim();
+  stripCodechatAliasFromProfile(profilePath);
+} catch {
+  // best effort
+}