用途
plan-it 是一个 HTML-first 的持久化规划技能，目标是用一个单一、可导航的 artifact（plan.html）替代人类容易跳过的 markdown 长文。当用户输入 "plan it"、"خطط"、"plane es"、"plan it"、"做计划"、"做計劃" 等触发词，或开始复杂任务时使用。
其设计理念借鉴了 Thariq Shihipar 2026-05-08 的文章《The Unreasonable Effectiveness of HTML》：智能体产出的格式就是人类检视的控制面。作者认为在长上下文模型下，token 成本不是正确指标，参与度才是；HTML 能保留空间关系、交互性、无需滚动的信息密度和视觉层级，而这些是 markdown 线性化后丢失的。滑块、可拖拽卡片、复制按钮、原型图被视为一等公民。
主要能力
- 生成单一自包含的 plan.html，内嵌 JSON 作为状态真源（source of truth）。
- 跨会话恢复：钩子会在每次提示时自动注入当前阶段摘要；配合 session catchup 脚本可发现上一会话未同步的编辑。
- 提供多种模板：implementation-plan、three-approaches、ticket-triage、feature-flag-editor、module-map、annotated-pr、living-design-system、animation-sandbox、weekly-status、incident-timeline。
- 提供命令：/plan（从模板创建 plan.html）、/plan-render（在默认浏览器打开）、/plan-attest（用 SHA-256 锁定计划，含 --show、--clear）、/plan-status（终端打印单行状态）、/plan-export markdown（展平为 task_plan.md，双向）、/plan-export json（导出内嵌 JSON 为 plan.json）、/plan-goal（与 Claude Code 的 /goal 组合，推导终止条件）、/plan-loop（与 /loop 组合，每次 tick 重读）。
- 提供安全边界：计划注入内容用 ===BEGIN PLAN DATA=== / ===END PLAN DATA=== 包裹，标记内被视为结构化数据而非指令；可选 SHA-256 校验，被篡改时阻止注入并显示预期/实际哈希。
- 可与 planning-with-files 组合：在 plan-it 项目内运行 /plan-export markdown，将 plan.html 展平为 pwf 的三文件形态（task_plan.md、findings.md、progress.md）。
使用方式
在任何复杂任务开始前：
- 选择模板并创建 plan.html。运行 /plan 或
bash scripts/init-plan.sh <template>。 - 打开它。运行 /plan-render 或
bash scripts/render-plan.sh，页面会在默认浏览器打开。 - 交互。拖拽卡片、移动滑块、写笔记，状态持久化在内嵌 JSON 中。
- 通过 JSON 更新，不要改渲染层。
<script type="application/json" id="plan-data">块是唯一真源。 - 可选：锁定。运行 /plan-attest 计算并存储 SHA-256。此后任何篡改都会阻止注入，直到重新 attest。
会话开始时应先恢复上下文：检查 plan.html 是否存在；存在则读取，钩子会自动注入当前阶段摘要；运行 session catchup 脚本 $(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"；如报告未同步上下文，运行 git diff --stat，读取内嵌 JSON，更新 progress_log 后再继续。
核心模式：上下文窗口 = RAM（易失、有限）；文件系统 = 磁盘（持久、无限）；plan.html = 规范界面（对人可视化，对智能体结构化）。
关键规则包括：先创建计划（即便是"快速"工作也用 /plan 强制阶段拆解）；JSON 是真源（始终更新内嵌 JSON，绝不手改周围 HTML 标签）；2-action 规则（每 2 次查看/浏览器/搜索操作后追加一条 findings）；决策前先读取；完成动作后更新（将阶段状态设为 complete 并加时间戳、追加 progress_log、递增 current_phase）；记录所有错误。
数据模式与约束
plan-data JSON schema 版本 v0.1.0，包含：schema_version、plan_title、goal、current_phase、template、created_at、updated_at、phases（含 id、title、status、items、milestones）、findings、progress_log、decisions、errors、attestation_sha256。
单文件约束（关键）：每个 plan.html 必须包含 DOCTYPE、lang、viewport meta；内联 <style>；<script type="application/json" id="plan-data"> 作为规范数据；内联 <script> 的 vanilla JS 渲染器（≤400 行）；WCAG AA 对比度、ARIA 标签、语义地标、键盘导航。禁止 <link rel="stylesheet">、<script src>、eval、Function()、远程 URL。总大小预算：HTML ≤30KB，JSON ≤50KB。
视觉规范（反粗糙）：强类型层级，单一强调色，不用渐变；直角（圆角 ≤4px）或无圆角；数据表格用等宽字体，标题可选衬线，正文用无衬线；信息密度优先于留白膨胀；表格优先于卡片；滑块 thumb 32px 无阴影；拖拽卡片 1px 边框而非 box-shadow；仅系统字体（system-ui、sans-serif、monospace），不用 web 字体；内联 style/script，图片用 base64 或内联 SVG，无 CDN，无构建步骤；适配 prefers-color-scheme（深色+浅色）。
适用场景与限制
适用场景包括：复杂任务开始前的阶段拆解；需要跨 /clear 保留状态的长期规划；希望用可交互界面而非 markdown 呈现计划；与 Claude Code 的 /goal、/loop 组合；对计划做完整性校验；需要把计划向下游 pwf 工具链和链式智能体导出时。
已知限制与注意事项（gotchas）：钩子在 cwd 无 plan.html 时静默退出 0；直接编辑 plan.html 导致渲染损坏时应从 git 恢复或运行 /plan-attest --clear && /plan 重新初始化，不要手改 HTML 标签；浏览器打开脚本在 WSL 上可能需要 wslview，macOS 用内置 open，Windows PowerShell 用 Invoke-Item；plan.html 过大时钩子只注入当前阶段摘要而非全文，可用 --lines 30 参数调节；技能选择器中描述乱码时检查钩子命令是否含字面量 --- 子串；Windows Git Bash 路径解析失败时，钩子体使用 $HOME 做回退，非标准安装路径可设 CLAUDE_PLUGIN_ROOT 环境变量；多个并行计划可设 PLAN_ID=<slug> 环境变量，此时读取 .planning/<slug>/plan.html；token 成本约为等效 markdown 的 2-3 倍，如需更低成本的链式中间产物可运行 /plan-export markdown。
补充说明
本项目欢迎翻译贡献。markdown 前身项目为 https://github.com/OthmanAdi/planning-with-files。关于收费、价格、平台与效果等更多细节，资料中暂未提供。