harnessmith 0.1.0__tar.gz

harnessmith-0.1.0/.claude/settings.local.json

@@ -0,0 +1,16 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(fuser -k 8001/tcp)",
+      "Bash(fuser -k 8841/tcp)",
+      "Bash(curl -s --max-time 2 http://127.0.0.1:8001/ -o /dev/null -w \"product :8001 -> %{http_code}\\\\n\")",
+      "Bash(curl -s --max-time 2 http://127.0.0.1:8841/ -o /dev/null -w \"wizard :8841 -> %{http_code}\\\\n\")",
+      "Bash(rm -rf /home/s1yu/HarnessForge/generate/obs_demo)",
+      "Read(//home/s1yu/longhaul-eval/product/**)",
+      "Bash(rm -rf .harness/sessions/* traces/* logs/* .harness/usage.json)",
+      "Bash(rm -rf /home/s1yu/longhaul-eval/workspace)",
+      "Bash(mkdir -p /home/s1yu/longhaul-eval/workspace)",
+      "Bash(chmod +x /home/s1yu/longhaul-eval/run_scenario_a.sh)"
+    ]
+  }
+}

harnessmith-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,22 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    # Must match the environment registered with the PyPI trusted publisher.
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Check tag matches project version
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          version=$(sed -n 's/^version = "\(.*\)"/\1/p' pyproject.toml)
+          [ "$tag" = "$version" ] || { echo "tag $tag != pyproject version $version"; exit 1; }
+      - run: pipx run build
+      - uses: pypa/gh-action-pypi-publish@release/v1

harnessmith-0.1.0/.gitignore

@@ -0,0 +1,22 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+
+# uv / virtualenv
+.venv/
+
+# Build artifacts (sdist/wheel) — produced by `uv build`, never tracked.
+dist/
+build/
+.ruff_cache/
+
+# Transient runtime/debug logs (serve, wizard, debuglog) — local-only, never shipped.
+*.log
+
+# Real API keys (human-managed, see CLAUDE.md §0.1) — never tracked.
+.env
+
+# Products generated by the wizard's one-click "generate" (default target dir).
+generate/

harnessmith-0.1.0/AGENTS.md

