svharness 0.14.16 → 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

@@ -23,6 +23,8 @@ 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);
@@ -157,6 +159,9 @@ function registerMenuKey(menuKey, command, iconValue) {
  */
 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);

package/dist/commands/wiki.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * `svharness wiki` — standalone wiki generation for any code project.
+ *
+ * Unlike the wiki embedded in `svharness build`, this command:
+ * - Scans source code in-place (no baseline copy).
+ * - Defaults output to `./wiki/` (relative to cwd).
+ * - Does NOT require a harness; optionally syncs S10_wiki via --update-state.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runWiki = runWiki;
+const fs_extra_1 = __importDefault(require("fs-extra"));
+const node_path_1 = __importDefault(require("node:path"));
+const picocolors_1 = __importDefault(require("picocolors"));
+const version_1 = require("../utils/version");
+const logger_1 = require("../utils/logger");
+const run_wiki_generation_1 = require("../lib/wiki/run-wiki-generation");
+const state_1 = require("../core/state");
+async function runWiki(opts) {
+    (0, logger_1.setVerbose)(!!opts.verbose);
+    const cwd = opts.cwd ?? process.cwd();
+    // 1. Mutual exclusion check
+    if (opts.generateWiki && opts.wikiTasksOnly) {
+        logger_1.logger.error('--generate-wiki 与 --wiki-tasks-only 不可同时启用');
+        return 1;
+    }
+    // 2. --update-state requires --harness
+    if (opts.updateState && !opts.harness) {
+        logger_1.logger.error('--update-state 须同时提供 --harness <path>');
+        return 1;
+    }
+    // 3. Resolve paths
+    const repoRootFs = node_path_1.default.resolve(cwd, opts.wikiSource ?? '.');
+    const outputRoot = node_path_1.default.resolve(cwd, opts.output ?? './wiki');
+    const wikiRelPath = node_path_1.default.relative(outputRoot, outputRoot); // always '.'
+    const projectName = opts.projectName ?? node_path_1.default.basename(repoRootFs);
+    const mode = opts.generateWiki ? 'full' : 'tasks';
+    // 4. Source guard
+    if (!(await fs_extra_1.default.pathExists(repoRootFs))) {
+        logger_1.logger.error(`源码目录不存在：${repoRootFs}`);
+        return 1;
+    }
+    // 5. Display config
+    logger_1.logger.info(`源码根：${repoRootFs}`);
+    logger_1.logger.info(`输出到：${outputRoot}`);
+    logger_1.logger.info(`模式：${mode === 'full' ? '完整生成（generate-wiki）' : '仅任务清单（tasks-only）'}`);
+    logger_1.logger.info(`语言：${opts.wikiLang ?? 'zh'}`);
+    // 6. Run wiki generation
+    const result = await (0, run_wiki_generation_1.runWikiGeneration)({
+        repoRootFs,
+        wikiOutputRootFs: outputRoot,
+        wikiRelPath: '.', // wiki output is directly in outputRoot
+        wikiLang: opts.wikiLang,
+        wikiModel: opts.wikiModel,
+        wikiBaseUrl: opts.wikiBaseUrl,
+        wikiApiKey: opts.wikiApiKey,
+        projectName,
+        cliVersion: (0, version_1.getCliVersion)(),
+        mode,
+        cwd,
+        forceFull: opts.forceFull,
+        wikiAudience: opts.harness ? 'agent' : 'human',
+        sourceRootRel: '.',
+        onLog: (m) => logger_1.logger.info(m),
+    });
+    // 7. Handle result
+    if (result.ok) {
+        if (mode === 'full') {
+            logger_1.logger.success(`wiki 已完整生成到：${outputRoot}`);
+        }
+        else {
+            logger_1.logger.success(`wiki 任务清单已生成：${result.tasksPath} （共 ${result.pageCount} 页任务）`);
+        }
+    }
+    else {
+        if (mode === 'full') {
+            logger_1.logger.error('wiki 完整生成失败（已产出部分文件可从 checkpoint 恢复）');
+        }
+        else {
+            logger_1.logger.error('wiki 任务清单生成失败');
+        }
+    }
+    // 8. Optional: sync S10_wiki to harness state
+    if (opts.updateState && opts.harness) {
+        const harnessRoot = node_path_1.default.resolve(cwd, opts.harness);
+        if (!(await fs_extra_1.default.pathExists(node_path_1.default.join(harnessRoot, 'harness.yaml')))) {
+            logger_1.logger.warn(`未找到 harness.yaml：${harnessRoot}，跳过 state 更新`);
+        }
+        else {
+            // Warn if output doesn't match harness/baseline/wiki
+            const expectedOutput = node_path_1.default.resolve(harnessRoot, 'baseline', 'wiki');
+            if (node_path_1.default.resolve(outputRoot) !== expectedOutput) {
+                logger_1.logger.warn(`--output (${outputRoot}) 不等于 <harness>/baseline/wiki。` +
+                    'state 中 S10_wiki 的 tasks_file 路径可能不匹配实际产出位置。');
+            }
+            await (0, state_1.patchS10WikiPhase)(harnessRoot, {
+                wikiPhase: result.wikiPhase,
+                wikiSource: result.wikiSource,
+            });
+        }
+    }
+    // 9. Next-steps hint
+    if (result.ok) {
+        logger_1.logger.plain('');
+        if (opts.updateState && opts.harness) {
+            logger_1.logger.plain(picocolors_1.default.bold('下一步（harness 联动）：'));
+            logger_1.logger.plain('  - 可执行 svharness doctor --harness <path> 校验 wiki 状态');
+            if (mode === 'tasks') {
+                logger_1.logger.plain('  - 可用 harness-build-skill-wiki-writer 按 TASKS.md 逐页补写');
+            }
+        }
+        else {
+            logger_1.logger.plain(picocolors_1.default.bold('下一步：'));
+            if (mode === 'tasks') {
+                logger_1.logger.plain(`  - 编辑 ${node_path_1.default.join(outputRoot, 'TASKS.md')} 中的 wiki 页面任务`);
+                logger_1.logger.plain('  - 或使用 --generate-wiki 直接完整生成');
+            }
+            else {
+                logger_1.logger.plain(`  - wiki 文件位于 ${outputRoot}`);
+            }
+        }
+    }
+    return result.ok ? 0 : 1;
+}

