fix(installer): detect same-metadata content updates

Publish req-prd and req-prototype 2.2.0.

.claude-plugin/marketplace.json

@@ -401,6 +401,19 @@
       ],
       "strict": false
     },
+    {
+      "name": "slark-cicd-plugin",
+      "source": "./skills-dev/slark-cicd-plugin",
+      "description": "Slark 仓库 staging、生产与 Desktop 安装包的端到端 CI/CD 发布技能。",
+      "version": "1.0.0",
+      "category": "devops",
+      "keywords": [
+        "devops",
+        "deployment",
+        "operations"
+      ],
+      "strict": false
+    },
     {
       "name": "req-audit-plugin",
       "source": "./skills-req/req-audit-plugin",
@@ -482,8 +495,8 @@
     {
       "name": "req-prd-plugin",
       "source": "./skills-req/req-prd-plugin",
-      "description": "产品需求设计技能。覆盖问答访谈、PRD、缺陷收敛及 HTML 原型验证闭环。纯产品视角，不含技术实现。",
-      "version": "2.1.0",
+      "description": "产品需求设计技能。覆盖问答、PRD、缺陷与 OSS 原型闭环，文档双写本地和 ai-proj。",
+      "version": "2.2.0",
       "category": "productivity",
       "keywords": [
         "project-management",
@@ -495,8 +508,8 @@
     {
       "name": "req-prototype-plugin",
       "source": "./skills-req/req-prototype-plugin",
-      "description": "原型生成与关联。支持 HTML 正式交付、Requirement 关联、iframe 验证闭环及 Stitch AI 视觉探索。",
-      "version": "2.1.0",
+      "description": "原型生成与关联。支持 HTML 本地留源、OSS 正式交付、Requirement/iframe 验证及 Stitch AI。",
+      "version": "2.2.0",
       "category": "productivity",
       "keywords": [
         "project-management",

generate-marketplace.py

@@ -60,7 +60,7 @@ def load_config():
 def get_category_and_keywords(plugin_name):
     if any(x in plugin_name for x in ['dev-', 'coding', 'frontend']):
         return "development", ["development", "coding", "workflow"]
-    elif any(x in plugin_name for x in ['ops-', 'deploy', 'server']):
+    elif any(x in plugin_name for x in ['ops-', 'deploy', 'server', 'slark-cicd']):
         return "devops", ["devops", "deployment", "operations"]
     elif any(x in plugin_name for x in ['ai-proj', 'req']):
         return "productivity", ["project-management", "tasks", "requirements"]

install-skills.sh

@@ -365,7 +365,7 @@ install_plugin() {
     else
       mkdir -p "$dst_dir"
       # rsync resolved source (handles nested skills/ structures)
-      rsync -a --delete "$src_dir/" "$dst_dir/"
+      rsync -a --checksum --delete "$src_dir/" "$dst_dir/"
       state_set "$install_name" "$version" "$effective_install_type" "$source_digest"
       ok "$install_name → skill (v$version)"
       INSTALL_ACTION=true

skills-dev/slark-cicd-plugin/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "slark-cicd-plugin",
+  "description": "Slark 仓库 staging、生产与 Desktop 安装包的端到端 CI/CD 发布技能。",
+  "version": "1.0.0",
+  "author": {
+    "name": "qiudl"
+  },
+  "install_name": "slark-cicd",
+  "install_type": "skill",
+  "dir_category": "dev"
+}

skills-dev/slark-cicd-plugin/skills/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: slark-cicd
+description: Slark 仓库 staging、生产和 Desktop 安装包的端到端 CI/CD 可执行 runbook。覆盖本地预推快检、PR 与内网 ci/internal-gate 门禁、合并 origin/main、staging 真机预验、审批式生产发布，以及在 m5max 构建签名、公证并上传 macOS/Windows Desktop 包到 OSS。当用户要在 slark（qiudl/qiu-slark）里发布/上线、部署到生产或 staging、发布 Desktop 安装包、盯 CI/合并 PR、复现或验证运行时行为、或排查发布链/推送路由问题时使用。
+---
+
+# Slark CI/CD runbook
+
+驱动 Slark 从改代码到上线的端到端流程。权威流程与完整细节见仓库文档
+`docs/cicd-staging-production.md`（本技能命令与之一致）；本文件是可直接照做的分阶段清单。
+
+仓库：`qiudl/qiu-slark`（本机克隆通常在 `/Users/donglinlai/coding/slark`）。所有命令在**仓库根**执行。
+`ai-proj` 相关命令加 `GODEBUG=netdns=go` 前缀。
+
+## 铁律（先记死）
+
+- GitHub `origin/main` 是唯一代码权威、合并入口与生产发布来源；`internal` 只用于 CI/镜像，永不发布。
+- 生产发布只接受**最新 `origin/main` 的精确 40 位 SHA**；`HEAD != origin/main` 会被 `deploy.sh` 拒绝。
+- 生产发布必须在**普通 clone** 中执行，且 `.git` 必须是目录；`release-prod.sh` / `deploy.sh` 会拒绝
+  `.git` 为指针文件的 git worktree。不要污染现有 checkout：主目录脏或被占用时，新建干净的临时 clone。
+- 审批式部署，永不自动：亲手敲的 `sudo`/`rm -rf`/`dd`/`curl|sh`/包安装是 `destructive`（NEVER_AUTO），
+  **每次都要人审**；命中审批闸就**等人批**，绝不绕过、绝不把这些 key 加进 auto-approve 白名单。
+- staging 与生产硬隔离：staging 脚本带生产 IP 拒运行护栏、不 push origin、不反向 rsync。
+- 当前 Slark staging 权威目标是 AWS `ap-southeast-2` 实例 `i-013e5ca3fdfddc13e`
+  （Name=`slark-staging`，2026-08-18 核验公网 IP `15.135.112.181`）。公网 IP 自动分配，发布前必须按
+  实例 ID 重查并确认 Name/状态；不得凭历史 IP 判断目标。
+- `82.157.141.202` 是 ai-proj 预生产宿主机。其 `/opt/slark-staging` cohost 是隔离的 Slark 兼容验收栈，
+  但不是 Slark 独立预生产；只有任务明确指定 cohost 时才能使用，不得作为普通 Slark staging 的默认目标。
+- staging 发布若影响 `packages/daemon`、`packages/runtime`、Server/daemon 公共协议或 Desktop 公共运行链，
+  必须把 `server-staging` 与 `daemon-staging` 更新到同一精确 SHA；两者版本不一致不得宣告 staging 成功。
+- 只修 PR 范围内的 CI 失败；不为过检去改 CI/workflow 或做无关改动。
+
+## 选择链路
+
+- 「发布/上线/部署生产」→ 生产发布链：阶段 1→2→4→5。
+- 「Desktop/桌面版打包、发布、上传 OSS」→ 阶段 1→2 后走 `docs/desktop-oss-release.md` 的 m5max 双平台链路。
+- 「盯 CI/合并 PR」→ 阶段 1→2（用 babysit 心态循环到 green + mergeable + 评论收口）。
+- 「复现/验证运行时行为、别碰生产」→ staging 预验链（阶段 3，可独立随时跑）。
+
+## 阶段 1：PR 与内网 gate（`ci/internal-gate`）
+
+真实门禁是内网 CI（GitHub Actions 已停用）。检查与自查：
+
+```bash
+gh pr checks <PR>                       # 应见 ci/internal-gate
+gh pr view <PR> --json state,mergeable,mergeStateStatus,isDraft,reviewDecision
+```
+
+- 基础门（全 PR）：release-contract / member-gate / authz-matrix / controlled-content-exits /
+  onconflict-predicate / migration-idempotency / wsl-path-translation / typecheck / test(全量)。
+- 条件外部门（按改动路径）：改 server DB/迁移/schema → `postgresql-security`；改 web → `web-e2e`；
+  android / daemon+desktop 各有门。
+- 本地复跑基础门可跑部分：`pnpm -r typecheck && pnpm test`。
+
+红了：只修本 PR 范围内的失败。疑似无关的合并阻塞→先 merge 最新 `main`（可能别的 PR 已修）。
+`BLOCKED: <label> requires <VAR>` = runner 环境未配外部门命令，属运维问题，不是 PR 代码问题。
+
+## 阶段 2：合并到 `origin/main`
+
+合并前确认：`mergeable=MERGEABLE`、`mergeStateStatus=CLEAN`、非 draft、`ci/internal-gate` 绿、评论收口。
+
+```bash
+gh pr merge <PR> --merge                # 仓库风格：merge commit
+```
+
+若本机 `main` 被其他 worktree 占用导致 `--delete-branch` 本地 checkout 失败（属本地副作用）：
+
+```bash
+gh pr view <PR> --json state,mergedAt,mergeCommit   # 确认 GitHub 侧 MERGED
+git push origin --delete <feature-branch>            # 删远端
+git branch -D <feature-branch>                       # 删本地（先切走）
+```
+
+## 阶段 3：staging 真机预验（可选，随时）
+
+### 3.1 当前权威路径：Slark 独立 staging
+
+稳定目标是 AWS `ap-southeast-2` 实例 `i-013e5ca3fdfddc13e`（Name=`slark-staging`）。它使用自动分配
+公网 IP，因此每次部署前先查询当前 IP；2026-08-18 核验值为 `15.135.112.181`：
+
+```bash
+aws ec2 describe-instances --region ap-southeast-2 \
+  --instance-ids i-013e5ca3fdfddc13e \
+  --query 'Reservations[0].Instances[0].{Name:Tags[?Key==`Name`]|[0].Value,State:State.Name,PublicIp:PublicIpAddress}' \
+  --output table
+
+export STAGING_SSH_KEY=~/.ssh/cloud-server-syd.pem
+export STAGING_REMOTE=ubuntu@15.135.112.181
+export STAGING_REMOTE_IP=15.135.112.181
+export STAGING_BASE=http://15.135.112.181
+
+scripts/deploy-staging.sh --migrate-dry-run
+scripts/deploy-staging.sh
+STAGING_TOKEN=$(cat /tmp/.staging_token) scripts/staging-seed.sh
+scripts/staging-verify-isolation.sh
+```
+
+不得把查询到的 Name 非 `slark-staging` 的机器当作目标。四件套细节与环境隔离约束见
+`docs/req-20260811-0059-staging-environment-design.md`。
+
+### 3.2 非权威路径：ai-proj cohost（仅明确指定时）
+
+ai-proj cohost 位于 `ubuntu@82.157.141.202:/opt/slark-staging`。全程使用隔离数据、数据库、密钥和状态目录，
+但宿主机身份仍是 ai-proj staging；普通“Slark 预生产”不得走这里。仅在任务明确要求 cohost 兼容验收时，
+先在**干净的独立 worktree**检出待验精确 SHA，再执行：
+
+```bash
+STAGING_SSH_KEY=~/.ssh/ai_proj_stg.pem \
+STAGING_KNOWN_HOSTS_FILE=~/.ssh/known_hosts \
+STAGING_REMOTE=ubuntu@82.157.141.202 \
+STAGING_REMOTE_IP=82.157.141.202 \
+  scripts/deploy-staging-cohost.sh
+```
+
+如果改动影响 daemon/runtime/公共协议，还需用 Compose `daemon` profile 更新 `daemon-staging`，并核对
+Server/daemon revision 同为待验 SHA。
+
+### 3.3 环境选择检查
+
+普通 Slark staging 默认走 3.1；只有用户或需求明确说“ai-proj cohost”才走 3.2。任何验收都必须记录：
+环境稳定身份、当次 IP、待验 40 位 SHA、Server/daemon revision/status、Server health 和目标功能结果。
+
+routed-remote 要 `network=enabled` 必须同时满足：① agent `workspace_access=write` +
+`repository_access=write`；② per-agent 工作区是可写 git worktree。细节见
+`docs/req-20260811-0059-staging-environment-design.md`。staging 刻意不碰 `deploy.sh` 的生产闸门。
+
+## 阶段 4：生产发布（审批式）
+
+**唯一姿势**：从干净的普通 clone 发布最新 `origin/main`（`HEAD == origin/main` 精确 SHA）。staging 可用
+独立 worktree，但生产脚本为保证同步与发布边界，会拒绝 worktree；不要在用户已有脏 checkout 中清理或发布。
+
+```bash
+# 若当前仓库不是普通 clone，先在安全父目录创建一次性干净 clone：
+git clone https://github.com/qiudl/qiu-slark.git <clean-production-clone>
+cd <clean-production-clone>
+
+git fetch origin main
+test -d .git                                            # 必须通过；worktree 的 .git 是文件
+git status --porcelain                                   # 必须干净
+git checkout --detach "$(git rev-parse origin/main)"     # 在产品分支上时先 detach 到该 SHA
+
+pnpm release:prod            # = release-prod.sh → deploy.sh --backend --no-install --no-mirror
+# 备选：scripts/deploy.sh --pull --backend
+```
+
+- `deploy.sh` 用 `check-production-release-sha.sh` 锁 `HEAD == origin/main` SHA，不符即拒。
+- `--backend` 才跑迁移：owner 连接（DDL 权）与运行时 `slark_app`（DML-only）分离；幂等、失败即非零。
+- 命中审批闸（发布/sudo）→ **等人批**；不要绕。脚本内部 SSH 载荷子进程的 sudo 不触发闸。
+- 普通工作 clone 发布完切回原分支：`git checkout <branch>`；一次性发布 clone 可保留作审计，清理时用可恢复方式。
+
+## 阶段 5：发布后核查
+
+```bash
+scripts/verify-deploy.sh    # 健康(前端/api/health=200)、bundle、server/daemon SHA、迁移集、federation、凭据
+```
+
+预期 `✓ deploy verification passed: server=<sha> daemon=<sha>` 且 `<sha> == origin/main`，舰队 `online ≥ 发布前`。
+镜像落后告警（默认 `--no-mirror`）非阻断，需补推按告警的幂等命令（需 Bitwarden session）；镜像仅单向 fast-forward。
+
+## Desktop m5max 双平台发布
+
+Desktop 安装包不走 Server 生产部署脚本。权威流程见仓库 `docs/desktop-oss-release.md`，已验证基线为
+REQ-20260819-0005 / Desktop 0.3.1：
+
+- 版本 PR 通过 `ci/internal-gate` 并合并后，m5max 从最新 `origin/main` 精确 SHA 的干净普通 clone 构建。
+- m5max 原生构建、Developer ID 签名并公证/staple macOS DMG/ZIP；交叉构建 Windows x64 NSIS EXE。
+- Darwin 不能执行 Windows 原生 `smoke:windows`。只有发布负责人明确接手 Windows 原生验收时才能继续交叉打包，交付证据必须标注该边界。
+- 资产不回传开发机；由 m5max 直接上传 `xiaoqu-public-file/slark/desktop/releases/v<version>/`，manifest 最后更新。
+- `xiaoqu-public-file` 的 canonical 凭证源是发布控制机上的 `/Users/donglinlai/coding/param.rxt`（必须为 `0600`）；AK/SK 分别位于 XML 标签 `ossAccessKeyId` / `ossAccessKeySecret`。不得改猜 Bitwarden、Keychain、通用 `credentials.env` 或 m5max 本地配置；只有该文件缺失、权限不符或标签解析为空时才停止并报告。
+- m5max 不持久化 OSS 凭证。发布控制机从 `param.rxt` 提取 AK/SK 后，只用 `printf '%s\n%s\n' ... | ssh m5max ...` 经 SSH stdin 传两行；远端用 `read -r` 接收并仅为当次 shell 导出 `OSS_ACCESS_KEY_ID` / `OSS_ACCESS_KEY_SECRET`，随后运行上传脚本。禁止 `scp` 凭证文件、写远端临时文件或把值打印到日志。
+- m5max 非交互 SSH 必须显式补 `PATH=/opt/homebrew/bin:/usr/local/bin:$HOME/.local/bin:$PATH`；已验证 `ossutil` 位于 `/Users/johnq/.local/bin/ossutil`。执行前检查 Node、三个安装包、精确 main SHA 和干净工作树，避免因交互 shell 环境差异重新猜路径。
+- m5max 默认出口若走 `utun`，只为当次 `ossutil` 使用 `--bind-address "$(ipconfig getifaddr en0)"`，不得修改整机 Tailscale/默认路由。
+- 完成前核对三份资产 SHA256/大小、macOS 签名与公证、公开 URL/manifest，并回写 ai-proj 证据。
+
+## 推送路由自查（换机器/新克隆必做）
+
+```bash
+git remote -v                          # origin 收发都应是 https://github.com/qiudl/qiu-slark.git
+git config --get-regexp '^url\.'       # 有输出 = pushInsteadOf 改写，push 可能被静默重定向到内网
+scripts/git-release-governance.sh check-local
+scripts/git-release-governance.sh status
+```
+
+## 故障分流
+
+| 现象 | 处置 |
+| --- | --- |
+| `release-prod` 拒绝 HEAD≠origin/main | `git fetch origin main` 后 detach 到 origin/main SHA，工作树须干净 |
+| `release-prod` 拒绝 git worktree / `.git` 不是目录 | 改用干净的普通 clone，锁定最新 `origin/main`；不要在现有脏 checkout 中强行切换 |
+| `ci/internal-gate` red | 看 gate 分组日志找 FAIL 项；`pnpm -r typecheck && pnpm test` 本地复现修复 |
+| `BLOCKED: <label> requires <VAR>` | runner 未配外部门命令，报运维配 `SLARK_CI_*_CMD`，非 PR 问题 |
+| 合并阻塞但与 PR 无关 | merge 最新 `main` 再看 |
+| push 成功但 GitHub 没有 | 查 `git config --get-regexp '^url\.'`，移除 pushInsteadOf 或显式指定 GitHub URL |
+| staging routed-remote 恒断网 | 查两道放网杠杆（workspace_access=write + 可写 git worktree） |
+| cohost Server 已更新但 daemon 仍是旧 SHA | 用 `--profile daemon up -d daemon-staging` 更新 daemon；核对两容器 revision 后才算完成 |
+| cohost daemon 启动即退出/fatal | 看 `docker logs slark_daemon_staging`；修复凭据/环境或版本契约，禁止用旧 daemon 冒充验收通过 |
+| verify 失败 SHA 不符 | 部署到了旧码，重发 |
+
+## ai-proj 流程（强制）
+
+任何改产品/代码行为的工作，动手前先在 ai-proj 立项 + 建 Task + 关联，实现/测试/交付回写；
+commit/PR 引用 `REQ-...`。纯文档/工具/只读排查除外。详见仓库 `AGENTS.md` / `CLAUDE.md`。

skills-req/req-prd-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "req-prd-plugin",
-  "description": "产品需求设计技能。覆盖问答访谈、PRD、缺陷收敛及 HTML 原型验证闭环。纯产品视角，不含技术实现。",
-  "version": "2.1.0",
+  "description": "产品需求设计技能。覆盖问答、PRD、缺陷与 OSS 原型闭环，文档双写本地和 ai-proj。",
+  "version": "2.2.0",
   "author": {
     "name": "qiudl"
   },

skills-req/req-prd-plugin/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: req-prd
-description: 产品设计与需求管理。用于 PRD 文档编写、需求分析、用户故事创建、功能设计和原型规划。当用户提到产品设计、PRD、需求文档、功能规划、用户故事相关任务时自动激活。
+description: 产品设计与需求管理。用于 PRD、需求分析、用户故事、功能设计和原型规划，并将正式需求文档双写到本地仓库与 ai-proj Task Document。
 ---
 
 # 产品需求设计 Skill (req-prd)
@@ -19,6 +19,36 @@ description: 产品设计与需求管理。用于 PRD 文档编写、需求分
 - `req-prototype` — UI 模块在 PRD/缺陷收敛后生成、上传并关联 HTML 原型
 - `defect-analysis` — 设计访谈确认后，对最新版 PRD 反复审计和修订直至收敛
 
+## 产品需求文档双写门禁
+
+本技能创建或修改的所有正式需求文档都必须同时保存到：
+
+1. 当前产品仓库的本地 Markdown 文件；
+2. Requirement 对应角色任务的 ai-proj Task Document。
+
+适用文档至少包括原始诉求/讨论记录、PRD、缺陷优化记录、原型版本与评审记录。Requirement description 只保存已确认的讨论摘要，不能替代 Task Document。
+
+### 路径与任务映射
+
+优先遵循仓库已有文档目录和命名约定；没有约定时使用：
+
+| 文档 | 本地默认路径 | ai-proj 任务角色 |
+|------|--------------|------------------|
+| 需求讨论记录 | `docs/product/{REQ-ID}-{slug}-discussion.md` | `documentation` |
+| PRD（含缺陷修订和原型回填） | `docs/product/{REQ-ID}-{slug}-prd.md` | `prd` |
+
+同一 Requirement、同一角色只维护一个当前任务文档。不得把本地文件路径当成 ai-proj 持久化，也不得只把远程 Task Document 导出一次后继续单边修改。
+
+### 每次写入协议
+
+1. 修改前同时读取本地文件与 ai-proj Task Document；任一不存在则基于另一份初始化，二者都不存在才新建空模板；
+2. 若两份内容不一致，比较文档 ID、版本、更新时间和内容摘要，保留双方未知内容并显式合并；无法安全合并时停止并请用户选择，禁止静默覆盖；
+3. 先用安全文件编辑方式写入本地 Markdown，再创建或更新对应 Task Document；
+4. 写后重新读取两端，计算或比较内容摘要，确认正文一致，并记录本地路径、task_id、document_id、version/updated_at；
+5. 任一端写入或复读失败都属于未完成的部分写入：保留已成功一端用于恢复，立即报告并停止后续阶段，不得宣称“已保存”“已收敛”或提交评审。
+
+问答每一轮、每次 PRD 修订、每轮 defect 处置和每次原型回填都执行该协议；不能等到流程结束再一次性补传。
+
 ## 模块设计访谈模式
 
 设计模块、系统、跨域流程，或目标/边界/业务规则尚未确定时，必须先执行问答式设计访谈，不得直接补全假设后生成 PRD。用户明确要求“你问我答”时也进入此模式。范围小、规则已完整确认的需求可以直接编写 PRD。
@@ -41,8 +71,8 @@ description: 产品设计与需求管理。用于 PRD 文档编写、需求分
 
 1. 原型基于最新版、已完成缺陷收敛的 PRD，并记录 PRD 文档标识、版本或内容摘要；
 2. 覆盖核心入口、主流程以及 PRD 明确要求的空态、失败态、无权限态和确认/撤销反馈；
-3. 上传后重新读取 Requirement，确认原型 URL/版本已关联，并验证 URL 可访问、iframe 可展示、核心交互可操作；
-4. 将 iframe、原型版本、版本说明和验证结果回填 PRD `4.2 界面原型`，并把生成、反馈、修订和确认写入同一讨论文档；
+3. 将本地 HTML 源文件通过 ai-proj 上传到 OSS；上传后重新读取 Requirement，确认 OSS URL/版本已关联，并验证 URL 可访问、iframe 可展示、核心交互可操作；
+4. 将 iframe、原型版本、版本说明和验证结果双写到本地 PRD 与 prd 角色 Task Document，并把生成、反馈、修订和确认双写到本地讨论记录与 documentation 任务文档；
 5. 用户明确确认最终 PRD 与原型表达的是同一方案。
 
 纯后端、批处理、基础设施等确实没有用户界面的模块可以跳过，但必须在讨论文档和 PRD `4.2` 中记录“无 UI，原型不适用”的理由及用户确认，不得静默省略。
@@ -401,6 +431,8 @@ mcp__ai-proj__link_tasks_to_requirement
 
 ### 文档管理
 
+以下 MCP 操作只完成 ai-proj 侧写入；每次调用前后都必须按“产品需求文档双写门禁”同步并校验本地 Markdown。
+
 ```bash
 # 创建 PRD 文档并关联任务
 mcp__ai-proj__create-and-attach
@@ -418,6 +450,8 @@ mcp__ai-proj__export_task_document_to_file
   - taskId: 任务ID
 ```
 
+导出命令不能代替双写校验：导出后仍需确认目标路径符合仓库约定、正文与 Task Document 当前版本一致，且没有覆盖本地新增内容。
+
 ---
 
 ## 功能设计流程
@@ -561,6 +595,8 @@ UI 模块还必须核对最终 HTML 原型与最新版 PRD 一致，并取得用
 ### PRD 完整性检查
 
 - [ ] 模块/系统设计已完成单轮单问访谈，且全过程已写入 ai-proj 讨论文档
+- [ ] 讨论记录与 PRD 均已保存到仓库本地 Markdown 和对应 ai-proj Task Document
+- [ ] 两端复读正文一致，交付说明包含本地路径、task/document 标识和远程版本
 - [ ] 讨论结论已由用户明确确认
 - [ ] `defect-analysis` 已基于最新版 PRD 收敛到一轮 0 个新缺陷
 - [ ] 无未处置的致命/高严重度缺陷

skills-req/req-prd-plugin/skills/references/design-interview-and-defect-loop.md

@@ -28,6 +28,7 @@
 
 - 任务标题：`【讨论】需求讨论: {需求标题}`
 - 文档标题：`{REQ-ID} 需求讨论记录`
+- 本地文件：优先使用仓库约定；默认 `docs/product/{REQ-ID}-{slug}-discussion.md`
 - 一个 Requirement 只维护一个当前讨论文档，不因会话中断重复创建。
 
 查找时同时核对 Requirement 关联关系、任务角色和标题，不能只按相似标题猜测。发现多个候选讨论文档时，列出标识和最近更新时间，请用户指定或授权合并；在此之前不得静默选择其中一个继续写入。
@@ -38,7 +39,15 @@
 
 若尚未指定 Requirement，先请用户提供已有 Requirement，或明确授权创建。取得 Requirement 和讨论文档前不得开始声称“已留痕”的正式访谈；不得仅为执行本技能本身擅自创建 Requirement。用户明确要求“创建需求并设计”才构成创建授权。
 
-每次恢复会话时，先读取 Requirement、现有 PRD 和讨论文档，从最后一个未决问题继续。讨论文档是跨会话、上下文压缩后的权威记录；模型记忆不能覆盖文档中的用户原话和已确认决策。
+每次恢复会话时，先读取 Requirement、现有 PRD，以及讨论记录/PRD 的本地文件和 ai-proj Task Document，从最后一个未决问题继续。两端持久化内容必须一致；模型记忆不能覆盖文档中的用户原话和已确认决策。
+
+### 本地与 ai-proj 双写
+
+- 讨论记录和 PRD 的每次新增或修订，都必须同步到仓库本地 Markdown 与对应 ai-proj Task Document；本地文件用于代码库评审和版本控制，Task Document 用于需求关联、跨会话恢复和团队查看。
+- 修改前读取两端。内容不一致时按版本、更新时间和摘要显式合并，保留双方未知内容；不能判断时停止并请用户选择，禁止以任一旧副本覆盖另一端。
+- 每轮问答按顺序完成：更新本地讨论文件 → 更新 documentation 任务文档 → 复读两端并核对正文/摘要 → 再向用户提出下一问。
+- 每次 PRD/defect/原型回填按同样协议更新本地 PRD 文件和 prd 任务文档。默认本地路径为 `docs/product/{REQ-ID}-{slug}-prd.md`，已有项目约定优先。
+- 任一端失败时记录“部分写入”及成功端的路径/标识，停止后续流程。恢复时从成功端与失败前最后版本合并，禁止重复追加同一 Q/Round/Prototype 编号。
 
 ### 写入纪律
 
@@ -49,7 +58,7 @@
 - 用户原话逐字保留在引用块中；AI 的解释、推论和建议必须分栏，不能伪装成用户决定。访问令牌、密码、私钥及依法需要保护的个人敏感信息不得落库，用 `[敏感信息已脱敏]` 替代并注明脱敏原因。
 - 文档以追加式记录为主。状态为“待回答”的问题块可以在收到回答后原位补全一次；变为“已确认”后不得静默改写。纠正已确认结论时追加“决策变更”，并引用被替代的编号。
 - 更新整篇文档前重新读取最新版并保留未知内容；若读取后文档又发生变化，基于最新版合并后重试，不能用旧副本覆盖其他会话的记录。
-- 写入后读取文档确认本轮编号和正文存在。写入或校验失败时立即报告，停止进入下一轮，且不得声称“已记录”。
+- 写入后读取本地文件和 ai-proj Task Document，确认本轮编号、正文和内容摘要一致。任一写入或校验失败时立即报告，停止进入下一轮，且不得声称“已记录”。
 - Requirement 描述只同步用户确认后的“讨论结论”摘要；完整过程保留在讨论文档中。
 
 ## 3. 单轮单问访谈
@@ -155,9 +164,9 @@ PRD 包含页面、表单、列表、可视状态、用户操作或跨页面流
 
 ### 6.3 上传、关联、回填与验证
 
-1. 通过 `upload_prototype` 上传 HTML，并记录 Requirement 数字 ID、原型 URL、版本说明和上传时间；
-2. 重新读取 Requirement，确认返回的原型 URL/版本确实已关联。仅拿到上传成功响应不足以通过；
-3. 将 iframe、PRD 基线、原型版本、版本说明和验证结果回填 PRD `4.2 界面原型`；
+1. 将 HTML 源文件保存到仓库约定目录（默认 `docs/prototypes/`），再通过 `upload_prototype` 上传到 ai-proj 配置的 OSS，并记录 Requirement 数字 ID、OSS URL、版本说明和上传时间；
+2. 重新读取 Requirement，确认返回的 OSS URL/版本确实已关联。仅有本地文件或上传成功响应不足以通过；
+3. 将 iframe、PRD 基线、原型版本、版本说明和验证结果同时回填本地 PRD 与 prd 角色 Task Document；
 4. 用浏览器或等价方式验证 URL 可访问、iframe 可展示、核心导航和交互可操作、关键状态可识别。使用临时浏览器时按环境规则关闭；
 5. 将生成输入、上传结果、验证证据和待确认差异写入讨论文档。任何写入或验证失败都必须停止，不得声称原型已完成。
 
@@ -236,7 +245,9 @@ PRD 包含页面、表单、列表、可视状态、用户操作或跨页面流
 
 - ai-proj Requirement 标识；
 - 讨论任务/文档标识；
+- 讨论记录本地路径及双写一致性状态；
 - PRD 任务/文档标识；
+- PRD 本地路径及双写一致性状态；
 - 问答轮数、缺陷审计轮数和收敛轮；
 - HTML 原型版本、URL、Requirement 关联与验证状态；无 UI 时给出跳过理由和用户确认；
 - 仍被接受的中/低风险；

skills-req/req-prototype-plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "req-prototype-plugin",
-  "description": "原型生成与关联。支持 HTML 正式交付、Requirement 关联、iframe 验证闭环及 Stitch AI 视觉探索。",
-  "version": "2.1.0",
+  "description": "原型生成与关联。支持 HTML 本地留源、OSS 正式交付、Requirement/iframe 验证及 Stitch AI。",
+  "version": "2.2.0",
   "author": {
     "name": "qiudl"
   },

skills-req/req-prototype-plugin/skills/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: req-prototype
-description: 原型生成与关联。支持两种模式：(1) Stitch AI 基于 PRD 自动生成 UI 原型截图；(2) AI 编写 HTML 原型并上传关联到需求详情页 iframe。当执行 /req prototype 或需要生成/上传界面原型时使用。
+description: 原型生成与关联。生成可交互 HTML、上传到 ai-proj OSS 并关联 Requirement/PRD iframe，也支持 Stitch AI 视觉探索。
 ---
 
 # 原型设计 Skill (req-prototype)
@@ -13,7 +13,7 @@ description: 原型生成与关联。支持两种模式：(1) Stitch AI 基于 P
 
 | 模式 | 命令 | 适用场景 | 输出 |
 |------|------|----------|------|
-| **HTML 上传** | `/req prototype upload` | UI 模块正式产品设计交付、评审与交互验证 | 可交互 HTML + Requirement 关联 + PRD iframe |
+| **HTML 上传** | `/req prototype upload` | UI 模块正式产品设计交付、评审与交互验证 | 本地 HTML 源文件 + OSS URL + Requirement 关联 + PRD iframe |
 | **Stitch AI** | `/req prototype` | 精细 UI 视觉探索、多屏草图 | 截图回填 PRD，后续仍需转为 HTML 正式原型 |
 
 ## 前置条件
@@ -27,6 +27,17 @@ description: 原型生成与关联。支持两种模式：(1) Stitch AI 基于 P
 | PRD 已完成 defect 收敛（正式 HTML 模式） | 读取讨论文档的收敛轮和最新版 PRD 标识 | 报错：先完成 req-prd/defect-analysis 收敛 |
 | UI 原型适用 | PRD 含页面、操作流程或可视状态 | 无 UI 时记录不适用理由与用户确认，不生成空壳原型 |
 
+## HTML 原型持久化门禁
+
+正式 HTML 原型必须上传到 ai-proj 配置的 OSS（对象存储），并以 OSS HTTPS URL 关联 Requirement。仅生成本地文件、`file://` URL、临时 HTTP 服务或聊天附件都不算完成。
+
+- 本地源文件优先遵循仓库约定；默认保存为 `docs/prototypes/{REQ-ID}-{slug}-v{N}.html`，纳入版本控制。
+- OSS 上传必须通过 `mcp__ai-proj__upload_prototype` 或 ai-proj 提供的等价正式接口完成，禁止绕过 Requirement 关联自行上传后只粘贴 URL。
+- `/tmp` 只能存放编码或校验过程中的临时副本，不能作为原型交付位置。
+- 上传后必须复读 Requirement，确认 `prototype_urls`/版本记录指向本次 OSS URL；再验证 URL 可访问、响应为 `text/html` 且可内联展示。
+- OSS 地址必须由 ai-proj 长期管理，不能把短期预签名 URL 写入 PRD；访问控制与 iframe 策略由 ai-proj 统一提供。
+- 原型元数据和 iframe 回填属于 PRD 修订，必须同时更新本地 PRD Markdown 与 prd 角色 Task Document，并复读校验一致。
+
 ## 子命令
 
 ### 0. `/req prototype upload [REQ-ID] [--note "版本说明"]` — 上传 HTML 原型（**推荐**）
@@ -40,24 +51,24 @@ description: 原型生成与关联。支持两种模式：(1) Stitch AI 基于 P
 2. 完整读取最新版 PRD，记录任务/文档 ID、版本、更新时间和内容摘要或哈希；正式交付还要核对 defect 收敛轮
 3. 从 PRD 提取页面清单、角色入口、主流程、关键状态和验收条件，形成覆盖矩阵
 4. AI 编写带完整样式和必要原生交互的独立 HTML 原型文件（见设计规范）
-5. 保存到 /tmp/proto_<req_id>_<timestamp>.html，并在本地做结构、大小和敏感信息检查
-6. Base64 编码：base64 < /tmp/proto_<req_id>_<timestamp>.html
-7. 调用 mcp__ai-proj__upload_prototype 上传（传入 requirementId + base64 content）
-8. 重新读取 Requirement，确认原型 URL/版本已关联；不得只相信上传响应
-9. 将 iframe、PRD 基线、原型版本/说明和验证状态回填 PRD「4.2 界面原型」
+5. 保存到仓库原型目录（默认 docs/prototypes/<REQ-ID>-<slug>-v<N>.html），并做结构、大小和敏感信息检查
+6. 从本地源文件 Base64 编码；如工具需要，可在 /tmp 创建临时编码副本
+7. 调用 mcp__ai-proj__upload_prototype 上传到 OSS（传入 requirementId + base64 content）
+8. 重新读取 Requirement，确认 OSS URL/版本已关联；不得只相信上传响应
+9. 将 iframe、PRD 基线、原型版本/说明和验证状态双写到本地 PRD 与 prd 角色 Task Document
 10. 打开最终 URL 或需求详情页，验证 iframe 展示和核心交互；记录证据后关闭临时浏览器
-11. 将生成、关联、验证、用户反馈和版本状态写入同一讨论文档
+11. 将生成、关联、验证、用户反馈和版本状态双写到本地讨论记录与 documentation 角色 Task Document
 ```
 
-**Step 5-6 执行方式**：
+**Step 6-7 执行方式**：
 
 ```bash
-# 5. Base64 编码 HTML 文件
-B64=$(base64 < /tmp/proto_<req_id>_<timestamp>.html)
+# 6. Base64 编码本地 HTML 源文件
+B64=$(base64 < docs/prototypes/<REQ-ID>-<slug>-v<N>.html)
 ```
 
 ```
-# 6. 通过 MCP 工具上传（无需本地后端）
+# 7. 通过 MCP 工具上传到 OSS（无需本地后端）
 mcp__ai-proj__upload_prototype(
   requirementId = <需求数字ID>,
   content       = <B64 字符串>,
@@ -72,7 +83,7 @@ mcp__ai-proj__upload_prototype(
   "success": true,
   "message": "原型已上传并关联到需求 <id>（version=N/A）",
   "data": {
-    "url": "https://ai-proj-1252326374.cos.ap-beijing.myqcloud.com/prototypes/<uuid>.html",
+    "url": "https://<ai-proj-oss-domain>/prototypes/<uuid>.html",
     "versionNote": "...",
     "uploadedAt": "...",
     "requirementId": <id>
@@ -80,7 +91,7 @@ mcp__ai-proj__upload_prototype(
 }
 ```
 
-**效果**：需求详情页自动出现「原型预览」卡片，iframe 加载 COS 上的 HTML 文件。**无需本地后端运行**。
+**效果**：需求详情页自动出现「原型预览」卡片，iframe 加载 OSS 上的 HTML 文件。**无需本地后端运行**。OSS 的具体厂商和域名由 ai-proj 服务配置，技能不得硬编码 COS、S3 或其他厂商地址。
 
 **参数**：
 
@@ -183,6 +194,9 @@ AI 生成的 HTML 原型必须满足以下要求：
 #### HTML 上传后验证清单
 
 - [ ] 上传响应成功且 Requirement 复读能看到同一 URL/版本
+- [ ] URL 为 ai-proj 返回的持久化 OSS HTTPS 地址，不是本地或临时地址
+- [ ] URL 不是短期预签名地址，响应 `Content-Type` 为 `text/html` 且不会强制下载
+- [ ] 仓库中保留与该 OSS 版本对应的 HTML 源文件
 - [ ] 原型 URL 返回可展示的 HTML，不是下载错误页、登录页或 404
 - [ ] 需求详情页使用 iframe 展示，没有降级为截图或图片
 - [ ] 核心入口、主流程和覆盖矩阵中的关键状态可识别/可操作
@@ -327,7 +341,7 @@ generated_at: "<timestamp>"
 
 | 异常 | 处理 |
 |------|------|
-| `mcp__ai-proj__upload_prototype` 返回失败 | 检查 requirementId 是否为数字 ID（非 display_id REQ-xxx） |
+| `mcp__ai-proj__upload_prototype` 返回失败 | 检查 requirementId 是否为数字 ID（非 display_id REQ-xxx）；不得降级为只留本地文件 |
 | HTML 文件超过 5MB | 精简样式或拆分多版本上传 |
 | iframe 不显示 | 检查 `prototype_urls` 字段是否非空：`mcp__ai-proj__get_requirement` 确认 |
 | base64 命令失败 | macOS 用 `base64 < file`，Linux 用 `base64 -w 0 < file` |

tests/install-skills.test.sh

@@ -42,6 +42,9 @@ description: Installer fixture version two.
 ---
 version two
 EOF
+# Reproduce rsync's quick-check edge case: changed content with identical size
+# and mtime must still replace the recorded, unmodified installation.
+touch -r "$TEST_HOME/.agents/skills/example/SKILL.md" "$FIXTURE_REPO/skills-dev/example-plugin/skills/SKILL.md"
 HOME="$TEST_HOME" "$FIXTURE_REPO/install-skills.sh" >/dev/null
 grep -q 'version two' "$TEST_HOME/.agents/skills/example/SKILL.md"
 grep -q '"version": "2.0.0"' "$TEST_HOME/.agents/.ai-proj-helper-installed-skills.json"