@@ -0,0 +1,100 @@
+# AGENTS.md — HarnessSmith 快速上手
+
+> 面向**在本仓库里干活的 Agent** 的导航地图：30 秒认清这是什么、代码在哪、怎么跑、怎么算"做完"。
+> 这里只讲"怎么上手"；**硬约束与红线看 [`CLAUDE.md`](./CLAUDE.md)，定位 / 范围 / 决策总表看 [`docs/02-development/00-overview.md`](./docs/02-development/00-overview.md)**。两者冲突时以那两份为准。
+
+## 1. 这是什么（一句话）
+
+HarnessSmith 是 **agent harness 的代码生成器**（`create-next-app` for agent harnesses）：吃一份 `HarnessSpec`（YAML / preset / 向导采集），渲染出一个**完整、独立、无 agent 框架锁定**的 Python 仓库。生成的产物与本生成器**零运行期关系**——生成即脱离。
+
+## 2. 两层心智（最重要，先记住）
+
+任何改动，先问自己**改的是哪一层**：
+
+| 层 | 位置 | 你在改什么 |
+|---|---|---|
+| **生成器本体** | `harnessmith/*.py`（`spec` / `generator` / `cli` / `scaffold` / `wizard` …） | spec schema、渲染引擎、CLI、向导、catalog、preset |
+| **产物模板** | `harnessmith/templates/**/*.j2` | **渲染后**才是用户拿到的代码。改这里 = 改所有未来产物 |
+
+推论：**测试必须覆盖"生成产物"本身**，不能只测生成器。黄金路径 = 生成 → `uv sync` → `pytest` → mock LLM 跑通一次 function-calling（见 §5）。
+
+## 3. 仓库地图
+
+```
+harnessmith/                  # ← 生成器本体（这个包发布到 PyPI）
+  spec.py                     # HarnessSpec（Pydantic v2 + YAML，extra=forbid）
+  generator.py                # 渲染模板 → 写仓库 + git init + uv lock + 冒烟自检
+  cli.py                      # Typer 入口：new / wizard / doctor
+  scaffold.py                 # 生成器与 CLI 向导共享的烤默认 / slug 派生（纯 stdlib）
+  cli_wizard.py               # 终端交互向导（questionary）
+  node_bootstrap.py           # Node 系 MCP server 的离线预热 / node 直跑
+  debuglog.py                 # 生成器侧 debug 日志
+  catalog/mcp_servers.yaml    # 精选静态 MCP catalog（向导/CLI 预填数据源）
+  presets/coding-assistant/   # 内置 preset（spec.yaml + mcp_prefill.yaml）
+  wizard/                     # Web 向导（FastAPI 单页，[wizard] extra，绝不进产物）
+  templates/                  # ← 产物模板（.j2）。渲染出的才是用户的代码
+    src/__project_slug__/harness/    # 产物核心：loop/llm/llm_anthropic/tools/context/
+                                     #   session/interaction/hooks/usage/trace/prompts/
+                                     #   paradigms/ + mcp/skills/memory（opt-in）
+    src/__project_slug__/interfaces/ # cli.py（+ web.py / web_index.html opt-in）
+    tests/                           # 产物自带测试（mock LLM）
+docs/02-development/          # 设计与切片文档（00-overview = 唯一口径）
+tests/                        # ← 生成器自身的测试（test_spec / test_generator / test_golden …）
+```
+
+## 4. 常用命令（已验证）
+
+```bash
+uv sync                                              # 装生成器依赖
+uv sync --extra wizard                               # 额外装 Web 向导依赖（FastAPI/uvicorn）
+
+# 生成产物
+uv run harnessmith new my-agent --preset coding-assistant   # 从 preset 非交互生成
+uv run harnessmith new my-agent --spec ./harness.spec.yaml  # 从手写 spec 生成
+uv run harnessmith new my-agent --no-verify                 # 跳过生成后冒烟（离线/快迭代）
+uv run harnessmith wizard                                   # Web 向导
+uv run harnessmith doctor                                   # 本机工具链预检
+
+# 测试（golden 默认被 addopts 的 -m 'not golden' 排除）
+uv run pytest -q                  # 快测（生成器单元 + 产物渲染，~200 例，约 20s）
+uv run pytest -m golden           # 黄金快照：真生成 + uv sync + 产物 pytest（慢）
+uv run pytest -m docker           # 需要 Docker daemon
+
+# 发布前
+uv build                          # 产 sdist + wheel 到 dist/
+uvx twine check dist/*            # 校验元数据 + README 渲染
+```
+
+> 默认开发用 **mock LLM**，不需要真 key（CLI `--mock`）。真 key / 联网 / 花钱属"只能人做"，见 `CLAUDE.md §0.1 / §6`。
+
+## 5. "完成"的硬门槛（详见 `CLAUDE.md §5`）
+
+宣称做完前，至少：
+
+- [ ] 新增 / 改动的生成器或模板代码**有自动化测试**。
+- [ ] **黄金路径绿**：preset/示例 spec 生成 → `uv sync && pytest` 全绿 → mock 跑通一次 function-calling（含一次工具调用）。
+- [ ] 断言生成的 `pyproject.toml` **不含 `langchain`/`langgraph`/`adk`**。
+- [ ] 生成后冒烟自检绿；`ReadLints` 无新增告警。
+- [ ] 动了 `HarnessSpec` / 模板核心 / 跨 ≥3 文件 → 额外跑 §5.2 回归（全量黄金 + Docker 冒烟 + `uvx harnessmith new` 冒烟）。
+
+## 6. 红线速记（命中即停，详见 `CLAUDE.md §6`）
+
+- **绝不**在产物里引入任何 agent 编排框架（LangChain/LangGraph/ADK）——定位红线。
+- **薄优先**：默认产物核心循环 150–300 行；重能力（MCP/Web/skills/memory）只走 **spec 开关**，关闭 = 代码与依赖中均不存在。
+- 改 `HarnessSpec` 字段语义、给**默认产物**加运行期依赖、改 LLM API 面、任何让**密钥进 git/spec/trace/日志**的路径 → 先停下请人审。
+- **密钥**只进 gitignored `.env`；`config.yaml` / spec 只存 env 引用名。
+
+## 7. HarnessSpec 速览（结构旋钮，决定生成什么）
+
+`harnessmith/spec.py` 的 `HarnessSpec`（顶层字段）：
+
+`version` · `project_slug`（产物包名，默认 `agent_harness`）· `display_name`（产物 UI/README 显示名）· `language`（产物 Web 默认语言 `en`/`zh`）· `llms`（每 profile 选 `provider: openai|anthropic`）· `roles` · `prompts`（`system` + `rules_files`）· `tools` · `paradigms`（`agent`/`plan`/`ask` 多选，默认 `["agent"]`）· `interfaces`（`cli`/`web`/`tui`）· `mcp.enabled` · `skills.enabled` · `memory.enabled` · `observability` · `context`（种子）· `rag`/`secrets`（预留）。
+
+口径：**spec = 配方（生成什么 + 初值，结构轴）；产物 `config.yaml` = 运行期权威（行为轴）**。结构变更要重新生成，行为变更不用。
+
+## 8. 入场阅读顺序
+
+1. `README.md` —— 速览定位与产物能力。
+2. `CLAUDE.md` —— 协作硬约束与红线（**必读**）。
+3. `docs/02-development/00-overview.md` —— 定位 / 范围 / 决策总表 / 切片地图（**唯一口径**）。
+4. 按当前任务**只读**相关 slice 子文档（`docs/02-development/` 下），别把全部塞进上下文。

