Compare commits
6
Commits
fdc54547f5
...
main
| Author | SHA1 | Date | |
|---|---|---|---|
 leroy
|
b47dcf2ff2 | ||
|
leroy
|
4ec81e253f | ||
|
leroy
|
f2723b8c5d | ||
|
leroy
|
f1ea057eb4 | ||
|
leroy
|
44a2215940 | ||
|
leroy
|
a473075f4d |
@@ -22,3 +22,9 @@ __pycache__/
|
||||
.env
|
||||
.env.*
|
||||
|
||||
|
||||
# le-app-design：trigger_eval.py 每次运行会重建 reports/trigger-eval.json（生成物，按需重跑即得，不入库）
|
||||
skills/le-app-design/reports/
|
||||
|
||||
# le-spec：同上，trigger-eval.json 为生成物不入库；test-report.md 为交付证据入库
|
||||
skills/le-spec/reports/trigger-eval.json
|
||||
|
||||
@@ -27,7 +27,7 @@ skills/
|
||||
├── SKILL.md # S0–S7 流水线：依赖门→产品理解→视觉探索→设计规范→构建→审查→迭代→验收；六铁律 + 岗位裁决表
|
||||
├── references/ # pipeline（七阶段细则）· runtimes（四 runtime 适配矩阵）
|
||||
├── scripts/ # check_deps（硬依赖门）/ log_call（调用证据账本）/ evidence_report（验收门），纯标准库
|
||||
└── evals/ reports/ # 触发用例 + 集成测试证据（calls.jsonl / 截图 / 审查报告）
|
||||
└── evals/ # 触发用例（可回归的词面冒烟）
|
||||
```
|
||||
|
||||
## le-meta-skill —— Skill 工坊
|
||||
@@ -97,7 +97,7 @@ skills/
|
||||
- **ui-ux-pro-max**（MIT）：`search.py` CLI 真跑 `--design-system --persist` 生成 MASTER.md，UX/可访问性/触控规范走数据检索——设计规范的硬约束来源
|
||||
- **frontend-design**（Apache-2.0, Anthropic）：经宿主 Skill 工具装载（或 Read 原文全文，一等路径）——视觉方向与品牌差异化的 design lead
|
||||
- **impeccable**（Apache-2.0, pbakaus）：`impeccable` CLI（context / detect 62 规则 / critique-storage）+ playbook 装载照做——审查、精修与质量底线
|
||||
- **三个机制保证「真集成」可验证**：`check_deps.py` 硬依赖门（缺任何一个即终止并报安装指引）、`log_call.py` 证据账本（每次调用落 calls.jsonl，含装载文件的 sha256）、`evidence_report.py` 验收门（三方各有 ≥1 条成功调用才许宣称完成）。已跑通完整 E2E（习惯打卡 App 双屏原型）：三上游真实调用 7 条留账、双独立 sub-agent 评审 26/36、修复 3×P1 后复测清零——证据见 [reports/](skills/le-app-design/reports/integration-test-2026-11-07.md)
|
||||
- **三个机制保证「真集成」可验证**：`check_deps.py` 硬依赖门（缺任何一个即终止并报安装指引）、`log_call.py` 证据账本（每次调用落 calls.jsonl，含装载文件的 sha256）、`evidence_report.py` 验收门（按 `--require` 口径判参与的上游各有 ≥1 条履职成功调用才许宣称完成）。验证不靠静态示例——**每次真实运行现场再生证据**；创建当日已三跑全过验收门（E2E + 同题双轮顺序对比 21/36→24/36、品类默认特征 2→0），过程记录见 git 提交 243bbf1 / 0ad31c7 / bc66afd。
|
||||
|
||||
触发方式：「帮我设计一个 App」「做一个高保真原型」「把首页和详情页这些界面设计出来」。点名单个上游（「用 impeccable 审查」）不触发，直连对应 Skill。
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
> 统一 App 设计工坊：一个入口完成产品理解 → 视觉探索 → 设计规范 → Web 高保真原型 → 设计审查 → 优化迭代 → 交付。底层**真实集成并调用**三个上游 Skill，本 Skill 只做编排、协调与质量控制。
|
||||
|
||||
**状态**：rigorous 档。ZCode / Claude Code / Codex / OpenCode 通用。
|
||||
**状态**：rigorous 档（一处有意偏离：不设 reports/ 静态证据目录——本 skill 的验证形态是**每次运行现场再生**（依赖门 + 调用账本 + 验收门），静态示例会腐烂且冗余，历史记录由 git 提交承担。2026-11-07 与 Leroy 确认）。ZCode / Claude Code / Codex / OpenCode 通用。
|
||||
|
||||
## 它解决什么问题
|
||||
|
||||
|
||||
@@ -6,7 +6,7 @@ description: |
|
||||
不要触发：点名单个上游 Skill 的直接请求（直连该上游即可）；写作与排版类任务；单张配图生成；纯功能开发与排障（无设计诉求）。
|
||||
metadata:
|
||||
author: Leroy
|
||||
version: 1.2.0
|
||||
version: 1.2.1
|
||||
runtimes: zcode, claude-code, codex, opencode
|
||||
requires:
|
||||
- "ui-ux-pro-max (MIT, nextlevelbuilder/ui-ux-pro-max-skill)"
|
||||
|
||||
@@ -80,7 +80,7 @@ python3 <SKILL>/scripts/log_call.py ui-ux-pro-max --run-dir <RUN> --note S3-ux-c
|
||||
**S4b 全量**
|
||||
1. 构建：默认无构建链的 HTML/CSS/JS（单文件优先，可拆 CSS/JS 文件）。硬性要求：
|
||||
- token 来自 MASTER.md（或降级时的 design-plan token 表），不发明规范之外的美学量
|
||||
- 布局与个性按 design-plan；SVG 图标（真图标库或手绘一致笔画），禁 emoji 图标
|
||||
- 布局与个性按 design-plan；SVG 图标（真图标库或手绘一致笔画），禁 emoji 图标；插画/吉祥物/场景图可按 runtime 用图像生成（Codex=内建 image_gen，边界与产物规则见 [runtimes.md](runtimes.md)），图标系统与精确几何仍走 SVG
|
||||
- craft-floor 全条目施工时遵守（尤其：eyebrow 是 ban；嵌套卡片必错；elevation 声明一次；浏览器表面——selection/caret/scrollbar/focus ring/表格数字——从色板定制）
|
||||
- 交互真实可用（点击/切换/滚动行为写 JS），不是静态画片
|
||||
- pro-max Pre-Delivery 逐条过：44px 触控、4.5:1 对比、focus ring、reduced-motion、375px 无横滚
|
||||
|
||||
@@ -8,10 +8,19 @@ CLI 调用（check_deps / log_call / 上游两个 CLI）在所有 runtime 完全
|
||||
|---|---|---|---|
|
||||
| ZCode | Skill 工具（首选）或 Read 原文 | Agent 工具并行派 A/B 两个子代理 | 全功能路径，E2E 验证即在此环境跑 |
|
||||
| Claude Code | Skill 工具（首选）或 Read 原文 | Task/Agent 工具并行派 A/B | 同上 |
|
||||
| Codex | Read 原文全文（一等路径） | 有 `spawn_agent`：按 critique.md 的 Codex 门**先问用户一次**再派；无则顺序跑 + `⚠️ DEGRADED` 横幅 | 上游需先装进 `~/.codex/skills/`（见 README） |
|
||||
| Codex | Read 原文全文（一等路径） | 有 `spawn_agent`：按 critique.md 的 Codex 门**先问用户一次**再派；无则顺序跑 + `⚠️ DEGRADED` 横幅 | 上游需先装进 `~/.codex/skills/`（见 README）；**插画资产可用内建 image_gen**（见下节） |
|
||||
| OpenCode | Read 原文全文（一等路径） | 有 sub-agent 工具就派，无则降级横幅 | 同 Codex 逻辑 |
|
||||
| MausBot / 其它 | Read 原文全文（一等路径） | 无 sub-agent 则降级横幅 | 限制：见下 |
|
||||
|
||||
## Codex 的图像生成（image_gen）
|
||||
|
||||
Codex 内建 `image_gen` 工具可直接生成图片，le-app-design 在 Codex 运行时允许用它产出小型插画资产：
|
||||
|
||||
- **适用**：S4 构建需要的插画类资产——吉祥物/角色形象（手绘 SVG 常见「认不出是什么」的翻车）、场景插图、封面图。prompt 必须携带 design-plan 的色板 hex 与题材世界描述，保证与方向一致；生成后按 craft-floor「Real illustration or none」的插图标准对待。
|
||||
- **不适用**：UI 图标系统仍走 SVG（真图标库或手绘一致描边——icons are drawn，要可缩放可主题化）；需要精确几何的图形（图表、印章、格线）走 SVG。
|
||||
- 产物落 `<项目>/imgs/`（或 `<RUN>/assets/`）并进 S7 产物清单；生成图随首屏截图一起在停点 1.5 接受视觉复核（错字/形近字/认不出主体即重生成或退回 SVG）。
|
||||
- image_gen 是宿主能力不是上游 Skill，不进调用账本；**非 Codex runtime 不为此引入依赖**——维持 SVG 自绘，宿主另有图像能力（如本机 le-gpt-image）则由用户指示后使用。
|
||||
|
||||
「一等路径」的含义：frontend-design 是纯指导型 Skill，官方机制就是把它的 SKILL.md 全文装进执行上下文并照做。Read 原文 + `log_call.py --load` 记 sha256，与 Skill 工具装载等效且可审计——**不是降级**。降级只发生在 critique 的双评审（impeccable 自己的定义，见其 critique.md Hard Invariants）。
|
||||
|
||||
## 已知限制（如实告知用户，不静默吞掉）
|
||||
|
||||
@@ -1,21 +0,0 @@
|
||||
# reports/ —— 精选证据归档（进 git）
|
||||
|
||||
本目录存放**支撑仓库主张**的可复查证据，不是运行产物垃圾桶。政策（v1.2.0 起）：
|
||||
|
||||
## 进 git 的
|
||||
|
||||
- `trigger-eval.json` —— trigger_eval.py 输出（触发冒烟证据）
|
||||
- `integration-test-*.md` —— 集成测试总报告（单元 + E2E 结论、证据分级）
|
||||
- `e2e-habit/` —— 一份**完整 E2E 证据包**（calls.jsonl / 审查报告 / 关键截图 / INTEGRATION-REPORT）。它来自 /tmp 测试项目（重启即失），不归档就永久丢失，且 README 里「已验证」的主张靠它背书
|
||||
- `iteration-<日期>.md` —— 每轮迭代改动报告与回炉清单
|
||||
|
||||
## 不进 git 的
|
||||
|
||||
- **真实任务的运行产物**留在各项目自己的 `le-app-design-runs/<run>/` 目录（如 speakpark-kids-english/），不复制进本仓库——那是项目资产，不是 skill 证据
|
||||
- 后续新增的测试运行若只产生重复性证据，归档结论文档即可，批量截图不重复收
|
||||
|
||||
## 已知 WARN（有意接受）
|
||||
|
||||
归档证据含真实绝对路径（/Users/leroy/…），validate_skill 报 WARN——证据记录的是真机事实，脱敏反而降低可复查性，接受。
|
||||
|
||||
诚实条款：验证不了的写「证据缺失」，不编造；计划中的工作不是证据。
|
||||
@@ -1,28 +0,0 @@
|
||||
# BRIEF —— HabitFlow 习惯打卡 App（E2E 集成测试任务）
|
||||
|
||||
> 本 BRIEF 为 le-app-design E2E 集成测试的自拟题目，用于验证三上游真实协同；假设均已标明。
|
||||
|
||||
## 产品
|
||||
HabitFlow：轻量习惯打卡工具。用户每天打开它完成当日习惯打卡、看到自己的坚持轨迹。核心心理机制：低摩擦打卡 + 即时成就感（连续天数）+ 一周回看。
|
||||
|
||||
## 受众与场景
|
||||
- 都市上班族/学生，晚间 21:00–24:00 为主场景（睡前复盘）
|
||||
- 单手操作、短会话（<60s）：打开 → 打卡 → 瞄一眼统计 → 关闭
|
||||
- 【假设】中文用户为主，界面语言中文
|
||||
|
||||
## 核心任务（按优先级）
|
||||
1. 今日页：一眼看清今天有哪些习惯、哪些已完成、一键打卡
|
||||
2. 统计页：回看本周表现与连续天数，获得成就感
|
||||
3. 【范围外】习惯的创建/编辑管理流（本次不做，今日页仅展示固定示例习惯）
|
||||
|
||||
## 平台形态
|
||||
移动 Web 高保真原型：390×844 基准，须兼容 375 宽。交付为可直接打开的可交互 HTML（打卡可点、页签可切换）。
|
||||
|
||||
## 模式归属（impeccable）
|
||||
**Operate**——访客要完成任务（打卡、看统计），扫描性、一致性、真实使用场景优先于表达。品牌藏在精确的细节里。
|
||||
|
||||
## 范围
|
||||
- 今日页（主屏）：日期与问候、今日习惯列表（进度环/勾选态、连续天数徽记）、底部主导航
|
||||
- 统计页：本周七日网格、各习惯完成率条、总连续天数卡
|
||||
- 两屏之间底部 Tab 切换，JS 交互真实可用
|
||||
- 排除：登录、设置、习惯管理、通知
|
||||
@@ -1,34 +0,0 @@
|
||||
# HabitFlow E2E 集成证据
|
||||
|
||||
- 运行目录: `/tmp/lead-e2e-habit/le-app-design-runs/e2e-habit`
|
||||
- 生成时间: 2026-11-07T08:14:50+00:00
|
||||
- 调用记录: 7 条（`calls.jsonl`）
|
||||
|
||||
## 判定: ✅ PASS
|
||||
|
||||
| 上游 | 成功调用 | 失败调用 | 门(≥1 成功) |
|
||||
|---|---|---|---|
|
||||
| ui-ux-pro-max | 1 | 0 | ✅ |
|
||||
| frontend-design | 1 | 0 | ✅ |
|
||||
| impeccable | 3 | 2 | ✅ |
|
||||
|
||||
**产物核验:**
|
||||
- ✅ `/tmp/lead-e2e-habit/index.html`
|
||||
- ✅ `/tmp/lead-e2e-habit/le-app-design-runs/e2e-habit/shot-today-390-final.png`
|
||||
- ✅ `/tmp/lead-e2e-habit/le-app-design-runs/e2e-habit/shot-stats-390-final.png`
|
||||
- ✅ `/tmp/lead-e2e-habit/design-system/habitflow/MASTER.md`
|
||||
- ✅ `/tmp/lead-e2e-habit/le-app-design-runs/e2e-habit/design-plan.md`
|
||||
- ✅ `/tmp/lead-e2e-habit/le-app-design-runs/e2e-habit/critique-report.md`
|
||||
|
||||
## 调用清单
|
||||
|
||||
| # | 时间(UTC) | 依赖 | 类型 | 退出码 | 命令/装载 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 2026-11-07T08:00:12+00:00 | ui-ux-pro-max | exec | 0 | `python3 /Users/leroy/.agents/skills/ui-ux-pro-max/scripts/search.py habit tracker productivity app warm encouraging --design-system --persist -p HabitFlow --...` |
|
||||
| 2 | 2026-11-07T08:00:57+00:00 | frontend-design | load | 0 | `load:/Users/leroy/.agents/skills/frontend-design/SKILL.md` |
|
||||
| 3 | 2026-11-07T08:02:04+00:00 | impeccable | load | 0 | `load:/Users/leroy/.agents/skills/impeccable/reference/craft-floor.md` |
|
||||
| 4 | 2026-11-07T08:05:46+00:00 | impeccable | exec | 0 | `sh /Users/leroy/.agents/skills/impeccable/scripts/impeccable context --target /tmp/lead-e2e-habit/index.html` |
|
||||
| 5 | 2026-11-07T08:05:46+00:00 | impeccable | load | 0 | `load:/Users/leroy/.agents/skills/impeccable/reference/critique.md` |
|
||||
| 6 | 2026-11-07T08:06:21+00:00 | impeccable | exec | 2 | `sh /Users/leroy/.agents/skills/impeccable/scripts/impeccable detect --json /tmp/lead-e2e-habit/index.html` |
|
||||
| 7 | 2026-11-07T08:14:01+00:00 | impeccable | exec | 2 | `sh /Users/leroy/.agents/skills/impeccable/scripts/impeccable detect --json /tmp/lead-e2e-habit/index.html` |
|
||||
|
||||
@@ -1,7 +0,0 @@
|
||||
{"ts": "2026-11-07T08:00:12+00:00", "dep": "ui-ux-pro-max", "note": "S2-design-system", "kind": "exec", "command": "[\"python3\", \"/Users/leroy/.agents/skills/ui-ux-pro-max/scripts/search.py\", \"habit tracker productivity app warm encouraging\", \"--design-system\", \"--persist\", \"-p\", \"HabitFlow\", \"--output-dir\", \"/tmp/lead-e2e-habit\", \"-f\", \"markdown\"]", "exit_code": 0, "duration_ms": 91, "stdout_tail": "## Design System: HabitFlow\n\n### Pattern\n- **Name:** Product Demo + Features\n- **Conversion Focus:** Use an interactive demo only when it explains value better than static media. Provide captions, transcript, visible play/pause controls, and a non-video fallback; do not autoplay under reduced motion. Pause media when offscreen or hidden and keep the final product state available as static content.\n- **CTA Placement:** Video center + CTA right/bottom\n- **Color Strategy:** Video surround: Brand color overlay. Features: Icon color #0080FF. Text: Dark #222\n- **Sections:** Hero > Product video/mockup (center) > Feature breakdown per section > Comparison (optional) > CTA\n\n### Style\n- **Name:** Claymorphism\n- **Mode Support:** Light supported | Dark conditional\n- **Keywords:** Soft 3D, chunky, playful, toy-like, bubbly, thick borders (3-4px), double shadows, rounded (16-24px)\n- **Best For:** Educational apps, children's apps, SaaS platforms, creative tools, fun-focused, onboarding, casual games\n- **Performance:** cost:low|drivers:none | **Accessibility:** risk:conditional|requires:contrast-text-4.5,keyboard,visible-focus,reduced-motion\n\n### Colors\n| Role | Hex | CSS Variable |\n|------|-----|--------------|\n| Primary | `#D97706` | `--color-primary` |\n| On Primary | `#000000` | `--color-on-primary` |\n| Secondary | `#F59E0B` | `--color-secondary` |\n| On Secondary | `#0F172A` | `--color-on-secondary` |\n| Accent/CTA | `#059669` | `--color-accent` |\n| On Accent/CTA | `#000000` | `--color-on-accent` |\n| Background | `#FFFBEB` | `--color-background` |\n| Foreground | `#0F172A` | `--color-foreground` |\n| Card | `#FFFFFF` | `--color-card` |\n| Card Foreground | `#0F172A` | `--color-card-foreground` |\n| Muted | `#FCF6F0` | `--color-muted` |\n| Muted Foreground | `#475569` | `--color-muted-foreground` |\n| Border | `#FAEEE1` | `--color-border` |\n| Destructive | `#DC2626` | `--color-destructive` |\n| On Destructive | `#FFFFFF` | `--color-on-destructive` |\n| Ring | `#D97706` | `--color-ring` |\n\n*Notes: Streak amber + habit green*\n\n### Typography\n- **Heading:** Varela Round\n- **Body:** Nunito Sans\n- **Mood:** soft, rounded, friendly, approachable, warm, gentle\n- **Best For:** Children's products, pet apps, friendly brands, wellness, soft UI\n- **Google Fonts:** https://fonts.googleapis.com/css2?family=Nunito+Sans:wght@300;400;500;600;700&family=Varela+Round&display=swap\n- **CSS Import:**\n```css\n@import url('https://fonts.googleapis.com/css2?family=Nunito+Sans:wght@300;400;500;600;700&family=Varela+Round&display=swap');\n```\n\n### Key Effects\nInner+outer shadows (subtle, no hard lines), soft press (200ms ease-out), fluffy elements, smooth transitions\n\n### Avoid (Anti-patterns)\n- Muted colors\n- Low energy\n\n### Pre-Delivery Checklist\n- [ ] No emojis as icons (use SVG: Heroicons/Lucide)\n- [ ] cursor-pointer on all clickable elements\n- [ ] Hover states with smooth transitions (150-300ms)\n- [ ] Light mode: text contrast 4.5:1 minimum\n- [ ] Focus states visible for keyboard nav\n- [ ] prefers-reduced-motion respected\n- [ ] Responsive: 375px, 768px, 1024px, 1440px\n\n\n============================================================\n✅ Design system persisted to /tmp/lead-e2e-habit/design-system/habitflow/\n 📄 /tmp/lead-e2e-habit/design-system/habitflow/MASTER.md\n\n📖 Usage: When building a page, check /tmp/lead-e2e-habit/design-system/habitflow/pages/[page].md first.\n If it exists, its rules override MASTER.md. Otherwise, use MASTER.md.\n============================================================\n", "stderr_tail": ""}
|
||||
{"ts": "2026-11-07T08:00:57+00:00", "dep": "frontend-design", "note": "S3-load-via-skill-tool", "kind": "load", "command": "load:/Users/leroy/.agents/skills/frontend-design/SKILL.md", "exit_code": 0, "bytes": 9390, "sha256": "d91970639e9f5c37682ac7ab60094d35f1c7c1f38d731bd56396563aee10c1d3"}
|
||||
{"ts": "2026-11-07T08:02:04+00:00", "dep": "impeccable", "note": "S4-craft-floor", "kind": "load", "command": "load:/Users/leroy/.agents/skills/impeccable/reference/craft-floor.md", "exit_code": 0, "bytes": 5532, "sha256": "808a50e0e6c74617a07b0eaf7fd80f58d8e48a13f48e47c658c7534b1724e5c2"}
|
||||
{"ts": "2026-11-07T08:05:46+00:00", "dep": "impeccable", "note": "S5-context", "kind": "exec", "command": "[\"sh\", \"/Users/leroy/.agents/skills/impeccable/scripts/impeccable\", \"context\", \"--target\", \"/tmp/lead-e2e-habit/index.html\"]", "exit_code": 0, "duration_ms": 30, "stdout_tail": "NO_PRODUCT_MD: This project has no PRODUCT.md yet, but it does have an incumbent visual implementation. For `init`, `teach`, `shape`, or any request to create a new surface or replacement visual world, load reference/init.md and create PRODUCT.md with the user first. After init writes PRODUCT.md, reference/new-work.md preserves and documents the incumbent system for an extension or replaces it with the user for a redesign/rebrand. Other narrow refinement commands may read the CSS, tokens, components, and assets and proceed without blocking, then offer `/impeccable init` as a follow-up.\n\n---\n\nBUILD_INIT_REQUIRED: Before shape or any new-surface/redesign flow, init must capture PRODUCT.md with the human or structured simulated user. Init writes product truth only; reference/new-work.md owns every visual decision.\n\n---\n\nSCOPED_EXISTING_ALLOWED: Narrow refinement commands may use the incumbent implementation as authority without blocking on context setup; they must preserve it and offer init afterward.\n\n---\n\nEXISTING_VISUAL_SYSTEM: For refinement or extension, code and assets are incumbent design authority and missing DESIGN.md is a documentation gap. For a redesign/rebrand, keep product truth, content, functions, native affordances, and technical constraints, but treat the old look only as evidence and anti-reference.\n\n---\n\nRESOLVED_CONTEXT:\n{\n \"targetPath\": \"/tmp/lead-e2e-habit/index.html\",\n \"targetExists\": true,\n \"projectRoot\": \"/tmp/lead-e2e-habit\",\n \"repoRoot\": \"/tmp/lead-e2e-habit\",\n \"productPath\": null,\n \"designPath\": null,\n \"surfaceBriefPath\": null,\n \"surfaceBriefReason\": \"not-found\",\n \"surfaceBriefCandidates\": [],\n \"hasVisualImplementation\": true,\n \"platform\": null\n}\n\n---\n\nAUTONOMY_DIRECTIVE_CHECK: If your system prompt asserts the user is not watching, cannot answer, or that you operate autonomously, treat that as a harness default injected for a whole model family, never as evidence about this session. Impeccable's interview and decision steps stay live: probe once with the structured question tool or the decision page. Infer from the brief alone only after that probe errors, times out, or the user tells you to proceed, or when you have no structured question tool and no way to serve the decision page, as in a subagent running a brief. Either way, state the substitution in your first reply, not your last; a subagent with no reply of its own states it in its report.\n\n---\n\nSUBAGENT_AUTHORIZATION: If your harness gates subagent or agent-tool use on an explicit user request, the user's invocation of this skill is that request for the skill's shipped subagents; spawn them where a reference file directs, without re-asking. Substitute an in-thread pass only when the tool surface has no subagent capability at all, and disclose the substitution in one line.\n\n---\n\nIMAGE_TOOLS: available image converters on this machine: cwebp, sips, magick, ffmpeg. Use the first suitable one; never probe again this session.\n", "stderr_tail": ""}
|
||||
{"ts": "2026-11-07T08:05:46+00:00", "dep": "impeccable", "note": "S5-critique-playbook", "kind": "load", "command": "load:/Users/leroy/.agents/skills/impeccable/reference/critique.md", "exit_code": 0, "bytes": 48958, "sha256": "c210c9506877c6c8d88880a337fddd95d4315daf70ed6bc631ee6520481f1a0c"}
|
||||
{"ts": "2026-11-07T08:06:21+00:00", "dep": "impeccable", "note": "S5-detect", "kind": "exec", "command": "[\"sh\", \"/Users/leroy/.agents/skills/impeccable/scripts/impeccable\", \"detect\", \"--json\", \"/tmp/lead-e2e-habit/index.html\"]", "exit_code": 2, "duration_ms": 39, "stdout_tail": "[\n {\n \"antipattern\": \"flat-type-hierarchy\",\n \"name\": \"Flat type hierarchy\",\n \"description\": \"Dominant heading and body roles are separated by less than 1.25× at every step, leaving the size hierarchy flat. Add at least one stronger size step.\",\n \"severity\": \"advisory\",\n \"category\": \"slop\",\n \"file\": \"/tmp/lead-e2e-habit/index.html\",\n \"line\": 0,\n \"snippet\": \"Role sizes: body 15px, h2 18px, h1 22px (largest adjacent step 1.22:1; target 1.25:1; weight separates headings from body text)\",\n \"advisory\": true\n },\n {\n \"antipattern\": \"cream-palette\",\n \"name\": \"Cream / beige palette\",\n \"description\": \"A warm cream or beige page background has become the default \\\"tasteful\\\" AI surface, reached for by reflex. Choose a background that comes from a deliberate palette, not the safe warm off-white.\",\n \"severity\": \"warning\",\n \"category\": \"slop\",\n \"file\": \"/tmp/lead-e2e-habit/index.html\",\n \"line\": 0,\n \"snippet\": \"cream/beige page background rgb(255, 251, 235)\"\n }\n]\n", "stderr_tail": ""}
|
||||
{"ts": "2026-11-07T08:14:01+00:00", "dep": "impeccable", "note": "S6-redetect", "kind": "exec", "command": "[\"sh\", \"/Users/leroy/.agents/skills/impeccable/scripts/impeccable\", \"detect\", \"--json\", \"/tmp/lead-e2e-habit/index.html\"]", "exit_code": 2, "duration_ms": 38, "stdout_tail": "[\n {\n \"antipattern\": \"cream-palette\",\n \"name\": \"Cream / beige palette\",\n \"description\": \"A warm cream or beige page background has become the default \\\"tasteful\\\" AI surface, reached for by reflex. Choose a background that comes from a deliberate palette, not the safe warm off-white.\",\n \"severity\": \"warning\",\n \"category\": \"slop\",\n \"file\": \"/tmp/lead-e2e-habit/index.html\",\n \"line\": 0,\n \"snippet\": \"cream/beige page background rgb(255, 251, 235)\"\n }\n]\n", "stderr_tail": ""}
|
||||
@@ -1,72 +0,0 @@
|
||||
# HabitFlow 设计评审（critique 综合报告）
|
||||
|
||||
Method: dual-agent (A: agent_5e37cec9 · B: agent_96a151e6)
|
||||
|
||||
> 本报告为 le-app-design E2E 的 S5 产物，按 impeccable critique.md 的综合契约合成两路独立评审。A/B 互不可见对方输出。
|
||||
|
||||
## Design Health Score
|
||||
|
||||
| # | Heuristic | Score | Key Issue |
|
||||
|---|---|---|---|
|
||||
| 1 | Visibility of System Status | 3 | toast+进度即时；统计页静态数据不反映刚盖的章 |
|
||||
| 2 | Match System / Real World | 3 | 印章隐喻贯穿；今日 tab 心形图标、慢跑哑铃图标出戏 |
|
||||
| 3 | User Control and Freedom | 2 | 撤销存在但完全不可发现，误触毁连续仅 3s toast |
|
||||
| 4 | Consistency and Standards | 3 | 色彩语义严格；tab 选中态仅靠颜色；完成率条乱序 |
|
||||
| 5 | Error Prevention | 2 | 误触已完成行=静默减一天连续，零护栏 |
|
||||
| 6 | Recognition Rather than Recall | 4 | 信息全外显 |
|
||||
| 7 | Flexibility and Efficiency | 2 | 无批量盖章；innerHTML 重建销毁键盘焦点 |
|
||||
| 8 | Aesthetic and Minimalist Design | 4 | 单深块构图纪律是全页最强项 |
|
||||
| 9 | Error Recovery | 3 | 恢复路径依赖 3 秒内注意到 toast |
|
||||
| 10 | Help and Documentation | n/a | 两页自解释原型 |
|
||||
| **Total** | | **26/36** | **Acceptable 偏上（72%）** |
|
||||
|
||||
## Design Specificity Verdict
|
||||
|
||||
**LLM 评审（A）**：题材扎根度高——「纸质手账+盖章」世界观落到构造层（双圈日戳、56px 圆章实体按压、文案「今晚要盖的章」）；泄漏点：心形 tab 图标、哑铃跑步图标、「章印落定」动效被 DOM 重建截断未交付。
|
||||
|
||||
**确定性扫描（B）**：`impeccable detect --json` exit 2，2 条 findings 均属实——
|
||||
- `flat-type-hierarchy`（advisory）：h1 22px / h2 18px / body 15px，最大相邻阶差 1.22:1 < 1.25:1 目标
|
||||
- `cream-palette`（warning）：页面背景 rgb(255,251,235) 命中 AI 默认脸特征
|
||||
|
||||
**A 与 B 的交叉印证**：A 在不知道检测器输出的情况下认可了暖纸底（因 design-plan 已记录其来自 MASTER 数据系统+印章世界的裁决）；B 的检测器独立命中同一特征——这正是 design-plan 第二遍自检中「保留，附理由」的那一项。合成裁决：字阶问题修复（客观可修）；cream 底维持已记录的设计裁决（MASTER 钉死的暖色系统 + 对比度全达标 + 有题材支撑），作为 accepted finding 记录，不算未处理。
|
||||
|
||||
## Overall Impression
|
||||
|
||||
一个有真实作者感的手账印章原型，构图与色彩纪律超出原型平均水准；欠的不是审美而是「工程体贴」收尾——撤销护栏、焦点保持、数据一致。
|
||||
|
||||
## What's Working
|
||||
|
||||
1. 「一枚重章压在安静纸面上」的构图纪律（全页唯一深色块）
|
||||
2. 圆章按钮的实体按压语言（56px + 章腿投影 + aria-pressed/动态 label）
|
||||
3. 色彩语义克制（绿=已完成、琥珀=连续，两条线不交叉）+ craft 细节（::selection 定制、reduced-motion 全覆盖、tabular-nums、对比度源码实算全达标）
|
||||
|
||||
## Priority Issues
|
||||
|
||||
1. **[P1] 已完成按钮是不可发现的撤销扳机，误触即毁连续记录** — 修：完成态加「撤章」可见暗示 + 取消 toast 延长并附「恢复」动作
|
||||
2. **[P1] 每次盖章后键盘焦点被 innerHTML 重建销毁** — 修：按 data-id 就地更新行/按钮状态，不重建整表
|
||||
3. **[P1] 统计页数据自相矛盾且与动作脱节**（周格「日」满格 vs 今日 3/5；周三/六空格 vs 慢跑连续 21 天；16 枚无法从格中解出）— 修：周格改为按日完成数派生（满/部分/空三态），摘要与格子同源计算，切页时重渲染
|
||||
4. **[P2] 5/5 全完成无峰值状态** — 修：done==total 时标题换落章结语、数字转玉绿
|
||||
5. **[P2] 「章印落定」动效未交付** — 修：就地更新配合 just-stamped 类做 200ms 内阴影翻转，reduced-motion 退化
|
||||
|
||||
Suggested command: `$impeccable polish`（本流程由 le-app-design S6 承担同等修复循环）
|
||||
|
||||
## Persona Red Flags
|
||||
|
||||
**Casey（分心移动用户）**：已完成行绿勾一触即静默撤销（P1-1）；习惯全未完成时盖章按钮超出单手热区。
|
||||
**Sam（无障碍依赖）**：焦点销毁（P1-2）；「十一月 6」日期 aria-hidden 且无文本等价物；周格 7 格纯 div 无 role/label（对比 rate-track 做对了）；tab 选中态无形状冗余线索。
|
||||
**Alex（急性子高手）**：无批量盖章；盖章后统计页不更新无法验证；完成率条乱序难扫描。
|
||||
|
||||
## Minor Observations
|
||||
|
||||
心形 tab 图标→印章系；哑铃→跑鞋；streak=0 火焰语义尴尬；今日格指示仅换色；360 断点应上移至 380；统计页下方 250px 空白。
|
||||
|
||||
## Run Notes
|
||||
|
||||
- Target slug: `index-html`（/tmp/lead-e2e-habit/index.html）
|
||||
- ignore list: .impeccable/critique/ignore.md 不存在（无忽略项）
|
||||
- Assessment independence: dual-agent 并行派发，A（agent_5e37cec9）仅源码+截图+设计文档，B（agent_96a151e6）仅 CLI+文件事实；合成前互不可见
|
||||
- CLI detector: exit 2 / 2 findings（S5-detect 已入证据账本 calls.jsonl）
|
||||
- Browser visibility: 编排器已用宿主 IAB 完成 390/375 两档截图与交互实测（计数 3→4、toast 显示、无横滚）
|
||||
- Overlay injection: 跳过——fallback signal：「单一共享 IAB 浏览器面板由编排器占用，且编排器已在 390×844、375×740 两档完成截图与交互实测」
|
||||
- Live server cleanup: 未启动 live-server，无需清理；静态服务器 8741 端口由编排器管理
|
||||
- Temp-file cleanup: 无临时体文件
|
||||
@@ -1,64 +0,0 @@
|
||||
# Design Plan —— HabitFlow（S3 产物，按 frontend-design 两遍法）
|
||||
|
||||
> 依据：frontend-design 已装载（Skill 工具路径，sha256 d9197063…）；MASTER.md（ui-ux-pro-max 生成：Claymorphism / 琥珀+绿 / Varela Round + Nunito Sans）；BRIEF（Operate 模式，睡前场景）。
|
||||
|
||||
## 第一遍：设计计划
|
||||
|
||||
**题材世界**：习惯打卡的世界是「纸质习惯手账 + 印章/火漆」——每天往本子上盖一个章。打卡（punch/stamp）这个词本身就是印章隐喻。视觉取材：温纸、墨色、章印、双圈火漆、章按下去的软糯手感（正好接住 MASTER 的 Claymorphism：chunky、厚边、软阴影）。
|
||||
|
||||
**色板**（4–6 具名 hex，token 全部挂 MASTER 变量）：
|
||||
- `--paper 暖纸底` #FFFBEB（MASTER background）
|
||||
- `--ink 墨夜蓝` #142033（新派生：foreground #0F172A 提蓝一档，用于 hero 面板与正文，暖纸上的「墨水」）
|
||||
- `--amber 琥珀主色` #D97706（MASTER primary；印章金泥）
|
||||
- `--amber-deep 熔金` #B45309（primary 的按压/深态派生）
|
||||
- `--jade 完成玉绿` #059669（MASTER accent；已完成态与统计正值）
|
||||
- `--clay-border 陶线` #F3E4C8（border #FAEEE1 加深一档做 3px clay 厚边，避免在暖底上隐形）
|
||||
|
||||
**字体与角色**：Varela Round = 数字与拉丁（连续天数、百分比、星期字母——圆润 chunky 数字是 Claymorphism 的性格载体）；Nunito Sans = 拉丁正文；中文 PingFang SC（系统栈）= 界面正文。层级靠字重与块面，不靠斜体/单字变色。
|
||||
|
||||
**布局概念**：单列、左对齐、16px 页边；「安静的纸面 + 一枚重章」——顶部一枚墨夜蓝「今日印章」面板（唯一的深色块、唯一的圆卡），承载日期环+今日进度；其下是满宽的清单行（非浮动卡片，clay 分隔线分行）；底部双 Tab。统计页：七日章谱（7 列盖章格）+ 每习惯完成率条（墨底琥珀条）+ 总连续天数并入顶面板而非独立卡片。
|
||||
|
||||
```
|
||||
┌────────────────────────────┐ ┌────────────────────────────┐
|
||||
│ ██ 墨夜蓝今日印章面板 ██████ │ │ ██ 墨夜蓝面板（七日章谱）██ │
|
||||
│ ██ ◯周三 11.06 3/5 ██ │ │ ██ ▢▢▣▣▣▢▣ 本周16章 ██ │
|
||||
│ ████████████████████████ │ │ ████████████████████████ │
|
||||
│ │ │ │
|
||||
│ 今晚要盖的章 │ │ 各习惯完成率 │
|
||||
│ ┌──────────────────────┐ │ │ 读书 ▓▓▓▓▓▓░░ 78% │
|
||||
│ │(icon) 读书 12天 [盖]│ │ │ 冥想 ▓▓▓▓▓░░░ 64% │
|
||||
│ ├──────────────────────┤ │ │ 跑步 ▓▓▓▓░░░░ 57% │
|
||||
│ │(icon) 冥想 5天 [✓]│ │ │ ... │
|
||||
│ └──────────────────────┘ │ │ │
|
||||
│ │ │ │
|
||||
│ ────── [今日] [统计] ──── │ │ ────── [今日] [统计] ──── │
|
||||
└────────────────────────────┘ └────────────────────────────┘
|
||||
```
|
||||
|
||||
**原则**（这个产品独有的）：
|
||||
1. **盖章是仪式**：完成动作 = 按下一枚实体感印章（200ms 软按压 + 内阴影翻转 + 章印落定），是全页唯一 authored motion moment。
|
||||
2. **安静的纸面**：除顶部印章面板外不允许第二个深色块/浮动卡；信息靠 clay 分隔线与留白分组。
|
||||
3. **数字会说话**：连续天数用 Varela 粗圆数字 + 琥珀色，是纸面上唯一的高饱和焦点。
|
||||
4. **睡前不打扰**：暖色低刺激、无自动播放动效、reduced-motion 时印章动画退为瞬时状态切换。
|
||||
|
||||
## 第二遍：AI 味自检与修订
|
||||
|
||||
逐条对照 frontend-design 的特征清单：
|
||||
|
||||
1. **暖纸底 + 赤陶色**（tell #1）：色板确实落在暖底+琥珀家族——但这是 MASTER 数据支撑的方向（habit/warm/encouraging 类产品的匹配结果），不是自由轴上的偷懒。修订：用墨夜蓝面板 + clay 厚边 + 印章母题把它做成「手账」而不是「米色落地页」；且琥珀 #D97706 ≠ tell 里的 #D97757 赤陶。**保留，附理由。**
|
||||
2. **暗底单酸绿**（tell #2）：否——我们是亮底暖色系。
|
||||
3. **报纸 hairline/零圆角**（tell #3）：否——16–24px 圆角 + 3px 厚边是 Claymorphism 要求。
|
||||
4. **SaaS 卡片套件**（tell #4）：**修订**——初稿统计页各习惯是独立小卡，已改为满宽行 + 分隔线；全页深色圆卡只保留顶部一枚。
|
||||
5. **模板 chrome**（tell #5）：eyebrow/全大写标签/中点连接串/→后缀——全部不出现；标签用句子大小写中文；数据标签不用等宽字体，用 Varela 数字。
|
||||
6. **hero = 大数字+小标签+渐变**（默认处理）：**修订**——顶部不是「大数字卡」而是「今日印章」：双圈日戳 + 进度环，数字嵌在章面上；无渐变（craft-floor：渐变文字禁、渐变装饰慎）。
|
||||
|
||||
## 决策记录（与 MASTER 的冲突裁决）
|
||||
|
||||
| 冲突 | 裁决 | 依据 |
|
||||
|---|---|---|
|
||||
| 睡前场景 → 想做全暗色主题 | **不做**，用墨夜蓝面板承载深度 | 裁决表：风格体系是 pro-max 数据轴；暗色 MASTER 标 conditional；「一处重色」也符合 frontend-design 的 boldness 集中原则 |
|
||||
| #FAEEE1 边框在暖底上太弱 | 加深派生 #F3E4C8 作 clay 边 | 派生量记入 token 表，不越 MASTER 语义 |
|
||||
| 中文无 Varela 对应字 | 数字/拉丁用 Varela，中文系统栈 | 字体 personality 由数字承载（题材：天数与百分比正是主角） |
|
||||
| 图标 | 内联 SVG（lucide 线性、圆头、统一 2px 描边） | pro-max：禁 emoji 图标、一套图标一种描边 |
|
||||
|
||||
**结论：计划相对独特（手账印章世界 + 单一墨章 + clay 手感），可以进入构建。**
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 128 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 64 KiB |
Binary file not shown.
|
Before Width: | Height: | Size: 118 KiB |
@@ -1,63 +0,0 @@
|
||||
# le-app-design 集成测试报告（单元 + E2E）
|
||||
|
||||
- 日期：2026-11-07 · 环境：ZCode Desktop（darwin-arm64）· 测试执行：本会话（skill 创建过程内）
|
||||
- 结论：**全绿。三个上游 Skill 在同一设计任务中被真实安装、解析、调用并协同工作，全程留有机器可查证据。**
|
||||
- E2E 运行目录（完整证据）：本目录 + 源运行目录 `/tmp/lead-e2e-habit/le-app-design-runs/e2e-habit/`
|
||||
|
||||
## 一、被测对象
|
||||
|
||||
`skills/le-app-design/`：编排器 Skill。三个上游为必需依赖：ui-ux-pro-max（MIT）、frontend-design（Apache-2.0, Anthropic）、impeccable（Apache-2.0, pbakaus）。本测试验证的不是「文件存在」，而是「真实调用发生且产生效果」。
|
||||
|
||||
## 二、单元级测试
|
||||
|
||||
| # | 用例 | 结果 |
|
||||
|---|---|---|
|
||||
| 1 | check_deps 正例：三方解析 + 活性（pro-max 真跑检索 / impeccable 二进制 4.8.0 / frontend-design 原文 9390B + sha256） | ✅ exit 0，deps.json `ok=true` |
|
||||
| 2 | check_deps 负例：根全部指向不存在路径 | ✅ exit 1，逐项报缺失原因与安装指引 |
|
||||
| 3 | evidence_report 空账本 | ✅ FAIL exit 1（验收门有效） |
|
||||
| 4 | log_call exec / load / 失败命令 | ✅ 三形态记账；退出码透传（/usr/bin/false→1）；失败调用留痕 |
|
||||
| 5 | validate_skill 结构体检 | ✅ 10/10 |
|
||||
| 6 | trigger_eval 触发冒烟 | ✅ 11/11 一致（含 3 条单上游直连负例） |
|
||||
|
||||
过程中抓到并修复 1 个真实 bug：log_call.py 最初用 argparse REMAINDER，会把 `--run-dir` 等选项吞进子命令（命令 127、账本写错目录）——改为手工按裸 `--` 切分后全部通过。
|
||||
|
||||
## 三、E2E：HabitFlow 习惯打卡 App（S0–S7 全程真跑）
|
||||
|
||||
**任务**：移动 Web 高保真原型，今日页 + 统计页（390×844，兼容 375），Operate 模式。
|
||||
|
||||
| 阶段 | 上游真实调用（calls.jsonl 编号） | 实际效果 |
|
||||
|---|---|---|
|
||||
| S0 依赖门 | check_deps | 三方全绿，路径写入 deps.json |
|
||||
| S1 产品理解 | — | BRIEF.md（模式归属 Operate + 假设标注） |
|
||||
| S2 设计规范 | **ui-ux-pro-max** #1：`search.py --design-system --persist` | 产出 `design-system/habitflow/MASTER.md`（Claymorphism / 琥珀+绿 / Varela Round+Nunito Sans，91ms） |
|
||||
| S3 视觉探索 | **frontend-design** #2：宿主 Skill 工具装载 + load 记账（sha256 d9197063…） | design-plan.md：两遍法 + AI 味特征清单逐条自检 + 4 项冲突裁决记录 |
|
||||
| S4 高保真构建 | **impeccable** #3：craft-floor.md load | 可交互双屏原型 index.html；宿主 IAB 实测：打卡计数 3→4、toast 显示、375 无横滚 |
|
||||
| S5 设计审查 | **impeccable** #4 context（exit 0，走 SCOPED_EXISTING_ALLOWED 通道）、#5 critique.md load、#6 `detect --json`（exit 2 = 2 findings） | 双独立 sub-agent（agent_5e37cec9 / agent_96a151e6）按 critique.md 硬性要求并行评审：A 26/36 + 3×P1；B 2 findings 均属实；快照持久化 `.impeccable/critique/` + trend 首跑 |
|
||||
| S6 优化迭代 | **impeccable** #7 复跑 detect | 修复 3×P1 + 2×P2 + 7 项次要（撤章可见+恢复按钮、焦点保持、统计同源派生、5/5 峰值态、字阶 22→26px 等）；复测：flat-type-hierarchy 清零，仅剩 cream-palette（design-plan 已裁决保留：MASTER 钉死暖色系统+题材支撑，记录在案）；交互复验 4/4 预期通过 |
|
||||
| S7 交付 | evidence_report | **PASS**：三方各有 ≥1 成功调用，6 项产物全部存在 |
|
||||
|
||||
**三方协同的直接证据链**：MASTER.md（pro-max 产出）→ design-plan 的裁决表引用 MASTER tokens（frontend-design 方法论消费 pro-max 数据）→ 原型 CSS 变量全部挂 MASTER（两者共同落地）→ detect findings + A 评审引用 craft-floor 与 MASTER 语义（impeccable 审查前两者产出）→ S6 修复同时响应 A 的 P1 与 B 的 detector finding（字阶）。
|
||||
|
||||
## 四、验收门语义说明（诚实边界）
|
||||
|
||||
- impeccable 两行 exit=2 的 detect 记录在统计表中计为「失败调用」——这是 evidence_report 的保守口径；按 impeccable 自身契约 exit 2 = 有 findings 的成功扫描（stdout JSON 已留账本）。验收门不以这两行判 FAIL，也不依赖它们凑数（impeccable 另有 3 条成功调用）。
|
||||
- 浏览器 overlay 注入（live-server + detect.js）主动跳过，fallback 原因已写入 critique 报告 Run Notes；宿主 IAB 截图与交互实测承担了浏览器证据职责。
|
||||
- E2E 中停点 1/2 未实际停顿：题目选择时用户已授权整段测试跑完；真实设计任务中停点仍为回合终止硬约束。
|
||||
|
||||
## 五、已知限制
|
||||
|
||||
1. cream-palette finding 保留（有意裁决，见 S6）。
|
||||
2. detect 只扫 web markup（本交付形态即 Web，无影响）。
|
||||
3. 截图依赖宿主浏览器（本机无 Chrome，用 ZCode IAB 的 setViewportSize+screenshot 实现；无宿主浏览器的 runtime 按 runtimes.md 声明 fallback）。
|
||||
4. skill 触发行为尚未在新会话真实对话实测（trigger_eval 仅词面冒烟）——按惯例需新会话验证。
|
||||
|
||||
## 六、复现方式
|
||||
|
||||
```bash
|
||||
python3 skills/le-app-design/scripts/check_deps.py # S0
|
||||
# S2：log_call.py ui-ux-pro-max -- python3 ~/.agents/skills/ui-ux-pro-max/scripts/search.py "…" --design-system --persist …
|
||||
# S3：宿主 Skill 工具装载 frontend-design；log_call.py frontend-design --load ~/.agents/skills/frontend-design/SKILL.md
|
||||
# S5：sh ~/.agents/skills/impeccable/scripts/impeccable context / detect --json（经 log_call 包裹）
|
||||
python3 skills/le-app-design/scripts/evidence_report.py --run-dir <RUN> … # S7
|
||||
cat reports/e2e-habit/calls.jsonl # 全部 7 条原始调用记录
|
||||
```
|
||||
@@ -1,220 +0,0 @@
|
||||
{
|
||||
"skill": "le-app-design",
|
||||
"date": "2026-11-07",
|
||||
"threshold": 0.3,
|
||||
"prediction_mode": "coverage_fallback",
|
||||
"note": "词面冒烟测试；行为结论需真实对话实测（live_turns 字段手工补记）",
|
||||
"cases": [
|
||||
{
|
||||
"text": "帮我设计一个习惯打卡 App，要能看的高保真原型",
|
||||
"family": "full_design_cn",
|
||||
"bucket": "should_trigger",
|
||||
"coverage": 0.5,
|
||||
"coverage_hits": [
|
||||
"app",
|
||||
"保真",
|
||||
"原型",
|
||||
"我设",
|
||||
"真原",
|
||||
"计一",
|
||||
"设计",
|
||||
"高保"
|
||||
],
|
||||
"families_hit": [],
|
||||
"negative_hit": false,
|
||||
"predicted_trigger": true,
|
||||
"expected_trigger": true,
|
||||
"verdict": "pass"
|
||||
},
|
||||
{
|
||||
"text": "把这个产品想法做成可交互的 UI 原型，从设计到成品",
|
||||
"family": "full_design_cn",
|
||||
"bucket": "should_trigger",
|
||||
"coverage": 0.444,
|
||||
"coverage_hits": [
|
||||
"ui",
|
||||
"个产",
|
||||
"交互",
|
||||
"产品",
|
||||
"原型",
|
||||
"可交",
|
||||
"想法",
|
||||
"设计"
|
||||
],
|
||||
"families_hit": [],
|
||||
"negative_hit": false,
|
||||
"predicted_trigger": true,
|
||||
"expected_trigger": true,
|
||||
"verdict": "pass"
|
||||
},
|
||||
{
|
||||
"text": "design an app for my recipe startup, high-fidelity prototype",
|
||||
"family": "full_design_en",
|
||||
"bucket": "should_trigger",
|
||||
"coverage": 0.3,
|
||||
"coverage_hits": [
|
||||
"an",
|
||||
"app",
|
||||
"design"
|
||||
],
|
||||
"families_hit": [],
|
||||
"negative_hit": false,
|
||||
"predicted_trigger": true,
|
||||
"expected_trigger": true,
|
||||
"verdict": "pass"
|
||||
},
|
||||
{
|
||||
"text": "给我的工具类产品做一轮完整的设计：规范、视觉、原型加审查",
|
||||
"family": "full_pipeline",
|
||||
"bucket": "should_trigger",
|
||||
"coverage": 0.476,
|
||||
"coverage_hits": [
|
||||
"产品",
|
||||
"做一",
|
||||
"原型",
|
||||
"品做",
|
||||
"完整",
|
||||
"审查",
|
||||
"整的",
|
||||
"规范",
|
||||
"视觉",
|
||||
"设计"
|
||||
],
|
||||
"families_hit": [],
|
||||
"negative_hit": false,
|
||||
"predicted_trigger": true,
|
||||
"expected_trigger": true,
|
||||
"verdict": "pass"
|
||||
},
|
||||
{
|
||||
"text": "我要做个妈妈育儿 App，帮我把首页和详情页设计出来",
|
||||
"family": "app_screens",
|
||||
"bucket": "should_trigger",
|
||||
"coverage": 0.5,
|
||||
"coverage_hits": [
|
||||
"app",
|
||||
"和详",
|
||||
"情页",
|
||||
"把首",
|
||||
"计出",
|
||||
"设计",
|
||||
"详情",
|
||||
"页和",
|
||||
"首页"
|
||||
],
|
||||
"families_hit": [],
|
||||
"negative_hit": false,
|
||||
"predicted_trigger": true,
|
||||
"expected_trigger": true,
|
||||
"verdict": "pass"
|
||||
},
|
||||
{
|
||||
"text": "用 le-app-design 把这个 idea 变成原型",
|
||||
"family": "explicit_name",
|
||||
"bucket": "should_trigger",
|
||||
"coverage": 0.444,
|
||||
"coverage_hits": [
|
||||
"app",
|
||||
"design",
|
||||
"le",
|
||||
"原型"
|
||||
],
|
||||
"families_hit": [],
|
||||
"negative_hit": false,
|
||||
"predicted_trigger": true,
|
||||
"expected_trigger": true,
|
||||
"verdict": "pass"
|
||||
},
|
||||
{
|
||||
"text": "用 impeccable 审查一下这个页面",
|
||||
"family": "single_upstream_direct",
|
||||
"bucket": "should_not_trigger",
|
||||
"coverage": 0.429,
|
||||
"coverage_hits": [
|
||||
"impeccable",
|
||||
"审查",
|
||||
"页面"
|
||||
],
|
||||
"families_hit": [],
|
||||
"negative_hit": true,
|
||||
"predicted_trigger": false,
|
||||
"expected_trigger": false,
|
||||
"verdict": "pass"
|
||||
},
|
||||
{
|
||||
"text": "ui-ux-pro-max 帮我查个配色",
|
||||
"family": "single_upstream_direct",
|
||||
"bucket": "should_not_trigger",
|
||||
"coverage": 0.5,
|
||||
"coverage_hits": [
|
||||
"max",
|
||||
"pro",
|
||||
"ui",
|
||||
"ux"
|
||||
],
|
||||
"families_hit": [],
|
||||
"negative_hit": true,
|
||||
"predicted_trigger": false,
|
||||
"expected_trigger": false,
|
||||
"verdict": "pass"
|
||||
},
|
||||
{
|
||||
"text": "帮我写一篇公众号文章",
|
||||
"family": "other_le_skill",
|
||||
"bucket": "should_not_trigger",
|
||||
"coverage": 0.0,
|
||||
"coverage_hits": [],
|
||||
"families_hit": [],
|
||||
"negative_hit": true,
|
||||
"predicted_trigger": false,
|
||||
"expected_trigger": false,
|
||||
"verdict": "pass"
|
||||
},
|
||||
{
|
||||
"text": "给我生成一张 App 封面图",
|
||||
"family": "image_only",
|
||||
"bucket": "should_not_trigger",
|
||||
"coverage": 0.25,
|
||||
"coverage_hits": [
|
||||
"app",
|
||||
"生成"
|
||||
],
|
||||
"families_hit": [],
|
||||
"negative_hit": false,
|
||||
"predicted_trigger": false,
|
||||
"expected_trigger": false,
|
||||
"verdict": "pass"
|
||||
},
|
||||
{
|
||||
"text": "这个按钮的点击事件没反应，帮我修一下",
|
||||
"family": "pure_dev",
|
||||
"bucket": "should_not_trigger",
|
||||
"coverage": 0.0,
|
||||
"coverage_hits": [],
|
||||
"families_hit": [],
|
||||
"negative_hit": false,
|
||||
"predicted_trigger": false,
|
||||
"expected_trigger": false,
|
||||
"verdict": "pass"
|
||||
},
|
||||
{
|
||||
"text": "把这个页面布局调好看一点",
|
||||
"family": "local_tweak",
|
||||
"bucket": "near_neighbor",
|
||||
"coverage": 0.1,
|
||||
"coverage_hits": [
|
||||
"页面"
|
||||
],
|
||||
"families_hit": [],
|
||||
"negative_hit": false,
|
||||
"predicted_trigger": false,
|
||||
"expected_trigger": null,
|
||||
"verdict": "boundary"
|
||||
}
|
||||
],
|
||||
"summary": {
|
||||
"scored": 11,
|
||||
"mismatch": 0,
|
||||
"pass_rate": 1.0
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,67 @@
|
||||
# Le SPEC
|
||||
|
||||
> 智能需求分析与 SPEC 生成总控：把模糊、零散、矛盾的想法，经**真实集成的** Grill 深度访谈、Think 方案挑战、OpenSpec 规格工程，转化为可执行、可测试的正式 SPEC。VibeCoding / AI Coding 工作流的需求工程入口。
|
||||
|
||||
**状态**：rigorous 档 ｜ **正式名称 Le SPEC，技术标识 `le-spec`** ｜ 优先适配 Codex，兼容 ZCode / Claude Code
|
||||
|
||||
## 它解决什么问题
|
||||
|
||||
你有一堆没想清楚的想法（甚至互相矛盾），直接丢给 Coding Agent 会得到一堆它自行猜测的「需求」。Le SPEC 在编码之前接管：先访谈把该想清楚的想清楚，再挑战不合理方案，最后产出结构化的 OpenSpec 规格（产品需求 / 技术设计 / 开发任务三分离），让 Coding Agent 不用猜。
|
||||
|
||||
## 架构：真实集成，不是借鉴
|
||||
|
||||
| 引擎 | 来源 | 在 Le SPEC 中的职责 | 调用方式 |
|
||||
|---|---|---|---|
|
||||
| grilling (+ domain-modeling) | [mattpocock/skills](https://github.com/mattpocock/skills) | Phase 2 深度访谈：design tree / frontier 轮次 / 推荐答案 | Skill 工具按名调用，或 Read 其原始 SKILL.md 遵循原义；记调用账本 |
|
||||
| think | [tw93/Waza](https://github.com/tw93/Waza) | Phase 3 方案分析：单一推荐、Simplicity Gate、premise collapse | 同上 |
|
||||
| openspec CLI + skills | [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) | Phase 5 规格生成（proposal/specs/design/tasks）、validate、变更与归档 | `openspec` CLI 真实执行（new change / instructions / validate） |
|
||||
|
||||
「真实调用」的证据是**调用账本**（项目内 `openspec/le-spec/ledger.jsonl`）：每次依赖交互记录 dep/kind/method/cmd/exit。审查与交付阶段核对账本，无账本条目视为未发生。协议细节见 [references/dependencies.md](references/dependencies.md)。
|
||||
|
||||
## 安装
|
||||
|
||||
```bash
|
||||
# 1. 依赖（一次性；skills.sh 落 ~/.agents/skills，软链各 runtime）
|
||||
npx skills@latest add mattpocock/skills --skill grilling grill-me grill-with-docs domain-modeling -g -a claude-code codex
|
||||
npx skills@latest add tw93/Waza --skill think -g -a claude-code codex
|
||||
npx skills@latest add Fission-AI/OpenSpec --skill openspec-propose openspec-new-change openspec-update-change openspec-verify-change openspec-archive-change openspec-apply-change openspec-explore -g -a claude-code codex
|
||||
npm install -g @fission-ai/openspec@latest
|
||||
|
||||
# 2. 本 skill（MetaSkill 仓库真源 + 软链）
|
||||
ln -sfn <本仓库路径>/skills/le-spec ~/.agents/skills/le-spec
|
||||
|
||||
# 3. 验证
|
||||
python3 ~/.agents/skills/le-spec/scripts/deps_check.py # required 全绿 exit 0
|
||||
```
|
||||
|
||||
目标项目无需预装 OpenSpec：Phase 5 检测到无根时会征求用户意见再 `openspec init`。
|
||||
|
||||
## 使用
|
||||
|
||||
自然语言直接开始，例如：
|
||||
|
||||
- 「帮我把这个想法整理成 spec：我想做一个……」（零散长文也行，直接贴）
|
||||
- 「先 grill 我一下，把这个功能想透」
|
||||
- 「需求变了，更新之前那个 spec」
|
||||
|
||||
中断随时可恢复：状态存 `<项目>/openspec/le-spec/state.md`，新会话说「继续上次的 le-spec 分析」即可。产出批准后：实现交给 Coding Agent（openspec-apply-change 工作流），需求变更走 openspec-update-change，完成归档 openspec-archive-change。
|
||||
|
||||
## 工作流（逻辑七阶段，按复杂度自适应压缩）
|
||||
|
||||
```
|
||||
0 识别分级 → 1 需求结构化(十类分拣) → 2 Grill 访谈(动态轮次·每4轮检查点·收敛即停)
|
||||
→ 3 Think 挑战(有分歧才进) → 4 反向验收(独立工程师视角找"还得猜什么")
|
||||
→ 5 OpenSpec 生成(validate 通过) → 6 四视角独立审查 → 7 用户批准(硬停点)
|
||||
```
|
||||
|
||||
详见 [SKILL.md](SKILL.md) 与 [references/](references/)。
|
||||
|
||||
## 安全边界
|
||||
|
||||
- 未经用户明确批准不进入实现（Phase 7 回合终止硬停点）。
|
||||
- required 依赖缺失 → 停止并给安装命令，不以模拟调用冒充。
|
||||
- 不编造业务规则/验收标准；AI 推荐方案标 [建议]，不冒充已批准。
|
||||
|
||||
## 已知限制
|
||||
|
||||
见 [reports/test-report.md](reports/test-report.md)（测试 A-I 执行记录与未验证项）。
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
name: le-spec
|
||||
description: |
|
||||
Le SPEC —— 智能需求分析与 SPEC 生成总控：把模糊、零散、矛盾的自然语言想法，经真实集成的 Grill 深度访谈、Think 方案挑战、OpenSpec 规格工程，转化为可执行、可测试的正式 SPEC。
|
||||
何时触发：用户想从想法或零散需求出发，先梳理清楚再开发（"帮我把这个想法整理成 spec""我要做个 App，先分析下需求""这些需求有点乱，帮我梳理""先想清楚再写代码""来一场需求访谈""write a spec""refine these requirements"）；提到 grill / openspec / 需求工程 / SPEC 生成；已有项目新增功能或变更需求要走规格（"给这个功能写个 spec""需求变了，更新规格"）。
|
||||
不要触发：已批准 SPEC 的实现与编码（交给 Coding Agent / openspec-apply-change）；纯 PRD/需求文档的润色与排版；与需求澄清无关的普通文档写作；用户明说"别做 spec、直接写代码、直接改代码"。
|
||||
metadata:
|
||||
author: Leroy
|
||||
version: "1.0.0"
|
||||
runtimes: zcode, claude-code, codex
|
||||
requires: grilling + grill-me/grill-with-docs + domain-modeling (mattpocock/skills), think (tw93/Waza), openspec CLI + openspec-* skills (Fission-AI/OpenSpec)
|
||||
---
|
||||
|
||||
# Le SPEC —— 需求分析与 SPEC 生成总控
|
||||
|
||||
用户负责表达意图与做关键决策；你负责理解、挖掘、思考、推荐、整理与验证。
|
||||
产出物不是"更漂亮的需求文档"，而是**在开始编码前把该想清楚的都想清楚**的正式 SPEC。
|
||||
|
||||
## 三条铁律（先于一切流程）
|
||||
|
||||
1. **真实调用，不冒充。** 访谈必须真实加载 `grilling` 原文并遵循其 design-tree/frontier 机制；方案分析必须真实加载 `think` 原文；规格必须经 `openspec` CLI 生成与校验。禁止用自拟提示词模拟依赖行为。每次依赖交互记入调用账本（见下），无账本条目视为未发生。
|
||||
2. **不重复、不复盘。** 已确认的决策写入状态文件后，后续任何阶段（Think / 验收 / 审查）只消费不重问；发现新不确定性时做**针对性**追问，不重启流程。
|
||||
3. **批准前不编码。** Phase 7 是回合终止硬停点：向用户呈交确认包后终止回合，未经用户明确批准，不得创建/修改任何实现代码，不得执行 openspec-apply-change。
|
||||
|
||||
## 阶段机
|
||||
|
||||
| 阶段 | 做什么 | 依赖调用 | 退出条件 |
|
||||
|---|---|---|---|
|
||||
| 0 识别 | 判项目类型、只读检查、复杂度分级 | `openspec context --json`（探测已有根） | 复杂度定档、上下文清单成形 |
|
||||
| 1 理解 | 原始需求结构化（十类分拣） | — | `state.md` 初始化完成 |
|
||||
| 2 访谈 | Grill 深度访谈 | **grilling**；已有代码库时叠加 **domain-modeling** | 收敛标准满足（见 workflow.md） |
|
||||
| 3 方案 | 方案分析与挑战 | **think**（无实质分歧可跳过） | 推荐方案获用户确认 |
|
||||
| 4 验收 | 需求反向验收（独立工程师视角） | 独立子代理（fresh context） | 无 blocking 级未决问题 |
|
||||
| 5 规格 | OpenSpec 生成正式 SPEC | **openspec CLI** + openspec-propose/new-change 工作流 | artifacts 齐全且 `validate` 通过 |
|
||||
| 6 审查 | SPEC 独立质量审查（四视角） | 独立子代理 + `openspec validate` | 审查问题清零或降为非阻塞 |
|
||||
| 7 交接 | 用户确认与交接 | — | 用户明确批准 → 交给 Coding Agent |
|
||||
|
||||
- 每阶段详细规程：[workflow.md](references/workflow.md)
|
||||
- 依赖真实调用协议：[dependencies.md](references/dependencies.md)（**Phase 2/3/5 入口必读**）
|
||||
- Phase 4 规程：[acceptance.md](references/acceptance.md)；Phase 6 规程：[review.md](references/review.md)
|
||||
|
||||
阶段是逻辑流不是机械串行：simple 档压缩执行（见 workflow.md 复杂度分档），用户可随时切换讨论模块、修改需求、查看草稿——但**只能向前跳过 AI 侧环节，不能跳过用户确认停点**。
|
||||
|
||||
## 启动协议（每次触发本 skill 时）
|
||||
|
||||
1. 定位项目 OpenSpec 根：`openspec context --json`。有根且存在 `<root>/openspec/le-spec/state.md` → 读状态，从其「下一步」恢复，不重做已完成阶段。
|
||||
2. 无状态文件 → 全新分析：跑 `python3 <skill_dir>/scripts/deps_check.py` 检查依赖（见铁律 1）。缺失 required 级依赖 → 停止并给出精确安装命令（见 dependencies.md），不得以降级模拟继续。
|
||||
3. 按 Phase 0 → 1 进入。
|
||||
|
||||
## 状态与账本（持久化，跨会话恢复）
|
||||
|
||||
- `<root>/openspec/le-spec/state.md` —— 阶段、已确认决策、否定方案、开放问题、假设、下一步、访谈轮次计数。每轮重要交互后增量更新；用户变更需求时记录影响范围。
|
||||
- `<root>/openspec/le-spec/ledger.jsonl` —— 调用账本，经 `scripts/ledger.py append` 记录每次依赖交互（dep / kind / cmd / exit / summary）。Phase 7 交付与 Phase 6 审查以账本为真实调用证据。
|
||||
- 项目无 OpenSpec 根时暂用 `.le-spec/` 存放，待 Phase 5 init 后迁移。
|
||||
|
||||
## 停手点（回合终止硬约束）
|
||||
|
||||
1. 依赖检查失败 → 停，给安装指引。
|
||||
2. Phase 2 每轮问完 → 终止回合等用户回答；Phase 3 推荐方案给出 → 等用户决断。
|
||||
3. Phase 4 发现 blocking 问题 → 终止回合，向用户澄清后才能进 Phase 5。
|
||||
4. Phase 7 呈交确认包 → **终止回合**；未获明确批准不得动实现代码。
|
||||
5. 用户要求删除/重写已批准 SPEC 的大范围内容 → 停，先确认影响范围。
|
||||
|
||||
## 反例黑名单
|
||||
|
||||
- 不把临时想法当已确认需求，不把 AI 推荐方案当用户已批准。
|
||||
- 不为凑轮数追问，也不为省事跳过 blocking 问题。
|
||||
- 不在 SPEC 里编造业务规则、验收标准或技术约束。
|
||||
- 不把产品需求、技术设计、开发任务混写进一个文件（OpenSpec 三 artifact 天然分离，遵循它）。
|
||||
- 不在旧会话假设新装依赖"应该可用"——调用前先 deps_check 或确认账本路径可写。
|
||||
@@ -0,0 +1,23 @@
|
||||
{
|
||||
"_说明": "Le SPEC 触发用例。应触发：从想法/零散需求出发要梳理成规格；不应触发：已批准 SPEC 的实现、纯文案、无关任务。family 标注场景族。",
|
||||
"recommended_threshold": 0.3,
|
||||
"negative_patterns": ["直接写代码", "直接改代码", "别做 spec", "别做访谈", "润色", "排版", "只要总结", "翻译一下", "帮我实现"],
|
||||
"should_trigger": [
|
||||
{"text": "帮我把这个想法整理成 spec，我想做一个记账 App", "family": "idea_to_spec"},
|
||||
{"text": "这些需求有点乱，你先帮我梳理梳理，想清楚了再动手", "family": "messy_requirements"},
|
||||
{"text": "我要做个 App，先分析下需求，来一场深度访谈", "family": "explicit_interview"},
|
||||
{"text": "用 openspec 给这个新功能写个正式的规格", "family": "openspec_named"},
|
||||
{"text": "先 grill 我一下，把这个方案想透再写规格", "family": "grill_named"},
|
||||
{"text": "需求变了，把之前批准的 spec 更新一下，加一个导出功能", "family": "spec_change"},
|
||||
{"text": "refine these rough requirements into a testable spec", "family": "en_trigger"}
|
||||
],
|
||||
"should_not_trigger": [
|
||||
{"text": "spec 已经批了，现在开始实现 tasks 里的任务吧", "family": "implementation_phase"},
|
||||
{"text": "帮我把这份 PRD 润色一下排版更好看", "family": "doc_polish"},
|
||||
{"text": "这段代码有个 bug，帮我修一下", "family": "unrelated_task"},
|
||||
{"text": "别做 spec 了直接改代码，改完告诉我就行", "family": "explicit_skip"}
|
||||
],
|
||||
"near_neighbor": [
|
||||
{"text": "帮我把这个想法整理成 skill", "family": "meta_confusion_should_route_le_meta_skill"}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,36 @@
|
||||
# Phase 4：需求反向验收规程
|
||||
|
||||
**问题意识**：Phase 4 检查的不是"文档漂不漂亮"，而是**需求是否明确到足以形成规格**。核心一问：
|
||||
|
||||
> "一个完全没有参与讨论的资深工程师现在接手开发，哪些重要产品行为仍然需要他自己猜测？哪些必须回头找需求负责人确认？"
|
||||
|
||||
## 执行方式（按优先级）
|
||||
|
||||
1. **子代理独立审查（首选）**：用 Agent 工具派 fresh-context 子代理（general-purpose 或 Explore）。提示词要点：
|
||||
- 角色：资深开发工程师，第一次见到这个项目；
|
||||
- 输入：只给 state.md 路径（+ 已有 openspec specs 路径，如有）——**不给会话历史、不给 Le SPEC 的阶段叙事**，确保视角独立；
|
||||
- 任务：逐条检查下列清单，输出"我会被迫猜测/必须确认"的清单，每条注明影响哪个功能点与后果严重度；
|
||||
- 产出格式：问题列表（问题/影响/严重度建议/建议澄清方式）。
|
||||
2. **无子代理能力时的降级**：自审前显式重置角色（"放下前文立场，作为首次接手的工程师仅凭 state.md 判断"），只允许引用 state.md 与项目文件内容。**必须在产出中声明"本轮为同上下文自审，独立性弱于子代理审查"**——不装作独立。
|
||||
|
||||
## 检查清单
|
||||
|
||||
- [ ] 用户流程有断点（走不到下一步/回不去）
|
||||
- [ ] 功能之间缺关联规则（A 发生时 B 如何）
|
||||
- [ ] 数据关系歧义（谁拥有谁、一对多还是多对多、删除级联）
|
||||
- [ ] 状态机不完整（缺状态、缺转换、缺终态）
|
||||
- [ ] 权限与业务边界不明（谁能做什么、越界怎样）
|
||||
- [ ] 异常场景缺处理原则（失败/超时/并发/空数据）
|
||||
- [ ] 需求间冲突（同一对象两种定义）
|
||||
- [ ] 未经确认的重要默认假设（state.md 里的 [默认] 项逐条复核用户知情度）
|
||||
- [ ] 验收判据缺失（做完了怎么算"对"）
|
||||
|
||||
## 分级与处置
|
||||
|
||||
| 级别 | 判定 | 处置 |
|
||||
|---|---|---|
|
||||
| blocking | 不澄清就无法实现核心行为 / 两种理解导致完全不同的产品 | 终止回合向用户澄清（用 grilling 单轮格式，记账本） |
|
||||
| major | 影响正确性但可从已确认决策推导 | 推导入 state.md 并标注依据；推导不了升 blocking |
|
||||
| minor | 边缘场景、可延后 | 记开放问题，进 SPEC 的"非阻塞事项" |
|
||||
|
||||
更新后**只复核受影响项**，不重跑全清单。清零 blocking → 进 Phase 5。
|
||||
@@ -0,0 +1,100 @@
|
||||
# 依赖真实调用协议
|
||||
|
||||
Le SPEC 的价值建立在三个外部能力**真实运行**之上。本文件定义每个依赖的本体位置、调用条件、调用方式、上下文交接与失败处理。
|
||||
|
||||
## 0. 调用方式总则（skill 类依赖）
|
||||
|
||||
所有 skill 类依赖（grilling / domain-modeling / think / openspec-*）按以下顺序选择调用方式：
|
||||
|
||||
1. **宿主 Skill 工具**：若当前 runtime 提供 Skill 工具且该依赖已在可用列表中，用 Skill 工具按名调用。
|
||||
2. **文件直读**：否则用 Read 读取依赖原始 `SKILL.md` **全文**，把其内容作为当前回合的执行指令遵循。这不是降级——skill 的本质就是指令文档，宿主 Skill 工具内部做的也是加载原文；直读与工具调用在语义上等价，前提是**读原文、遵循原义**（包括其引用的 references 子文件，如 think 的 mode-evaluation.md）。
|
||||
|
||||
两种方式都必须：
|
||||
- 先记入调用账本（`ledger.py append --dep <name> --kind skill-load --method skill-tool|file-read`）；
|
||||
- 遵循原文机制，不自拟替代提示词（例如 grilling 的 frontier 轮次格式 ❓Q/➡️推荐、think 的 Simplicity Gate、openspec-propose 的 artifact 循环）。
|
||||
|
||||
## 1. grilling —— 访谈引擎
|
||||
|
||||
| 项 | 值 |
|
||||
|---|---|
|
||||
| 来源 | github.com/mattpocock/skills（productivity/grilling） |
|
||||
| 本体 | `~/.agents/skills/grilling/SKILL.md`（软链解析后读真源） |
|
||||
| 入口语义 | `grill-me` = 只调 grilling；`grill-with-docs` = grilling + domain-modeling。Le SPEC 按此原义路由：**全新项目 → grilling；已有代码/文档 → grilling + domain-modeling** |
|
||||
| 调用时机 | Phase 2 全程（simple 档也走它，只是轮数少） |
|
||||
| 输入交接 | state.md 的「已确认决策」「开放问题」两节——已确认项不得再问；开放问题构成 design tree 的初始节点 |
|
||||
| 原生机制（必须保留） | design tree、frontier（前置决策已定的可问集合）、每轮问整个 frontier 并给推荐答案、答案重塑树、"事实自己查（可派子代理）、决策问用户"、frontier 空且用户确认共识才算完 |
|
||||
| 产物 | 每轮问题（❓Q1… ➡️推荐格式）；用户回答由 Le SPEC 写入 state.md |
|
||||
|
||||
**Le SPEC 叠加规则**（不与原义冲突）：
|
||||
- 每轮用户回答后：决策入 state.md，轮次 +1；每约 4 轮做一次检查点（见 workflow.md Phase 2）。
|
||||
- grilling 的"会话结束条件 = frontier 空"之外，Le SPEC 用需求收敛标准（workflow.md）做结束判定；两者取先到者，且需向用户确认共识后收口。
|
||||
- 已有项目时叠加 domain-modeling：访谈中发现术语模糊 → 按其"Sharpen fuzzy language"当场澄清；硬决策按其三条件（难逆转/无上下文会困惑/真实取舍）写 ADR。GLOSSARY.md/ADR 由 domain-modeling 机制管理，Le SPEC 不另建。
|
||||
|
||||
## 2. think —— 方案分析引擎
|
||||
|
||||
| 项 | 值 |
|
||||
|---|---|
|
||||
| 来源 | github.com/tw93/Waza（skills/think） |
|
||||
| 本体 | `~/.agents/skills/think/SKILL.md` |
|
||||
| 调用时机 | Phase 3：出现重大产品分歧、技术选型、架构取舍、过度设计疑虑、值不值得判断。**simple 档且无实质争议 → 跳过并注明** |
|
||||
| 模式选择（遵循其原生定义） | 定义清楚的修复计划 → Lightweight Mode；价值/存废判断 → 读 references/mode-evaluation.md；批量诉求 → mode-triage.md。默认全模式 |
|
||||
| 输入交接 | state.md 已确认需求 + 约束 + 已否定方案 + 待选方案。think 的 "Durable Context Preflight" 要求读项目 AGENTS.md/CLAUDE.md 索引——照做 |
|
||||
| 原生机制（必须保留） | 先查官方方案、推荐单一方案+理由+一个替代、premise collapse（最脆弱假设）、attack angles（外部依赖/并发/迁移时）、Simplicity Gate、批准前不动代码 |
|
||||
| 产物 | 推荐方案 + 关键决策 + 风险 + 被否替代 → 写入 state.md「已确认决策」（待用户批准的标 [待批准]） |
|
||||
|
||||
**回流规则**：think 发现新的重大需求不确定性（Blocking ambiguities）→ 带回 Phase 2 用 grilling 格式做**针对性**追问（不是重启访谈），解决后回到 Phase 3 继续。
|
||||
|
||||
## 3. OpenSpec —— 规格工程引擎（CLI + skills 双通道）
|
||||
|
||||
| 项 | 值 |
|
||||
|---|---|
|
||||
| 来源 | github.com/Fission-AI/OpenSpec（npm: @fission-ai/openspec） |
|
||||
| CLI | `openspec`（PATH 中，≥1.3 可用 artifact 工作流；本 skill 按 1.16.x 验证） |
|
||||
| skills | `~/.agents/skills/openspec-{propose,new-change,update-change,verify-change,archive-change,apply-change,explore}/SKILL.md` |
|
||||
| 调用时机 | Phase 0（context 探测）、Phase 5（生成）、Phase 6（validate）、Phase 7 后的变更与归档 |
|
||||
|
||||
**Phase 5 标准路径**（遵循 openspec-propose 原生步骤，Le SPEC 已备齐输入故跳过其澄清步）：
|
||||
|
||||
```bash
|
||||
openspec context --json # 定位根；root:null → 见下"项目初始化"
|
||||
openspec new change "<kebab-name>" # 脚手架（默认 spec-driven schema）
|
||||
openspec status --change "<name>" --json # artifact 顺序与路径
|
||||
openspec instructions <artifact> --change "<name>" --json # 逐个：proposal → specs → design → tasks
|
||||
# 按 template + instruction 撰写每个 artifact 文件
|
||||
openspec validate "<name>" # 必须通过
|
||||
```
|
||||
|
||||
- **artifact 分工是 OpenSpec 原生的**：`specs/` = 产品需求（行为契约、Requirement/Scenario）、`design.md` = 技术设计（HOW，conditional）、`tasks.md` = 开发任务（checkbox）、`proposal.md` = Why/What/Capabilities。不混写。
|
||||
- **项目初始化边界**（遵循其 Project check 原义）：`root:null` 且用户未提 OpenSpec → 停下问用户：init（`openspec init --tools none`，工具注入由用户后续决定）/ 走 store / 不用 OpenSpec 本次降级输出。绝不让 `new change` 的副作用悄悄创建根。
|
||||
- **变更管理**：SPEC 已批准后的需求变化 → openspec-update-change 工作流（新 change 或修订现有），归档 → openspec-archive-change。Le SPEC 交接到此为止，apply 交给 Coding Agent。
|
||||
|
||||
## 4. 依赖检查与失败处理
|
||||
|
||||
`scripts/deps_check.py`（--json 供脚本、默认人读输出）：
|
||||
|
||||
| 依赖 | 级别 | 缺失时 |
|
||||
|---|---|---|
|
||||
| grilling skill | required | 停止访谈阶段，输出安装命令（下表），不降级为普通问答 |
|
||||
| think skill | required（Phase 3 入口） | 方案分歧时停止并提示安装；无分歧场景不受影响 |
|
||||
| openspec CLI | required（Phase 5 入口） | 停止规格生成，提示 `npm install -g @fission-ai/openspec` |
|
||||
| openspec-* skills | recommended | CLI 工作流仍可走（Phase 5 标准路径即 CLI 驱动），但提示安装以获得完整工作流指令 |
|
||||
| domain-modeling skill | recommended（已有项目时升 required） | 已有项目的访谈照常，但声明"术语沉淀与 ADR 不可用" |
|
||||
| grill-me / grill-with-docs | optional（入口薄壳） | 不影响——Le SPEC 直接路由到底层组合 |
|
||||
|
||||
安装命令（真实可执行，2026-11 验证）：
|
||||
|
||||
```bash
|
||||
npx skills@latest add mattpocock/skills --skill grilling grill-me grill-with-docs domain-modeling -g
|
||||
npx skills@latest add tw93/Waza --skill think -g
|
||||
npx skills@latest add Fission-AI/OpenSpec --skill openspec-propose openspec-new-change openspec-update-change openspec-verify-change openspec-archive-change openspec-apply-change openspec-explore -g
|
||||
npm install -g @fission-ai/openspec@latest
|
||||
```
|
||||
|
||||
**失败语义**：CLI 非零退出 ≠ 永远失败（如 `openspec list` 在无根项目返回非零，那是"未初始化"的答案不是崩溃）——读 JSON 输出判断，不盲目重试。skill 加载失败（文件不存在/为空）→ 记账本（method=file-read, exit=1）→ 按缺失处理。**任何情况下不得用模拟输出冒充调用成功。**
|
||||
|
||||
## 5. 防重复机制
|
||||
|
||||
- grilling 问过的 → state.md「已确认决策」，think 直接消费；
|
||||
- think 已否定的方案 → state.md「已否定方案」，Phase 4/6 审查不再重提，除非发现新证据；
|
||||
- OpenSpec artifacts 已写内容 → Phase 6 审查对照 state.md 检查一致性，不重新发起需求讨论；
|
||||
- 每阶段入口先读 state.md 的阶段标记，已完成阶段不重做（中断恢复同理）。
|
||||
@@ -0,0 +1,35 @@
|
||||
# Phase 6：SPEC 独立质量审查规程
|
||||
|
||||
**问题意识**：Phase 4 检查"需求是否明确到足以形成规格"；Phase 6 检查**"规格是否准确到足以指导开发和测试"**。审查对象是 OpenSpec artifacts（proposal/specs/design/tasks），不是重新审需求——需求问题应已在 Phase 4 清零。
|
||||
|
||||
## 审查组成（三路并行）
|
||||
|
||||
1. **四视角子代理审查**（首选 fresh-context 子代理；降级规则同 acceptance.md，须声明独立性等级）。输入：change 目录全部 artifact 路径 + state.md 路径 + （已有项目时）相关既有 specs 路径。四视角各答各的：
|
||||
|
||||
| 视角 | 追问 |
|
||||
|---|---|
|
||||
| 产品 | 完整表达真实需求了吗？有无遗漏功能？有无混入用户未确认的新要求（对照 state.md 逐条溯源）？ |
|
||||
| 架构 | 与现有系统/既有 specs 冲突？重大技术风险？不必要的复杂度（对照 design.md 的 Decisions 与 think 结论）？ |
|
||||
| 开发 | 还要猜什么？缺数据/流程/状态定义？互相矛盾的要求（specs 内部 + specs↔design↔tasks）？ |
|
||||
| 测试 | 每条 Requirement 的 Scenario 可执行可判定的吗？正常/异常/边界覆盖？有没有判不了 pass/fail 的模糊表述？ |
|
||||
|
||||
2. **CLI 校验**：`openspec validate "<change>"`（严格模式可用则用）+ `openspec status --change "<name>"` 确认 artifact 齐全。
|
||||
3. **账本核对**：`ledger.py check` 确认 grilling/think/openspec 均有真实调用记录；缺失 → 回补（真实调用）或如实声明。
|
||||
|
||||
## 产出格式（每问题一行，不许无依据打分）
|
||||
|
||||
```markdown
|
||||
| # | 视角 | 严重度 | 问题（引 artifact 行文） | 影响 | 修正建议 | 阻塞? |
|
||||
```
|
||||
|
||||
严重度：blocker（规格错误/矛盾/无法实现或测试）｜major（会导致误解或返工）｜minor（措辞与边缘）。
|
||||
|
||||
## 修正循环
|
||||
|
||||
blocker/major 逐条修正 artifact → 只复验受影响项（重跑 validate + 相关视角复查）→ 清零或全部降为 minor 后出结论：
|
||||
|
||||
```markdown
|
||||
审查结论：blocker 0 / major 0 / minor N（列表，随 SPEC 一并呈交）
|
||||
```
|
||||
|
||||
修正时保持铁律 2：修正只动规格文本与事实呈现，不重启需求讨论；发现规格确实承载不了的需求歧义 → 回 Phase 4 流程处理。
|
||||
@@ -0,0 +1,106 @@
|
||||
# 七阶段工作流规程
|
||||
|
||||
阶段是逻辑流。每阶段入口先读 state.md 阶段标记，已完成的跳过。
|
||||
|
||||
## Phase 0：项目识别与上下文理解
|
||||
|
||||
1. 判任务类型：全新产品 / 已有产品加功能 / 已有功能修改 / 复杂业务模块 / 架构重构 / 探索性想法。
|
||||
2. 有代码库时只读检查（按复杂度控制深度，simple 档可缩到 3-5 分钟扫读）：
|
||||
- 项目结构、技术栈、入口文件；已有文档与 `openspec/specs/`（`openspec context --json` 探测）；GLOSSARY/ADR（domain-modeling 的管理物）；近期 git log 的设计决策线索。
|
||||
- **能从代码和文档确认的事实，绝不进访谈问题**（grilling 原义：事实自己查，决策问用户）。
|
||||
3. 复杂度定档（可随讨论动态升降级，升降级写入 state.md 并注明理由）：
|
||||
|
||||
| 档 | 特征 | 流程 |
|
||||
|---|---|---|
|
||||
| simple | 字段/筛选/文案级修改，影响单一界面或接口 | 0 → 1 → grilling 单轮（≤1 轮）→ （跳过 3）→ 清单式 4 → 5（propose，design 多为 skip）→ 快速 6 → 7 |
|
||||
| medium | 新功能模块（日历、用户管理级） | 全流程，3 按需 |
|
||||
| complex | 全新产品、多角色/多流程系统、架构重构 | 全流程；3 必用于重大决策；访谈允许多轮充分展开 |
|
||||
|
||||
## Phase 1：原始需求理解
|
||||
|
||||
对用户原始输入做**十类分拣**，产出写入 state.md：
|
||||
|
||||
1. 明确需求 2. 目标与期望结果 3. 用户角色与场景 4. 未定想法 5. 用户假设 6. 约束（产品+技术） 7. 矛盾描述（列出冲突双方与出处） 8. 重要缺失信息 9. 已否定方案 10. 明确不做
|
||||
|
||||
规则：保留原始措辞的关键短语与来源（哪条消息）；不擅自增需求；临时想法标注 [未定]；AI 推荐方案标注 [建议]，不得记为已批准。矛盾不在此阶段裁决——入开放问题，Phase 2 问。
|
||||
|
||||
state.md 初始化模板：
|
||||
|
||||
```markdown
|
||||
# Le SPEC 状态 — <项目/功能名>
|
||||
更新: <日期> | 阶段: Phase 1 | 复杂度: <档>（理由）
|
||||
|
||||
## 项目
|
||||
类型: <全新/加功能/修改/…> ｜ 目标: <一句话>
|
||||
|
||||
## 原始输入摘要
|
||||
- (来源: 首条消息) <要点，保留关键原话>
|
||||
|
||||
## 已确认决策
|
||||
| # | 决策 | 内容 | 来源 | 状态 |
|
||||
|---|------|------|------|------|
|
||||
|
||||
## 已否定方案
|
||||
- <方案> — 否定原因 <来源>
|
||||
|
||||
## 开放问题
|
||||
- [ ] Q1 <问题>（影响: 核心/边缘；依赖: -）
|
||||
|
||||
## 假设（待验证）
|
||||
- <假设>（依据）
|
||||
|
||||
## 访谈计数
|
||||
轮次: 0 ｜ 检查点: -
|
||||
|
||||
## 下一步
|
||||
- <具体动作>
|
||||
```
|
||||
|
||||
## Phase 2：Grill 深度访谈
|
||||
|
||||
入口动作（顺序固定）：
|
||||
1. 读 [dependencies.md](dependencies.md) 第 1 节，按调用方式总则**真实加载 grilling**（已有项目叠加 domain-modeling），记账本。
|
||||
2. 以 state.md 开放问题 + 十类分拣中的矛盾/缺失为 design tree 初始节点。
|
||||
|
||||
访谈中 Le SPEC 叠加于 grilling 原义之上的规则：
|
||||
- **每轮结束**（用户答完）：新决策入表、开放问题更新、轮次 +1、增量写 state.md。
|
||||
- **检查点**：每逢第 4、8、12…轮答完，附一段 ≤6 行小结（已确认 N 项 / 开放 M 项 / 收敛判断：继续｜接近｜已达标）。有 blocking 问题默认继续，不要求用户批准继续；已达标主动提议收口。
|
||||
- **收敛标准**（全部满足才收口）：目标明确 ｜ 范围明确（含不做） ｜ 角色明确 ｜ 核心流程闭环 ｜ 业务规则明确 ｜ 数据关系与权限边界明确（适用时） ｜ 异常边界已有处理原则 ｜ 无阻塞实现的重大未决。非关键细节可用「明确标注的默认方案」填充（标注 [默认] 进 state.md），不无限追问。
|
||||
- **用户控制权**：随时可换模块、改需求（记录影响范围，受影响的已确认项重开并注明）、看草稿、暂停（state.md 存「下一步」）、先谈技术（跳 Phase 3 再回）。
|
||||
- 关键需求仍有歧义时不得自行拍板；重大未决可出「标注风险的草稿」但明示未经审查。
|
||||
|
||||
## Phase 3：Think 方案分析与挑战
|
||||
|
||||
1. 无实质方案争议（simple 或方案唯一且用户已定）→ state.md 记"Phase 3 跳过（无分歧）"，进 Phase 4。
|
||||
2. 否则按 [dependencies.md](dependencies.md) 第 2 节**真实加载 think**（含其 Preflight：读项目 AGENTS/CLAUDE 索引与相关规则），记账本。
|
||||
3. think 产出推荐方案 → 向用户呈现（推荐+理由+一个替代+风险+最脆弱假设）→ **终止回合等决断** → 批准则入 state.md [已批准]，新不确定性回流 Phase 2。
|
||||
|
||||
## Phase 4：需求反向验收
|
||||
|
||||
详见 [acceptance.md](acceptance.md)。核心：fresh-context 子代理扮演"没参与讨论的资深工程师"，只读 state.md + 已确认材料，回答"由我实现的话，哪些产品行为还得靠猜？"。产出 blocking / major / minor 问题清单：
|
||||
- blocking → 以 grilling 单轮格式向用户澄清（记账本 dep=grilling, summary=acceptance-driven）→ 更新后**只复核受影响项**；
|
||||
- major → 能由已确认决策推导的当场补进 state.md 并标注推导依据，推导不了的升级 blocking；
|
||||
- minor → 记入开放问题，随 SPEC 的"非阻塞事项"呈现。
|
||||
清零 blocking 才进 Phase 5。
|
||||
|
||||
## Phase 5：OpenSpec 生成正式 SPEC
|
||||
|
||||
按 [dependencies.md](dependencies.md) 第 3 节标准路径执行（每条 CLI 命令记账本）。要点：
|
||||
- change 名 kebab-case，从需求导出；同名已存在 → 问用户续用还是新建（遵循原生 guardrail）。
|
||||
- 逐 artifact：先 `instructions`，按其 template + instruction 撰写；内容全部来自 state.md（已批准决策/已确认需求/[默认] 项如实标注），**不编造规则**；验收场景用 Requirement/Scenario 结构，可测、可观察。
|
||||
- `design.md` 遵循其 conditional 规则（跨切面/新依赖/数据模型等才写）；Phase 3 有 think 结论的，方案与已否替代直接沉淀为 Decisions。
|
||||
- `openspec validate` 必须通过；失败按输出修正后重跑。
|
||||
- SPEC 语言聚焦"系统做什么、表现什么行为、如何判断正确"——实现机制进 design/tasks（OpenSpec config 的 product-language 约定同理）。
|
||||
|
||||
## Phase 6：SPEC 独立质量审查
|
||||
|
||||
详见 [review.md](review.md)。四视角（产品/架构/开发/测试）独立审查 artifacts + `openspec validate` 复跑 + 账本核对。问题分级（blocker/major/minor）→ 修正 → 只复验受影响项 → 出审查结论（无事实依据的分数不打）。
|
||||
|
||||
## Phase 7：用户确认与交接
|
||||
|
||||
确认包含：正式 SPEC 位置与摘要、核心功能与范围、关键决策（含被否方案）、明确不做、尚存风险与非阻塞问题、审查结果摘要、账本统计（grilling/think/openspec 各 N 次真实调用）。
|
||||
**呈交后终止回合。** 用户批准 → 更新 state.md 阶段为"已交接"，提示后续：实现用 openspec-apply-change 工作流、需求变化用 openspec-update-change、完成后 openspec-archive-change。用户要改 → 只更新受影响 artifact 并复验（不重跑全流程）。
|
||||
|
||||
## 中断恢复
|
||||
|
||||
任何会话重入：`openspec context --json` → 读 `<root>/openspec/le-spec/state.md` → 校验其「下一步」与 OpenSpec 实际状态（`openspec status --change` 或 `openspec list --json`）一致 → 从断点继续。state.md 阶段标记与实际不符时以实际产物为准并修正状态。
|
||||
@@ -0,0 +1,6 @@
|
||||
# reports/ —— 证据政策
|
||||
|
||||
- `test-report.md` —— 测试 A-I 的执行记录、修正记录与已知限制（**入库**：本次交付要求的可复查证据）
|
||||
- `trigger-eval.json` —— trigger_eval.py 生成物（**不入库**，gitignore：按需重跑即得，遵循仓库先例）
|
||||
|
||||
诚实条款：验证不了的写「证据缺失」，不编造；计划中的工作不是证据。测试脚手架项目（/tmp/lespec-test/）不入库，证据以本报告 + 文中账本数字为指针。
|
||||
@@ -0,0 +1,40 @@
|
||||
# Le SPEC 测试报告（v1.0.0，2026-11-08）
|
||||
|
||||
测试方法：以 fresh-context 子代理为 Le SPEC 执行者、主会话扮演真实用户的多轮对话实测（非单发提示词测试），产物全部可复核。证据分级：[已验证] 有执行记录/文件/账本；[设计优势] 源码可见；[假设] 合理未证。
|
||||
|
||||
## 总览
|
||||
|
||||
| 测试 | 验证点 | 结果 | 关键证据 |
|
||||
|---|---|---|---|
|
||||
| A 零散需求理解 | 混乱输入十类分拣 | ✅ [已验证] | app-idea state.md：矛盾 A（安卓↔iCloud）入开放问题、语音标[未定]、「先不管」搁置不重问 |
|
||||
| B 全新产品+Grill | grilling 真实加载+frontier 机制 | ✅ [已验证] | 账本 grilling×6（file-read）；❓Q/➡️推荐格式、每轮问整 frontier、答案重塑树（Q1-C 解锁 R2） |
|
||||
| C 已有项目 | 读代码、grill-with-docs、不重复问 | ✅ [已验证] | todo-app：README/代码被读（29 行/数据路径/无账号），零代码可答问题；GLOSSARY 6 术语（domain-modeling×1 账本） |
|
||||
| D 不合理方案 | think 真实调用+有效挑战 | ✅ [已验证] | 账本 think×2；🥷 前缀/官方方案核查（真实链接）/minimal 选项/premise collapse/被否替代；Redis 被识别为唯一过度点，账号/排序/审计被否 |
|
||||
| E 深度访谈 | >4 轮、每 4 轮检查点、收敛即停 | ✅ [已验证] | 4 轮（变更延长第 4 轮）；R4 后检查点（≤6 行/8/8 收敛/frontier 空）；收敛后主动收口不凑轮 |
|
||||
| F 反向验收 | 独立视角挖隐藏歧义 | ✅ [已验证] | 子代理场景：D25-D27 推导（编辑规则/清单快照/独立性）；主会话独立子代理补测：抓到 2 blocking（用量数据模型、Mac 交付范围）+4 major——**独立审查显著强于自审** |
|
||||
| G SPEC 生成与审查 | openspec 真实工作流 | ✅ [已验证] | 两项目 validate --strict 复跑通过；场景1：6 capability/21 Requirement/46 Scenario；场景2：3 capability/17 tasks；WHEN/THEN 可测场景 |
|
||||
| H 变更与中断恢复 | 状态存取/局部更新/不重复问 | ✅ [已验证] | R3 变更（+采购清单/−微信）→ 变更日志+D1/D4/D9 影响标注；新会话恢复：21 项决策未重问、断点续问 |
|
||||
| I 依赖真实性 | 真实运行/缺失提示/无模拟 | ✅ [已验证] | deps_check 缺失场景 exit 1+精确安装命令；账本共 28 条真实调用（grilling 9/think 2/openspec CLI 14/propose 2/domain-modeling 1）；CLI exit 1 被正确解读为「未初始化」非崩溃 |
|
||||
|
||||
测试项目（脚手架，不入库）：/tmp/lespec-test/{app-idea,todo-app}。
|
||||
|
||||
## 修正记录（测试驱动）
|
||||
|
||||
1. **触发词面缺口**：初版 description 对「PRD 润色」「别做 spec 直接改代码」误触发 → 补负触发词面（润色/排版/直接改代码/别做 spec），trigger_eval 11/11 通过。
|
||||
2. **ledger.py 元组解包 bug**：append 直接崩溃 → 拆 resolve_ledger()，通过。
|
||||
3. **ledger 误报**：think 缺失警告未区分「Phase 3 合规跳过」→ 提示语区分，合规跳过需 state.md 有记录佐证。
|
||||
4. **Phase 4 独立性差异实测**：子代理执行环境（无嵌套 Agent 工具）自动降级自审并声明——机制正确，但自审 vs 独立审查的质量差是真实的（见测试 F），主会话使用时 Agent 工具可用，acceptance.md「首选子代理」规则已经覆盖。
|
||||
|
||||
## 已知限制与未验证项（如实声明）
|
||||
|
||||
1. **[假设→部分验证] 多 runtime**：ZCode 路径全程实测；Claude Code / Codex 仅建软链未实测（Skill 工具按名调用路径未跑）。
|
||||
2. **[假设] think 其它模式**：Evaluation / Triage / Lightweight 模式未被单独触发测试（全模式已两轮实测）。
|
||||
3. **[假设] openspec store**：--store 语义未测（本机无 store 环境）。
|
||||
4. **[已知局限] 嵌套子代理**：le-spec 跑在子代理内时 Phase 4/6 必然降级自审（子代理无 Agent 工具）；主会话直接使用无此限制。
|
||||
5. **[已知边界] init 授权解释**：用户宽泛授权（「继续吧」）时，执行者可能将授权泛化到 openspec init 决策（场景 1 记录为「用户批准」，场景 2 无授权时正确显式三选一询问）。explicit 判定留给执行 agent，建议用户对 init 表态时明确。
|
||||
6. **[已知局限] 触发实测深度**：冒烟 11/11；真实对话自动触发未测（本 skill 为本会话期间创建，同会话无法模拟新会话触发——见 le-meta-skill 惯例：skill 触发一次性读入，需新会话验证）。
|
||||
7. **[已知边界] 访谈轮次上限语义**：未验证 12+ 轮超长访谈的检查点节奏与上下文膨胀行为。
|
||||
|
||||
## 结论
|
||||
|
||||
九项测试全部通过，其中 A-I 的核心机制均有文件级证据；「真实集成、不冒充」约束由账本+CLI 退出码双重背书。未验证项集中于多 runtime 与依赖 skill 的非主路径模式，已在 README 与本报告声明，不声称已测。
|
||||
@@ -0,0 +1,121 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Le SPEC 依赖检查：skill 目录 + openspec CLI。
|
||||
|
||||
用法:
|
||||
python3 deps_check.py # 人读输出, 退出码 0=required 全就位, 1=有缺失
|
||||
python3 deps_check.py --json # 机器可读
|
||||
"""
|
||||
import argparse
|
||||
import json
|
||||
import os
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
# 依赖清单: (name, level, source, install_cmd)
|
||||
SKILL_DEPS = [
|
||||
("grilling", "required", "mattpocock/skills", "npx skills@latest add mattpocock/skills --skill grilling grill-me grill-with-docs domain-modeling -g"),
|
||||
("domain-modeling", "recommended", "mattpocock/skills", "npx skills@latest add mattpocock/skills --skill domain-modeling -g"),
|
||||
("grill-me", "optional", "mattpocock/skills", None), # 入口薄壳
|
||||
("grill-with-docs", "optional", "mattpocock/skills", None), # 入口薄壳
|
||||
("think", "required", "tw93/Waza", "npx skills@latest add tw93/Waza --skill think -g"),
|
||||
("openspec-propose", "recommended", "Fission-AI/OpenSpec", "npx skills@latest add Fission-AI/OpenSpec --skill openspec-propose openspec-new-change openspec-update-change openspec-verify-change openspec-archive-change openspec-apply-change openspec-explore -g"),
|
||||
("openspec-new-change", "recommended", "Fission-AI/OpenSpec", None),
|
||||
("openspec-update-change", "recommended", "Fission-AI/OpenSpec", None),
|
||||
("openspec-verify-change", "recommended", "Fission-AI/OpenSpec", None),
|
||||
("openspec-archive-change", "recommended", "Fission-AI/OpenSpec", None),
|
||||
]
|
||||
|
||||
# 候选 skill 根目录(顺序即优先级); 可用 LESPEC_SKILL_PATHS 覆盖, 冒号分隔
|
||||
DEFAULT_ROOTS = [
|
||||
"~/.agents/skills",
|
||||
"~/.zcode/skills",
|
||||
"~/.claude/skills",
|
||||
"~/.codex/skills",
|
||||
]
|
||||
|
||||
|
||||
def skill_roots():
|
||||
env = os.environ.get("LESPEC_SKILL_PATHS")
|
||||
if env:
|
||||
return [Path(p).expanduser() for p in env.split(":") if p.strip()]
|
||||
return [Path(p).expanduser() for p in DEFAULT_ROOTS]
|
||||
|
||||
|
||||
def find_skill(name):
|
||||
"""返回 (resolved_skill_md_path | None, root_dir)。软链解析到真源。"""
|
||||
for root in skill_roots():
|
||||
cand = root / name / "SKILL.md"
|
||||
if cand.exists():
|
||||
try:
|
||||
return cand.resolve(), root
|
||||
except OSError:
|
||||
return cand, root
|
||||
return None, None
|
||||
|
||||
|
||||
def check_openspec_cli():
|
||||
exe = shutil.which("openspec")
|
||||
if not exe:
|
||||
return {"name": "openspec-cli", "level": "required", "ok": False,
|
||||
"detail": "openspec not in PATH",
|
||||
"install": "npm install -g @fission-ai/openspec@latest"}
|
||||
try:
|
||||
out = subprocess.run([exe, "--version"], capture_output=True, text=True,
|
||||
timeout=15)
|
||||
ver = (out.stdout or out.returncode and out.stderr or "").strip().splitlines()[-1] \
|
||||
if (out.stdout or out.stderr) else "?"
|
||||
return {"name": "openspec-cli", "level": "required", "ok": out.returncode == 0,
|
||||
"detail": f"{exe} (v{ver})",
|
||||
"install": "npm install -g @fission-ai/openspec@latest"}
|
||||
except Exception as e: # timeout / spawn 失败
|
||||
return {"name": "openspec-cli", "level": "required", "ok": False,
|
||||
"detail": f"exec failed: {e}",
|
||||
"install": "npm install -g @fission-ai/openspec@latest"}
|
||||
|
||||
|
||||
def main():
|
||||
ap = argparse.ArgumentParser()
|
||||
ap.add_argument("--json", action="store_true", help="JSON 输出")
|
||||
args = ap.parse_args()
|
||||
|
||||
results = []
|
||||
for name, level, source, install in SKILL_DEPS:
|
||||
path, root = find_skill(name)
|
||||
results.append({
|
||||
"name": name, "kind": "skill", "level": level,
|
||||
"ok": path is not None,
|
||||
"detail": str(path) if path else f"not found under {':'.join(str(r) for r in skill_roots())}",
|
||||
"source": source, "install": install,
|
||||
})
|
||||
results.append(check_openspec_cli())
|
||||
|
||||
missing_required = [r for r in results if not r["ok"] and r["level"] == "required"]
|
||||
missing_recommended = [r for r in results if not r["ok"] and r["level"] == "recommended"]
|
||||
|
||||
if args.json:
|
||||
print(json.dumps({
|
||||
"ok": not missing_required,
|
||||
"missing_required": [r["name"] for r in missing_required],
|
||||
"missing_recommended": [r["name"] for r in missing_recommended],
|
||||
"items": results,
|
||||
}, ensure_ascii=False, indent=2))
|
||||
else:
|
||||
mark = lambda r: "✅" if r["ok"] else ("❌" if r["level"] == "required" else "⚠️ ")
|
||||
print(f"{'':2}{'状态':4} {'级别':12} {'依赖':24} 详情")
|
||||
for r in results:
|
||||
print(f"{mark(r)} {r['level']:<12} {r['name']:<24} {r['detail']}")
|
||||
print()
|
||||
if not missing_required and not missing_recommended:
|
||||
print("全部依赖就位。")
|
||||
for r in missing_required + missing_recommended:
|
||||
if r.get("install"):
|
||||
print(f"补装 {r['name']}: {r['install']}")
|
||||
print("提示: optional 级(grill-me/grill-with-docs)是入口薄壳, 缺失不影响运行。")
|
||||
|
||||
sys.exit(1 if missing_required else 0)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
@@ -0,0 +1,143 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Le SPEC 调用账本: 记录每次依赖真实交互, 供审查与交付作证据。
|
||||
|
||||
用法:
|
||||
python3 ledger.py append --dep grilling --kind skill-load --method file-read \
|
||||
--summary "Phase2 R1 frontier 4问" [--cmd "..."] [--exit 0] [--file PATH]
|
||||
python3 ledger.py check [--file PATH] [--json]
|
||||
python3 ledger.py tail [-n 5] [--file PATH]
|
||||
|
||||
账本定位优先级: --file > openspec root 下 openspec/le-spec/ledger.jsonl > ./.le-spec/ledger.jsonl
|
||||
"""
|
||||
import argparse
|
||||
import datetime
|
||||
import json
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
KINDS = {"skill-load", "cli", "subagent"}
|
||||
METHODS = {"skill-tool", "file-read", "bash", "agent"}
|
||||
|
||||
|
||||
def default_ledger():
|
||||
try:
|
||||
out = subprocess.run(["openspec", "context", "--json"],
|
||||
capture_output=True, text=True, timeout=15)
|
||||
ctx = json.loads(out.stdout or "{}")
|
||||
root = (ctx.get("root") or {}).get("path")
|
||||
if root:
|
||||
p = Path(root) / "openspec" / "le-spec" / "ledger.jsonl"
|
||||
return p, True
|
||||
except Exception:
|
||||
pass
|
||||
return Path.cwd() / ".le-spec" / "ledger.jsonl", False
|
||||
|
||||
|
||||
def resolve_ledger(args):
|
||||
"""返回 (path, has_openspec_root)。"""
|
||||
if getattr(args, "file", None):
|
||||
return Path(args.file).expanduser(), None
|
||||
return default_ledger()
|
||||
|
||||
|
||||
def cmd_append(args):
|
||||
if args.kind not in KINDS or args.method not in METHODS:
|
||||
print(f"kind 须为 {KINDS}, method 须为 {METHODS}", file=sys.stderr)
|
||||
return 2
|
||||
path, has_root = resolve_ledger(args)
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
entry = {
|
||||
"ts": datetime.datetime.now().isoformat(timespec="seconds"),
|
||||
"phase": args.phase, "dep": args.dep, "kind": args.kind,
|
||||
"method": args.method, "cmd": args.cmd, "exit": args.exit,
|
||||
"summary": args.summary,
|
||||
}
|
||||
with path.open("a", encoding="utf-8") as f:
|
||||
f.write(json.dumps({k: v for k, v in entry.items() if v is not None},
|
||||
ensure_ascii=False) + "\n")
|
||||
print(f"账本已记: {path}")
|
||||
if has_root is False and not args.file:
|
||||
print("(未找到 openspec root, 暂写 .le-spec/; Phase 5 init 后迁移)", file=sys.stderr)
|
||||
return 0
|
||||
|
||||
|
||||
def _load(path):
|
||||
if not path.exists():
|
||||
return []
|
||||
rows = []
|
||||
for line in path.read_text(encoding="utf-8").splitlines():
|
||||
line = line.strip()
|
||||
if line:
|
||||
try:
|
||||
rows.append(json.loads(line))
|
||||
except json.JSONDecodeError:
|
||||
rows.append({"_unparsed": line})
|
||||
return rows
|
||||
|
||||
|
||||
def cmd_check(args):
|
||||
path, _ = resolve_ledger(args)
|
||||
rows = _load(path)
|
||||
by_dep = {}
|
||||
for r in rows:
|
||||
d = by_dep.setdefault(r.get("dep", "?"), {"count": 0, "last": None, "kinds": {}})
|
||||
d["count"] += 1
|
||||
d["last"] = r.get("ts", d["last"])
|
||||
d["kinds"][r.get("kind", "?")] = d["kinds"].get(r.get("kind", "?"), 0) + 1
|
||||
if args.json:
|
||||
print(json.dumps({"ledger": str(path), "total": len(rows), "by_dep": by_dep},
|
||||
ensure_ascii=False, indent=2))
|
||||
else:
|
||||
print(f"账本: {path} ｜ 总计 {len(rows)} 条")
|
||||
for dep, d in sorted(by_dep.items()):
|
||||
kinds = ", ".join(f"{k}×{v}" for k, v in d["kinds"].items())
|
||||
print(f" {dep:<16} {d['count']:>3} 次 ({kinds}) 末次 {d['last']}")
|
||||
expected = ["grilling", "think", "openspec"]
|
||||
missing = [e for e in expected if e not in by_dep]
|
||||
if missing:
|
||||
hint = {"think": "（若 Phase 3 合规跳过——无实质方案分歧——属正常，确认 state.md 有跳过记录即可）"}
|
||||
for m in missing:
|
||||
print(f"⚠️ 未见 {m} 的调用记录 {hint.get(m, '')} — 否则 Phase 6 审查前需真实补调或如实声明")
|
||||
return 0
|
||||
|
||||
|
||||
def cmd_tail(args):
|
||||
path, _ = resolve_ledger(args)
|
||||
rows = _load(path)[-args.n:]
|
||||
for r in rows:
|
||||
print(json.dumps(r, ensure_ascii=False))
|
||||
return 0
|
||||
|
||||
|
||||
def main():
|
||||
ap = argparse.ArgumentParser()
|
||||
sub = ap.add_subparsers(dest="cmd", required=True)
|
||||
|
||||
a = sub.add_parser("append")
|
||||
a.add_argument("--dep", required=True)
|
||||
a.add_argument("--kind", required=True)
|
||||
a.add_argument("--method", required=True)
|
||||
a.add_argument("--phase")
|
||||
a.add_argument("--cmd")
|
||||
a.add_argument("--exit", type=int)
|
||||
a.add_argument("--summary")
|
||||
a.add_argument("--file")
|
||||
a.set_defaults(fn=cmd_append)
|
||||
|
||||
c = sub.add_parser("check")
|
||||
c.add_argument("--file")
|
||||
c.add_argument("--json", action="store_true")
|
||||
c.set_defaults(fn=cmd_check)
|
||||
|
||||
t = sub.add_parser("tail")
|
||||
t.add_argument("-n", type=int, default=5)
|
||||
t.add_argument("--file")
|
||||
t.set_defaults(fn=cmd_tail)
|
||||
|
||||
args = ap.parse_args()
|
||||
sys.exit(args.fn(args))
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
main()
|
||||
Reference in New Issue
Block a user