svharness 0.14.17 → 0.15.1

package/README.md

@@ -35,6 +35,9 @@ svharness wizard
 # 配置文件驱动（团队模板 / CI）
 svharness build --config svharness.config.yaml --yes
 
+# 全自动模式 —— 资料整理 → 构建 → 审查 → 优化，支持断点续跑
+svharness auto --work-dir . --auto-approve -y
+
 # 一行式 —— 跳过交互，直接生成
 svharness build --harness-name my-app --arch android-compose --agent qoder --yes
 
@@ -60,6 +63,8 @@ svharness start-agent --work-dir .
 
 **`svharness wizard`**：分步 TUI，支持同时填写**文件路径**与**说明文字**（如 `requirementsNote`），结束时可选「立即执行 / 仅保存配置 / 保存并执行」。
 
+**`svharness auto`**：无人值守构建入口。工作目录可以是已有 `<name>-harness/`（从 `.harness-build-state.yaml` 断点续跑），也可以是资料包根（自动检测 `baseline/`、`requirements/`、`references/`、`extra-skills/` 后先执行 build）。配置示例见 `auto/templates/auto.config.example.yaml`。
+
 生成完成后，在你的 Agent IDE 中说：
 - "运行 harness-build-skills-main"或"harness-build-skill-orchestrator"即可开始逐步填充内容；
 - 构建完成后在目标项目中说"应用 harness-apply-skills-main 完成 xxx 功能开发"即可调用 harness。
@@ -235,6 +240,7 @@ svharness wizard
 | 字段 | 说明 |
 |------|------|
 | `requirementsNote` | 需求文档业务说明 |
+| `goal` | harness 构建目的（写入 harness 目录） |
 | `referencesNote` | 参考资料说明 |
 | `extraSkillsNote` | 额外 skills/rules 说明 |
 
@@ -270,7 +276,8 @@ svharness build \
 | `--save-config [path]` | 可选 | build 成功后把参数写入配置文件 | — |
 | `--harness-name <name>` | ✅ 必填* | harness 名称；可在 `build.harnessName` 中提供 | — |
 | `--name <name>` | ⚠️ 已废弃别名 | 等同 `--harness-name`，下个 minor 版本移除 | — |
-| `--arch <arch>` | 可选 | 架构模板：`android-compose` / `android-xml` / `cpp` / `web-react` / `python` | `android-compose` |
+| `--arch <arch>` | 可选 | 架构模板：`android-compose` / `android-xml` / `cpp` / `web-react` / `python` / `documents` | `android-compose` |
+| `--goal <text>` | 可选 | harness 构建目的（1–2 句话，写入 `harness.yaml` 与 state；最多 500 字符） | — |
 | `--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） | — |
@@ -733,11 +740,13 @@ svharness start-agent --work-dir ~/projects/my-app
 
 #### 平台说明
 
-| 平台 | spawn 模式 | 右键菜单 |
-|------|------------|----------|
+| 平台 | spawn 模式 | 右键菜单 / PowerShell 别名 |
+|------|------------|----------------------------|
 | Windows | `shell: true` | 支持（`svharness shell`） |
 | Linux / macOS | `shell: false` | 不支持 |
 
+Windows 下首次 `start-agent` 会**尽力**写入 PowerShell `codechat` 函数（与 `shell install` 相同逻辑）；若未全局安装 svharness，可手动执行 `svharness shell install`。
+
 ### 无需 svharness：独立 PowerShell 启动器
 
 未安装 npm / svharness 时，可拷贝 [`templates/codechat/Start-CodeChat.ps1`](templates/codechat/Start-CodeChat.ps1) 到项目 `.claude\`，实现相同的 env 同步与 `run.bat` 解析（含 Android Studio / IDEA 插件路径）：
@@ -745,7 +754,12 @@ svharness start-agent --work-dir ~/projects/my-app
 ```powershell
 Copy-Item .\templates\codechat\Start-CodeChat.ps1 .\.claude\
 .\.claude\Start-CodeChat.ps1                              # 启动
-.\.claude\Start-CodeChat.ps1 -Action InstallMenu          # 可选：独立右键菜单
+.\.claude\Start-CodeChat.ps1 -Action Install              # 可选：独立右键 + 别名
+.\.claude\Start-CodeChat.ps1 -Action InstallMenu          # 仅右键
+.\.claude\Start-CodeChat.ps1 -Action InstallAlias         # 仅别名
+.\.claude\Start-CodeChat.ps1 -Action UninstallMenu        # 反注册独立右键
+.\.claude\Start-CodeChat.ps1 -Action UninstallAlias       # 反注册独立别名
+.\.claude\Start-CodeChat.ps1 -Action Status
 ```
 
 右键菜单使用注册表键 `CodeChatStandaloneAgent`，**不与** `svharness shell install` 冲突；可与 svharness 菜单并存。
@@ -762,24 +776,74 @@ launch_codechat_cli D:\projects\my-app    # Windows
 launch_codechat_cli ~/projects/my-app     # Linux
 ```
 
-### `shell` —— Windows 右键菜单（v0.16+，仅 win32）
+### `shell` —— Windows 右键菜单与 PowerShell 别名（v0.16+，仅 win32）
+
+在资源管理器**文件夹空白处**与**文件夹图标**右键增加「在此启动 CodeChat Agent」，并在 PowerShell `$PROFILE` 写入 `codechat` 函数（等价于 `launch_codechat_cli [workdir]`）。**注册与反注册**对右键菜单、本地 stub、PowerShell 别名**一并**处理。
 
