svharness 0.14.13 → 0.14.17

package/README.md

@@ -133,7 +133,7 @@ Harness 是一个 **项目本地的知识层**，由两大部分组成：
 └── tasks/                        # 可复用的开发者工作流
 ```
 
-同时，CLI 会在**项目根**写入 `CLAUDE.md`（`--agent codechat` 或 `claude-code`）或 `AGENTS.md`（`qoder` / `cursor` / `opencode` / `generic`），并向 Agent IDE 的 skill 目录注入 **7 个构建辅助 skill**：
+同时，CLI 会在**项目根**写入 `CLAUDE.md`（`--agent codechat` 或 `claude-code`）或 `AGENTS.md`（`qoder` / `cursor` / `opencode` / `codex` / `generic`），并向 Agent IDE 的 skill 目录注入 **7 个构建辅助 skill**：
 
 | Skill | 职责 |
 |-------|------|
@@ -228,6 +228,7 @@ svharness wizard
 | `apply` | 对应 `svharness apply` |
 | `convert` | 对应 `svharness convert` |
 | `doctor` | 对应 `svharness doctor` |
+| `wiki` | 对应 `svharness wiki` |
 
 `build` 节除路径外，可写人类可读说明（仅写入配置文件，供团队阅读）：
 
@@ -270,7 +271,7 @@ svharness build \
 | `--harness-name <name>` | ✅ 必填* | harness 名称；可在 `build.harnessName` 中提供 | — |
 | `--name <name>` | ⚠️ 已废弃别名 | 等同 `--harness-name`，下个 minor 版本移除 | — |
 | `--arch <arch>` | 可选 | 架构模板：`android-compose` / `android-xml` / `cpp` / `web-react` / `python` | `android-compose` |
-| `--agent <agent>` | 可选 | 目标 Agent IDE：`codechat` / `qoder` / `cursor` / `claude-code` / `opencode` / `generic` | `codechat` |
+| `--agent <agent>` | 可选 | 目标 Agent IDE：`codechat` / `qoder` / `cursor` / `claude-code` / `opencode` / `codex` / `generic` | `codechat` |
 | `--baseline <path\|url>` | 可选 | 基线来源：本地目录 **或** git 仓库 URL | — |
 | `--requirements <path>` | 可选 | 需求输入路径（文件或目录）；build 阶段**扁平**拷贝到 `requirements/raw/`（不保留源目录里的 `assets/raw/converted_md` 等嵌套），随后自动 convert 到 `requirements/md/`（失败仅告警，不中断 build） | — |
 | `--references <path>` | 可选 | 参考资料输入路径（文件或目录）；build 阶段**扁平**拷贝到 `references/raw/`，随后自动 convert 到 `references/md/`（失败仅告警，不中断 build） | — |
@@ -312,6 +313,8 @@ svharness build \
 | `--baseline` + `--generate-wiki` | 逐页调用 LLM 生成完整 wiki | 初始 `DONE`；失败降级为 `PENDING` |
 
 > Wiki 生成失败不会回滚 harness 骨架，仅输出警告。
+>
+> build 内置 wiki 的 LLM prompt **面向编码 Agent**（知识路由卡片）；独立 `svharness wiki` 默认面向人类开发者，见 [`wiki` 命令](#wiki-standalone) 一节。
 
 #### Repomix（`--repomix`）{#repomix-repomix}
 
@@ -351,7 +354,9 @@ svharness build --harness-name my-app --baseline ./src --repomix
 | `qoder` | `.qoder/skills/` | `.md` | — |
 | `cursor` | `.cursor/rules/` | `.mdc` | 自动注入 frontmatter |
 | `claude-code` | `.claude/skills/` | `.md` | — |
-| `generic` | `.agent/skills/` | `.md` | 中立回退 |
+| `opencode` | `.opencode/skills/` | `.md` | — |
+| `codex` | `.agents/skills/` | `.md` | — |
+| `generic` | `.harness/skills/` | `.md` | 中立回退 |
 
 ### `apply` —— 把已构建好的 harness 绑定到目标项目
 
@@ -367,7 +372,7 @@ svharness apply --harness ../my-app-harness --target ./to-apply-project --clone
 
 **在 Agent IDE 中触发**：对话框输入 `应用 harness-apply-skills-main 完成 xxx 功能开发`，薄入口会提示并优先使用已注入的 `harness-apply-skills-*` 子 skill。
 
-同时，CLI 会在**目标项目根**写入 `CLAUDE.md`（`--agent codechat` 或 `claude-code`）或 `AGENTS.md`（`qoder` / `cursor` / `opencode` / `generic`）。该入口由 `<harness>/AGENTS_APPLY.md` 拷贝并重命名生成（与 `build` 写入项目根入口的规则一致，不再单独落地 `AGENTS_APPLY.md`）。
+同时，CLI 会在**目标项目根**写入 `CLAUDE.md`（`--agent codechat` 或 `claude-code`）或 `AGENTS.md`（`qoder` / `cursor` / `opencode` / `codex` / `generic`）。该入口由 `<harness>/AGENTS_APPLY.md` 拷贝并重命名生成（与 `build` 写入项目根入口的规则一致，不再单独落地 `AGENTS_APPLY.md`）。
 
 此外，`apply` 会同步注入运行期资产：
 
@@ -399,7 +404,7 @@ S60（`harness-build-skill-references-intake`）属于 **build 阶段**。若某
 |------|----------|------|--------|
 | `--harness <path>` | ✅ 必填 | 已构建好的 harness 目录（形如 `./my-app-harness`） | — |
 | `--target <path>` | 可选 | 目标项目根目录 | **当前工作目录（cwd）** |
-| `--agent <agent>` | 可选 | 目标 Agent：`codechat` / `qoder` / `cursor` / `claude-code` / `opencode` / `generic` | `codechat` |
+| `--agent <agent>` | 可选 | 目标 Agent：`codechat` / `qoder` / `cursor` / `claude-code` / `opencode` / `codex` / `generic` | `codechat` |
 | `--clone` | 可选 flag | 兼容参数；当前实现下行为与默认一致（都会拷贝 harness） | `false` |
 | `--include-build-assets` | 可选 flag | 显式拷贝构建期 skills/rules 到 `build-agent-env/`（用于二次改造） | `false` |
 | `--inject-build-main-bridge` | 可选 flag | 向运行期 skills 注入 `harness-build-skills-bridge`（需 `--include-build-assets`） | `false` |
@@ -574,6 +579,92 @@ convert-failures.json
 
 完整契约、fallback chain、Docker 部署见 [markitdown_serve/README.md](./markitdown_serve/README.md)；模块设计见 [tmp/svharnessbuild-detail-design.md §4.10](../tmp/svharnessbuild-detail-design.md#410-文档转换convert-命令--markitdown_serve-远端服务)。
 
+### `wiki` —— 对任意代码工程生成 baseline wiki（v0.15+）
+
+独立子命令，**不依赖 harness 生命周期**，直接对任意代码工程目录就地扫描生成 wiki。与 `build` 内置 wiki 共用同一 repowiki 核心，但不拷贝 code、不创建 harness 骨架。
+
+```bash
+# 对当前工程生成 wiki 骨架（默认 ./wiki/）
+svharness wiki
+
+# 完整生成（LLM 逐页）
+svharness wiki --generate-wiki
+
+# 指定源码目录 + 完整生成
+svharness wiki --wiki-source ./src --generate-wiki --output ./docs/wiki
+
+# 对外部仓库目录生成（不拷贝，就地扫描）
+svharness wiki --wiki-source /path/to/other-project --output ./other-wiki
+
+# 可选：同步到已有 harness 的 S10_wiki
+svharness wiki --wiki-source ./src \
+  --output ./my-app-harness/baseline/wiki \
+  --harness ./my-app-harness --update-state --generate-wiki
+```
+
+#### 全部参数
+
+| 参数 | 必填 | 说明 | 默认值 |
+|------|------|------|--------|
+| `--wiki-source <path>` | 否 | 要扫描的代码工程根目录 | `.`（cwd） |
+| `--output <path>` | 否 | wiki 产物输出目录 | `./wiki` |
+| `--generate-wiki` | 否 | 完整生成（LLM 逐页；与 `--wiki-tasks-only` 互斥） | `false` |
+| `--wiki-tasks-only` | 否 | 仅生成 outline + TASKS.md（与默认等价） | `true`（隐式默认） |
+| `--wiki-lang <lang>` | 否 | 输出语言：`zh` \| `en` | `zh` |
+| `--wiki-model <model>` | 否 | LLM 模型名称 | 内置默认 |
+| `--wiki-base-url <url>` | 否 | OpenAI 兼容 API 地址 | 内置默认 |
+| `--wiki-api-key <key>` | 否 | API 密钥 | 环境变量 / `.env` |
+| `--project-name <name>` | 否 | TASKS.md 标题（默认取 `wiki-source` 的目录名） | — |
+| `--force-full` | 否 | full 模式忽略 checkpoint 强制重新生成 | `false` |
+| `--harness <path>` | 否 | 已有 harness 根目录；**提供时 wiki prompt 面向编码 Agent**（配合 `--update-state` 同步 state） | — |
+| `--update-state` | 否 | 同步 S10_wiki 到 harness 的 `.harness-build-state.yaml`（须同时提供 `--harness`） | `false` |
+| `--config <path>` | 否 | 从配置文件读取 wiki 节 | `svharness.config.yaml` |
+| `--verbose` | 否 | 显示详细日志 | `false` |
+
+#### 与 `build` 内置 wiki 的区别
+
+| 维度 | `svharness build`（内置） | `svharness wiki`（独立） |
+|------|--------------------------|-------------------------|
+| 源码 | 拷贝 `--baseline` → `<harness>/baseline/code/` | **就地扫描**，不拷贝 |
+| 默认源码根 | `baseline/code/` | **cwd（`.`）** |
+| 输出目录 | `<harness>/baseline/wiki/` | **`./wiki/`** |
+| 依赖 harness | 是（创建 harness 骨架） | **否** |
+
+**Wiki 受众（prompt 自动选择，无需 CLI 开关）**：
+
+| 入口 | 受众 | 产出风格 |
+|------|------|----------|
+| `svharness build --baseline` | 编码 AI Agent | 知识地图：路由式大纲、固定章节正文 |
+| `svharness wiki`（无 `--harness`） | 人类开发者 | 教程式大纲、简介 + TOC + 叙述性文档 |
+| `svharness wiki --harness <path>` | 编码 AI Agent | 与 build 相同（供 harness baseline/wiki 消费） |
+| state 更新 | init 时自动写 S10_wiki | 默认不写；可选 `--update-state --harness` |
+
+#### 产出布局
+
+```
+./wiki/                      # 或 --output 指定的目录
+├── structure.xml            # outline XML
+├── TASKS.md                 # tasks 模式产出（可交给 agent 补页）
+├── metadata.json            # full 模式产出
+├── checkpoint.json          # full 模式进度（可续跑）
+└── zh/<section>/<page>.md   # full 模式各页面
+```
+
+#### 配置文件支持
+
+在 `svharness.config.yaml` 中可配置 wiki 节：
+
+```yaml
+wiki:
+  wikiSource: .
+  output: ./wiki
+  generateWiki: false
+  wikiLang: zh
+  wikiModel: Qwen3.6-27B
+```
+
+优先级：CLI 参数 > `wiki:` 节 > `defaults:` > 内置默认。
+
 ### `start-agent` —— 启动 Agent 填充 harness（v0.16+）
 
 `build` 生成骨架后，用本命令在**项目根（workdir）**启动 CodeChat CLI，驱动 S10–S90 构建阶段；`apply` 之后亦可在目标项目根启动 Agent 做业务开发。
@@ -608,12 +699,58 @@ svharness start-agent --work-dir . --no-sync-env --no-skip-permissions
 | `--no-sync-env` | 不读取项目 `.claude/.env` 同步到用户级（仍可用已有 `~/.claude/.env`；若无则仅写入用户级内置模板） | false |
 | `--no-skip-permissions` | 不传 `--dangerously-skip-permissions` | 默认传 |
 
+#### CodeChat runner 解析
+
+`start-agent` / `launch_codechat_cli` 按以下优先级查找 `run.bat`（Windows）或 `run.sh`（Linux/macOS）：
+
+| 优先级 | 来源 | 路径示例 |
+|--------|------|----------|
+| 1 | 环境变量 | `CODECHAT_CLI_RUNNER` 指向绝对路径 |
+| 2 | 独立安装 | `~/.codechat/cli_app/run.bat`（Win）/ `run.sh`（Linux） |
+| 3 | IDE 插件 | `%APPDATA%\Google\AndroidStudio*\plugins\CodeChat\cli\run.bat` 等 |
+
+若 CodeChat 仅通过 **Android Studio / IntelliJ IDEA 插件**安装（无 `~/.codechat/cli_app`），会自动扫描 IDE 插件目录，**无需指定 IDE 版本号**。
+
+启动成功时日志示例：
+
+```text
+CodeChat CLI: C:\Users\...\AndroidStudio2024.2\plugins\CodeChat\cli\run.bat (ide-plugin: Android Studio 2024.2)
+```
+
+**手动指定 runner**（PowerShell）：
+
+```powershell
+$env:CODECHAT_CLI_RUNNER = "$env:APPDATA\Google\AndroidStudio2024.2\plugins\CodeChat\cli\run.bat"
+svharness start-agent --work-dir D:\projects\my-app
+```
+
+**bash**：
+
+```bash
+export CODECHAT_CLI_RUNNER="$HOME/.local/share/JetBrains/IntelliJIdea2024.2/plugins/CodeChat/cli/run.sh"
+svharness start-agent --work-dir ~/projects/my-app
+```
+
 #### 平台说明
 
-| 平台 | CodeChat runner |
-|------|-----------------|
-| Windows | `~/.codechat/cli_app/run.bat` |
-| Linux | `~/.codechat/cli_app/run.sh` |
+| 平台 | spawn 模式 | 右键菜单 |
+|------|------------|----------|
+| Windows | `shell: true` | 支持（`svharness shell`） |
+| Linux / macOS | `shell: false` | 不支持 |
+
+### 无需 svharness：独立 PowerShell 启动器
+
+未安装 npm / svharness 时，可拷贝 [`templates/codechat/Start-CodeChat.ps1`](templates/codechat/Start-CodeChat.ps1) 到项目 `.claude\`，实现相同的 env 同步与 `run.bat` 解析（含 Android Studio / IDEA 插件路径）：
+
+```powershell
+Copy-Item .\templates\codechat\Start-CodeChat.ps1 .\.claude\
+.\.claude\Start-CodeChat.ps1                              # 启动
+.\.claude\Start-CodeChat.ps1 -Action InstallMenu          # 可选：独立右键菜单
+```
+
+右键菜单使用注册表键 `CodeChatStandaloneAgent`，**不与** `svharness shell install` 冲突；可与 svharness 菜单并存。
+
+详见 [`docs/standalone-codechat-ps1.md`](docs/standalone-codechat-ps1.md)。
 
 ### `launch_codechat_cli` —— 全局快捷命令（v0.16+）
 
@@ -633,6 +770,8 @@ launch_codechat_cli ~/projects/my-app     # Linux
 svharness shell install      # 注册（幂等）
 svharness shell uninstall    # 移除
 svharness shell status       # 查看 stub / 注册表状态
+svharness shell uninstall
+npm uninstall -g svharness
 ```
 
 `npm install -g svharness` 在 Windows 上 **默认自动** `shell install`。跳过：

