svharness 0.14.11 → 0.14.13

package/README.md

@@ -580,6 +580,8 @@ convert-failures.json
 
 详细设计见 [`docs/agent-launcher-design.md`](docs/agent-launcher-design.md)。
 
+**env 策略（单向，只写用户目录）**：可**读取**项目 `<workdir>/.claude/.env` 并同步到 `~/.claude/.env`；**绝不**在项目内创建或修改 `.claude/.env`。无 env 时内置模板**仅**生成 `~/.claude/.env`。
+
 #### 快速示例
 
 ```bash
@@ -603,7 +605,7 @@ svharness start-agent --work-dir . --no-sync-env --no-skip-permissions
 | `[workdir]` | 工作目录（前一参数为 agent 时使用） | — |
 | `--work-dir <path>` | Agent 工作目录（harness 项目根） | 当前目录 |
 | `--agent <agent>` | 目标 Agent（**当前仅 codechat 可实际启动**） | `codechat` |
-| `--no-sync-env` | 不同步 `<workdir>/.claude/.env` → `~/.claude/.env` | false |
+| `--no-sync-env` | 不读取项目 `.claude/.env` 同步到用户级（仍可用已有 `~/.claude/.env`；若无则仅写入用户级内置模板） | false |
 | `--no-skip-permissions` | 不传 `--dangerously-skip-permissions` | 默认传 |
 
 #### 平台说明
@@ -625,7 +627,7 @@ launch_codechat_cli ~/projects/my-app     # Linux
 
 ### `shell` —— Windows 右键菜单（v0.16+，仅 win32）
 
-在资源管理器**文件夹空白处**与**文件夹图标**右键增加「在此启动 CodeChat Agent」。
+在资源管理器**文件夹空白处**与**文件夹图标**右键增加「在此启动 CodeChat Agent」，点击后打开 **PowerShell** 窗口并启动 Agent。
 
 ```bash
 svharness shell install      # 注册（幂等）

package/bin/launch-codechat-cli.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 'use strict';
 
 const { runStartAgent } = require('../dist/lib/agent-launcher');

package/dist/commands/shell-integration.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveLaunchScriptPath = resolveLaunchScriptPath;
+exports.resolveWindowsTerminalPath = resolveWindowsTerminalPath;
 exports.runShellInstall = runShellInstall;
 exports.runShellUninstall = runShellUninstall;
 exports.getShellStatus = getShellStatus;
@@ -12,10 +13,12 @@ exports.runShellInstallSafe = runShellInstallSafe;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 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 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.cmd');
+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');
 function logInfo(msg, silent) {
     if (!silent)
         logger_1.logger.info(msg);
@@ -49,19 +52,74 @@ function resolveLaunchScriptPath() {
     }
     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);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve wt.exe at shell install time (Explorer context menus use this path directly).
