diff --git a/.githooks/pre-commit b/.githooks/pre-commit index 16e33629..b3d5bf3d 100755 --- a/.githooks/pre-commit +++ b/.githooks/pre-commit @@ -22,6 +22,8 @@ snapshot_managed_release_paths() { "CHANGELOG.md" "skills/zh/header.md.template" "skills/en/header.md.template" + "skills/zh/cursor-plugin-rule.mdc.template" + "skills/en/cursor-plugin-rule.mdc.template" ) local path local src @@ -152,6 +154,8 @@ git -C "$ROOT_DIR" add \ CHANGELOG.md \ skills/zh/header.md.template \ skills/en/header.md.template \ + skills/zh/cursor-plugin-rule.mdc.template \ + skills/en/cursor-plugin-rule.mdc.template \ tests/golden-snapshots.json cat >"$STATE_FILE" < **未列入面默认可删**：`state/sessions/*`、`state/last_route.json`、runtime 内部模块边界、route name 全集、output 渲染文案措辞均为 runtime 内部实现，不在 keep-list 内。P4b 减重时可自由处置。 -`host_support` 只声明官方适配器能把 Skill 语义交付到对应宿主的支持界面并由宿主消费。它不等同于原生 Skill discovery，也不证明该宿主已经完成 E2E；支持等级、已验证能力和入口形态继续由 `HostCapability` 表达。当前五个内置 Skill 面向 `codex / claude / qoder / copilot`，其中 Copilot 通过单文件展开消费。 +`host_support` 只声明官方适配器能把 Skill 语义交付到对应宿主的支持界面并由宿主消费。它不等同于原生 Skill discovery，也不证明该宿主已经完成 E2E；支持等级、已验证能力和入口形态继续由 `HostCapability` 表达。当前五个内置 Skill 面向 `codex / claude / qoder / copilot / cursor`，其中 Copilot 通过单文件展开消费，Cursor IDE 通过用户 Plugin Rule 与全局 Skill 树拆分消费；Agent CLI 只保留手工 Skill 与用户 Hook 兼容面。 ## Output Rendering Audit — *[pre-P8 legacy reference]* @@ -504,6 +504,7 @@ output.py 渲染层逐字段分类。只做分类，不做改造决策（改造 | Claude | `protocol_verified` | `install.sh --target claude:zh-CN` | CONTINUATION + INTERACTION + AUDIT | 已验证 | | Qoder | `protocol_verified` | `install.sh --target qoder` | CONTINUATION + INTERACTION + AUDIT | W3.1-W3.3 已验证 | | Copilot | `baseline_supported` | `install.sh --target copilot` | PROMPT_ONLY | Prompt-only | +| Cursor | `baseline_supported` | `install.sh --target cursor` | PROMPT_ONLY + HOOKS | IDE user Plugin Rule + global Skills/payload + user-level `~/.cursor/hooks.json`; observable IDE baseline evidence, CLI manual Skills only | ### 契约消费矩阵（P8 2-file state model） @@ -543,7 +544,7 @@ output.py 渲染层逐字段分类。只做分类，不做改造决策（改造 - MCP 只承接 active plan / handoff 读取、protocol check 与受 guard 约束的低层 receipt 写入；分析、设计、开发、checkpoint 与 finalize 决策继续由 prompt/skill 和宿主负责。 - repo-local server 为 `scripts/sopify_mcp_server.py`。Codex-first 注册已通过官方 `codex mcp get/add`、真实 stdio tool 调用和 no-op 复验。 - 2026-07-17 Claude 会话级消费已通过：使用临时 MCP 配置加载同一 repo-local server，成功调用 `sopify.workspace_status_lite`；该证据不等同于持久注册。 -- Codex-first 表示验证顺序，不改变 Qoder、Claude、Copilot 的能力梯度或支持声明。其他宿主自动注册须复用同一最小契约并各自补证据。 +- Codex-first 表示验证顺序，不改变 Qoder、Claude、Copilot、Cursor 的能力梯度或支持声明。其他宿主自动注册须复用同一最小契约并各自补证据。 - 当前不把 Python/MCP 依赖供给、payload 打包、doctor 检查或多宿主配置抽象升级为产品面；只有后续证据证明重复痛点时再设计。 ### 禁止消费面 diff --git a/.sopify/plan/20260819_cursor_support/audits/cursor_ide_final_review.md b/.sopify/plan/20260819_cursor_support/audits/cursor_ide_final_review.md new file mode 100644 index 00000000..50bf5725 --- /dev/null +++ b/.sopify/plan/20260819_cursor_support/audits/cursor_ide_final_review.md @@ -0,0 +1,121 @@ +# Sopify Cursor IDE Plugin 最终独立复审任务 + +## 复审模式 + +- 只读。不要修改代码、方案、`.sopify/state`、receipts、Cursor 配置或 Git index。 +- 仓库：`/Users/weixin.li/code/github/sopify` +- 分支：`feat/cursor-support` +- 基线：`d0e81f168be629cfa7f1e6b3cce5ed01f712fc3e` +- 复审对象：相对基线的全部未提交 diff，包括删除文件与 untracked 文件。 +- 不沿用实现者结论；只按源码、测试输出、IDE 工具轨迹和文件结果独立裁决。 + +## 已定产品边界 + +1. Cursor IDE 是自动语义入口：用户级 Plugin 中一个薄 `alwaysApply: true` Rule 负责意图分类和精确 Skill 路由。 +2. Agent CLI 是低频兼容面：不承诺自动加载 Plugin Rule，只保留手工 Skill 与 Cursor 实际加载范围内的用户 Hooks。 +3. 不安装项目 `.cursor/rules/sopify.mdc`，不新增 launcher、prompt injector、Command、Custom Agent、MCP、orchestrator 或 runtime。 +4. 全局五项 Skills、shared references、payload 与用户 Hooks 由同一个 Cursor host installer 管理。 +5. 支持档位保持 `BASELINE_SUPPORTED`；独立 sessionStart、显式 finalize、AskQuestion 跨模型稳定性不是本轮阻塞项，也不得写成已验证。 +6. 不修改 Cursor settings、代理、模型、账号、API Key、钥匙串或 MCP；不支持 Cloud Agent。 + +## 代码与结构审查 + +- Cursor 仍是多宿主内核中的第五个 adapter，不是 fork。 +- `installer/cursor_plugin.py` 只负责本地 Plugin manifest、README 和一个薄 Rule；不得维护 Plugin 私有 Skills 副本。 +- Cursor 安装不要求 workspace、不预热项目 `.sopify`，首次产品写入前预检用户 hooks。 +- Hooks 只保护明显直接写入 state/handoff/receipt，放行方案文档、业务代码和正常 `sopify_writer` 库 API；helper 异常 fail-open，并由 Doctor 报告。 +- Doctor 分开报告 Plugin、Skill、payload、hooks 与 IDE/CLI behavior；临时本机 transcript 不得让静态 behavior 项冒充产品认证。 +- 检查 Codex、Claude、Qoder、Copilot 行为没有被 Cursor-specific 分支意外改变。 + +实现者在 2026-08-22 的最终候选上报告：308 passed / 78 subtests，Python compileall、`bash -n install.sh` 与 `git diff --check` 均通过。复审者应按下面命令自行重跑，不把这段记录当成独立通过。 + +同日真实 home Doctor 中，Cursor 的 Plugin、payload、bundle resolution、Skill tree 与 Hooks 五项均为 pass；IDE/CLI behavior 仍按静态设计为 skip / `BLACK_BOX_NOT_VERIFIED`。Doctor 的 overall fail 来自本仓库旧 `.sopify/sopify.json` 对 Codex、Claude、Qoder bundle 的历史 pin，不是 Cursor 检查失败，本任务不顺手改写该 workspace 配置。 + +## 可独立核验的 IDE 证据 + +### Plugin、consult 与 Analyze + +- 用户范围的 Sopify Plugin Rule 已在 Cursor Customize > Rules 中显示为 Always Apply，Plugin 服务日志报告 `ruleCount: 1`。 +- consult transcript：`/Users/weixin.li/.cursor/projects/Users-weixin-li-code-github-sopify/agent-transcripts/067ce461-c667-46fb-88ce-bffe4c4362a1/067ce461-c667-46fb-88ce-bffe4c4362a1.jsonl` +- Analyze transcript：`/Users/weixin.li/.cursor/projects/Users-weixin-li-code-nio-data-sprite/agent-transcripts/7101b90b-ce5d-4acb-8fc3-930056f95e68/7101b90b-ce5d-4acb-8fc3-930056f95e68.jsonl` +- 核验重点：consult 不加载阶段 Skill、不续旧方案、不写 machine truth；Analyze 实际读取 Cursor Skill 并执行评分脚本，低分时不进入 Design 或写文件。 + +### AskQuestion + +- transcript：`/Users/weixin.li/.cursor/projects/Users-weixin-li-code-nio-data-sprite/agent-transcripts/84e9fa01-c2dc-4db5-9611-0f15c120bcb8/84e9fa01-c2dc-4db5-9611-0f15c120bcb8.jsonl` +- 同一会话包含 AskQuestion tool use 与 `Tool not found` 回退；结构化问卷 UI 属人工观察，transcript 不含 tool result、选项回传或 `Other...`。 +- 这只证明 AskQuestion 调用尝试与文本回退都发生过；结构化问卷 UI 仍是人工观察。不要据此宣称每个模型或每次会话都会稳定提供问卷。 + +### Managed 主链与 Hook + +- 临时仓库：`/private/tmp/sopify-cursor-managed-blackbox.WRxVtd` +- transcript：`/Users/weixin.li/.cursor/projects/private-tmp-sopify-cursor-managed-blackbox-WRxVtd/agent-transcripts/2448476f-57b8-4e1d-a522-c19e8202d658/2448476f-57b8-4e1d-a522-c19e8202d658.jsonl` +- 初始业务文件为 `hello\n`。第一轮实际读取 Analyze/Design Skills，执行评分 `10/10` 和 light 分级，创建方案并经 writer 写 active plan/handoff，然后在 `confirm_decision` 停车，业务文件未改。 +- 用户确认后，第二轮读取四步链与 Develop Skill，将 `src/greeting.txt` 精确改成 `hello from Cursor\n`，更新方案为 `ready_to_archive`，并经 writer 追加 `exec_001`、`verify_001` 与 handoff；未 finalize、未 commit。 +- 第三轮实际执行紧贴重定向的 Shell 直写 `active_plan.json`，Cursor Hook 返回拒绝；Agent 未尝试绕过。 + +现场哈希： + +```text +f9e1d6f57a5d7a795513cfb8ef1ce5c8c7c3deb3319a0ab38df5a73a735ad0b2 .sopify/state/active_plan.json +f24d2621d2fbc470b9febdcd8e700679358469f025c25f668e74dd1e661ce950 .sopify/state/current_handoff.json +7335746bb72af92df43cb5b1435934d8bed6fbe282307f02630d62836dfe4ecd .sopify/plan/20260822_greeting_from_cursor/receipts/exec_001.json +70c06cac2adeecc10e91443a04149cd6d5c627befc8cc6fbdbba8943c4ff3e47 .sopify/plan/20260822_greeting_from_cursor/receipts/verify_001.json +bd601aecf0dae231623085daa65a69e8304327aaa829e629eb8362f34cb0496b src/greeting.txt +``` + +不要只看最终回复。以 transcript 中的 `tool_use`、方案/receipt 内容、Git diff 和文件哈希为证据。 + +## CLI 已知边界 + +- 自动用户 Plugin：`4c24eab4-dd82-46f3-8fd7-67888baa1a53` +- 显式 `--plugin-dir`：`7626c137-9668-450f-ab00-a44619f90f9c` +- 唯一标记探针：`109d2991-78e6-46d8-a19a-5bd86f3198f0` + +三次都没有证明 Agent CLI 自动加载用户 Plugin Rule。该能力不在产品承诺内，不是 IDE baseline 阻塞项，也不得改写成 CLI 自动支持。 + +## 建议命令 + +```bash +cd /Users/weixin.li/code/github/sopify +git status --short --branch +git diff --check +git diff -- . ':(exclude).sopify/plan/20260819_cursor_support/audits/cursor_ide_final_review.md' +PYTHONDONTWRITEBYTECODE=1 /opt/homebrew/opt/python@3.11/libexec/bin/python3 -m pytest -p no:cacheprovider tests -q +PYTHONDONTWRITEBYTECODE=1 /opt/homebrew/opt/python@3.11/libexec/bin/python3 scripts/sopify_doctor.py --format json --home-root /Users/weixin.li +``` + +普通 `git diff` 不展示 untracked 文件，请单独读取 `git status --short` 列出的全部新资产，尤其是： + +- `installer/cursor_plugin.py` +- 双语 Cursor Plugin Rule 与 README 模板 +- 本审计文件 + +## 输出要求 + +请直接在 chat 返回，不写文件： + +1. 一句话裁决。 +2. P0 / P1 / P2 findings；没有则明确“无”，每条附文件或可观察证据。 +3. 是否存在过度设计、冗余入口或口径过强。 +4. 自动化、IDE、CLI 三类证据分别证明什么，哪些仍未验证。 +5. 是否认可保持 `BASELINE_SUPPORTED`。 +6. 精确状态：`accept`、`accept_with_fixes` 或 `reject`。 + +不要 commit、push、安装新组件、删除兼容 Skill，或生成 verify receipt。 + +## 独立复审结果（2026-08-22） + +- 精确裁决：`accept`；P0 无，P1 无。 +- 认可：Cursor 仍是第五个 adapter，不是 fork；用户 Plugin 薄 Rule、全局 Skills/payload 与用户 Hooks 的分层没有引入 launcher、runtime、MCP、Custom Agent 或第二套项目 Rule。 +- P2-1：复审时真实安装 Rule/README 与候选模板有文字差异。已用最终 `cursor:zh-CN` 候选原位重装并逐字核对；Hooks、CLI/User settings、MCP 文件存在状态与系统代理前后不变。 +- P2-2：AskQuestion transcript 证明调用尝试与文本回退，但不独立证明结构化问卷结果。公开文档与方案已删除“原生问卷/Other 已验证”等过强口径，不承诺跨模型稳定性或选项回传。 +- P2-3：本轮独立复审没有重看 Customize UI 或 `ruleCount: 1` 日志。公开证据口径以已安装 Rule 的 `alwaysApply: true`、consult/Analyze 工具轨迹和既有人工 UI 观察分层记录，不把 UI 观察写成可移植认证。 +- 自动化：最终候选 `308 passed, 78 subtests passed`；Python compileall、`bash -n install.sh`、SVG XML 与 `git diff --check` 通过。 +- 支持边界：保持 `BASELINE_SUPPORTED`。独立 sessionStart、显式 finalize、AskQuestion 跨模型稳定性、CLI 自动 Plugin Rule 与 Cloud Agent 不在本轮闭环内。 + +## 独立视觉与文档复审（2026-08-22） + +- 最终裁决：`accept`；P0/P1/P2 均无，未发现重复入口或过度设计。 +- 三张全量宿主矩阵 SVG 均通过视觉检查；Cursor 与 Copilot 均按 baseline 表达。封面、demo 与跨宿主场景图保持具体示例，不为凑齐宿主重绘。 +- 首轮发现的 Cursor Verify Setup 断点、badge 错误导航与 README 顶部跨宿主过强口径，已分别以用户级 Doctor/Always 验证、专项文档直链和支持入口/档位分层关闭。 diff --git a/.sopify/plan/20260819_cursor_support/audits/implementation_review.md b/.sopify/plan/20260819_cursor_support/audits/implementation_review.md new file mode 100644 index 00000000..df078c6c --- /dev/null +++ b/.sopify/plan/20260819_cursor_support/audits/implementation_review.md @@ -0,0 +1,82 @@ +# Sopify Cursor 宿主实施 · 独立复审包 + +## 审计任务 + +只读审查当前本地提交，不修改代码、方案、state、receipt 或 Git index。不要复述实现者结论；按源码、基线 diff、测试与真实 Cursor CLI transcript 独立裁决。 + +- Repository: `/Users/weixin.li/code/github/sopify` +- Branch: `feat/cursor-support` +- Baseline: `2c2c13f3f8fd94f05fb3e3789bd2e20755e27863` +- Diff: `git diff 2c2c13f3f8fd94f05fb3e3789bd2e20755e27863..HEAD`，并检查 `git status --short` +- Delivery: 本地已提交，未 push +- 范围: 本地 Cursor IDE + Cursor Agent CLI；不含 Cloud Agent +- 档位: `BASELINE_SUPPORTED`；不得从文件存在或单次模型自述推导 `PROTOCOL_VERIFIED` + +## 已定边界 + +- 保留多宿主内核，Cursor 是新 host，不建 fork。 +- 项目规则：`/.cursor/rules/sopify.mdc`；全局 Skills：`~/.cursor/skills/sopify/`；payload：`~/.cursor/sopify/`；用户 Hooks：`~/.cursor/hooks.json`。 +- 项目规则负责语义路由；Hook 只注入状态事实、拒绝明显直接改写 machine truth。它是 fail-open 防误写 guard，不是安全沙箱。 +- 没有项目规则时 Hook no-op；不写仓库级 hooks；不修改 Cursor settings、代理、模型、账号、API Key、钥匙串或 MCP。 +- managed writer 全流程与 finalize 不在本轮声明范围；不扩建 MCP、runtime、plugin、orchestrator 或 writer CLI。 + +## 本轮修复过的审计 finding + +1. Doctor 缺席只看 Sopify 自有落点，不再把整个 `~/.cursor` 当成已安装。 +2. Cursor 禁用未验证的 EvidentLoop agent 映射；`--workspace` 只安装项目规则，不 bootstrap `.sopify`。 +3. Hook doctor 核对 helper 实际路径、可执行 Python 和 `failClosed: false`。 +4. `sessionStart` 只注入与 active plan 匹配的 handoff，并声明状态事实不是恢复命令。 +5. latest receipt 遵循 `final.json` 优先、timestamp 降序、缺 timestamp 时 receipt 数字兜底。 +6. 文件 Hook 按目标路径选择多根 workspace；Shell 在 writer marker 前拒绝明显直接改写。 +7. 非法 `hooks.json` 在任何 Sopify 产品写入前失败；合法配置原子合并并保留用户条目。 +8. Cursor Hook/helper 绑定具体 `cursor` host，不与通用 `project_rules` surface 隐式耦合。 +9. Helper 严格按 `hook_event_name` 分发，不猜事件。 +10. 安装结果不再把项目规则落点误报成“已预热”。 +11. 安装结果不再声称项目规则“会自动加载”，只说明已按 `alwaysApply: true` 安装并要求在 Cursor Rules 中确认。 +12. 多根 `sessionStart` 只在 `cwd` 唯一归属一个已启用 workspace 时注入方案事实；否则只报告歧义。 +13. Shell guard 可识别 state 与 receipt 的 `echo x>.sopify/...`、`echo x>>.sopify/...` 等紧贴输出重定向；仍明确不是完整 Shell 解析器或安全沙箱。 + +第一次独立 Cursor 复审对当时实现给出的裁决是：无 P0/P1，上述 11–13 为应修 P2。第二次复审确认 11、12 关闭，但重现了 receipt 紧贴 `>` 时 13 未关闭。当前实现只给 receipt 命令边界增加 `>`，并补对应测试和真实 CLI 复测；没有引入 Shell parser。`verify_002` 是修复前的过强历史 receipt，未覆盖；本轮用 `verify_003` 纠正。请重新按源码与可观察证据裁决，不沿用实现者结论。 + +## 自动化证据 + +- `python3 -m pytest tests -q`：307 passed / 76 subtests。 +- `python3 -m compileall -q installer scripts sopify_writer`：passed。 +- `git diff --check`：passed。 +- 临时 home 测试覆盖 settings 保持不变、非法 hooks 无半安装、stale/fail-closed hooks doctor 失败、project_rules 不隐式装 Cursor Hook、多根路径与多根 sessionStart 歧义、receipt 排序、普通 Shell 绕过、state/receipt 紧贴重定向与命令路径空格。 + +## 真实 Cursor Agent CLI 证据 + +临时项目：`/private/tmp/sopify-cursor-cli-blackbox-v2.vDHYE4`。真实安装使用本机已登录的 `agent`，进程环境保留现有 `127.0.0.1:7898` 代理；未改代理或钥匙串。 + +- Consult：session `c647872d-20e2-4be3-8888-6b4cd0476b44` 实际读取项目 Rule 与 `~/.cursor/skills/sopify/references/shared-writing-dna.md`，未读 Claude/Codex 同名 Skill，未写 state/receipt；但仍读取 Develop Skill/payload，因此只证明副作用边界，不证明 consult 语义路由完全符合规则。 +- sessionStart：session `162b4762-f5e1-4a87-970c-4b5dc3bf711f` 在不读取 `.sopify` 文件的情况下收到 `blackbox_plan / continue_host_develop / exec_001` Hook context。 +- Shell deny：session `d9670b90-0173-4744-8f6f-c20976a77646` 的 `echo hacked > .sopify/state/active_plan.json # sopify_writer` 被 `beforeShellExecution` 拒绝。 +- 无空格 Shell deny：session `40d6cbc5-5486-4df8-80bf-bbdb50dc8c19` 的实际命令 `echo hacked>.sopify/state/active_plan.json` 被 Hook 拒绝。 +- Receipt 紧贴重定向 deny：session `3a13cbf2-d184-488e-9331-25e7a7510365` 的实际命令 `echo hacked>.sopify/plan/blackbox_plan/receipts/exec_001.json` 在 `agent -p --output-format stream-json` 标准输出中返回 `tool_call completed` 与 `result.rejected`。持久 transcript 仍只保存 `tool_use` 和模型回复，因此工具拒绝以本次 stream-json 输出为证，未用 transcript 中的模型自述替代。 +- 文件工具 deny：session `4ac55fd4-aa38-4f9e-a39f-dc5601ffca99` 对 `current_handoff.json` 的 edit tool 调用被 `preToolUse` 拒绝。 +- Analyze 部分失败：session `d2b1121e-7a5e-4c74-8e48-12050e18a32e` 实际读取项目 Rule、Cursor `analyze/SKILL.md`、长规则与评分脚本，但没有调用 `score_requirement.py`，而是继续寻找仓库中不存在的评分细则；会话被停止。不得判定评分门通过。 +- 三份 machine truth 最终哈希与黑盒前一致：active `7bc36890...`、handoff `95438c62...`、receipt `00c09422...`；receipt 紧贴重定向复测后再次核对未变。 +- Cursor IDE settings 前后哈希均为 `93128937...`；`~/.cursor/settings.json` 仍不存在。 +- 多根 `sessionStart` 的歧义处理目前只有自动化证据，没有真实 IDE/CLI 多根黑盒；不得外推为宿主行为已验证。 + +Transcript 根目录：`/Users/weixin.li/.cursor/projects/private-tmp-sopify-cursor-cli-blackbox-v2-vDHYE4/agent-transcripts/`。请检查实际 tool call / hook result，不以 thinking 或最终自述代替证据。 + +## 明确未通过或未验证 + +- CLI Analyze：Skill 路由通过，评分脚本执行未通过。 +- CLI consult：machine-truth 零写入通过，语义路由不干净。 +- Cursor IDE：未验证 Rules 面板 `Always Apply`、IDE 内 consult/analyze/Hook 行为。 +- managed develop/finalize writer-only 完整闭环：不在本轮发布声明范围。 +- Doctor 的 IDE/CLI behavior 仍固定报告 `BLACK_BOX_NOT_VERIFIED`，没有把本机临时证据写成产品级持久认证。 + +## 请独立裁决 + +1. 是否存在 P0/P1 正确性或回归风险；给出文件、行号、复现。 +2. `project_rules` 新 surface 是否保持最小，Cursor-specific Hook 是否避免污染其他 host。 +3. Hook 的 fail-open、用户级落点、多根路径、shell 明显改写策略是否与声明一致；不要把它当安全沙箱审计。 +4. Doctor、README、专项文档与支持档位是否存在过强口径。 +5. 当前准确状态应否是：安装与 Hook baseline 已实现，CLI 黑盒部分通过，Analyze 与 IDE 未闭环，保持 `BASELINE_SUPPORTED`。 +6. 是否有可删除的重复层、无消费者抽象或超出本期范围的实现。 + +输出建议按 `P0 / P1 / P2 / 非阻塞 / 证据缺口 / 过度设计 / 最终裁决`，只报告可复现问题。 diff --git a/.sopify/plan/20260819_cursor_support/plan.md b/.sopify/plan/20260819_cursor_support/plan.md new file mode 100644 index 00000000..ec9b1365 --- /dev/null +++ b/.sopify/plan/20260819_cursor_support/plan.md @@ -0,0 +1,111 @@ +--- +title: Sopify Cursor 宿主支持 +plan_id: 20260819_cursor_support +status: completed +lifecycle_state: ready_to_archive +level: standard +created: 2026-08-19 +updated: 2026-08-22 +archive_ready: true +knowledge_sync: + project: review + background: review + design: required + tasks: review +--- + +# Sopify Cursor 宿主支持 + +就绪状态: Ready to archive +依据: 用户范围的 Sopify Plugin Rule 已在 Customize > Rules 中显示为 Always Apply；consult、Analyze 评分门、AskQuestion 调用尝试与文本回退、Analyze → Design → Develop、writer 写回及 Hook direct-write deny 均有可观察 IDE 证据。最终独立复审返回 `accept`；未单独验证的 sessionStart、显式 finalize 与 AskQuestion 跨模型稳定性只作为后续边界，不阻塞本次 baseline 收口。 + +## Context / Why + +当前 `feat/cursor-support` 已将第五个 host 从每仓项目 Rule 修正为 IDE 用户 Plugin、全局五项 Skills/payload 与用户级 Hooks。安装面、Rule 路由、consult、Analyze 评分、AskQuestion 调用与回退路径、managed develop、writer 写回与 Hook direct-write 证据已闭环；最终独立复审已接受候选，支持档位保持 `BASELINE_SUPPORTED`。Doctor 的行为项继续静态报告 `BLACK_BOX_NOT_VERIFIED`，不把本机临时证据写成可移植产品认证。 + +用户主要在包含多个独立 Git 仓库的工作区中使用 Cursor，希望 Sopify 成为安装一次即可跨仓库工作的默认语义入口，自动区分 consult、quick fix 与 managed workflow，并按当前仓库的 `.sopify/`、项目规则和知识文档进入现有 Skills。每个仓库单独安装项目 `.mdc` 会增加迁移成本，也无法证明模型实际执行协议。 + +Cursor 官方允许用户范围安装 Cursor Plugin，Plugin 可包含 `rules/*.mdc`，`alwaysApply: true` 的 Rule 可作为 IDE 默认上下文；官方 CLI 文档仍只明确列出项目 `.cursor/rules`、`AGENTS.md` 与 `CLAUDE.md`。真实 CLI 也未自动加载用户 Plugin Rule，因此本期将 IDE 作为自动入口，CLI 作为手工 Skill 兼容面。 + +## Scope + +- 保留 Sopify 多宿主内核与 `cursor` host，不创建 Cursor fork；现有 Codex、Claude、Qoder、Copilot 行为保持不变。 +- Cursor IDE 改为用户级 Cursor Plugin：安装到 `~/.cursor/plugins/local/sopify/`，包含 `.cursor-plugin/plugin.json` 与一个极薄的 `rules/sopify.mdc`，作为 IDE 唯一 Sopify 语义入口。 +- Agent CLI 不承诺自动加载 Plugin Rule；低频使用时手工调用已安装的 `/analyze`、`/design`、`/develop` 等 Skill，用户 Hooks 继续提供其实际加载范围内的写保护。 +- IDE Plugin Rule 负责意图分类与 Skill 路由；Analyze 需要有限选项澄清时，当前会话提供内建 AskQuestion 就优先调用并使用问卷自带自由输入，否则回退文本。问卷不成为 Sopify machine truth，也不授权提前进入 Design/Develop。 +- Cursor 不再要求 `--workspace`，不再安装或检查项目 `.cursor/rules/sopify.mdc`；当前双语项目 Rule 的有效内容迁入全局薄 Rule 后删除项目 Rule 模板与本仓库临时规则。 +- 同一次 Sopify 安装继续管理 `~/.cursor/skills/sopify/`、`~/.cursor/sopify/` 与 `~/.cursor/hooks.json`。Plugin 不维护 Cursor 私有 Skills 副本，也不复制 Hook 配置或 helper。 +- 复用现有 `sessionStart`、`preToolUse`、`beforeShellExecution` Hooks。Hook 不再以项目 `.mdc` 为开关，改为按本次事件的目标路径、`cwd` 与 `workspace_roots` 识别由 `.sopify/` 管理的仓库。 +- 文件工具按目标路径选择所属 managed root；Shell 按 `cwd` 选择；`sessionStart` 只有在唯一 managed root 且 active plan 语义有效时才注入事实，多根不唯一或状态无效时 no-op。 +- `preToolUse` 与 `beforeShellExecution` 继续只拒绝对 `active_plan.json`、`current_handoff.json`、`plan/*/receipts/*.json` 的明显直接写入；`plan.md`、`tasks.md`、`design.md` 与业务代码不在保护范围，`sopify_writer` 库 API 继续放行。 +- Doctor 分开报告 Plugin/Rule、全局 Skill 树、payload、用户级 Hooks 的安装事实，以及 IDE/CLI 的行为证据；安装事实不得冒充宿主遵守协议。 +- 同步 installer、registry/capability、CLI 安装文案、README、Cursor 专项文档、长期 blueprint 与相关自动化测试。 + +## Approach + +- 只增加 Cursor-specific 的用户 Plugin 安装能力，不抽象通用 Plugin 框架。Plugin 资产由仓库内单一模板/manifest 生成，五项 Skills 与共享 references 继续来自现有权威源码。 +- IDE 薄 Rule 只保留路由与边界：先分类本轮意图；consult 不续旧 plan；quick fix 不写 protocol machine truth；Analyze 必须实际评分，有限选项澄清按当前会话能力优先调用非 MCP 的内建 AskQuestion；machine truth 只经 `sopify_writer`。不新增问卷状态、tool wrapper 或手工“其他”选项。 +- 不给阶段 Skills 增加 `disable-model-invocation: true`。该字段会把 Skills 变成手工调用，与自然语言默认路由目标冲突；阶段语义继续由薄 Rule 的精确路径读取约束和黑盒证据验证。 +- `.sopify/` 只作为 Hook 写保护的 managed-root 信号，不作为可恢复方案事实。`sessionStart` 仍须验证 active plan 指针、对应 `plan.md` 与匹配 handoff；不能仅凭目录存在注入恢复上下文。 +- 保持 Hook fail-open：helper 缺失或异常不阻塞 Cursor，由 Doctor 报错。Hook 是应用层防误写 guard，不是安全沙箱，不新增完整 Shell parser。 +- 先在隔离 home 验证 Plugin Rule、Skills、payload、Hooks 与 settings 不变，再安装到真实 `~/.cursor`，以 IDE 作为本期唯一自动入口黑盒。 +- CLI 自动 Plugin Rule 与显式 `--plugin-dir` 的失败证据作为已知边界保留，不再作为发布否决门；不长期保留双入口，也不把手工 Skill 使用写成自动路由。 + +## Waves / Steps + +1. 把 Cursor adapter 从 `project_rules` 调整为用户 Plugin 安装面，增加最小 Plugin manifest/Rule 资产并移除 workspace 依赖。 +2. 调整 installer、distribution、Doctor/status 与缺席判定，保证一次安装完成 Plugin、Skills、payload、Hooks，且不修改 Cursor settings、代理或账号相关文件。 +3. 复用现有 Hook helper，替换项目 Rule 启用条件，补目标路径、Shell cwd、唯一 session workspace 与有效事实注入测试。 +4. 删除项目 Rule 产品路径，更新 capability、双语文案、README、Cursor 文档、blueprint 与自动化。 +5. 运行定向和全量回归；保留 CLI 自动入口失败证据，随后执行真实 IDE 黑盒和独立 Cursor 复审。所有行为结论以工具轨迹和文件结果为证据。 + +## Key Decisions + +- 继续使用当前分支 `feat/cursor-support` 与当前 active plan `20260819_cursor_support`；这是同一宿主功能的架构修正，不另建分支或方案包。 +- Cursor IDE 的唯一 Sopify 语义入口是用户级 Plugin 中的薄 Always Rule；项目 `.cursor/rules/sopify.mdc` 不保留为默认或可选第二入口。 +- Plugin 只承载 manifest 与薄 Rule。现有全局 Skills、shared references、payload 与用户级 Hooks 由同一个安装器管理，只有一份维护源和一个安装生命周期。 +- 项目 `AGENTS.md`、`CLAUDE.md`、已有 `.cursor/rules` 与 `.sopify/` 是当前仓库事实，不是第二套 Sopify 入口。真实冲突按 Cursor 规则优先级处理，writer/Hook 边界不依赖模型服从。 +- Hook 使用 `.sopify/` managed-root 信号，但按事件选择目标：文件工具看目标路径、Shell 看 `cwd`、sessionStart 只接受唯一有效 workspace；不新增通用 Git-root resolver。 +- 不设置 `disable-model-invocation: true`，不把 Plugin 的正常构建/安装产物误判为第二套协议源码。 +- 支持档位本波继续为 `BASELINE_SUPPORTED`。Plugin 已安装、Rule 显示 Always、Skill 可发现或模型自述均不能自动升级；`PROTOCOL_VERIFIED` 不在本波承诺范围。 +- CLI 自动入口明确不支持；手工 Skill 是低频兼容路径。当前分支不增加 launcher、prompt injector 或第二套 Rule。 + +## Constraints / Not-in-scope + +- 不做 Marketplace 发布、Team Plugin、Cloud Agent、workspaceOpen 动态加载或 data-sprite 专用 manifest。 +- 不新增 `/sopify` dispatcher、Custom Agent、Command、`/go`、MCP、orchestrator、runtime 或 writer CLI。 +- 不新增 Plugin 自有 Hooks，不把五项 Skills 手工复制成 Cursor 私有维护树，不建立项目 `.mdc` 兼容探测层。 +- 不修改 Cursor `settings.json`、代理、模型、账号、API Key、钥匙串或 MCP 配置；现有 `127.0.0.1:7898` 环境不受影响。 +- 不把文件存在、Customize 列表、Rule 为 Always、Skill discovery 或模型自述当成行为通过。 +- 不覆盖已有 `exec_001`、`exec_002`、`verify_001`、`verify_002`、`verify_003` 或独立审计；新实施和验证追加新 receipt。 +- 显式 finalize 不在本轮范围。合并与 release 只在用户明确授权后执行。 + +## Status / Progress + +- [x] 原 Cursor adapter、用户级 Hooks 与 baseline 修正已提交为 `d0e81f1`；既有自动化为 307 passed / 76 subtests。 +- [x] 用户确认采用“全局 Plugin 唯一薄入口 + 现有 Skills/payload/Hooks”的产品方向，并确认不新增 Hooks 框架。 +- [x] 完成独立 Cursor 审计的二次裁决：接受证据门与分层，驳回 `sopify.json` 唯一标记、`disable-model-invocation: true`、禁止 Plugin 正常复用权威资产三项过度修正。 +- [x] 2026-08-20 复核 Cursor 官方 Plugin、Rules、Hooks 与 CLI 文档，并把 CLI 未自动加载 Plugin Rule 的事实固化为支持边界。 +- [x] 当前 standard 方案与任务清单已按新决策收口，Ready to implement。 +- [x] 实施用户级 Plugin 安装面、Hook managed-root 启用、Doctor 与文档调整。 +- [x] 完成定向与全量自动化，保持其他 host 行为不变：308 passed / 78 subtests，compileall 与 `git diff --check` 通过。 +- [x] 唯一一轮 Cursor 独立复审已返回；批判裁决接受安装结构与 Hook D，关闭其沙箱 pytest 与代理快照误判，保留 IDE A/B/C 行为缺口。 +- [x] 按官方本地 Plugin 流程补充 Reload/Restart 安装提示与测试，重新本地安装；settings、CLI config、hooks 与系统代理哈希均未变化。 +- [x] 根据真实 Customize 空白详情页补充最薄双语 Plugin README；只介绍用途、工作方式与支持边界，不复制 Rule 或协议正文。真实 Reload 证明 Local 详情页不渲染 manifest description 或 README，用户已接受该宿主限制；README 保留为包内/发布文档，但不作为 Doctor 或 installed 健康硬门槛。 +- [-] CLI 自动入口验收已按产品决策关闭：2026-08-20 session `4c24eab4-dd82-46f3-8fd7-67888baa1a53` 反证自动 Plugin 入口未加载；显式 `--plugin-dir` session `7626c137-9668-450f-ab00-a44619f90f9c` 与唯一标记探针 `109d2991-78e6-46d8-a19a-5bd86f3198f0` 同样未加载 Rule。三份 machine truth 哈希均未变化。用户接受 CLI 低频手工 Skill 路径，因此不实施 launcher。 +- [x] 批判核验 Plugin 自动入口失败：包加载成功但 Plugin `ruleCount: 0`；“会遵循 Plugin”的回答前主动 Glob/Read 本地 Rule，不计注入证据。完成单变量 manifest 自动发现修复、22 tests / 2 subtests 定向验证、308 tests / 78 subtests 全量回归、compileall、diff check 与真实重装，受保护配置哈希未变。 +- [x] Reload 后用户范围的 Sopify Plugin Rule 在 Customize > Rules 中显示为 `sopify`、模式为 Always Apply；真实文件名为 `sopify.mdc`，Cursor Plugin 服务在 sopify、data-sprite 等窗口均报告 `ruleCount: 1`，目录自动发现修复成立。 +- [x] IDE consult 会话 `067ce461-c667-46fb-88ce-bffe4c4362a1` 只读取 Cursor shared-writing-dna 并执行只读 Git 查询；分支和 23 个 tracked / 6 个 untracked 变更与现场一致，未加载阶段 Skill、未续跑 active plan、未写 machine truth。 +- [x] IDE Analyze 会话 `7101b90b-ce5d-4acb-8fc3-930056f95e68` 读取 Cursor Analyze Skill、必要规则与输出契约，并实际运行 `score_requirement.py` 得到 `3/10, pass=false`；随后只追问，不进入 Design、不创建 plan/state/receipt。 +- [x] 真实 Cursor 安装原位切换为 `cursor:zh-CN`；Plugin 与 Skill 根各只有一份，英文 `Requirements Analysis` 模板无残留，hooks / CLI config 哈希及系统代理不变，settings 仍不存在。全量回归为 308 passed / 78 subtests，compileall 与 `git diff --check` 通过。 +- [x] 最薄 AskQuestion 扩展仅修改双语 Cursor Plugin Rule 与既有静态契约测试：有限选项按当前会话能力优先使用内建 AskQuestion，不经 MCP 探测，使用问卷自带自由输入并保留文本回退。会话 `84e9fa01-c2dc-4db5-9611-0f15c120bcb8` 保留了 AskQuestion tool use 与 `Tool not found` 回退；结构化问卷 UI 属人工观察，transcript 不含 tool result 或选项回传，因此不承诺跨模型稳定性。 +- [x] 临时仓库 `/private/tmp/sopify-cursor-managed-blackbox.WRxVtd` 完成真实 IDE managed 主链：首轮评分 `10/10`、选择 light、创建 plan 并经 writer 写 active plan/handoff 后停车；用户确认后修改唯一业务文件，经 writer 追加 `exec_001`、`verify_001` 与 handoff，方案保持 `ready_to_archive` 且未 finalize/commit。随后 Shell 直写 `active_plan.json` 被 Hook 拒绝，前后哈希一致。完整轨迹为 session `2448476f-57b8-4e1d-a522-c19e8202d658`。 +- [x] 2026-08-22 最终 Cursor 只读独立复审返回 `accept`：P0/P1 无；三个 P2 分别以真实安装对齐、AskQuestion 证据降级和 UI/文件证据分层关闭。 +- [x] README 宿主 badge、架构图与中英文产品形态 SVG 已同步 Cursor；仅修改全量宿主矩阵，封面、demo 与跨宿主场景图保持具体示例，不为凑齐宿主重绘。 +- [x] 独立视觉/文档复审最终返回 `accept`，P0/P1/P2 均无；其发现的 Cursor 验证断点、badge 导航和顶部跨宿主口径已做最小修正，未新增入口或机制。 +- [x] 最终候选回归通过：308 passed / 78 subtests，Python compileall、`bash -n install.sh`、SVG XML、视觉渲染与 `git diff --check` 均通过；真实 `cursor:zh-CN` 安装与候选逐字对齐，受保护配置及系统代理前后不变。 +- [x] Release 收口检查通过：Cursor 双语 Rule 已纳入版本同步、版本一致性检查和 pre-commit 回滚；README、宿主文档与 GitHub Pages 的双语数据已对齐。定向测试 33 passed，全量测试 311 passed / 78 subtests，隔离 Cursor 安装通过 Doctor。安装结果不替代 IDE/CLI 行为认证。 + +## Next + +本方案保持 `ready_to_archive`；按用户授权合并 PR、发布 latest release 并验证稳定安装包。显式归档留给后续 `~go finalize`。 diff --git a/.sopify/plan/20260819_cursor_support/receipts/exec_001.json b/.sopify/plan/20260819_cursor_support/receipts/exec_001.json new file mode 100644 index 00000000..72b0bc87 --- /dev/null +++ b/.sopify/plan/20260819_cursor_support/receipts/exec_001.json @@ -0,0 +1,25 @@ +{ + "evidence": { + "decision": "accept_with_modifications", + "modifications": [ + "user_level_hooks_json", + "enable_only_when_project_rule_present", + "helper_fail_open", + "session_start_non_resume_clause", + "pretooluse_no_narrow_matcher", + "before_shell_execution", + "fix_baseline_audit_findings", + "keep_baseline_supported" + ], + "required_host_action_was": "confirm_decision" + }, + "provenance": { + "host": "cursor", + "plan_id": "20260819_cursor_support", + "plan_version": "sha256:52de3f2cb9a976b28201b1fe978c05c6dae0268fb8a64724b27623a398e21518", + "receipt_id": "exec_001", + "source": "user_decision" + }, + "timestamp": "2026-08-19T06:08:17+00:00", + "verdict": "decision_accepted_with_modifications" +} diff --git a/.sopify/plan/20260819_cursor_support/receipts/exec_002.json b/.sopify/plan/20260819_cursor_support/receipts/exec_002.json new file mode 100644 index 00000000..8ecd23ba --- /dev/null +++ b/.sopify/plan/20260819_cursor_support/receipts/exec_002.json @@ -0,0 +1,21 @@ +{ + "evidence": { + "decision": "authorized", + "finalize_authorized": false, + "operations": [ + "commit feat/cursor-support locally", + "switch /Users/weixin.li/code/github/sopify to feat/cursor-support", + "remove /Users/weixin.li/.codex/worktrees/f74d/sopify" + ], + "push_authorized": false + }, + "provenance": { + "host": "codex", + "plan_id": "20260819_cursor_support", + "plan_version": "sha256:d45f120c339224588ce6562b9d96f183ac6f4f7bf0969d3507b65a0f5e9b7ffe", + "receipt_id": "exec_002", + "source": "user_decision" + }, + "timestamp": "2026-08-19T08:30:57+00:00", + "verdict": "local_commit_switch_and_worktree_removal_authorized_no_push" +} diff --git a/.sopify/plan/20260819_cursor_support/receipts/verify_001.json b/.sopify/plan/20260819_cursor_support/receipts/verify_001.json new file mode 100644 index 00000000..70e8505b --- /dev/null +++ b/.sopify/plan/20260819_cursor_support/receipts/verify_001.json @@ -0,0 +1,38 @@ +{ + "evidence": { + "black_box": { + "cursor_cli_behavior": "BLACK_BOX_NOT_VERIFIED", + "cursor_ide_behavior": "BLACK_BOX_NOT_VERIFIED", + "open_workspace_has_project_rule": false, + "real_home_has_sopify_cursor_assets": false, + "reason_code": "human_action_required" + }, + "command": "python3 -m pytest tests", + "committed": false, + "pushed": false, + "pytest": { + "passed": 293, + "subtests": 73 + }, + "reason_code": null, + "result": "passed", + "retry_count": 0, + "review_result": { + "code_quality": "pass_with_known_fail_open_limits", + "spec_compliance": "pass_with_residual_black_box" + }, + "root_cause": null, + "scope": "tasks 3.1-3.4, 4.2; installer/cursor_hook.py, installer/cursor_hooks.py, installer/inspection.py, installer/payload.py, installer/hosts/cursor.py, tests/test_cursor_hooks.py", + "support_tier": "baseline_supported", + "verification_source": "project_native" + }, + "provenance": { + "host": "cursor", + "plan_id": "20260819_cursor_support", + "plan_version": "sha256:5f1d69c2e7a3887d62947f95f308d0f8db961c159dacfa09cd5fc0620f71f1da", + "receipt_id": "verify_001", + "source": "implementation_verify" + }, + "timestamp": "2026-08-19T06:37:45+00:00", + "verdict": "implementation_complete_black_box_pending" +} diff --git a/.sopify/plan/20260819_cursor_support/receipts/verify_002.json b/.sopify/plan/20260819_cursor_support/receipts/verify_002.json new file mode 100644 index 00000000..6682dcb6 --- /dev/null +++ b/.sopify/plan/20260819_cursor_support/receipts/verify_002.json @@ -0,0 +1,50 @@ +{ + "evidence": { + "command": "python3 -m pytest tests", + "committed": false, + "compileall": "passed", + "cursor_cli": { + "analyze_score_gate": "not_executed", + "consult_machine_truth_writes": 0, + "consult_semantic_routing": "not_clean", + "no_space_redirect_denied": true, + "no_space_redirect_session": "40d6cbc5-5486-4df8-80bf-bbdb50dc8c19", + "status": "partial" + }, + "cursor_ide": { + "status": "BLACK_BOX_NOT_VERIFIED" + }, + "diff_check": "passed", + "machine_truth_hashes_unchanged": true, + "multi_root_session_start": { + "automated": "passed", + "real_host_black_box": "not_run" + }, + "pushed": false, + "pytest": { + "passed": 307 + }, + "reason_code": null, + "result": "passed", + "retry_count": 0, + "review_result": { + "code_quality": "pass_minimal_heuristic_guard", + "independent_review_before_fix": "no_p0_p1_three_p2", + "spec_compliance": "pass_with_declared_behavior_gaps" + }, + "root_cause": null, + "scope": "independent-review P2 fixes: installation wording, multi-root sessionStart selection, no-space shell redirection", + "settings_sha256_before_after": "9312893735cb53aa1a8acece3f9adde34dcc8128e3d03c1a72f7ec423344f1e5", + "support_tier": "baseline_supported", + "verification_source": "project_native_and_cursor_cli" + }, + "provenance": { + "host": "codex", + "plan_id": "20260819_cursor_support", + "plan_version": "sha256:3386c563b18ae7a154a9c980bd10370e27ef30820999c04d1972af645c7accfb", + "receipt_id": "verify_002", + "source": "implementation_verify" + }, + "timestamp": "2026-08-19T08:02:11+00:00", + "verdict": "cursor_baseline_p2_fixed_cli_partial_ide_pending" +} diff --git a/.sopify/plan/20260819_cursor_support/receipts/verify_003.json b/.sopify/plan/20260819_cursor_support/receipts/verify_003.json new file mode 100644 index 00000000..f05d9af4 --- /dev/null +++ b/.sopify/plan/20260819_cursor_support/receipts/verify_003.json @@ -0,0 +1,50 @@ +{ + "evidence": { + "command": "python3 -m pytest tests -q", + "committed": false, + "compileall": "passed", + "cursor_cli": { + "analyze_score_gate": "not_executed", + "command": "echo hacked>.sopify/plan/blackbox_plan/receipts/exec_001.json", + "consult_semantic_routing": "not_clean", + "persistent_transcript_contains_tool_result": false, + "receipt_redirect_session": "3a13cbf2-d184-488e-9331-25e7a7510365", + "receipt_sha256_unchanged": "00c09422e88cc03dbeee39c2a267884a2bf9f46f9594a5a6d63352debe5a7970", + "status": "partial", + "stream_json_tool_result": "completed_rejected_by_hook" + }, + "cursor_ide": { + "status": "BLACK_BOX_NOT_VERIFIED" + }, + "diff_check": "passed", + "fix": "add > to the existing receipt command prefix boundary; no shell parser or new abstraction", + "machine_truth_hashes_unchanged": true, + "pushed": false, + "pytest": { + "passed": 307, + "subtests_passed": 76 + }, + "reason_code": null, + "result": "passed", + "retry_count": 0, + "review_result": { + "code_quality": "minimal_boundary_change", + "independent_review_before_fix": "no_p0_p1_one_open_p2", + "spec_compliance": "receipt_p2_fixed_with_declared_behavior_gaps" + }, + "root_cause": "RECEIPT_COMMAND_RE did not accept output redirection as a path boundary", + "scope": "receipt path immediately following shell output redirection", + "settings_sha256_unchanged": "9312893735cb53aa1a8acece3f9adde34dcc8128e3d03c1a72f7ec423344f1e5", + "support_tier": "baseline_supported", + "verification_source": "project_native_and_cursor_cli_stream_json" + }, + "provenance": { + "host": "cursor", + "plan_id": "20260819_cursor_support", + "plan_version": "sha256:5980ff839636ac70ef10d0fe01ffc565b709ac6f6de315ef3c0c327363b1bfa1", + "receipt_id": "verify_003", + "source": "implementation_verify_after_independent_review" + }, + "timestamp": "2026-08-19T08:26:34+00:00", + "verdict": "receipt_redirect_fixed_cli_rejected_remaining_black_box_gaps" +} diff --git a/.sopify/plan/20260819_cursor_support/receipts/verify_004.json b/.sopify/plan/20260819_cursor_support/receipts/verify_004.json new file mode 100644 index 00000000..4f6b48de --- /dev/null +++ b/.sopify/plan/20260819_cursor_support/receipts/verify_004.json @@ -0,0 +1,81 @@ +{ + "evidence": { + "automated_verification": { + "bash_n_install_sh": "passed", + "git_diff_check": "passed", + "pytest": { + "passed": 308, + "subtests_passed": 78 + }, + "python_compileall": "passed", + "svg_visual_render": "passed", + "svg_xml": "passed" + }, + "committed": false, + "cursor_cli": { + "automatic_plugin_rule": "unsupported", + "manual_skill_path": "documented_compatibility_surface" + }, + "cursor_ide": { + "analyze_score_gate": "score_script_executed", + "askquestion": "capability_path_observed_with_text_fallback", + "consult_readonly": "observable_read_only_tool_trace", + "hook_direct_write": "denied_with_hash_unchanged", + "managed_chain": "analyze_design_stop_then_develop_observed", + "rule_registration": "always_apply_observed", + "writer_boundary": "state_handoff_receipts_written_via_library_api" + }, + "doctor": { + "cli_behavior": "BLACK_BOX_NOT_VERIFIED", + "ide_behavior": "BLACK_BOX_NOT_VERIFIED", + "install_surface": "passed" + }, + "finalized": false, + "implementation": { + "extra_runtime_or_launcher": false, + "hooks": "user_level_fail_open_guard", + "ide_entry": "user_plugin_always_rule", + "payload": "user_level_versioned_bundle", + "project_rule": "removed", + "skills": "global_five_skill_tree" + }, + "independent_reviews": { + "cursor_implementation": { + "p0": 0, + "p1": 0, + "verdict": "accept" + }, + "visual_and_docs": { + "p0": 0, + "p1": 0, + "p2": 0, + "verdict": "accept" + } + }, + "pushed": false, + "real_install": { + "candidate_assets_exact_match": true, + "protected_cursor_configuration_unchanged": true, + "system_proxy_unchanged": true + }, + "released": false, + "result": "passed", + "support_tier": "BASELINE_SUPPORTED", + "unverified_boundaries": [ + "independent_sessionStart_black_box", + "explicit_finalize_black_box", + "AskQuestion_cross_model_stability", + "Cloud_Agent" + ] + }, + "provenance": { + "host": "codex", + "plan_id": "20260819_cursor_support", + "plan_version": "sha256:09e5ddd1ef473a0d410f65c882bdc56ccf0aebc3f85c038479c402293699e4dd", + "receipt_id": "verify_004", + "reviewer": "cursor", + "source": "final_closeout_after_cursor_and_visual_independent_reviews" + }, + "timestamp": "2026-08-22T02:46:58+00:00", + "verdict": "cursor_baseline_supported_release_candidate_verified" +} diff --git a/.sopify/plan/20260819_cursor_support/receipts/verify_005.json b/.sopify/plan/20260819_cursor_support/receipts/verify_005.json new file mode 100644 index 00000000..c951af91 --- /dev/null +++ b/.sopify/plan/20260819_cursor_support/receipts/verify_005.json @@ -0,0 +1,45 @@ +{ + "evidence": { + "command": "python3 -m pytest -p no:cacheprovider tests -q", + "committed": false, + "finalized": false, + "git_diff_check": "passed", + "implementation_changed": false, + "independent_audit": { + "p0": 0, + "p1": 0, + "p2_resolved": [ + "AskQuestion persisted evidence separated from manual UI observation", + "Plugin Rule separated from native User Rule terminology" + ], + "sessionStart": "declared_unverified_boundary_no_code_change", + "verdict": "accept" + }, + "pushed": false, + "pytest": { + "passed": 308, + "subtests_passed": 78 + }, + "reason_code": null, + "released": false, + "result": "passed", + "retry_count": 0, + "review_result": { + "code_quality": "documentation_only_no_new_entry_or_runtime", + "spec_compliance": "evidence claims now match transcript and Cursor Plugin terminology" + }, + "scope": "AskQuestion evidence wording and user-scope Plugin Rule terminology", + "support_tier": "BASELINE_SUPPORTED", + "verification_source": "project_native" + }, + "provenance": { + "host": "codex", + "plan_id": "20260819_cursor_support", + "plan_version": "sha256:482b990ac2ca05fd7a37092e7d2f5f83957fe09e2bfb670b05fa80966d840671", + "receipt_id": "verify_005", + "reviewer": "external_cursor", + "source": "post_commit_independent_audit_documentation_cleanup" + }, + "timestamp": "2026-08-22T03:41:09+00:00", + "verdict": "cursor_release_docs_evidence_terminology_aligned" +} diff --git a/.sopify/plan/20260819_cursor_support/receipts/verify_006.json b/.sopify/plan/20260819_cursor_support/receipts/verify_006.json new file mode 100644 index 00000000..6284e956 --- /dev/null +++ b/.sopify/plan/20260819_cursor_support/receipts/verify_006.json @@ -0,0 +1,30 @@ +{ + "evidence": { + "behavior_boundary": "IDE and CLI behavior checks remain separate from file installation checks", + "committed": false, + "full_tests": "309 passed, 78 subtests passed", + "git_diff_check": "passed", + "isolated_cursor_install": "Plugin, Rule, Skills, payload and Hooks passed Doctor", + "merged": false, + "pushed": false, + "python_syntax": "54 files parsed", + "release_sync_replay": "four source templates updated to one version", + "released": false, + "scope": "Cursor release version sync and public installation text", + "shell_syntax": "passed", + "support_tier": "BASELINE_SUPPORTED", + "svg_xml": "passed", + "targeted_tests": "33 passed", + "version_consistency": "passed" + }, + "provenance": { + "host": "codex", + "plan_id": "20260819_cursor_support", + "plan_version": "sha256:1e7865f1abbe2479326ccbd15de8741058050dd4e232ea700ad2c39939e93701", + "receipt_id": "verify_006", + "reviewer": "codex_release_preflight", + "source": "final_worktree_commands_and_file_review" + }, + "timestamp": "2026-08-22T05:37:02+00:00", + "verdict": "release_preflight_passed" +} diff --git a/.sopify/plan/20260819_cursor_support/receipts/verify_007.json b/.sopify/plan/20260819_cursor_support/receipts/verify_007.json new file mode 100644 index 00000000..0536eff8 --- /dev/null +++ b/.sopify/plan/20260819_cursor_support/receipts/verify_007.json @@ -0,0 +1,33 @@ +{ + "evidence": { + "behavior_boundary": "IDE and CLI behavior checks remain separate from file installation checks", + "committed": false, + "full_tests": "311 passed, 78 subtests passed", + "git_diff_check": "passed", + "isolated_cursor_install": "Plugin, Rule, Skills, payload and Hooks passed Doctor", + "merged": false, + "pages_content": "Cursor appears in both language host lists, install support text and FAQ", + "pages_visual_check": "desktop home and Chinese mobile layouts rendered with existing styles", + "pushed": false, + "python_syntax": "54 files parsed", + "release_sync_replay": "four source templates updated to one version", + "released": false, + "scope": "Cursor release candidate including GitHub Pages", + "shell_syntax": "passed", + "static_page_tests": "20 passed", + "support_tier": "BASELINE_SUPPORTED", + "svg_xml": "passed", + "targeted_release_tests": "33 passed", + "version_consistency": "passed" + }, + "provenance": { + "host": "codex", + "plan_id": "20260819_cursor_support", + "plan_version": "sha256:2df4073325e3cf657226230f58b37479028d74375becc9a4d625ec5d34c4fb53", + "receipt_id": "verify_007", + "reviewer": "codex_release_candidate", + "source": "final_worktree_commands_file_review_and_local_browser_render" + }, + "timestamp": "2026-08-22T05:46:06+00:00", + "verdict": "release_candidate_passed" +} diff --git a/.sopify/plan/20260819_cursor_support/tasks.md b/.sopify/plan/20260819_cursor_support/tasks.md new file mode 100644 index 00000000..90352a13 --- /dev/null +++ b/.sopify/plan/20260819_cursor_support/tasks.md @@ -0,0 +1,77 @@ +# 任务清单: Sopify Cursor 宿主支持 + +目录: `.sopify/plan/20260819_cursor_support/` + +## 1. 用户级 Plugin 入口 + +- [x] 1.1 将 Cursor adapter 从项目 Rule 安装面调整为 Cursor-specific 用户 Plugin 安装面；移除 `--workspace` 必需条件，不影响其他 host 的 instruction surface。 + - 产物：Cursor registration/capability 与最小安装路径。 + - 验收：`--target cursor` 在未传 workspace 时可安装；Codex、Claude、Qoder、Copilot adapter 测试不变。 +- [x] 1.2 增加 `.cursor-plugin/plugin.json`、渐进式双语 `README.md` 与单一 `rules/sopify.mdc` 资产，由现有双语权威内容生成/安装到 `~/.cursor/plugins/local/sopify/`。 + - 产物：用户级 Plugin manifest、用户可见简介与薄 Always Rule。 + - 验收：Rule 有合法 frontmatter、意图分类、精确 Skill 路由、Analyze 评分门、按当前会话能力使用 AskQuestion 并安全回退、四步入口和 writer-only 边界；Plugin 不含 Commands、Agents、MCP、Hooks 或私有 Skills 树。 +- [x] 1.3 删除项目 `.cursor/rules/sopify.mdc` 的产品安装路径、双语项目 Rule 模板及本仓库临时规则；不建立 fallback 或兼容探测层。 + - 依赖：1.2 的隔离安装测试完成；最终删除受 5.2 CLI 发布门约束。 + - 验收：新安装不会写目标仓库 `.cursor/`；仓库不需要逐个安装 Sopify Rule。 + +## 2. 安装、状态与 Doctor + +- [x] 2.1 调整 Cursor 安装流程：先预检已有 `~/.cursor/hooks.json`，再以同一次安装写 Plugin、全局五项 Skills/shared references、payload/helper 与用户级 Hooks。 + - 验收：非法 hooks JSON 时在首次产品写入前停止且原文件不变；重复安装幂等；不修改 `settings.json`、代理、模型、账号、API Key、钥匙串或 MCP。 +- [x] 2.2 将 Cursor 安装结果、CLI help、distribution 文案从“项目规则落点”改为“用户级 Plugin + 全局资产”；移除 Cursor 的 workspace/bootstrap 暗示。 + - 验收：中英文输出只声明文件安装事实，先提示 Reload/Restart，再提示在 Cursor Customize 中确认 Rule 为 Always；不声称 IDE/CLI 已执行。 +- [x] 2.3 将 Doctor/status 的 `project_rule_present` 改为 Cursor Plugin/Rule 安装检查，并继续独立检查 Skill 树、payload、Hooks、IDE/CLI behavior。 + - 验收：仅有 Cursor IDE settings 时 host 为 absent/skip；缺 Plugin Rule、Skill、payload 或 Hooks 时准确失败；行为项仍为 `BLACK_BOX_NOT_VERIFIED`，不因安装完整自动通过。 + +## 3. 复用用户级 Hooks + +- [x] 3.1 移除 Hook helper 对项目 `.cursor/rules/sopify.mdc` 的依赖；按事件选择 `.sopify/` managed root：文件工具看目标路径，Shell 看 `cwd`，sessionStart 看唯一候选 workspace。 + - 验收：无 `.sopify/` 的普通仓库 no-op；父目录包含多个 Git 仓时不默认取第一个；目标明确落在某个子仓时只保护该仓。 +- [x] 3.2 保持 sessionStart 非恢复语义，只有 active plan 指针、对应语义文件和匹配 handoff 有效时才注入事实；目录存在、残留 state 或多根歧义均不注入方案动作。 + - 验收：consult 不因快照自动 continue；handoff plan_id 不匹配时 action 为 none；latest receipt 仍按协议 timestamp/fallback 选择。 +- [x] 3.3 保持现有 `preToolUse` 与 `beforeShellExecution` 最小写保护、`sopify_writer` 放行和 fail-open 行为，不新增 Hook 类型或完整 Shell parser。 + - 验收：Write/StrReplace 与明显 Shell 重定向不能直写 state/handoff/receipt；`plan.md` 与正常 writer API 调用放行；helper 异常由 Doctor 报告但不阻塞 Cursor。 + +## 4. 契约、文档与回归 + +- [x] 4.1 更新 Cursor capability、registry/catalog、README、`docs/cursor-host.md`、install.sh/install.ps1 帮助和 distribution 文案，统一描述“用户级 Plugin 唯一语义入口 + 全局 Skills/payload + 用户 Hooks”。 + - 验收：不再出现每仓安装项目 Rule、Plugin 已等价覆盖 CLI、文件存在等于行为通过等过强口径。 + - 视觉同步：README 顶部 badge、架构图和中英文产品形态图已加入 Cursor baseline；具体场景图保持示例语义，不扩写为宿主矩阵。 + - 独立视觉/文档复审：修复 Cursor 用户级安装后的 Verify Setup 断点、badge 导航和顶部跨宿主过强口径后返回 `accept`；P0/P1/P2 均无。 +- [x] 4.2 同步 `.sopify/blueprint/` 中受影响的宿主架构与任务索引，不扩写与 Cursor 无关的协议内容。 + - 验收：长期文档与本方案在入口、Hook 边界、支持档位和证据门上无冲突。 +- [x] 4.3 补 installer、distribution、Doctor、Plugin 资产与 Hook root-selection 测试，并重跑相关定向测试和全量 `python3 -m pytest tests -q`。 + - 验收：全量通过，`git diff --check` 与 Python compile 检查通过；其他四个 host 的安装快照与行为不变。 + +## 5. 黑盒与交付 + +- [x] 5.1 在隔离 home 安装 Cursor，证明 Plugin manifest/Rule、Skills、payload、helper、Hooks 路径正确，目标仓库没有 `.cursor/rules/sopify.mdc`，Cursor settings 与代理相关文件哈希不变。 +- [-] 5.2 在不含项目 `.mdc` 的临时仓库运行真实 Cursor Agent CLI 自动入口验收。 + - 原自动入口判据：观察全局 Plugin 是否生效，以及 consult、Analyze 与 Hooks 的工具轨迹和文件哈希；该能力现已明确不在产品承诺内。 + - 2026-08-20 自动入口实测失败：session `4c24eab4-dd82-46f3-8fd7-67888baa1a53` 未加载用户 Plugin Rule，实际读取 `~/.claude/skills/sopify/kb/SKILL.md` 并在 consult 中读取 active plan/handoff/receipt；三份 machine truth 哈希未变。 + - 2026-08-20 纯 launcher 前置门失败：显式 `--plugin-dir ~/.cursor/plugins/local/sopify` 的 session `7626c137-9668-450f-ab00-a44619f90f9c` 未读取 Cursor shared-writing-dna，仍读取旧 `~/.claude/skills/sopify/develop/SKILL.md` 与 managed plan/state；唯一标记 Cursor Plugin 探针 session `109d2991-78e6-46d8-a19a-5bd86f3198f0` 未读取 marker 且直接回复 `OK`。依据“验证后实施”决策，不增加无效 launcher。 + - 产品收口：用户接受 IDE/CLI 能力不对称；CLI 低频使用时手工调用已安装 Skill，不承诺自动 Plugin Rule，本自动入口任务按范围取消。 +- [x] 5.3 经用户授权安装到真实 `~/.cursor`，在 Cursor IDE 单独验证 Customize 中 Rule 为 Always、consult/analyze 路由与 direct-write deny；CLI 证据不得外推 IDE。 + - 真实安装与 2026-08-20 重装已完成；settings、CLI config、hooks 与代理哈希安装前后不变。Plugin 可见已通过；Local 详情页不渲染 description/README 的宿主限制已由用户接受，不再作为行为门。 + - 2026-08-20 首轮 Rule 复验失败：Customize Rules 为空，日志显示 Plugin `ruleCount: 0`，相关回答由 Agent 主动读取 Rule 后产生。已删除 manifest 的显式 `rules` 字段、保留 `rules/sopify.mdc` 目录自动发现并完成回归与真实重装；等待 Reload 后复验，不增加 fallback。 + - 2026-08-20 Reload 复验通过：Customize 在 User 范围显示 `sopify`，打开后真实文件为 `rules/sopify.mdc` 且为 Always Apply；多个最新窗口日志中的 Cursor Plugin 服务均为 `ruleCount: 1`。这关闭注册门，不外推 consult/Analyze 行为。 + - 2026-08-20 consult 会话 `067ce461-c667-46fb-88ce-bffe4c4362a1` 只读取 Cursor shared-writing-dna 和只读 Git 状态；Analyze 会话 `7101b90b-ce5d-4acb-8fc3-930056f95e68` 读取精确 Cursor Skill 并运行评分脚本得到 `3/10, pass=false`，两轮均无写入。 + - 2026-08-20 原位切换 `cursor:zh-CN` 后只有一个 Plugin 根和一个 Skill 根，英文阶段模板无残留；保护配置与系统代理不变。`sessionStart` 只保留自动化与既有补充线索，不把模型转述升级为独立行为通过。 + - 2026-08-20 AskQuestion baseline 证据完成：会话 `84e9fa01-c2dc-4db5-9611-0f15c120bcb8` 保留 AskQuestion tool use 与 `Tool not found` 回退。UI 卡片属于人工观察，transcript 不含 tool result 或选项回传；本期不承诺每个模型/会话都提供。 + - 2026-08-22 managed 黑盒完成：临时仓库 `/private/tmp/sopify-cursor-managed-blackbox.WRxVtd` 的 session `2448476f-57b8-4e1d-a522-c19e8202d658` 完成 Analyze → Design → 停车 → Develop，业务文件精确变更，state/handoff/receipt 只经 writer 写入；直接 Shell 改写 active plan 被 Hook 拒绝且哈希不变，未 finalize/commit。 +- [x] 5.4 更新现有独立审计包，交 Cursor 只读复审；通过 `sopify_writer` 追加新的 verify receipt，不覆盖历史 receipt。 + - 前置 IDE baseline 证据已齐：Rule/consult/Analyze/AskQuestion/managed develop/writer/Hook 分别保留工具轨迹或文件结果；模型自述不单独计证据。 + - 2026-08-22 最终候选验证：308 passed / 78 subtests，Python compileall、`bash -n install.sh` 与 `git diff --check` 均通过。 + - 最终复审返回 `accept`，P0/P1 无。其三个 P2 已以真实安装与候选对齐、AskQuestion 口径降级和 UI/文件证据分层关闭；后续独立审计的两处术语修正由 `verify_005` 绑定最终方案版本。 +- [x] 5.5 保持 `BASELINE_SUPPORTED`，清楚记录自动化、CLI、IDE 各自证据与缺口。 + - 独立 sessionStart、显式 finalize、AskQuestion 跨模型稳定性、CLI 自动 Plugin Rule 与 Cloud Agent 均记录为未验证或不支持边界，不阻塞本次 baseline 收口。 + +## 6. Release 收口修正 + +- [x] 6.1 将双语 Cursor Plugin Rule 的 `SOPIFY_VERSION` 纳入现有 release-sync、版本一致性检查和 pre-commit 回滚/暂存，不新增版本机制。 +- [x] 6.2 将 Cursor 用户文档与宿主矩阵改为显式语言 target，并提供 stable release 一键安装命令。 +- [x] 6.3 运行定向与全量回归，并追加新的 verify receipt，确认当前提交可以进入合并与发布步骤。 + - 结果：定向测试 33 passed；全量测试 311 passed / 78 subtests；Python 语法、Shell 语法、SVG XML 与 `git diff --check` 均通过。 + - 安装检查：隔离 home 中的 Cursor Plugin、Rule、Skills、payload 和 Hooks 均通过 Doctor；IDE/CLI 行为项仍保持未认证，不从文件安装结果外推。 +- [x] 6.4 同步 GitHub Pages 的中英文宿主列表、安装支持范围和 FAQ；复用现有标签与响应式布局，不新增页面结构或样式机制。 + - 结果：双语内容测试 20 passed；桌面首页与中文移动端完成本地浏览器渲染检查，Cursor 标签沿用现有 baseline 样式。 diff --git a/CHANGELOG.md b/CHANGELOG.md index 35204841..13302a2e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,20 @@ Format: Summary → Changed → Plan Packages. File-level details live in `git l ## [Unreleased] +## [2026-08-22.134737] - 2026-08-22 + +### Summary + +Added baseline support for local Cursor IDE without per-project Sopify setup. + +### Changed + +- **Cursor host**: Added a user Plugin entry, global Skills/payload, user Hooks, and matching GitHub Pages content. Local IDE evidence covers routing, planning, writer writes, and direct-write rejection. Agent CLI automatic entry and Cloud Agent remain outside scope. + +### Plan Packages + +- `20260819_cursor_support` → release candidate; explicit archive remains a later `~go finalize` action + ## [2026-07-21] - 2026-07-21 ### Summary diff --git a/README.md b/README.md index ea217fe6..f23f0ac9 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,14 @@ [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge)](./LICENSE) [![Docs](https://img.shields.io/badge/docs-CC%20BY%204.0-green.svg?style=for-the-badge)](./LICENSE-docs) -[![Version](https://img.shields.io/badge/version-2026--07--21-orange.svg?style=for-the-badge)](#version-history) +[![Version](https://img.shields.io/badge/version-2026--08--22.134737-orange.svg?style=for-the-badge)](#version-history) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge)](./CONTRIBUTING.md) [![Codex](https://img.shields.io/badge/host-Codex-4A9EFF.svg?style=for-the-badge)](#quick-start) [![Claude](https://img.shields.io/badge/host-Claude-CC785C.svg?style=for-the-badge)](#quick-start) [![Qoder](https://img.shields.io/badge/host-Qoder-7C3AED.svg?style=for-the-badge)](#quick-start) [![Copilot](https://img.shields.io/badge/host-Copilot-000000.svg?style=for-the-badge)](#quick-start) +[![Cursor](https://img.shields.io/badge/host-Cursor-111827.svg?style=for-the-badge)](./docs/cursor-host.md) English · [简体中文](./README.zh-CN.md) · [Quick Start](#quick-start) · [Contributors](./CONTRIBUTORS.md) @@ -26,14 +27,14 @@ English · [简体中文](./README.zh-CN.md) · [Quick Start](#quick-start) · [ AI coding tools are fast. But when they jump to code before the facts are clear, speed turns into rework. Sopify is a development process protocol layer for AI coding: in managed workflows, the host asks before coding when requirements are incomplete or a decision still needs you. -Sopify stores plans and verification receipts in `.sopify/` as project files tracked by git. Only the local resume pointers stay out of git. In the same repo, explicitly ask to continue or use `~go` to resume managed work from those files on any supported host. +Sopify stores plans and verification receipts in `.sopify/` as project files tracked by git. Only the local resume pointers stay out of git. In the same repo, use the managed entry supported by your current host to resume from those files; entry shape and verification level stay explicit in the host support matrix. -No new editor, no new CLI. Install into the host you already use — Codex, Claude, Qoder, or Copilot. +No new editor, no new CLI. Install into the host you already use — Codex, Claude, Qoder, Copilot, or Cursor. **Design principles:** - **Stop when unsure** — score every requirement; ask before assuming -- **Resume from anywhere** — plans and verification receipts are tracked in `.sopify/`; open the repo on any host and pick up where you left off +- **Resume across managed hosts** — plans and verification receipts are tracked in `.sopify/`; hosts with continuation support can pick up where you left off - **Trace every decision** — plans, choices, and reviews persist in `.sopify/` **What Sopify prevents:** @@ -99,7 +100,7 @@ The host LLM executes. Sopify supplies shared workflow rules and preserves plans Sopify does three things: -- **Shared workflow rules** — supported hosts load the same Sopify workflow rules, so switching hosts does not change the process and boundaries you already confirmed +- **Shared workflow protocol** — each adapter delivers the same protocol through the host surfaces it supports; entry mode and verification level remain explicit - **Git-tracked project record** — plans, decisions, and verification evidence travel with the repository; local pointers do not - **Explicit resume and closeout** — ask to continue or use `~go` before the host resumes; `~go finalize` archives the plan only after delivery evidence is ready @@ -137,8 +138,9 @@ Host support: | Claude | PROTOCOL_VERIFIED | `claude:en-US` / `claude:zh-CN` | Full capability continuation | | Qoder | PROTOCOL_VERIFIED | `qoder` | Validated on Qoder CLI | | Copilot | BASELINE_SUPPORTED | `copilot:en-US` / `copilot:zh-CN` | Prompt-only; payload uplift planned | +| [Cursor](docs/cursor-host.md) | BASELINE_SUPPORTED | `cursor:en-US` / `cursor:zh-CN` | IDE user Plugin + global Skills/payload + user hooks | -Pass `--workspace ` to target another repo, `--language ` to control output language. +Pass `--workspace ` to target another repo for workspace-scope or prewarm installs; Cursor installs once at user scope and does not require it. Use `--language ` to control output language. [EvidentLoop](https://github.com/evidentloop/evidentloop) is an optional code-change audit tool. It turns a local Git diff into an interactive report, ties audit findings to changed diff --git a/README.zh-CN.md b/README.zh-CN.md index 1cee5fa3..bba8fede 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -6,13 +6,14 @@ [![许可证](https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=for-the-badge)](./LICENSE) [![文档](https://img.shields.io/badge/docs-CC%20BY%204.0-green.svg?style=for-the-badge)](./LICENSE-docs) -[![版本](https://img.shields.io/badge/version-2026--07--21-orange.svg?style=for-the-badge)](#版本历史) +[![版本](https://img.shields.io/badge/version-2026--08--22.134737-orange.svg?style=for-the-badge)](#版本历史) [![欢迎PR](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=for-the-badge)](./CONTRIBUTING_CN.md) [![Codex](https://img.shields.io/badge/host-Codex-4A9EFF.svg?style=for-the-badge)](#快速开始) [![Claude](https://img.shields.io/badge/host-Claude-CC785C.svg?style=for-the-badge)](#快速开始) [![Qoder](https://img.shields.io/badge/host-Qoder-7C3AED.svg?style=for-the-badge)](#快速开始) [![Copilot](https://img.shields.io/badge/host-Copilot-000000.svg?style=for-the-badge)](#快速开始) +[![Cursor](https://img.shields.io/badge/host-Cursor-111827.svg?style=for-the-badge)](./docs/cursor-host.md) [English](./README.md) · 简体中文 · [快速开始](#快速开始) · [贡献者](./CONTRIBUTORS.md) @@ -26,14 +27,14 @@ AI 工具写代码很快。但在事实没搞清、关键决策还没拍板前就直接动手，快就会变成返工。Sopify 是 AI 编程的开发过程协议层：在托管流程里，需求不全或决策未定时，宿主会先追问，再写代码。 -Sopify 把方案和验证收据保存在 `.sopify/` 中，作为可纳入 git 的项目文件；只有恢复用的本地指针不进 git。在同一个仓库中，明确说“继续”或使用 `~go`，任一受支持的宿主都可以读取这些文件，从上次停点恢复托管任务。 +Sopify 把方案和验证收据保存在 `.sopify/` 中，作为可纳入 git 的项目文件；只有恢复用的本地指针不进 git。在同一个仓库中，通过当前宿主已支持的托管入口从这些文件接续；具体入口与验证档位以宿主支持矩阵为准。 -无需新编辑器、无需新 CLI。安装到你已有的宿主：Codex、Claude、Qoder、Copilot 均支持。 +无需新编辑器、无需新 CLI。安装到你已有的宿主：Codex、Claude、Qoder、Copilot、Cursor 均支持。 **设计原则：** - **不确定就停下** — 需求不全时先追问，再动手 -- **随时恢复** — 方案和验证收据都持久保存在 `.sopify/` 里；换宿主、换机器、换人接手都能从项目状态继续 +- **跨托管宿主恢复** — 方案和验证收据都持久保存在 `.sopify/` 里；支持接续的宿主可从项目状态继续 - **决策留痕** — 方案、取舍、审查持久保存在 `.sopify/` **Sopify 主要在防什么：** @@ -98,7 +99,7 @@ Sopify 需要 Python 3.11 或更高版本；安装器会在下载前检查。这 Sopify 主要做三件事： -- **共享工作流规则** — 支持的宿主加载同一套 Sopify 工作流规则，换宿主也不会改变已经确认的流程和边界 +- **共享工作流协议** — 各适配器通过宿主已支持的入口交付同一协议；入口形态与验证档位保持显式 - **项目记录随 Git 携带** — 方案、决策和验证证据跟着仓库走，本地指针不跟随 - **明确接续与收口** — 说“继续”或输入 `~go` 后，宿主才会恢复；交付证据就绪后，`~go finalize` 才归档方案 @@ -136,8 +137,9 @@ Get-Content sopify-install.ps1 | more | Claude | PROTOCOL_VERIFIED | `claude:zh-CN` / `claude:en-US` | 全能力接续 | | Qoder | PROTOCOL_VERIFIED | `qoder` | 已在 Qoder CLI 验证 | | Copilot | BASELINE_SUPPORTED | `copilot:zh-CN` / `copilot:en-US` | 仅 prompt；payload 升级计划中 | +| [Cursor](docs/cursor-host.md) | BASELINE_SUPPORTED | `cursor:zh-CN` / `cursor:en-US` | IDE 用户 Plugin + 全局 Skills/payload + 用户 Hooks | -可用 `--workspace ` 指定目标仓库，`--language ` 控制输出语言。 +可用 `--workspace ` 指定目标仓库，`--language ` 控制输出语言；Cursor 为用户级一次安装，不需要 `--workspace`。 [EvidentLoop](https://github.com/evidentloop/evidentloop) 是一个可选的代码变更审计工具， 可基于本地 Git diff 生成交互式报告，将审计发现定位到具体修改行，并支持用户通过反馈 diff --git a/assets/sopify-architecture.svg b/assets/sopify-architecture.svg index 3689b3ff..4cebe173 100644 --- a/assets/sopify-architecture.svg +++ b/assets/sopify-architecture.svg @@ -30,24 +30,28 @@ HOST LAYER Host LLM executes code; Sopify preserves the process as files - - - Codex + + + Codex - - - Claude + + + Claude - - - Qoder + + + Qoder - - - Copilot + + + Copilot - - Other adapters + + + Cursor + + + Other adapters @@ -163,5 +167,5 @@ Convention mode only — host self-drives, writer validates - Sopify · 2026-06 + Sopify · 2026-08 diff --git a/assets/sopify-product-form-release-en.svg b/assets/sopify-product-form-release-en.svg index 885bb288..720a9b39 100644 --- a/assets/sopify-product-form-release-en.svg +++ b/assets/sopify-product-form-release-en.svg @@ -40,9 +40,9 @@ I HOST User asks in a supported host - One protocol, four entry points + One protocol, five host adapters - + @@ -68,12 +68,19 @@ verified - Same .sopify/ project - Supported hosts load the same rules - Project records stay consistent + + + + Cursor + baseline + + + Same .sopify/ project + Supported hosts consume one protocol + Project records stay consistent - ~go - · user starts the work + request + · user starts the work @@ -241,5 +248,5 @@ baseline - Sopify · 2026-06 + Sopify · 2026-08 diff --git a/assets/sopify-product-form-release.svg b/assets/sopify-product-form-release.svg index 7ccc59f6..f39e803c 100644 --- a/assets/sopify-product-form-release.svg +++ b/assets/sopify-product-form-release.svg @@ -40,9 +40,9 @@ I HOST 用户在受支持宿主提需求 - 同一协议，四个入口 + 同一协议，五个宿主适配 - + @@ -68,12 +68,19 @@ verified - 同一 .sopify/ 项目 - 受支持宿主加载同一套规则 - 项目记录保持一致 + + + + Cursor + baseline + + + 同一 .sopify/ 项目 + 受支持宿主消费同一协议 + 项目记录保持一致 - ~go - · 用户发出请求 + request + · 用户发出请求 @@ -241,5 +248,5 @@ baseline supported - Sopify · 2026-06 + Sopify · 2026-08 diff --git a/docs/cursor-host.md b/docs/cursor-host.md new file mode 100644 index 00000000..5cde51ff --- /dev/null +++ b/docs/cursor-host.md @@ -0,0 +1,69 @@ +# Cursor 宿主接入 + +主要支持本地 Cursor IDE。Cursor Agent CLI 不提供自动 Plugin Rule 入口，Cloud Agent 不在本期范围。支持档位保持 `BASELINE_SUPPORTED`。真实 IDE 已观察到 Plugin Rule 路由、Analyze 评分、AskQuestion 调用尝试与文本回退、managed develop、writer 写回和 Hook 拒绝明显直写；这些证据不代表跨模型稳定性或完整协议认证。本期不为 CLI 增加 launcher、项目 Rule 或 runtime。 + +## 安装面 + +```bash +curl -fsSL https://github.com/evidentloop/sopify/releases/latest/download/install.sh | bash -s -- --target cursor:zh-CN +``` + +首次安装或更新本地 Plugin 后，重启 Cursor，或执行 `Developer: Reload Window`，再检查 Plugin 与 Rule。Cursor 官方将 reload/restart 作为 `~/.cursor/plugins/local` 本地测试流程的一部分。 + +安装一次，管理四个用户级落点： + +- Plugin：`~/.cursor/plugins/local/sopify/.cursor-plugin/plugin.json`、`README.md` 与 `rules/sopify.mdc`。README 渐进介绍用途与边界；薄 Always Rule 是 IDE 的语义入口。 +- Skills：`~/.cursor/skills/sopify/` 下的 `analyze`、`design`、`develop`、`kb`、`templates` 和共享 references。 +- Payload：`~/.cursor/sopify/`，包含版本化 bundle 与 Hook helper。 +- Hooks：合并到 `~/.cursor/hooks.json`；不写仓库级 hooks。 + +Cursor 不需要 `--workspace`，安装器不在目标仓库创建 `.cursor/rules/sopify.mdc` 或预热 `.sopify`。它也不创建或修改 Cursor 的 `settings.json`、代理、模型、账号、API Key、钥匙串或 MCP。兼容目录中的同名 Skills 不作为安装成功依据；Rule 明确路由到 `~/.cursor/skills/sopify`。 + +`--with-evidentloop` 对 Cursor 当前版本 fail closed。 + +## 语义与 Hook 边界 + +IDE Plugin Rule 负责意图分类与 Skill 路由： + +- `consult_readonly` 直接只读回答，不自动恢复 active plan； +- `quick_fix` 可修改用户授权的产品代码，但不直接写协议 state、handoff、receipt 或知识库； +- `new_plan`、`continue_plan`、`finalize` 和明确的 managed develop 才进入对应 Skill 与四步协议入口； +- Analyze 必须实际执行 Skill 中的评分脚本，machine truth 只经 `sopify_writer` 库 API 写入。 + +用户级 Hooks 只补确定性边界，不做意图分类： + +- `.sopify/` 是 managed-root 信号；没有该目录时文件与 Shell guard no-op。 +- `sessionStart` 只在唯一 managed root 且 active plan 方案包有效时注入事实；多根不唯一或状态无效时不猜测。 +- `preToolUse` 按文件目标路径拒绝明显直接写入 `active_plan.json`、`current_handoff.json` 与 `plan/*/receipts/*.json`。 +- `beforeShellExecution` 只在 `cwd` 所属 managed root 中拒绝同类明显直接写入；`plan.md`、`tasks.md`、`design.md` 和业务代码不在保护范围。 +- helper 缺失或异常 fail-open，由 Doctor 报告；这不是完整 Shell parser 或安全沙箱。 + +## Doctor 语义 + +```bash +python3 scripts/sopify_doctor.py --format json --home-root "$HOME" +``` + +Cursor 分开报告： + +- `cursor_plugin_present`：Plugin manifest 与 Rule 是否存在；README 是包内说明，不作为行为或安装健康硬门槛； +- `global_skill_tree_present`：五项 Skills、共享写作/输出契约与 Analyze 评分脚本是否存在； +- `payload_present`：payload/bundle 是否结构完整； +- `cursor_hooks_present`：用户 hooks 与 helper 是否安全、完整； +- `cursor_ide_behavior`、`cursor_cli_behavior`：真实宿主黑盒，默认 `skip (BLACK_BOX_NOT_VERIFIED)`。 + +缺席判定只看 Sopify 自有落点，不把整个 `~/.cursor` 或现有 IDE settings 当成已安装。文件检查通过不代表 Cursor 已遵循工作流。 + +## IDE / CLI 证据边界 + +IDE 与 CLI 分开记录，不互相外推： + +1. IDE baseline 已有可观察证据：已安装 Rule 含 `alwaysApply: true`，consult 实际读取 Cursor 写作规范并保持只读；Analyze 读取 Cursor Skill 并执行评分脚本；有限选项澄清留下 AskQuestion tool use 与 `Tool not found` 文本回退，结构化问卷 UI 仅作为人工观察，transcript 不含 tool result 或选项回传；managed 场景按 Analyze → Design → Develop 推进，经 `sopify_writer` 写 state、handoff 与 receipts；明显 Shell 直写 machine truth 被 Hook 拒绝且文件哈希不变。 +2. IDE 未验证边界：AskQuestion 是否跨模型稳定提供、独立 `sessionStart` 行为与显式 finalize。本期依赖文本追问回退和现有协议边界，不把这些项目作为 baseline 发布阻塞。 +3. CLI 未验证自动语义入口。CLI 的结果不能用于证明 IDE 行为，IDE 的结果也不能用于证明 CLI 行为。 + +Cursor 官方 CLI 文档明确项目 Rules，但没有把用户 Plugin Rule 写成 CLI 加载契约。2026-08-20 的真实会话也未读取 Cursor Plugin Rule 指定的共享规范，显式 `--plugin-dir` 唯一标记探针同样未生效。因此 CLI 自动入口明确不支持，也不阻塞本次 IDE baseline 发布。 + +一次临时仓库黑盒已观察到四步读链、managed develop 与 `sopify_writer` 写回；显式 finalize 仍按用户命令触发，未纳入本次 baseline 黑盒。Doctor 的行为项继续保持静态 `BLACK_BOX_NOT_VERIFIED`，不把某台机器上的临时 transcript 写成可移植产品认证。 + +官方依据：[`Cursor Plugins`](https://cursor.com/docs/plugins)、[`Plugin format`](https://cursor.com/docs/reference/plugins)、[`Cursor Rules`](https://cursor.com/docs/rules)、[`Cursor Agent Skills`](https://cursor.com/docs/skills)、[`Cursor Hooks`](https://cursor.com/docs/hooks)、[`Cursor CLI`](https://cursor.com/docs/cli/using)。 diff --git a/docs/dev/release-process.md b/docs/dev/release-process.md index 197a4a66..3725a449 100644 --- a/docs/dev/release-process.md +++ b/docs/dev/release-process.md @@ -55,11 +55,13 @@ bash scripts/check-version-consistency.sh version-2026--03--26.103000-orange.svg ``` -**两个源模板顶部注释**： +**四个发布版本源文件顶部注释**： ``` skills/zh/header.md.template → skills/en/header.md.template +skills/zh/cursor-plugin-rule.mdc.template +skills/en/cursor-plugin-rule.mdc.template ``` 更新后验证： @@ -74,7 +76,8 @@ bash scripts/check-version-consistency.sh ```bash TAG="2026-03-26.103000" git add CHANGELOG.md README.md README.zh-CN.md \ - skills/zh/header.md.template skills/en/header.md.template + skills/zh/header.md.template skills/en/header.md.template \ + skills/zh/cursor-plugin-rule.mdc.template skills/en/cursor-plugin-rule.mdc.template git commit -m "release: $TAG" git push ``` @@ -120,6 +123,10 @@ grep "SourceChannel\|SourceRef" "$OUT_DIR/install.ps1" # 快速验证（推荐） HOME="$(mktemp -d)" bash -c \ 'curl -fsSL https://github.com/evidentloop/sopify/releases/latest/download/install.sh | bash -s -- --target codex:zh-CN' + +# 本次 release 包含 Cursor 变更时，再验证 Cursor +HOME="$(mktemp -d)" bash -c \ + 'curl -fsSL https://github.com/evidentloop/sopify/releases/latest/download/install.sh | bash -s -- --target cursor:zh-CN' ``` 或用 smoke 脚本： diff --git a/docs/getting-started.md b/docs/getting-started.md index c11efb07..eac68a88 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -15,7 +15,7 @@ Sopify adds resumable, traceable AI workflows to any project. After setup: - Git repository (local or remote) - Python 3.11+ -- An AI host: Codex, Claude, Qoder, or Copilot +- An AI host: Codex, Claude, Qoder, Copilot, or Cursor ## Quick Setup (One Command) @@ -139,9 +139,44 @@ Copilot reads project-level instruction files across its supported surfaces Full trigger wiring (equivalent to Codex/Claude `~go`) is coming in a future release. +### Cursor IDE (optional Agent CLI) + +Cursor IDE uses one user-level Plugin rule. The same installation provides a +global Skill/payload tree under `~/.cursor/` and user-level hooks in +`~/.cursor/hooks.json`: + +```bash +curl -fsSL https://github.com/evidentloop/sopify/releases/latest/download/install.sh | bash -s -- --target cursor:en-US +``` + +After the first install or any local Plugin update, restart Cursor or run +`Developer: Reload Window` before checking the Plugin and its Rule. + +`--workspace` is not required and no project Rule or `.sopify` state is +created during install. `--with-evidentloop` is not supported for Cursor in +this release. The Plugin Rule uses valid `.mdc` frontmatter with +`alwaysApply: true` and routes to `~/.cursor/skills/sopify`. + +The tested Agent CLI does not automatically load this user Plugin Rule. +Automatic entry for Agent CLI and Cloud Agent is outside this release. No +launcher, project Rule, prompt injector, or runtime is added. See +[Cursor host acceptance](./cursor-host.md). The current tier remains +`BASELINE_SUPPORTED`. + ## Verify Setup -After bootstrap, check the workspace marker: +Cursor installs at user scope and intentionally does not create a workspace +marker. From the Sopify checkout, verify its install surface with: + +```bash +python3 scripts/sopify_doctor.py --format json --home-root "$HOME" +``` + +After reloading Cursor, also confirm that the user-scope Sopify Plugin rule +appears under Customize > Rules with mode Always. These checks prove +installation and Plugin rule registration, not model behavior. + +For a separately bootstrapped workspace, check its marker with: ```bash cat .sopify/sopify.json diff --git a/docs/how-sopify-works.en.md b/docs/how-sopify-works.en.md index b308443e..eb20d543 100644 --- a/docs/how-sopify-works.en.md +++ b/docs/how-sopify-works.en.md @@ -16,7 +16,7 @@ Official reference: [`Harness engineering: leveraging Codex in an agent-first wo Sopify preserves the **process** of AI development — plans, decisions, handoffs, execution evidence, and archival records — as traceable assets. Cross-session and cross-host continuation is the natural result of these assets being portable and verifiable. -The host (Codex, Claude, Qoder, Copilot) executes. Sopify ensures every decision leaves a trace that survives session boundaries, host switches, and team handoffs. +The host (Codex, Claude, Qoder, Copilot, or Cursor) executes. Sopify ensures every decision leaves a trace that survives session boundaries, host switches, and team handoffs. **Runtime retired; workflow retained.** The analyze → design → develop → finalize workflow is unchanged. What changed is that workflow rules now live in protocol files and host prompt assets, not in a runtime process. @@ -109,6 +109,7 @@ Layer notes: | Claude | PROTOCOL_VERIFIED | `install.sh --target claude:en-US` | Full capability continuation | | Qoder | PROTOCOL_VERIFIED | `install.sh --target qoder` | Validated on Qoder CLI | | Copilot | BASELINE_SUPPORTED | `install.sh --target copilot` | Prompt-only; payload uplift planned | +| Cursor | BASELINE_SUPPORTED | `install.sh --target cursor:en-US` | IDE user Plugin + global Skills/payload + user hooks | ## Appendix: Plan Lifecycle diff --git a/docs/how-sopify-works.md b/docs/how-sopify-works.md index 20d1435e..337376d2 100644 --- a/docs/how-sopify-works.md +++ b/docs/how-sopify-works.md @@ -16,7 +16,7 @@ Sopify 借鉴 harness engineering 的设计思路，但不把它作为仓库首 Sopify 把 AI 开发过程中的**方案、决策、交接、执行/验证证据和归档记录**沉淀为可追溯资产。跨 session、跨宿主的接续是这些资产可携带、可验证后的自然结果。 -宿主（Codex、Claude、Qoder、Copilot）负责执行。Sopify 确保每个决策都留下痕迹，且这些痕迹能跨越 session 边界、宿主切换和团队交接。 +宿主（Codex、Claude、Qoder、Copilot、Cursor）负责执行。Sopify 确保每个决策都留下痕迹，且这些痕迹能跨越 session 边界、宿主切换和团队交接。 **Runtime 已退场；工作流保留。** analyze → design → develop → finalize 的默认工作流不变。变化的是：工作流规则现在活在协议文件和宿主 prompt 资产里，而不是 runtime 进程里。 @@ -109,6 +109,7 @@ Sopify 不默认安装或运行验证器。只用 Sopify、使用其他 Verifier | Claude | PROTOCOL_VERIFIED | `install.sh --target claude:zh-CN` | 全能力接续 | | Qoder | PROTOCOL_VERIFIED | `install.sh --target qoder` | 已在 Qoder CLI 验证 | | Copilot | BASELINE_SUPPORTED | `install.sh --target copilot` | 仅 prompt；payload 升级计划中 | +| Cursor | BASELINE_SUPPORTED | `install.sh --target cursor:zh-CN` | IDE 用户 Plugin + 全局 Skills/payload + 用户 Hooks | ## 附录：Plan 生命周期 diff --git a/index.html b/index.html index d30e065b..a0a66d92 100644 --- a/index.html +++ b/index.html @@ -64,7 +64,7 @@

Resumable, traceable AI coding

Install Sopify View on GitHub -

No new editor. No new CLI. Start with ~go in the host you already use.

+

No new editor. No new CLI. Install into the host you already use and follow its documented entry.

@@ -155,8 +155,8 @@

The host executes. Sopify keeps the work resumable

preserves plans, decisions, and verification evidence as project files in .sopify/.

- Ask to continue or run ~go in a supported host to resume an unfinished plan. A local handoff pointer - provides a same-workspace resume hint. + Ask to continue or use the managed entry supported by the current host to resume an unfinished plan. A + local handoff pointer provides a same-workspace resume hint.

.sopify/plan/…
    @@ -164,6 +164,7 @@

    The host executes. Sopify keeps the work resumable

  • Claude · verified
  • Qoder · verified
  • Copilot · baseline
    • +
  • Cursor · baseline
Add Sopify to the host you already use