package/dist/adapters/codex.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.codexAdapter = void 0;
+const _frontmatter_1 = require("./_frontmatter");
+/**
+ * OpenAI Codex: project skills under `.agents/skills/<name>/SKILL.md`,
+ * project guidance via `AGENTS.md`.
+ * @see https://developers.openai.com/codex/skills
+ * @see https://developers.openai.com/codex/guides/agents-md
+ */
+exports.codexAdapter = {
+    name: 'codex',
+    projectEntryFile: 'AGENTS.md',
+    skillsDir: '.agents/skills',
+    skillExt: '.md',
+    rulesDir: '.agents/rules',
+    ruleExt: '.mdc',
+    ruleTransform: (0, _frontmatter_1.ensureMdcFrontmatter)('Harness build-time rule'),
+};

package/dist/adapters/index.js

@@ -8,12 +8,14 @@ const cursor_1 = require("./cursor");
 const claude_code_1 = require("./claude-code");
 const generic_1 = require("./generic");
 const opencode_1 = require("./opencode");
+const codex_1 = require("./codex");
 const REGISTRY = {
     codechat: codechat_1.codechatAdapter,
     qoder: qoder_1.qoderAdapter,
     cursor: cursor_1.cursorAdapter,
     'claude-code': claude_code_1.claudeCodeAdapter,
     opencode: opencode_1.opencodeAdapter,
+    codex: codex_1.codexAdapter,
     generic: generic_1.genericAdapter,
 };
 function getAdapter(name) {

package/dist/commands/doctor/utils.js

@@ -164,6 +164,7 @@ exports.AGENT_BLACKLIST = [
     'cursor',
     'claude-code',
     'opencode',
+    'codex',
     'claude',
     'chatgpt',
     'gpt-4',
@@ -172,6 +173,7 @@ exports.AGENT_BLACKLIST = [
     '.cursor/',
     '.claude/',
     '.opencode/',
+    '.agents/',
 ];
 exports.TASK_CATEGORY_HINTS = [
     ['新增', '信号', '接口', '数据', 'increment', 'add'],

package/dist/commands/init.js

@@ -61,6 +61,7 @@ const extra_assets_intake_1 = require("../core/extra-assets-intake");
 const baseline_copy_1 = require("../utils/baseline-copy");
 const doc_intake_paths_1 = require("../core/doc-intake-paths");
 const convert_1 = require("./convert");
+const run_wiki_generation_1 = require("../lib/wiki/run-wiki-generation");
 const wiki_1 = require("../wiki");
 /**
  * Resolve the absolute path to the bundled templates/ directory.
@@ -387,11 +388,17 @@ async function runInit(opts) {
             agent: validated.agent,
             force: !!opts.force,
         });
+        // Collect adapter-specific root directories for gitignore.
+        const ignoreRoots = new Set();
+        ignoreRoots.add(node_path_1.default.posix.join('/', node_path_1.default.posix.dirname(adapterEntry.skillsDir), '/'));
+        if (adapterEntry.rulesDir) {
+            ignoreRoots.add(node_path_1.default.posix.join('/', node_path_1.default.posix.dirname(adapterEntry.rulesDir), '/'));
+        }
         const ignoreEntries = [
             `/${dirName}/`,
             '/AGENTS.md',
             '/CLAUDE.md',
-            '/.codechat/',
+            ...ignoreRoots,
         ];
         const ignoreAdded = await (0, project_ignore_1.appendProjectIgnoreEntries)({
             projectRoot: cwd,
@@ -454,141 +461,42 @@ async function runInit(opts) {
     //    the wiki result.
     let resolvedWikiPhase = wikiMode === 'off' ? 'none' : wikiMode === 'tasks' ? 'pending' : 'done';
     let resolvedWikiSource;
-    if (wikiMode === 'full') {
-        logger_1.logger.section(`步骤 ${stepWiki}/${totalSteps} - 生成 baseline wiki`);
-        let wikiFullOk = false;
-        try {
-            const repoRootFs = wikiSourceRoot;
-            const wikiOutputRootFs = targetRoot;
-            const wikiRelPath = node_path_1.default.join('baseline', 'wiki');
-            // Guard: baseline wiki must be based on real code. If the user provided
-            // --baseline but the copy step produced an empty directory (e.g. every
-            // file was filtered out), refuse to silently index cwd or an empty dir.
-            if (hasBaseline) {
-                const exists = await fs_extra_1.default.pathExists(repoRootFs);
-                const entries = exists ? await fs_extra_1.default.readdir(repoRootFs) : [];
-                if (!exists || entries.length === 0) {
-                    throw new Error(`Wiki 源码目录为空或不存在：${repoRootFs}。` +
-                        '请检查基线拷贝结果（黑名单/大小上限可能过滤掉了所有文件）。');
-                }
-            }
-            const cfg = await (0, wiki_1.resolveWikiRunConfig)({
-                cwd,
-                apiKey: opts.wikiApiKey,
-                baseUrl: opts.wikiBaseUrl,
-                model: opts.wikiModel,
-            });
-            const langFolder = opts.wikiLang === 'en' ? 'en' : 'zh';
-            const langRun = (0, wiki_1.langRunForRepowikiTarget)(langFolder);
-            logger_1.logger.info(`  源码根：${repoRootFs}`);
-            logger_1.logger.info(`  输出到：${node_path_1.default.join(wikiOutputRootFs, wikiRelPath)}`);
-            logger_1.logger.info(`  语言：${langFolder} · 模型：${cfg.model}`);
-            await (0, wiki_1.runRepowikiIndex)({
-                repoRootFs,
-                wikiOutputRootFs,
-                wikiRelPath,
-                baseUrl: cfg.baseUrl,
-                apiKey: cfg.apiKey,
-                model: cfg.model,
-                languages: [langRun],
-                comprehensiveSections: true,
-                onLog: (m) => logger_1.logger.info(m),
-                onProgress: (p) => {
-                    if (p.total > 0) {
-                        logger_1.logger.info(`  [${p.done}/${p.total}] ${p.detail}`);
-                    }
-                    else {
-                        logger_1.logger.info(`  ${p.detail}`);
-                    }
-                },
-            });
-            logger_1.logger.success('baseline wiki 已生成');
-            wikiFullOk = true;
-        }
-        catch (err) {
-            if ((0, wiki_1.isAbortError)(err)) {
-                logger_1.logger.warn('wiki 生成被中断（已写出部分页可从 checkpoint 恢复）');
+    if (wikiMode === 'full' || wikiMode === 'tasks') {
+        const stepLabel = wikiMode === 'full'
+            ? `步骤 ${stepWiki}/${totalSteps} - 生成 baseline wiki`
+            : `步骤 ${stepWiki}/${totalSteps} - 生成 baseline wiki 任务清单`;
+        logger_1.logger.section(stepLabel);
+        const wikiResult = await (0, run_wiki_generation_1.runWikiGeneration)({
+            repoRootFs: wikiSourceRoot,
+            wikiOutputRootFs: targetRoot,
+            wikiRelPath: node_path_1.default.join('baseline', 'wiki'),
+            wikiLang: opts.wikiLang,
+            wikiModel: opts.wikiModel,
+            wikiBaseUrl: opts.wikiBaseUrl,
+            wikiApiKey: opts.wikiApiKey,
+            projectName: validated.name,
+            cliVersion,
+            mode: wikiMode === 'full' ? 'full' : 'tasks',
+            cwd,
+            wikiAudience: 'agent',
+            sourceRootRel: node_path_1.default.relative(targetRoot, wikiSourceRoot).replace(/\\/g, '/') || '.',
+            onLog: (m) => logger_1.logger.info(m),
+        });
+        resolvedWikiPhase = wikiResult.wikiPhase;
+        resolvedWikiSource = wikiResult.wikiSource;
+        if (wikiResult.ok) {
+            if (wikiMode === 'full') {
+                logger_1.logger.success('baseline wiki 已生成');
             }
             else {
-                logger_1.logger.warn(`wiki 生成失败（不回滚 harness 骨架）：${err.message}`);
+                logger_1.logger.success(`baseline wiki 任务清单已生成：${node_path_1.default.relative(targetRoot, wikiResult.tasksPath)} （共 ${wikiResult.pageCount} 页任务）`);
             }
         }
-        // If the full run failed, downgrade S10_wiki from DONE to PENDING
-        // so the agent can pick it up via harness-build-skill-wiki-writer.
-        if (!wikiFullOk) {
-            resolvedWikiPhase = 'pending';
-            resolvedWikiSource = 'cli-full-degraded';
+        else if (wikiMode === 'full') {
+            // Full mode failure downgrades to PENDING so the agent can pick it up.
             logger_1.logger.warn('S10_wiki 将标记为 PENDING，等待 agent 接力补齐');
         }
     }
-    else if (wikiMode === 'tasks') {
-        logger_1.logger.section(`步骤 ${stepWiki}/${totalSteps} - 生成 baseline wiki 任务清单`);
-        try {
-            const repoRootFs = wikiSourceRoot;
-            const wikiOutputRootFs = targetRoot;
-            const wikiRelPath = node_path_1.default.join('baseline', 'wiki');
-            if (hasBaseline) {
-                const exists = await fs_extra_1.default.pathExists(repoRootFs);
-                const entries = exists ? await fs_extra_1.default.readdir(repoRootFs) : [];
-                if (!exists || entries.length === 0) {
-                    throw new Error(`Wiki 源码目录为空或不存在：${repoRootFs}。` +
-                        '请检查基线拷贝结果（黑名单/大小上限可能过滤掉了所有文件）。');
-                }
-            }
-            const cfg = await (0, wiki_1.resolveWikiRunConfig)({
-                cwd,
-                apiKey: opts.wikiApiKey,
-                baseUrl: opts.wikiBaseUrl,
-                model: opts.wikiModel,
-            });
-            const langFolder = opts.wikiLang === 'en' ? 'en' : 'zh';
-            const langRun = (0, wiki_1.langRunForRepowikiTarget)(langFolder);
-            logger_1.logger.info(`  源码根：${repoRootFs}`);
-            logger_1.logger.info(`  输出到：${node_path_1.default.join(wikiOutputRootFs, wikiRelPath)}`);
-            logger_1.logger.info(`  语言：${langFolder} · 模型：${cfg.model}`);
-            logger_1.logger.info('  模式：仅任务清单（tasks-only，默认）');
-            const outline = await (0, wiki_1.runRepowikiOutlineOnly)({
-                repoRootFs,
-                wikiOutputRootFs,
-                wikiRelPath,
-                baseUrl: cfg.baseUrl,
-                apiKey: cfg.apiKey,
-                model: cfg.model,
-                languages: [langRun],
-                comprehensiveSections: true,
-                onLog: (m) => logger_1.logger.info(m),
-                onProgress: (p) => {
-                    if (p.total > 0) {
-                        logger_1.logger.info(`  [${p.done}/${p.total}] ${p.detail}`);
-                    }
-                    else {
-                        logger_1.logger.info(`  ${p.detail}`);
-                    }
-                },
-            });
-            const tasksPath = await (0, wiki_1.writeWikiTasks)({
-                outline,
-                targetRoot,
-                wikiRelPath,
-                projectName: validated.name,
-                cliVersion,
-                model: cfg.model,
-                generatedAtIso: new Date().toISOString(),
-                sourceRootRel: node_path_1.default
-                    .relative(targetRoot, wikiSourceRoot)
-                    .replace(/\\/g, '/') || '.',
-            });
-            logger_1.logger.success(`baseline wiki 任务清单已生成：${node_path_1.default.relative(targetRoot, tasksPath)} （共 ${outline.pages.length} 页任务）`);
-        }
-        catch (err) {
-            if ((0, wiki_1.isAbortError)(err)) {
-                logger_1.logger.warn('wiki 任务清单生成被中断');
-            }
-            else {
-                logger_1.logger.warn(`wiki 任务清单生成失败（不回滚 harness 骨架）：${err.message}`);
-            }
-        }
-    }
     // 7. Write build state file (after wiki, so wiki result is accurately reflected).
     let declarationSummary;
     try {

package/dist/commands/shell-integration.js

@@ -3,6 +3,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveShellMenuIconSourcePath = resolveShellMenuIconSourcePath;
+exports.installShellMenuIcon = installShellMenuIcon;
 exports.resolveLaunchScriptPath = resolveLaunchScriptPath;
 exports.resolveWindowsTerminalPath = resolveWindowsTerminalPath;
 exports.runShellInstall = runShellInstall;
@@ -19,6 +21,10 @@ 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.ps1');
 const LEGACY_STUB_PATH = path_1.default.join(STUB_DIR, 'launch_codechat_cli.cmd');
+const ICON_FILENAME = 'codechat-agent.ico';
+const ICON_STUB_PATH = path_1.default.join(STUB_DIR, ICON_FILENAME);
+const STANDALONE_MENU_KEY_BG = 'HKCU\\Software\\Classes\\Directory\\Background\\shell\\CodeChatStandaloneAgent';
+const STANDALONE_MENU_KEY_DIR = 'HKCU\\Software\\Classes\\Directory\\shell\\CodeChatStandaloneAgent';
 function logInfo(msg, silent) {
     if (!silent)
         logger_1.logger.info(msg);
@@ -36,6 +42,28 @@ function assertWin32() {
             'Linux/macOS 请使用：launch_codechat_cli 或 svharness start-agent --work-dir <path>');
     }
 }
+/**
+ * Resolve bundled context-menu icon from the installed package.
+ */
+function resolveShellMenuIconSourcePath() {
+    const fromDist = path_1.default.resolve(__dirname, '..', '..', 'assets', ICON_FILENAME);
+    if (fs_extra_1.default.existsSync(fromDist)) {
+        return fromDist;
+    }
+    const fromCwd = path_1.default.resolve(__dirname, '..', '..', '..', 'assets', ICON_FILENAME);
+    if (fs_extra_1.default.existsSync(fromCwd)) {
+        return fromCwd;
+    }
+    throw new Error(`未找到 ${ICON_FILENAME}（预期：${fromDist}）`);
+}
+/**
+ * Copy icon to LOCALAPPDATA stub dir; return registry Icon value (`path,0`).
+ */
+async function installShellMenuIcon() {
+    const source = resolveShellMenuIconSourcePath();
+    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.
  */
@@ -121,8 +149,9 @@ function buildMenuCommand(ps1Path, dirPlaceholder, wtPath) {
     }
     return `powershell.exe ${psArgs}`;
 }
-function registerMenuKey(menuKey, command) {
+function registerMenuKey(menuKey, command, iconValue) {
     (0, win_registry_1.regSetDefault)(menuKey, win_registry_1.SHELL_MENU_LABEL);
+    (0, win_registry_1.regSetString)(menuKey, 'Icon', iconValue);
     (0, win_registry_1.regSetDefault)(`${menuKey}\\command`, command);
 }
 /**
@@ -130,20 +159,25 @@ function registerMenuKey(menuKey, command) {
  */
 async function runShellInstall(opts = {}) {
     assertWin32();
+    // 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();
     await fs_extra_1.default.ensureDir(STUB_DIR);
     await writeStubFile(launchScriptPath);
     if (await fs_extra_1.default.pathExists(LEGACY_STUB_PATH)) {
         await fs_extra_1.default.remove(LEGACY_STUB_PATH);
     }
+    const iconValue = await installShellMenuIcon();
     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);
+    registerMenuKey(win_registry_1.SHELL_MENU_KEY_BG, bgCommand, iconValue);
+    registerMenuKey(win_registry_1.SHELL_MENU_KEY_DIR, dirCommand, iconValue);
     const via = wtPath ? 'Windows Terminal' : 'PowerShell（UTF-8）';
     logSuccess(`Windows 右键菜单已注册：「在此启动 CodeChat Agent」（${via}）`, opts.silent);
     logInfo(`  stub: ${STUB_PATH}`, opts.silent);
+    logInfo(`  icon: ${ICON_STUB_PATH}`, opts.silent);
     logInfo(`  脚本: ${launchScriptPath}`, opts.silent);
     if (wtPath) {
         logInfo(`  wt:   ${wtPath}`, opts.silent);
@@ -159,6 +193,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(ICON_STUB_PATH)) {
+        await fs_extra_1.default.remove(ICON_STUB_PATH);
+    }
     if (await fs_extra_1.default.pathExists(LEGACY_STUB_PATH)) {
         await fs_extra_1.default.remove(LEGACY_STUB_PATH);
     }