harnessmith-0.1.0/CLAUDE.md

@@ -0,0 +1,127 @@
+# CLAUDE.md — HarnessSmith 项目守则
+
+> Agent 进入本项目（**vibe coding 模式**）入场必读。本文件是 Agent 工作的**硬约束**。
+> 项目定位 / 范围 / 决策 / 开发节奏与切片门禁见 `docs/02-development/00-overview.md`。
+>
+> **Tradeoff**：偏向"先把事情做对"。显然小到不值得讨论的操作自己判断,别让流程把简单任务搞复杂。
+
+## 0. 协作模式与角色边界
+
+本项目**主要由 Agent 开发**,人只负责决策、验证、以及"只能人做"的环境配置。
+
+| 角色 | 负责 | 不做 |
+|------|------|------|
+| **Agent(你)** | 写生成器与模板代码、写/跑测试、调试、维护文档与变更记录、按 slice 自驱推进、**测试全绿后直接 commit + push `main`**、写完成报告 | 不替人拍板产品决策、不动用钱/联网批量/破坏定位的事、不 `--force` push、不在测试未绿时推 `main` |
+| **人** | 方向与验收、slice 关键决策点签字、**环境与密钥配置(见 §0.1)**、对外发布 | 不写代码、不做 Agent 已能自动化的事 |
+
+**一句话**:Agent 负责"怎么做",人负责"做不做、装环境、给 key、何时发布"。
+开发文档里写"开发者要做 X"一律理解为"**你(Agent)要做 X**,由人按切片节奏验收"。
+
+### 0.1 只能由人配置的环境(Agent 不代劳)
+
+- 安装本机工具链:`uv`、`docker`(Agent 不改系统级配置、不装系统包)。
+- **API key / `.env` 真实值**:Agent 只维护 `.env.example`,**绝不写入真实 `.env`、绝不把 key 写进任何被 git 跟踪的文件**。日常开发用 **mock LLM**,不需要真 key;只有"真实 LLM 冒烟 / 对外演示"才需要人提供 key。
+- PyPI 发布凭证、GitHub 仓库设置、对外发布。
+
+> Agent 需要某个 key / 环境时:在 plan 阶段列出所需 `.env` key 名与用途,**停下来请人配置**,不要自己编造或跳过。
+
+## 1. Think Before Coding
+
+**不要假设。不要藏起困惑。把权衡显式说出来。** 动手前:声明假设,不确定就问;多种合理解读时列出来让人选;有更简单的方案先说一声。宁可开工前多问 1 个问题,不要跑了 30 分钟才发现方向错了。
+
+## 2. Thin First(薄优先 —— 本项目核心卖点,硬约束)
+
+- 默认产物模板保持**极薄**:核心循环目标 150–300 行,整体远小于一个框架。
+- 不做没要求的功能;一次性代码不先抽象;不为"以后可能要"加灵活性。
+- 高级能力(RAG / MCP / context 策略 / Web)只通过 **spec 开关**生成,不塞进默认产物。
+- 200 行能压到 50 行就重写。
+
+## 3. Surgical Changes
+
+只动该动的,只清理自己制造的烂摊子。不"顺手优化"无关代码或格式;不重构没坏的东西;沿用现有风格;发现 dead code **提一句**,别擅自删。
+
+## 4. 两层心智:生成器 vs 生成产物(本项目特有)
+
+你写的是一个**生成器**,它渲染出**独立的生成产物仓库**。任何时候分清你在改哪一层:
+
+- 改 `harnessmith/`(生成器本体):spec / 渲染引擎 / CLI / 向导 / catalog / presets。
+- 改 `harnessmith/templates/`(产物模板):渲染后才是用户拿到的代码。
+- **测试必须覆盖"生成产物"本身**:生成 → `uv sync` → `pytest` → mock LLM 跑通一次工具调用,而不只是测生成器。
+
+## 5. 目标驱动 + 测试硬门槛(按生成器项目定制)
+
+"完成"的硬门槛见 §5.1,没达到 = 没完成,别用"逻辑简单不用测"或"先合后补"做借口。
+例外:纯文档 / 纯注释 / 纯重命名(改名工具已覆盖全部引用)可不加测试,但要在完成报告里点名说明。
+
+### 5.1 黄金测试是"完成"的硬门槛
+
+任何被宣称完成的功能必须:
+
+- 新增 / 改动的生成器或模板代码**有自动化测试**(unit 或 integration)。
+- **黄金路径绿**:用示例 / preset spec 生成项目 → `uv sync && pytest` 全绿 → mock LLM 跑通一次 function-calling(含一次工具调用)。
+- 断言生成的 `pyproject.toml` **不含 `langchain`/`langgraph`/`adk`**。
+- **可运行性自检绿**:生成后冒烟(`uv sync` + import + mock 跑一步 + `pytest -q`)。
+- `ReadLints`(IDE 诊断)无新增 error / warning。
+
+### 5.2 "大改动"额外跑回归
+
+判定:动了 `HarnessSpec`、模板核心,或跨 ≥ 3 个文件。额外跑:
+
+- 全量黄金快照(示例 spec + 每个 preset 各生成并 `pytest`)。
+- **Docker 冒烟**:生成产物 `docker build` 成功 + `docker run` 跑通 mock 一步。
+- `uvx harnessmith new` 冒烟。
+
+任一项失败 → 该功能**未完成**,先修,不要急着开下一项。
+
+### 5.3 可自主决定(不必请示)
+
+命名;实现细节 / 内部数据结构 / stdlib 选择;已在文档区间内的参数(默认 context 策略、预算默认值等);fixture / mock 风格 / 测试组织;在 `pyproject.toml` 已列家族内加可选依赖(如 `pytest-*`)。执行后在完成报告里一句话提一下。
+
+## 6. 停下来问人 / 上报的触发条件(命中任一即停)
+
+1. 改 `HarnessSpec` schema 字段或其语义(影响生成器与所有模板)。
+2. 给**默认产物模板**新增运行期依赖,或把 L2/L3 依赖混进默认核心依赖(违反"薄")。
+3. 在生成产物里引入任何 **agent 编排框架**(LangChain/LangGraph/ADK…)——**定位红线,绝不允许**。
+4. 改 LLM API 面(Chat Completions ↔ Responses)或底座 SDK 选型。
+5. 任何可能让**密钥进入 git / spec 快照 / trace / 日志**的路径。
+6. 跨 slice 的范围调整:把 L3 提前进 MVP,或把 L1 推迟。
+7. 需要真实 key / 联网 / 花钱:真实 LLM 跑批、发布到 PyPI、对外网开放端口。
+8. 生成产物核心代码体积明显超"薄"目标(核心循环远超 300 行)。
+9. 同一问题连续两次尝试都失败——别进"再试一遍"循环,停下说清卡点。
+10. 多种合理实现且权衡不清,影响 ≥ 2 个模块 / 后续 slice。
+
+上报格式:**[需要人介入]** + 触发第几条 / 在做什么 / 卡在哪 / 已试过什么(尝试 1·2 及结果)/ 可选项 A·B 及代价 / 我的倾向。等回复再继续。
+
+## 7. Agent 标准工作循环:plan → implement → self-verify → handoff
+
+- **plan**:读相关 slice 文档顶部"交付物";复述理解 + 实现计划(≤ 10 行);列会改的文件、新增测试、所需 `.env` key 名;命中 §6 就在 plan 阶段先停。
+- **implement**:先用 Read/Grep/SemanticSearch 看现有代码沿用风格;小步走能 commit 就 commit;不碰无关代码。
+- **self-verify**:跑 §5.1(大改动加 §5.2);自查 §1–§4 没违反;fail 先修不要假装看不见。
+- **handoff**:**先按 §9 把受影响文档更新到与实现一致**(门禁勾选、字段 / 行为描述、决策点结论);再按 `docs/02-development/00-overview.md §完成报告模板` 输出报告;**改动构成一个完整功能且 §5.1 门禁全绿后,直接执行 commit(默认行为,无需先问"要不要提交")**,按 Conventional Commits。
+
+## 8. 提交与分支
+
+- **Conventional Commits**:`feat: / fix: / refactor: / docs: / chore: / test: / perf: / build: / ci:`。
+- 一个 commit 一件事,不捎带无关改动。
+- **完整功能 + 测试完毕 = 直接 commit(默认行为,不必先问人)**:当本次改动构成一个完整功能(`feat` / `fix` 等)且 §5.1 门禁全绿后,**直接执行 commit**,不要停下来征求"要不要提交"。多个独立功能各自单独 commit(承接"一个 commit 一件事")。纯文档 / 注释 / 重命名等小改动同理可直接提交。
+- `main` **不再受保护**:门禁全绿后,Agent **可直接 commit 并 push `main`**,无需 feature branch / PR。仍 **不 `--force` push、不跳 pre-commit hook**(除非人明确允许);测试未绿不得推 `main`。需要走 PR 时人会显式要求。
+
+## 9. 文档维护
+
+- **任务完成即更新文档(硬规则)**:每个任务 / slice 一旦实现完成,必须把受影响的文档更新到**与实现一致**——slice 子文档勾选退出门禁、修正字段枚举 / 行为描述、回填人审决策点结论,并同步 `docs/02-development/00-overview.md` 的相关条目。**文档落后于实现 = 任务未完成**。
+- 改 `HarnessSpec` 字段:同步 `docs/02-development/00-overview.md §5` + 相关 slice 文档。
+- 改全局决策(罕见,走 §6 人审):必须改 `docs/02-development/00-overview.md` 的决策总表。
+- 改 `.env.example` / 默认依赖:同步产物 README / AGENTS.md 与相关 slice 文档。
+- 文档与代码相互引用的地方,**改一处必检另一处**。Agent 是这套文档体系的唯一维护者。
+
+## 10. 语言与文风
+
+- 人机对话默认中文;代码注释 / commit / 文档正文沿用各文件原有语言,勿强行翻译。
+- 不写"// 自增计数器"这类废话注释;不在文档里写"我 / 我们"或 LLM 客套话。
+
+## 11. 入场顺序(Agent 第一次进入本项目时)
+
+1. 读 `README.md` 速览定位。
+2. 读本文件(`CLAUDE.md`)—— 你正在读。
+3. 读 `docs/02-development/00-overview.md`(定位 / 范围 / 决策 / 切片门禁)。
+4. 按当前任务**只读**相关 slice 子文档;不要把全部文档塞进上下文。

