# Harness — Agent 上下文说明

本文件供 **Cursor Agent**（Local / Worktree / Cloud）快速理解仓库结构与操作规范。人类维护者请参阅 [`docs/`](docs/index.qmd) 中的详细文档。

## 仓库定位

`harness` 集中管理跨项目可复用的 **工程配置**、**环境脚本**与**代码片段**，主要面向 **R、Quarto、JavaScript、PowerShell、Windows 11**。

## 目录约定（新增文件必须遵守）

| 路径 | 用途 |
|------|------|
| `ide/<IDE>/` | 编辑器/IDE 全局或工作区配置 |
| `js/` | 跨项目复用的 JavaScript 工具 |
| `scripts/<lang>/` | 独立脚本（`r/`、`powershell/`、`sql/` 等） |
| `templates/` | 配置如何被调用的微型示例 |
| `docs/` | 技术说明（Quarto `.qmd`，Listing 自动收录） |

**禁止**在仓库根目录堆砌与上述分类无关的文件。

## 常用命令

### Quarto 网站（本仓库根）

```powershell
quarto check
quarto render
```

产物目录 `_site/` **不提交** Git。

### 配置资产验证（以 MathJax 为例）

通用规程：[配置资产本地验证与发布工作流](docs/harness-asset-validation-workflow.qmd)

```powershell
cd js/mathjax/test
Rscript Rscript/test-wrap-display-math.R          # L0 单元
Rscript Rscript/run-module.R mod-display-core     # L1 分模块（独立 R 进程）
Rscript Rscript/run-all-modules.R                 # L2 冒烟（可选）
```

**原则**：迭代只改 `test/` 镜像；L1 全绿后再晋升 `js/mathjax/` 下 canonical 文件。`output/`、`renv/`、`TEST-LOG.md` **不提交**。

### Git Worktree

Worktree 创建时自动执行 [`.cursor/setup-worktree-windows.ps1`](.cursor/setup-worktree-windows.ps1)（Windows）或 [`.cursor/setup-worktree-unix.sh`](.cursor/setup-worktree-unix.sh)（Unix）。配置见 [`.cursor/worktrees.json`](.cursor/worktrees.json)。

## 提交规范

- Conventional Commits（如 `feat:`、`docs:`、`fix:`）
- 不提交密钥、本机绝对路径、测试产物、`renv/` 缓存

---

## Cursor Cloud specific instructions

Cloud Agent 在 **Ubuntu VM** 中运行。以下说明帮助云端环境与 Local/Worktree 行为一致。

### 1. 环境前提

| 组件 | 要求 |
|------|------|
| Git | 已连接 GitHub（read-write）；Cloud 从远程 **干净 checkout** 起步 |
| R | ≥ 4.2；Cloud Environment Snapshot 中应预装常用包或 `renv::restore()` |
| Quarto | 已安装且 `quarto check` 通过 |
| Secrets | 本仓库 **通常不需要** API 密钥；若任务涉及外部服务，在 [Cloud Dashboard → Secrets](https://cursor.com/dashboard/cloud-agents) 配置，**勿**依赖未提交的 `.env` |

Cloud Environment 已配置：见 [`.cursor/environment.json`](.cursor/environment.json)（Snapshot `snapshot-20260525-faa29445-b11d-4b39-aa1c-793e981fe6ce`，2026-05-25）。每次启动执行 [`.cursor/install-cloud.sh`](.cursor/install-cloud.sh)（Quarto 1.9.37 回退安装 → `quarto check` → 可选 `renv::restore()`）。Dashboard **Update command** 填 `bash .cursor/install-cloud.sh`。

### 2. Move to Cloud 前 checklist

- [ ] 本地改动已 **commit 或 stash**（Move to Cloud **不会**携带未提交文件）
- [ ] 任务描述中注明目标路径（如 `js/mathjax/test/` vs `docs/`）
- [ ] 若依赖 `.Renviron`，确认主 checkout 已有该文件（worktree setup 会从 `ROOT_WORKTREE_PATH` 复制；Cloud 需通过 Secrets 或 Environment 注入等价变量）

### 3. Cloud 上的验证策略

| 任务类型 | 推荐验证 |
|----------|----------|
| 修改 `docs/*.qmd` | `quarto render docs/<file>.qmd` 或 `quarto render`（全站） |
| 修改 `js/mathjax/` 资产 | 在 `js/mathjax/test/` 跑 L0 → L1；负向用例用独立模块 |
| 修改 PowerShell 脚本 | 在 Windows Local/Worktree 验证；Cloud VM 为 Linux，**勿**在 Cloud 上测试 Windows 专有脚本 |
| 修改 `ide/` 配置 | 文档化即可；无需 render |

配置资产任务请严格遵循 [验证工作流](docs/harness-asset-validation-workflow.qmd) 的 **Isolate → Verify → Promote** 顺序；Cloud Agent 在 `test/` 沙盒迭代，L1 全绿后再改 canonical。

### 4. Move to Local 注意

- Move to Local 按钮仅在 Cloud 任务 **结束后** 出现
- **跨机器不可用**：在 B 电脑打开曾在 A 电脑 Local 启动的会话时，不会出现 Move to Local；请改用 **PR + git pull** 或 [cursor.com/agents](https://cursor.com/agents)
- 需要本机 RStudio/debugger 时，在 **同一台 Windows 机器** 上 Move to Local

### 5. 并行与资源分工（低配硬件友好）

| 场景 | 建议环境 |
|------|----------|
| Plan、小改、review | Local / Editor |
| 1 个中等任务 | Local 或 1 个 Worktree |
| 2+ 并行实现、全站 render、L1 多模块 | **Cloud** |
| Windows PowerShell 脚本 | Local / Worktree |

本机 Worktree 上限建议：`cursor.worktreeMaxCount` 设为 **8–12**（默认 25 对磁盘不友好）。

### 6. 文档与 Mermaid

- 新增/修改 `docs/*.qmd` 时，Mermaid 须用 Quarto 块 **` ```{mermaid} `**，勿用普通 ` ```mermaid `
- YAML `date` 使用固定编写日期，勿用 `last-modified`

### 7. 相关文档

- [Cursor Local + Cloud 并行开发进阶指南](docs/cursor-local-cloud-parallel-dev.qmd)
- [配置资产验证工作流](docs/harness-asset-validation-workflow.qmd)