-在资源管理器**文件夹空白处**与**文件夹图标**右键增加「在此启动 CodeChat Agent」，点击后打开 **PowerShell** 窗口并启动 Agent。
+#### 注册
 
 ```bash
-svharness shell install      # 注册（幂等）
-svharness shell uninstall    # 移除
-svharness shell status       # 查看 stub / 注册表状态
-svharness shell uninstall
-npm uninstall -g svharness
+svharness shell install      # 注册右键 + 安装 codechat 别名（幂等）
+svharness shell status       # 查看是否已完整安装
 ```
 
-`npm install -g svharness` 在 Windows 上 **默认自动** `shell install`。跳过：
+注册时会写入：
+
+| 项 | 路径 / 键 |
+|----|-----------|
+| 空白处右键 | `HKCU\Software\Classes\Directory\Background\shell\SvharnessLaunchCodeChatAgent` |
+| 文件夹右键 | `HKCU\Software\Classes\Directory\shell\SvharnessLaunchCodeChatAgent` |
+| 启动 stub | `%LOCALAPPDATA%\svharness\bin\launch_codechat_cli.ps1` |
+| 菜单图标 | `%LOCALAPPDATA%\svharness\bin\codechat-agent.ico` |
+| PowerShell 别名 | 当前用户 `$PROFILE` 内 `# >>> codechat >>>` … `# <<< codechat <<<` 块 |
+
+`npm install -g svharness` 在 Windows 上 **默认自动** 执行上述注册。跳过：
 
 ```bash
 SVHARNESS_SKIP_SHELL=1 npm install -g svharness
 ```
 
+**PowerShell 别名用法**（注册后需**新开** PowerShell 窗口才生效）：
+
+```powershell
+codechat                       # 当前目录启动
+codechat D:\projects\my-app    # 指定项目根
+```
+
+#### 反注册
+
+```bash
+svharness shell uninstall    # 移除右键、stub、图标与 profile 中的 codechat 块
+svharness shell status       # 确认「右键菜单完整 / codechat 别名」均为否
+```
+
+反注册时会删除：
+
+| 项 | 说明 |
+|----|------|
+| 上述两个 HKCU 注册表键 | 资源管理器右键菜单项消失（无需重启 Explorer） |
+| `%LOCALAPPDATA%\svharness\bin\` | 删除 stub `.ps1` 与 `.ico` |
+| `$PROFILE` 中的 codechat 块 | 移除 `# >>> codechat >>>` … `# <<< codechat <<<` 整段；**不**删除 profile 文件本身 |
+
+全局卸载 npm 包时，`preuninstall` 会**尽力**自动反注册（与 `shell uninstall` 相同范围）：
+
+```bash
+npm uninstall -g svharness
+```
+
+若自动反注册失败，可手动执行 `svharness shell uninstall`（包仍在时），或自行检查：
+
+- 注册表：`reg query HKCU\Software\Classes\Directory\Background\shell\SvharnessLaunchCodeChatAgent` 应报错「找不到」
+- 目录：`%LOCALAPPDATA%\svharness\bin\` 应不存在或为空
+- profile：打开 `$PROFILE`，确认无 `# >>> codechat >>>` 标记块
+
+**注意**：`shell uninstall` **仅**移除 svharness 注册的菜单（键名 `SvharnessLaunchCodeChatAgent`）。若曾用独立脚本 [`Start-CodeChat.ps1`](templates/codechat/Start-CodeChat.ps1) 注册过菜单（键名 `CodeChatStandaloneAgent`），需单独反注册：
+
+```powershell
+.\.claude\Start-CodeChat.ps1 -Action UninstallMenu    # 独立右键
+.\.claude\Start-CodeChat.ps1 -Action UninstallAlias   # 独立别名（若曾 Install / InstallAlias）
+```
+
 ---
 
 ## 架构模板
@@ -793,6 +857,13 @@ SVHARNESS_SKIP_SHELL=1 npm install -g svharness
 | `cpp` | C++17 + CMake | 5 条 `seed-*.md` | 现代 C++ + CMake 规范 |
 | `web-react` | TypeScript + React | 5 条 `seed-*.md` | Hooks + 状态管理规范 |
 | `python` | Python | — | 通用 Python 模板 |
+| `documents` | — | — | 文档型 harness（无代码基线；spec 域为 behavior + interfaces） |
+
+```bash
+# 文档型 harness + 构建目的
+svharness build --harness-name doc-demo --arch documents --agent codechat \
+  --goal "车载 CAN 信号协议文档标准化 harness" --yes --force
+```
 
 > **两层叠拷合并**：`_shared/` 先落盘，`<arch>/` 随后覆盖同名文件。
 > 新增架构只需在 `templates/<new-arch>/skeleton/agent-env/rules/` 下放 3-5 条规则文件，
@@ -1083,7 +1154,7 @@ svharness build --harness-name demo-unknown --arch python --agent codechat `
 - [x] 参数 `--name` → `--harness-name`（保留 `--name` 别名一版本）
 - [x] `--arch` 默认 `android-compose`、`--agent` 默认 `codechat`
 - [x] `build` —— 骨架 + 元文件 + 状态文件 + skill 注入
-- [x] 多架构模板（`android-compose` / `android-xml` / `cpp` / `web-react` / `python`）
+- [x] 多架构模板（`android-compose` / `android-xml` / `cpp` / `web-react` / `python` / `documents`）
 - [x] `_shared/` + `<arch>/` 两层叠拷合并
 - [x] 每个架构自带 3-5 条规则文件（`.mdc` 格式，`alwaysApply: true` 默认启用）
 - [x] `apply` —— 把已构建好的 harness 绑定到目标项目（默认复制模式，`--clone` 兼容保留）