harnessmith-0.1.0/HarnessSmith.bat

@@ -0,0 +1,177 @@
+@echo off
+REM One-click launcher for the HarnessSmith setup wizard.
+REM Lets you pick how to configure your harness: the Web form (opens in a browser)
+REM or an interactive CLI wizard (right here in the terminal). Prefers uv (auto-syncs
+REM the [wizard] extra for the web form); offers to install uv if it's missing.
+echo [HarnessSmith] Setup launcher
+cd /d "%~dp0"
+echo [HarnessSmith] Folder: %CD%
+echo.
+
+REM --- Reuse the system proxy (corporate networks) so the curl probe below, the
+REM official uv install, and uv's own sync all reach the net the same way. Only when
+REM none is already set; curl/uv don't read the Windows WinINET proxy on their own,
+REM whereas the wizard's urllib probe DOES - so without this the curl probe could
+REM wrongly report PyPI unreachable and pin a mirror the proxy can't even reach.
+if defined HTTP_PROXY goto :proxy_done
+if defined HTTPS_PROXY goto :proxy_done
+for /f "usebackq delims=" %%p in (`powershell -NoProfile -ExecutionPolicy Bypass -Command "$s=Get-ItemProperty 'HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings' -ErrorAction SilentlyContinue; if ($s.ProxyEnable -eq 1 -and $s.ProxyServer) { $p=[string]$s.ProxyServer; if ($p -match 'https?=([^;]+)') { $p=$matches[1] }; if ($p -notmatch '://') { $p='http://'+$p }; $p }"`) do set "HTTP_PROXY=%%p"
+if not defined HTTP_PROXY goto :proxy_done
+set "HTTPS_PROXY=%HTTP_PROXY%"
+echo [HarnessSmith] Using system proxy: %HTTP_PROXY%
+echo.
+:proxy_done
+
+REM Web form (browser) vs interactive CLI wizard (this terminal). Web is the
+REM default on Windows (a browser is normally present). Set HARNESSMITH_MODE to
+REM web or cli to skip the prompt (e.g. for automation). Flat goto flow only.
+set "MODE=web"
+if defined HARNESSMITH_MODE goto :mode_env
+echo [HarnessSmith] How do you want to set up your harness?
+echo     [1] Web wizard - fill a form in your browser
+echo     [2] CLI wizard - interactive setup in this terminal
+set /p "MODE=  Choose [1/2] (Enter = web): "
+if "%MODE%"=="2" set "MODE=cli"
+if not "%MODE%"=="cli" set "MODE=web"
+goto :mode_done
+:mode_env
+set "MODE=%HARNESSMITH_MODE%"
+:mode_done
+echo.
+
+echo [HarnessSmith] Step 1/4: looking for uv on PATH ...
+where uv >nul 2>nul
+if not errorlevel 1 goto :run
+
+echo [HarnessSmith] Step 2/4: checking known uv install locations ...
+if exist "%USERPROFILE%\.local\bin\uv.exe" set "PATH=%USERPROFILE%\.local\bin;%PATH%"
+if exist "%LOCALAPPDATA%\Microsoft\WinGet\Links\uv.exe" set "PATH=%LOCALAPPDATA%\Microsoft\WinGet\Links;%PATH%"
+where uv >nul 2>nul
+if not errorlevel 1 goto :run
+
+REM Look for the installed console script by its .exe name on purpose: a bare
+REM `harnessmith` would resolve to THIS file (HarnessSmith.bat) first, since
+REM Windows searches the current dir and is case-insensitive -> infinite relaunch.
+echo [HarnessSmith] Step 3/4: looking for an installed harnessmith command ...
+where harnessmith.exe >nul 2>nul
+if not errorlevel 1 goto :run_cmd
+
+echo [HarnessSmith] Step 4/4: uv is not installed yet.
+echo.
+echo   The wizard needs uv - a small tool that manages Python and dependencies for
+echo   you (user-level install, no admin required). How would you like to install it?
+echo     [1] Standard - official installer (downloads uv from GitHub)
+echo     [2] China mirror - pip + Tsinghua mirror (needs Python already installed)
+echo     [n] Don't install
+set "CHOICE=1"
+set /p "CHOICE=  Choose [1/2/n]: "
+if /i "%CHOICE%"=="n" goto :manual
+if "%CHOICE%"=="2" goto :install_cn
+
+REM Use the official installer directly (NOT winget): winget first updates its
+REM own source CDN, which hangs for a long time and fails on some networks (e.g.
+REM behind the GFW) even when the GitHub download itself works fine.
+echo [HarnessSmith] Installing uv via the official installer ...
+powershell -ExecutionPolicy Bypass -NoProfile -Command "irm https://astral.sh/uv/install.ps1 | iex"
+if exist "%USERPROFILE%\.local\bin\uv.exe" set "PATH=%USERPROFILE%\.local\bin;%PATH%"
+where uv >nul 2>nul
+if not errorlevel 1 goto :run
+goto :manual
+
+:install_cn
+echo [HarnessSmith] China mirror: installing uv from the Tsinghua PyPI mirror ...
+set "PY="
+where py >nul 2>nul && set "PY=py -3"
+if not defined PY (
+    where python >nul 2>nul && set "PY=python"
+)
+if not defined PY (
+    echo [HarnessSmith] No Python found - the China-mirror path needs Python first.
+    goto :manual_cn
+)
+%PY% -m pip install --user uv -i https://pypi.tuna.tsinghua.edu.cn/simple
+%PY% -m uv --version >nul 2>nul
+if errorlevel 1 (
+    echo [HarnessSmith] pip did not produce a runnable uv.
+    goto :manual_cn
+)
+echo [HarnessSmith] uv installed. Using the Tsinghua mirror + your system Python.
+set "UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple"
+set "UV_PYTHON_PREFERENCE=only-system"
+goto :run_py
+
+:manual
+echo.
+echo [HarnessSmith] Could not find or install uv. Install it manually (user-level, no admin):
+echo     winget install astral-sh.uv
+echo     - or -  powershell -c "irm https://astral.sh/uv/install.ps1 ^| iex"
+echo   then double-click this again.
+echo.
+pause
+goto :eof
+
+:manual_cn
+echo.
+echo [HarnessSmith] The China-mirror path needs Python. Options:
+echo     1) Install Python (https://www.python.org/downloads/ , reachable in China),
+echo        then run this again and choose [2].
+echo     2) Or with Python present:  pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple
+echo     3) Or use a VPN/proxy and choose [1].
+echo.
+pause
+goto :eof
+
+:run
+REM Auto-pick the package index: when no index is pinned and the official PyPI is
+REM unreachable (e.g. behind the GFW), use the Tsinghua mirror for this run so the
+REM first `uv sync` can still fetch deps. An explicit UV_DEFAULT_INDEX always wins;
+REM we only probe when curl is present (ships with Windows 10 1803+).
+if defined UV_DEFAULT_INDEX goto :run_go
+where curl >nul 2>nul
+if errorlevel 1 goto :run_go
+echo [HarnessSmith] Checking whether PyPI is reachable ...
+curl -sS -m 3 -I https://pypi.org/simple/ >nul 2>nul
+if not errorlevel 1 goto :run_go
+echo [HarnessSmith] PyPI looks unreachable - using the Tsinghua mirror this run.
+set "UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple"
+:run_go
+if "%MODE%"=="cli" goto :run_go_cli
+echo [HarnessSmith] Launching: uv run --extra wizard harnessmith wizard --open
+echo.
+uv run --extra wizard harnessmith wizard --open
+goto :after_run
+:run_go_cli
+echo [HarnessSmith] Launching: uv run harnessmith new
+echo.
+uv run harnessmith new
+goto :after_run
+
+:run_cmd
+if "%MODE%"=="cli" goto :run_cmd_cli
+echo [HarnessSmith] Launching: harnessmith.exe wizard --open
+echo.
+harnessmith.exe wizard --open
+goto :after_run
+:run_cmd_cli
+echo [HarnessSmith] Launching: harnessmith.exe new
+echo.
+harnessmith.exe new
+goto :after_run
+
+:run_py
+if "%MODE%"=="cli" goto :run_py_cli
+echo [HarnessSmith] Launching: %PY% -m uv run --extra wizard harnessmith wizard --open
+echo.
+%PY% -m uv run --extra wizard harnessmith wizard --open
+goto :after_run
+:run_py_cli
+echo [HarnessSmith] Launching: %PY% -m uv run harnessmith new
+echo.
+%PY% -m uv run harnessmith new
+goto :after_run
+
+:after_run
+echo.
+echo [HarnessSmith] Process exited (code %errorlevel%). Press a key to close.
+pause >nul
+goto :eof