package/dist/config/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.saveConfigSection = exports.mergeDoctorOptions = exports.mergeConvertOptions = exports.mergeApplyOptions = exports.mergeBuildOptions = exports.resolveConfigHarnessName = exports.normalizeConfig = exports.resolveConfigPath = exports.loadConfig = exports.CONFIG_SCHEMA_VERSION = exports.DEFAULT_CONFIG_FILENAME = void 0;
+exports.saveConfigSection = exports.mergeWikiOptions = exports.mergeDoctorOptions = exports.mergeConvertOptions = exports.mergeApplyOptions = exports.mergeBuildOptions = exports.resolveConfigHarnessName = exports.normalizeConfig = exports.resolveConfigPath = exports.loadConfig = exports.CONFIG_SCHEMA_VERSION = exports.DEFAULT_CONFIG_FILENAME = void 0;
 var constants_1 = require("./constants");
 Object.defineProperty(exports, "DEFAULT_CONFIG_FILENAME", { enumerable: true, get: function () { return constants_1.DEFAULT_CONFIG_FILENAME; } });
 Object.defineProperty(exports, "CONFIG_SCHEMA_VERSION", { enumerable: true, get: function () { return constants_1.CONFIG_SCHEMA_VERSION; } });
@@ -15,5 +15,6 @@ Object.defineProperty(exports, "mergeBuildOptions", { enumerable: true, get: fun
 Object.defineProperty(exports, "mergeApplyOptions", { enumerable: true, get: function () { return merge_options_1.mergeApplyOptions; } });
 Object.defineProperty(exports, "mergeConvertOptions", { enumerable: true, get: function () { return merge_options_1.mergeConvertOptions; } });
 Object.defineProperty(exports, "mergeDoctorOptions", { enumerable: true, get: function () { return merge_options_1.mergeDoctorOptions; } });
+Object.defineProperty(exports, "mergeWikiOptions", { enumerable: true, get: function () { return merge_options_1.mergeWikiOptions; } });
 var save_config_1 = require("./save-config");
 Object.defineProperty(exports, "saveConfigSection", { enumerable: true, get: function () { return save_config_1.saveConfigSection; } });