+ */
+function resolveWindowsTerminalPath() {
+    try {
+        const out = (0, child_process_1.execFileSync)('where', ['wt'], { encoding: 'utf8', windowsHide: true }).trim();
+        const first = out.split(/\r?\n/)[0]?.trim();
+        if (first && canAccessExecutable(first)) {
+            return first;
+        }
+    }
+    catch {
+        // wt not on PATH during install
+    }
+    const localAppData = process.env.LOCALAPPDATA ?? path_1.default.join(os_1.default.homedir(), 'AppData', 'Local');
+    const candidates = [
+        path_1.default.join(localAppData, 'Microsoft', 'WindowsApps', 'wt.exe'),
+        path_1.default.join(process.env.ProgramFiles ?? 'C:\\Program Files', 'Windows Terminal', 'wt.exe'),
+    ];
+    for (const candidate of candidates) {
+        if (candidate && canAccessExecutable(candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
 function buildStubContent(launchScriptPath) {
-    return `@echo off
-setlocal EnableExtensions
-set "WORKDIR=%~1"
-if "%WORKDIR%"=="" set "WORKDIR=%CD%"
-cd /d "%WORKDIR%"
-node "${launchScriptPath.replace(/"/g, '""')}" "%WORKDIR%"
-exit /b %ERRORLEVEL%
+    const escapedNodeScript = launchScriptPath.replace(/'/g, "''");
+    // ASCII-only + UTF-8 BOM. Legacy conhost fallback sets UTF-8 before CodeChat TUI.
+    return `param(
+  [string]$WorkDir = (Get-Location).Path
+)
+
+$ErrorActionPreference = 'Stop'
+
+try { chcp 65001 | Out-Null } catch {}
+[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
+[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+$OutputEncoding = [System.Text.UTF8Encoding]::new($false)
+
+Set-Location -LiteralPath $WorkDir
+& node '${escapedNodeScript}' $WorkDir
+exit $LASTEXITCODE
 `;
 }
-function buildMenuCommand(stubPath, dirPlaceholder) {
-    const quotedStub = stubPath.includes(' ') ? `"${stubPath}"` : stubPath;
-    return `cmd.exe /s /k ${quotedStub} ${dirPlaceholder}`;
+function writeStubFile(launchScriptPath) {
+    const content = buildStubContent(launchScriptPath);
+    return fs_extra_1.default.writeFile(STUB_PATH, `\uFEFF${content}`, 'utf8');
+}
+function buildPsInvokeArgs(ps1Path, dirPlaceholder) {
+    return `-NoExit -NoProfile -ExecutionPolicy Bypass -File "${ps1Path}" ${dirPlaceholder}`;
+}
+function buildMenuCommand(ps1Path, dirPlaceholder, wtPath) {
+    const psArgs = buildPsInvokeArgs(ps1Path, dirPlaceholder);
+    if (wtPath) {
+        // Launch WT directly from registry — avoids an extra conhost window from stub bootstrap.
+        return `"${wtPath}" -d ${dirPlaceholder} --title CodeChat -- powershell.exe ${psArgs}`;
+    }
+    return `powershell.exe ${psArgs}`;
 }
 function registerMenuKey(menuKey, command) {
     (0, win_registry_1.regSetDefault)(menuKey, win_registry_1.SHELL_MENU_LABEL);
@@ -74,14 +132,22 @@ async function runShellInstall(opts = {}) {
     assertWin32();
     const launchScriptPath = resolveLaunchScriptPath();
     await fs_extra_1.default.ensureDir(STUB_DIR);
-    await fs_extra_1.default.writeFile(STUB_PATH, buildStubContent(launchScriptPath), 'utf8');
-    const bgCommand = buildMenuCommand(STUB_PATH, '"%V"');
-    const dirCommand = buildMenuCommand(STUB_PATH, '"%1"');
+    await writeStubFile(launchScriptPath);
+    if (await fs_extra_1.default.pathExists(LEGACY_STUB_PATH)) {
+        await fs_extra_1.default.remove(LEGACY_STUB_PATH);
+    }
+    const wtPath = resolveWindowsTerminalPath();
+    const bgCommand = buildMenuCommand(STUB_PATH, '"%V"', wtPath);
+    const dirCommand = buildMenuCommand(STUB_PATH, '"%1"', wtPath);
     registerMenuKey(win_registry_1.SHELL_MENU_KEY_BG, bgCommand);
     registerMenuKey(win_registry_1.SHELL_MENU_KEY_DIR, dirCommand);
-    logSuccess('Windows 右键菜单已注册：「在此启动 CodeChat Agent」', opts.silent);
+    const via = wtPath ? 'Windows Terminal' : 'PowerShell（UTF-8）';
+    logSuccess(`Windows 右键菜单已注册：「在此启动 CodeChat Agent」（${via}）`, opts.silent);
     logInfo(`  stub: ${STUB_PATH}`, opts.silent);
     logInfo(`  脚本: ${launchScriptPath}`, opts.silent);
+    if (wtPath) {
+        logInfo(`  wt:   ${wtPath}`, opts.silent);
+    }
 }
 /**
  * Remove HKCU context menus and stub file.
@@ -93,6 +159,9 @@ async function runShellUninstall(opts = {}) {
     if (await fs_extra_1.default.pathExists(STUB_PATH)) {
         await fs_extra_1.default.remove(STUB_PATH);
     }
+    if (await fs_extra_1.default.pathExists(LEGACY_STUB_PATH)) {
+        await fs_extra_1.default.remove(LEGACY_STUB_PATH);
+    }
     logSuccess('Windows 右键菜单已卸载', opts.silent);
 }
 /**
@@ -110,12 +179,14 @@ function getShellStatus() {
     const backgroundMenu = (0, win_registry_1.regKeyExists)(win_registry_1.SHELL_MENU_KEY_BG);
     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();
     return {
         installed: backgroundMenu && directoryMenu && stubExists,
         stubPath: STUB_PATH,
         backgroundMenu,
         directoryMenu,
         launchScriptPath,
+        viaWindowsTerminal: wtPath !== null,
     };
 }
 function printShellStatus() {
@@ -126,6 +197,7 @@ function printShellStatus() {
     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）' : '否'}`);
 }
 async function runShellInstallSafe(opts = {}) {
     try {

package/dist/core/next-steps.js

@@ -65,7 +65,7 @@ function printNextSteps(input) {
         lines.push('   - ' + picocolors_1.default.cyan('svharness start-agent --work-dir .'));
         lines.push('   - 或: ' + picocolors_1.default.cyan('launch_codechat_cli'));
         if (process.platform === 'win32') {
-            lines.push('   - 或: 资源管理器右键 →「在此启动 CodeChat Agent」');
+            lines.push('   - 或: 资源管理器右键 →「在此启动 CodeChat Agent」（PowerShell）');
         }
         lines.push('');
     }

package/dist/index.js

@@ -422,7 +422,7 @@ function main() {
         .description('启动 Agent CLI 填充 harness（build 后 S10–S90）或 apply 后的业务开发。默认 agent=codechat，默认 workdir=当前目录。')
         .option('--work-dir <path>', 'Agent 工作目录（harness 项目根）')
         .option('--agent <agent>', '目标 Agent（当前仅 codechat 可启动）')
-        .option('--no-sync-env', '不同步项目 .claude/.env 到用户级 ~/.claude/.env')
+        .option('--no-sync-env', '不读取项目 .claude/.env 同步到 ~/.claude/.env（永不写入项目目录）')
         .option('--no-skip-permissions', '不向 CodeChat CLI 传递 --dangerously-skip-permissions')
         .action(async (agentOrWorkdir, workdir, opts) => {
         try {
@@ -447,7 +447,7 @@ function main() {
         .description('Windows 资源管理器右键菜单管理（仅 win32）');
     shellCmd
         .command('install')
-        .description('注册 HKCU 右键菜单「在此启动 CodeChat Agent」')
+        .description('注册 HKCU 右键菜单「在此启动 CodeChat CLI」')
         .action(async () => {
         try {
             await (0, shell_integration_1.runShellInstall)();

package/dist/lib/agent-launcher.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveWorkdir = resolveWorkdir;
+exports.resolveDefaultEnvTemplatePath = resolveDefaultEnvTemplatePath;
 exports.runStartAgent = runStartAgent;
 exports.parseStartAgentPositionals = parseStartAgentPositionals;
 const fs_extra_1 = __importDefault(require("fs-extra"));
@@ -13,9 +14,46 @@ const child_process_1 = require("child_process");
 const logger_1 = require("../utils/logger");
 const validate_args_1 = require("../utils/validate-args");
 const SUPPORTED_START_AGENTS = ['codechat'];
+const DEFAULT_ENV_TEMPLATE = 'default-claude.env';
 function homePath(...segments) {
     return path_1.default.join(os_1.default.homedir(), ...segments);
 }
+/** Absolute normalized path for runner CLI args. */
+function resolveUserEnvPath(config) {
+    return path_1.default.resolve(config.envFile);
+}
+function formatRunnerArg(name, value) {
+    const resolved = path_1.default.resolve(value);
+    if (process.platform === 'win32') {
+        // Quote paths for cmd.exe (matches manual: --env-file="C:\Users\...\.claude\.env")
+        return `${name}="${resolved.replace(/"/g, '""')}"`;
+    }
+    return `${name}=${resolved}`;
+}
+const ENV_FILE_VERIFY_RETRIES = 5;
+const ENV_FILE_VERIFY_DELAY_MS = 40;
+async function delay(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** Wait until user env exists and is non-empty (Windows AV / flush visibility). */
+async function verifyUserEnvWritten(userEnvPath) {
+    for (let attempt = 1; attempt <= ENV_FILE_VERIFY_RETRIES; attempt++) {
+        try {
+            const stat = await fs_extra_1.default.stat(userEnvPath);
+            if (stat.isFile() && stat.size > 0) {
+                return;
+            }
+        }
+        catch {
+            // retry
+        }
+        if (attempt < ENV_FILE_VERIFY_RETRIES) {
+            await delay(ENV_FILE_VERIFY_DELAY_MS);
+        }
+    }
+    throw new Error(`env 写入后校验失败（文件不存在或为空）：${userEnvPath}\n` +
+        `请重试 svharness start-agent，或手动创建该文件。`);
+}
 function getCodechatRunnerConfig() {
     const platform = process.platform;
     if (platform === 'win32') {
@@ -62,14 +100,66 @@ function resolveWorkdir(opts) {
     }
     return resolved;
 }
-async function syncProjectEnv(workdir, config) {
+/**
+ * Bundled templates/default-claude.env (shipped with npm package).
+ */
+function resolveDefaultEnvTemplatePath() {
+    const candidates = [
+        path_1.default.resolve(__dirname, '..', '..', 'templates', DEFAULT_ENV_TEMPLATE),
+        path_1.default.resolve(__dirname, '..', '..', '..', 'templates', DEFAULT_ENV_TEMPLATE),
+    ];
+    for (const candidate of candidates) {
+        if (fs_extra_1.default.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    throw new Error(`未找到内置 env 模板（预期之一：\n  ${candidates.join('\n  ')}）`);
+}
+/**
+ * Env writes are allowed ONLY on ~/.claude/.env — never on project workdir.
+ */
+function assertUserEnvWriteTarget(userEnvPath) {
+    const expected = normalizeComparable(homePath('.claude', '.env'));
+    const actual = normalizeComparable(path_1.default.resolve(userEnvPath));
+    if (actual !== expected) {
+        throw new Error(`内部错误：env 只能写入用户目录 ${homePath('.claude', '.env')}，禁止写入项目路径。`);
+    }
+}
+async function copyEnvToUserOnly(fromPath, userEnvPath) {
+    assertUserEnvWriteTarget(userEnvPath);
+    const dest = path_1.default.resolve(userEnvPath);
+    await fs_extra_1.default.ensureDir(path_1.default.dirname(dest));
+    const content = await fs_extra_1.default.readFile(fromPath, 'utf8');
+    await fs_extra_1.default.writeFile(dest, content, { encoding: 'utf8' });
+    await verifyUserEnvWritten(dest);
+}
+/**
+ * Sync project env to user profile, or seed bundled default when none exists.
+ *
+ * **One-way only (read project, write user):**
+ * - May read `<workdir>/.claude/.env` as source
+ * - May write ONLY `~/.claude/.env`
+ * - NEVER creates or modifies `<workdir>/.claude/.env`
+ *
+ * Priority:
+ * 1. Project env exists + syncEnv → copy project → user (user overwritten, project untouched)
+ * 2. User env exists → keep
+ * 3. Bundled default → copy to user only
+ */
+async function ensureUserEnv(workdir, config, syncEnv) {
     const projectEnv = path_1.default.join(workdir, config.envSyncFromRel);
-    if (!(await fs_extra_1.default.pathExists(projectEnv))) {
+    const userEnv = config.envFile;
+    if (syncEnv && (await fs_extra_1.default.pathExists(projectEnv))) {
+        await copyEnvToUserOnly(projectEnv, userEnv);
+        logger_1.logger.info(`已读取项目 env 并同步到用户目录（未修改项目文件）→ ${userEnv}`);
         return;
     }
-    await fs_extra_1.default.ensureDir(path_1.default.dirname(config.envFile));
-    await fs_extra_1.default.copy(projectEnv, config.envFile, { overwrite: true });
-    logger_1.logger.info(`已同步项目 env → ${config.envFile}`);
+    if (await fs_extra_1.default.pathExists(userEnv)) {
+        return;
+    }
+    const defaultTemplate = resolveDefaultEnvTemplatePath();
+    await copyEnvToUserOnly(defaultTemplate, userEnv);
+    logger_1.logger.info(`已写入内置默认 env 到用户目录（未写入项目）→ ${userEnv}`);
 }
 function warnIfNotHarnessProject(workdir) {
     const hints = [];
@@ -93,9 +183,10 @@ function warnIfNotHarnessProject(workdir) {
     }
 }
 function buildRunnerArgs(config, workdir, skipPermissions) {
+    const envFile = resolveUserEnvPath(config);
     const args = [
-        `--env-file=${config.envFile}`,
-        `--cwd=${workdir}`,
+        formatRunnerArg('--env-file', envFile),
+        formatRunnerArg('--cwd', workdir),
     ];
     if (skipPermissions) {
         args.push('--dangerously-skip-permissions');
@@ -118,16 +209,16 @@ async function runStartAgent(opts) {
     const config = getCodechatRunnerConfig();
     const syncEnv = opts.syncEnv !== false;
     const skipPermissions = opts.skipPermissions !== false;
-    if (syncEnv) {
-        await syncProjectEnv(workdir, config);
-    }
+    await ensureUserEnv(workdir, config, syncEnv);
+    const userEnvFile = resolveUserEnvPath(config);
     if (!(await fs_extra_1.default.pathExists(config.runner))) {
         throw new Error(`未找到 CodeChat CLI：${config.runner}\n请先安装 CodeChat CLI 到用户目录。`);
     }
-    if (!(await fs_extra_1.default.pathExists(config.envFile))) {
-        throw new Error(`未找到 env 文件：${config.envFile}\n` +
-            `请在 ${path_1.default.join(workdir, config.envSyncFromRel)} 或 ${config.envFile} 创建配置。`);
+    if (!(await fs_extra_1.default.pathExists(userEnvFile))) {
+        throw new Error(`未找到 env 文件：${userEnvFile}\n` +
+            `请提供 ${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 Agent（workdir: ${workdir}）`);

package/dist/lib/win-registry.js

@@ -49,4 +49,4 @@ function regKeyExists(key) {
 }
 exports.SHELL_MENU_KEY_BG = 'HKCU\\Software\\Classes\\Directory\\Background\\shell\\SvharnessLaunchCodeChatAgent';
 exports.SHELL_MENU_KEY_DIR = 'HKCU\\Software\\Classes\\Directory\\shell\\SvharnessLaunchCodeChatAgent';
-exports.SHELL_MENU_LABEL = '在此启动 CodeChat Agent';
+exports.SHELL_MENU_LABEL = '在此启动 CodeChat CLI';

package/docs/agent-launcher-design.md

@@ -36,7 +36,7 @@
 │ 入口层                                                       │
 │  launch_codechat_cli [workdir]                               │
 │  svharness start-agent [agent] [workdir] [--work-dir ...]    │
-│  Explorer 右键 → stub.cmd → launch-codechat-cli.js           │
+│  Explorer 右键 → stub.ps1 → launch-codechat-cli.js           │
 └───────────────────────────┬─────────────────────────────────┘
                             │
 ┌───────────────────────────▼─────────────────────────────────┐
@@ -125,14 +125,28 @@ launch_codechat_cli ./my-app     # 指定 workdir
 
 ## 5. env 同步策略
 
-| 步骤 | 行为 |
-|------|------|
-| 1 | 检查 `<workdir>/.claude/.env` |
-| 2 | 若存在且未指定 `--no-sync-env`，拷贝到 `~/.claude/.env`（覆盖） |
-| 3 | 自动创建 `~/.claude/` 目录 |
-| 4 | 启动时使用 `--env-file=~/.claude/.env` |
+**铁律：单向同步，只写用户目录，永不碰项目。**
+
+| 操作 | 允许 | 禁止 |
+|------|------|------|
+| 读取 `<workdir>/.claude/.env` | ✅ | — |
+| 写入 `~/.claude/.env` | ✅ | — |
+| 写入 `<workdir>/.claude/.env` | — | ❌ |
+| 覆盖 / 修改项目级 `.claude/.env` | — | ❌ |
+
+优先级（高 → 低）：
+
+| 优先级 | 条件 | 行为 |
+|--------|------|------|
+| 1 | 项目 `.claude/.env` 存在且未 `--no-sync-env` | **只读**项目文件，内容复制到 `~/.claude/.env`（覆盖用户级；**项目文件不变**） |
+| 2 | `~/.claude/.env` 已存在 | 保持不变 |
+| 3 | 以上均不满足 | 从 `templates/default-claude.env` **仅**生成 `~/.claude/.env` |
+
+内置模板为德赛 CodeChat 通用配置（含默认 `ANTHROPIC_AUTH_TOKEN`）。项目 `.claude/.env` 仍可覆盖同步到用户目录。
 
-若同步后用户级 env 仍不存在 → 报错并提示创建方式。
+启动时 CodeChat 使用 `--env-file=~/.claude/.env`（Windows 下带引号的绝对路径，避免 cmd 解析偶发失败）。
+
+写入 `~/.claude/.env` 后会做 **存在 + 非空** 校验（最多 5 次、间隔 40ms），缓解 Windows 上杀毒/索引导致的短暂不可见。
 
 ---
 
@@ -156,25 +170,63 @@ macOS (`darwin`) 路径约定与 Linux 相同；若 runner 不存在则报错。
 资源管理器触发的命令 **不保证** 含 `%AppData%\npm` PATH。因此 registry 指向固定路径：
 
 ```
-%LOCALAPPDATA%\svharness\bin\launch_codechat_cli.cmd
+%LOCALAPPDATA%\svharness\bin\launch_codechat_cli.ps1
 ```
 
 stub 接收 Explorer 传入的目录参数，`cd` 后调用 **绝对路径** 的 `bin/launch-codechat-cli.js`。
 
-### 7.2 注册表结构
+### 7.3 终端与编码（右键 vs 手动 PowerShell）
+
+| 启动方式 | 典型终端 | 现象 |
+|----------|----------|------|
+| 手动打开 PowerShell 再 `start-agent` | **Windows Terminal** / 已配置 UTF-8 的会话 | CodeChat TUI 框线正常 |
+| 资源管理器右键（旧实现） | **conhost 经典蓝底** + `-NoProfile` | Unicode 框线乱码、`>>` 变 `\|\|` |
+
+原因：CodeChat CLI 使用 Unicode 制表符（`╔═╗`）。经典控制台默认代码页（如 GBK）无法正确渲染。
+
+**修复（注册表直接启动 WT）**：
+
+1. `shell install` 检测到 **Windows Terminal**（`wt.exe`）时，注册表 command **直接调用 wt**，不再先开 conhost 再二次跳转（避免两个窗口）
+2. 未安装 WT 时 fallback：`powershell.exe` + stub 内 `chcp 65001` UTF-8
+
+重新注册：`svharness shell install`
+
+### 7.4 注册表结构
 
 | 位置 | 键 |
 |------|-----|
 | 文件夹空白处 | `HKCU\Software\Classes\Directory\Background\shell\SvharnessLaunchCodeChatAgent` |
 | 文件夹图标 | `HKCU\Software\Classes\Directory\shell\SvharnessLaunchCodeChatAgent` |
 
-菜单标题：`在此启动 CodeChat Agent`
+菜单标题：`在此启动 CodeChat CLI`
+
+Command（Background，已安装 WT 时）：
+
+```text
+"C:\Users\<user>\AppData\Local\Microsoft\WindowsApps\wt.exe" -d "%V" --title CodeChat -- powershell.exe -NoExit -NoProfile -ExecutionPolicy Bypass -File "<stub.ps1>" "%V"
+```
+
+Command（Background，无 WT 时）：
+
+```text
+powershell.exe -NoExit -NoProfile -ExecutionPolicy Bypass -File "<stub.ps1>" "%V"
+```
+
+Command（Directory，已安装 WT 时）：
+
+```text
+"C:\Users\<user>\AppData\Local\Microsoft\WindowsApps\wt.exe" -d "%1" --title CodeChat -- powershell.exe -NoExit -NoProfile -ExecutionPolicy Bypass -File "<stub.ps1>" "%1"
+```
+
+Command（Directory，无 WT 时）：
 
-Command（Background）：`cmd.exe /s /k "<stub>" "%V"`
+```text
+powershell.exe -NoExit -NoProfile -ExecutionPolicy Bypass -File "<stub.ps1>" "%1"
+```
 
-Command（Directory）：`cmd.exe /s /k "<stub>" "%1"`
+使用 `-NoExit` 保持 PowerShell 窗口开启以便 CodeChat 交互；`-ExecutionPolicy Bypass` 避免本地脚本执行策略拦截 stub。
 
-使用 `/k` 保持 CMD 窗口开启以便 CodeChat 交互。
+stub 脚本须为 **UTF-8 BOM + ASCII 正文**（Windows PowerShell 5.1 对无 BOM 的 UTF-8 文件中的非 ASCII 注释会解析失败）。
 
 ---
 
@@ -239,7 +291,7 @@ svharness start-agent --work-dir . --no-skip-permissions
 **Q: 右键菜单无反应**
 
 1. `svharness shell status` 检查注册状态
-2. 确认 stub 存在：`%LOCALAPPDATA%\svharness\bin\launch_codechat_cli.cmd`
+2. 确认 stub 存在：`%LOCALAPPDATA%\svharness\bin\launch_codechat_cli.ps1`
 3. 重新安装：`svharness shell install`
 
 **Q: 未找到 run.bat / run.sh**

package/package.json

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

package/templates/default-claude.env

@@ -0,0 +1,60 @@
+# ============================================================
+# CodeChat 接口（svharness 内置默认模板 → 仅 ~/.claude/.env）
+# 仅写入用户目录；不会创建或修改项目 <workdir>/.claude/.env
+# 若项目已有 .claude/.env，start-agent 只读并同步到 ~/.claude/.env
+# ============================================================
+ANTHROPIC_AUTH_TOKEN=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InVpZHEzNjQwIiwiZXhwIjoxNzgyMDM2MTkxfQ.GXsNuJ2Wi92VHepau51dTWGswHft6xovvOufVjtuBYk
+ANTHROPIC_BASE_URL=https://aiplus.desaysv.com/chatbot/anthropic
+# ANTHROPIC_BASE_URL=http://127.0.0.1:6008/chatbot/anthropic  # 德赛本地调试
+ANTHROPIC_MODEL=deepseek
+ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek
+ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek
+API_TIMEOUT_MS=3000000
+
+# ============================================================
+# OpenAI（通过 LiteLLM 代理）
+# 先启动: litellm --config litellm_config.yaml --port 4000
+# ============================================================
+# ANTHROPIC_AUTH_TOKEN=sk-anything
+# ANTHROPIC_BASE_URL=http://localhost:4000
+# ANTHROPIC_MODEL=gpt-4o
+# ANTHROPIC_DEFAULT_SONNET_MODEL=gpt-4o
+# ANTHROPIC_DEFAULT_HAIKU_MODEL=gpt-4o
+# ANTHROPIC_DEFAULT_OPUS_MODEL=gpt-4o
+# API_TIMEOUT_MS=3000000
+
+# ============================================================
+# DeepSeek（通过 LiteLLM 代理）
+# ============================================================
+# ANTHROPIC_AUTH_TOKEN=sk-anything
+# ANTHROPIC_BASE_URL=http://localhost:4000
+# ANTHROPIC_MODEL=deepseek-chat
+# ANTHROPIC_DEFAULT_SONNET_MODEL=deepseek-chat
+# ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-chat
+# ANTHROPIC_DEFAULT_OPUS_MODEL=deepseek-chat
+# API_TIMEOUT_MS=3000000
+
+# ============================================================
+# OpenRouter（直连 Anthropic 兼容接口）
+# ============================================================
+# ANTHROPIC_AUTH_TOKEN=sk-or-v1-xxx
+# ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1
+# ANTHROPIC_MODEL=openai/gpt-4o
+# ANTHROPIC_DEFAULT_SONNET_MODEL=openai/gpt-4o
+# ANTHROPIC_DEFAULT_HAIKU_MODEL=openai/gpt-4o-mini
+# ANTHROPIC_DEFAULT_OPUS_MODEL=openai/gpt-4o
+
+# ============================================================
+# 德赛调试专用
+# ============================================================
+CLAUDE_CODE_TRACE_ENABLED=0
+CLAUDE_CODE_TRACE_PIPELINE=0
+CLAUDE_CODE_TRACE_PIPELINE_FILE=
+CLAUDE_CODE_TRACE_WIRE_PARAMS=0
+
+# ============================================================
+# 通用设置（建议始终开启）
+# ============================================================
+DISABLE_TELEMETRY=1
+CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
+ENABLE_TOOL_SEARCH=0