harnessmith-0.1.0/HarnessSmith.sh

@@ -0,0 +1,139 @@
+#!/usr/bin/env bash
+# One-click launcher for the HarnessSmith setup wizard.
+#
+# Lets you pick how to configure your harness: the Web form (opens in a browser)
+# or an interactive CLI wizard (right here in the terminal). Prefers `uv` (which
+# auto-syncs the optional [wizard] extra for the web form); if uv is missing it
+# offers to install it (user-level, no root).
+set -e
+echo "[HarnessSmith] Setup launcher"
+cd "$(dirname "$0")"
+echo "[HarnessSmith] Folder: $PWD"
+
+find_uv() {
+  if command -v uv >/dev/null 2>&1; then echo uv; return 0; fi
+  [ -x "$HOME/.local/bin/uv" ] && { echo "$HOME/.local/bin/uv"; return 0; }
+  return 1
+}
+
+# Web form vs interactive CLI wizard. On a headless Linux box (no display) the
+# terminal wizard is the sensible default — the web form would only be reachable
+# via SSH port-forward; elsewhere the browser form is the default. Echoes "web"
+# or "cli" on stdout (prompts go to stderr). Set HARNESSMITH_MODE=web|cli to
+# skip the prompt (e.g. for automation).
+choose_mode() {
+  if [ -n "${HARNESSMITH_MODE:-}" ]; then echo "$HARNESSMITH_MODE"; return 0; fi
+  default=web
+  if [ "$(uname)" = Linux ] && [ -z "${DISPLAY:-}" ] && [ -z "${WAYLAND_DISPLAY:-}" ]; then
+    default=cli
+  fi
+  {
+    echo "[HarnessSmith] How do you want to set up your harness?"
+    echo "    [1] Web wizard - fill a form in your browser"
+    echo "    [2] CLI wizard - interactive setup here in the terminal"
+    printf "  Choose [1/2] (Enter = %s): " "$default"
+  } >&2
+  read -r reply </dev/tty 2>/dev/null || reply=""
+  case "$reply" in
+    1) echo web ;;
+    2) echo cli ;;
+    *) echo "$default" ;;
+  esac
+}
+
+# Auto-pick the package index: when no index is pinned and the official PyPI is
+# unreachable (e.g. behind the GFW), use the Tsinghua mirror for this run so the
+# first `uv sync` can still fetch deps. An explicit UV_DEFAULT_INDEX always wins;
+# we only probe when curl is available.
+pick_index() {
+  [ -n "${UV_DEFAULT_INDEX:-}" ] && return 0
+  command -v curl >/dev/null 2>&1 || return 0
+  echo "[HarnessSmith] Checking whether PyPI is reachable ..."
+  if curl -sS -m 3 -I https://pypi.org/simple/ >/dev/null 2>&1; then return 0; fi
+  echo "[HarnessSmith] PyPI looks unreachable - using the Tsinghua mirror this run."
+  export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple
+}
+
+# Reuse the system proxy so the curl probe above, the uv install, and uv's sync all
+# reach the net the same way. Only when none is already set. macOS's GUI proxy isn't
+# read by curl/uv on their own, so on a Mac we read it via scutil and export it
+# (Linux users set *_PROXY as usual -> this is a no-op there). Best-effort: any parse
+# miss just leaves the env untouched. Mirrors the wizard's proxy-aware urllib probe.
+pick_proxy() {
+  [ -n "${HTTP_PROXY:-}${HTTPS_PROXY:-}${http_proxy:-}${https_proxy:-}" ] && return 0
+  [ "$(uname)" = Darwin ] || return 0
+  command -v scutil >/dev/null 2>&1 || return 0
+  local enabled host port px
+  enabled="$(scutil --proxy 2>/dev/null | awk '/^[[:space:]]*HTTPSEnable/ {print $3}')"
+  [ "$enabled" = 1 ] || return 0
+  host="$(scutil --proxy 2>/dev/null | awk '/^[[:space:]]*HTTPSProxy/ {print $3}')"
+  [ -n "$host" ] || return 0
+  port="$(scutil --proxy 2>/dev/null | awk '/^[[:space:]]*HTTPSPort/ {print $3}')"
+  px="http://$host"
+  [ -n "$port" ] && px="$px:$port"
+  export HTTP_PROXY="$px" HTTPS_PROXY="$px"
+  echo "[HarnessSmith] Using system proxy: $px"
+}
+
+pick_proxy
+
+echo "[HarnessSmith] Looking for uv ..."
+uv_bin="$(find_uv || true)"
+if [ -z "$uv_bin" ]; then
+  # No uv yet: an already-installed harnessmith command works too.
+  if command -v harnessmith >/dev/null 2>&1; then
+    echo "[HarnessSmith] Found the harnessmith command."
+    if [ "$(choose_mode)" = cli ]; then
+      echo "[HarnessSmith] Launching: harnessmith new"
+      exec harnessmith new
+    fi
+    echo "[HarnessSmith] Launching: harnessmith wizard --open"
+    exec harnessmith wizard --open
+  fi
+  echo "[HarnessSmith] uv is not installed yet. How would you like to install it?"
+  echo "    [1] Standard - official installer (downloads from GitHub)"
+  echo "    [2] China mirror - pip + Tsinghua mirror (needs python3 already installed)"
+  echo "    [n] Don't install"
+  printf "  Choose [1/2/n]: "
+  read -r choice </dev/tty 2>/dev/null || choice=1
+  case "$choice" in
+    [Nn]*) ;;
+    2)
+      if command -v python3 >/dev/null 2>&1; then py=python3
+      elif command -v python >/dev/null 2>&1; then py=python
+      else py=; fi
+      if [ -n "$py" ]; then
+        echo "[HarnessSmith] Installing uv via pip + Tsinghua mirror ..."
+        "$py" -m pip install --user uv -i https://pypi.tuna.tsinghua.edu.cn/simple || true
+        if "$py" -m uv --version >/dev/null 2>&1; then
+          export UV_DEFAULT_INDEX=https://pypi.tuna.tsinghua.edu.cn/simple
+          export UV_PYTHON_PREFERENCE=only-system
+          echo "[HarnessSmith] Launching: $py -m uv run --extra wizard harnessmith wizard --open"
+          exec "$py" -m uv run --extra wizard harnessmith wizard --open
+        fi
+      fi
+      echo "[HarnessSmith] China path needs python3 first (then: pip install uv -i <Tsinghua>)." >&2
+      ;;
+    *)
+      echo "[HarnessSmith] Installing uv via the official installer ..."
+      curl -LsSf https://astral.sh/uv/install.sh | sh \
+        || echo "[HarnessSmith] uv install failed; see https://docs.astral.sh/uv/" >&2 ;;
+  esac
+  uv_bin="$(find_uv || true)"
+fi
+
+if [ -n "$uv_bin" ]; then
+  pick_index
+  if [ "$(choose_mode)" = cli ]; then
+    echo "[HarnessSmith] Launching: $uv_bin run harnessmith new"
+    exec "$uv_bin" run harnessmith new
+  fi
+  echo "[HarnessSmith] Launching: $uv_bin run --extra wizard harnessmith wizard --open"
+  exec "$uv_bin" run --extra wizard harnessmith wizard --open
+fi
+
+echo "[HarnessSmith] Could not find or install uv. Install it (user-level, no root):" >&2
+echo "    curl -LsSf https://astral.sh/uv/install.sh | sh" >&2
+echo "    - or (China) -  pip install uv -i https://pypi.tuna.tsinghua.edu.cn/simple" >&2
+echo "  then re-run this script." >&2
+exit 1

harnessmith-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 EpisodeYu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.