svharness 0.14.11 → 0.14.12

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

@@ -15,7 +15,8 @@ const os_1 = __importDefault(require("os"));
 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);
@@ -50,18 +51,23 @@ function resolveLaunchScriptPath() {
     throw new Error(`未找到 launch-codechat-cli.js（预期：${fromDist}）`);
 }
 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: Windows PowerShell 5.1 misparses UTF-8 without BOM when comments contain non-ASCII.
+    return `param(
+  [string]$WorkDir = (Get-Location).Path
+)
+
+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 buildMenuCommand(ps1Path, dirPlaceholder) {
+    return `powershell.exe -NoExit -NoProfile -ExecutionPolicy Bypass -File "${ps1Path}" ${dirPlaceholder}`;
 }
 function registerMenuKey(menuKey, command) {
     (0, win_registry_1.regSetDefault)(menuKey, win_registry_1.SHELL_MENU_LABEL);
@@ -74,12 +80,15 @@ 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');
+    await writeStubFile(launchScriptPath);
+    if (await fs_extra_1.default.pathExists(LEGACY_STUB_PATH)) {
+        await fs_extra_1.default.remove(LEGACY_STUB_PATH);
+    }
     const bgCommand = buildMenuCommand(STUB_PATH, '"%V"');
     const dirCommand = buildMenuCommand(STUB_PATH, '"%1"');
     registerMenuKey(win_registry_1.SHELL_MENU_KEY_BG, bgCommand);
     registerMenuKey(win_registry_1.SHELL_MENU_KEY_DIR, dirCommand);
-    logSuccess('Windows 右键菜单已注册：「在此启动 CodeChat Agent」', opts.silent);
+    logSuccess('Windows 右键菜单已注册：「在此启动 CodeChat Agent」（PowerShell）', opts.silent);
     logInfo(`  stub: ${STUB_PATH}`, opts.silent);
     logInfo(`  脚本: ${launchScriptPath}`, opts.silent);
 }
@@ -93,6 +102,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);
 }
 /**

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,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 SUPPORTED_START_AGENTS = ['codechat'];
+const DEFAULT_ENV_TEMPLATE = 'default-claude.env';
 function homePath(...segments) {
     return path_1.default.join(os_1.default.homedir(), ...segments);
 }
@@ -62,14 +64,63 @@ 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);
+    await fs_extra_1.default.ensureDir(path_1.default.dirname(userEnvPath));
+    await fs_extra_1.default.copy(fromPath, userEnvPath, { overwrite: true });
+}
+/**
+ * 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;
+    }
+    if (await fs_extra_1.default.pathExists(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}`);
+    const defaultTemplate = resolveDefaultEnvTemplatePath();
+    await copyEnvToUserOnly(defaultTemplate, userEnv);
+    logger_1.logger.info(`已写入内置默认 env 到用户目录（未写入项目）→ ${userEnv}`);
 }
 function warnIfNotHarnessProject(workdir) {
     const hints = [];
@@ -118,15 +169,13 @@ 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);
     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} 创建配置。`);
+            `请提供 ${path_1.default.join(workdir, config.envSyncFromRel)}，或确保内置模板 templates/default-claude.env 可访问。`);
     }
     warnIfNotHarnessProject(workdir);
     const args = buildRunnerArgs(config, workdir, skipPermissions);

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,26 @@ 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` |
 
-若同步后用户级 env 仍不存在 → 报错并提示创建方式。
+内置模板为德赛 CodeChat 通用配置。首次使用前请配置有效 `ANTHROPIC_AUTH_TOKEN`（改用户级 env 或项目 `.claude/.env`）。
+
+启动时 CodeChat 使用 `--env-file=~/.claude/.env`。
 
 ---
 
@@ -156,7 +168,7 @@ 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`。
@@ -168,13 +180,23 @@ stub 接收 Explorer 传入的目录参数，`cd` 后调用 **绝对路径** 的
 | 文件夹空白处 | `HKCU\Software\Classes\Directory\Background\shell\SvharnessLaunchCodeChatAgent` |
 | 文件夹图标 | `HKCU\Software\Classes\Directory\shell\SvharnessLaunchCodeChatAgent` |
 
-菜单标题：`在此启动 CodeChat Agent`
+菜单标题：`在此启动 CodeChat CLI`
+
+Command（Background）：
+
+```text
+powershell.exe -NoExit -NoProfile -ExecutionPolicy Bypass -File "<stub.ps1>" "%V"
+```
+
+Command（Directory）：
 
-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 +261,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.12",
   "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=YOUR_ANTHROPIC_AUTH_TOKEN
+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