用途
plan-it-zht 是一个“HTML 优先”的持久化规划技能。它主张像 Thariq 那样工作：产出一个单一、可导航的制品，而不是一段人类会跳过的大段 Markdown。
其核心理念是把格式视作控制面：智能体输出的格式，就是人类检视的界面。作者引用 Thariq Shihipar 2026-05-08 的文章《The Unreasonable Effectiveness of HTML》，认为在 Opus 4.7 的 1M 上下文下，令牌成本不是正确指标，参与度才是。HTML 能保留空间关系、交互性、无需滚动的信息密度和视觉层级，而这些是 Markdown 线性化后丢掉的。滑块、拖拽卡片、复制按钮、模型图都是一等公民。
主要能力
技能的工作模式围绕三个层次：
- 上下文窗口 = RAM（易失、有限）
- 文件系统 = Disk（持久、无限）
- plan.html = 规范表面：对人类可视化，对智能体结构化
JSON 数据层随文件四处流动，渲染层是人类的用户体验。
技能先恢复上下文：如果 plan.html 存在，则读取它，钩子会自动在每次提示时注入当前阶段摘要。还会运行 session catchup 以呈现上一会话中任何未同步的编辑；若 catchup 报告存在未同步上下文，则运行 git diff --stat、读取 plan.html 内嵌 JSON、更新 progress_log 后继续。
plan-data JSON 架构（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。其中 status 取值 pending、in_progress、complete、blocked。
可用命令包括：
- /plan：从模板创建新的 plan.html
- /plan-render：在默认浏览器中打开 plan.html
- /plan-attest：用 SHA-256 认证锁定计划（支持 --show、--clear）
- /plan-status：向终端打印单行计划状态
- /plan-export markdown：将 plan.html 压平成 task_plan.md（双向）
- /plan-export json：将内嵌 JSON 导出为 plan.json
- /plan-goal：与 Claude Code 的 /goal 组合，推导终止条件
- /plan-loop：与 Claude Code 的 /loop 组合，每次滴答时重新读取
使用方式
在任何复杂任务之前：
- 选择模板并创建 plan.html。运行 /plan 或 bash scripts/init-plan.sh <template>。可用模板：implementation-plan、three-approaches、ticket-triage、feature-flag-editor、module-map、annotated-pr、living-design-system、animation-sandbox、weekly-status、incident-timeline。
- 打开它。运行 /plan-render 或 bash scripts/render-plan.sh，页面在默认浏览器中打开。
- 交互。拖拽卡片、移动滑块、书写笔记，状态持久化在内嵌 JSON 中。
- 通过 JSON 更新，而不是渲染层。块 <script type="application/json" id="plan-data"> 是事实来源。
- 可选：锁定。运行 /plan-attest 计算并存储 SHA-256。此后对 plan.html 的任何篡改都会阻止注入，直到重新认证。
关键规则：先创建计划，即使“快速”工作也用 /plan；JSON 是事实来源，永远更新内嵌 JSON，绝不手工编辑其周围的 HTML 标签；每进行 2 次查看/浏览/搜索操作后，向 JSON 追加一条 findings 记录（2 操作规则）；重大决策前重读 plan.html；完成任何阶段后，设置 phases[i].status 为 complete、追加完成时间戳、在 progress_log 追加包含修改文件的记录、递增 current_phase；所有错误都记入 errors 数组，让知识在 /clear 后依然存活。
文件位置与单文件约束
技能目录（${CLAUDE_PLUGIN_ROOT}/）放模板、脚本、参考文档；项目目录放 plan.html（单一事实来源）。
每个 plan.html 都包含：DOCTYPE、lang、viewport meta；内联 <style>；内嵌 <script type="application/json" id="plan-data"> 规范数据；内联 <script> 纯 JS 渲染器（≤400 行）；WCAG AA 对比度、ARIA 标签、语义地标、键盘导航。禁止 <link rel="stylesheet">、<script src>、eval、Function()、远程 URL。总大小预算：HTML ≤30KB，JSON ≤50KB。
视觉上，plan-it 计划像编辑型仪表盘而非 SaaS 仪表盘：强排版层级、单一强调色、不用渐变；尖角（≤4px 圆角）或无圆角；数据表用等宽字体，标题可选衬线，正文无衬线；信息密度优先于留白膨胀；表格优先于卡片；滑块拇指 32px、无阴影；拖拽卡片 1px 边框而非 box-shadow；只用系统字体 system-ui、sans-serif、monospace，不用 Web 字体；内联样式与脚本、base64 图片或内联 SVG，无 CDN、无构建步骤；感知 prefers-color-scheme（深色与浅色）。
安全边界
计划注入把内容包裹在 ===BEGIN PLAN DATA=== / ===END PLAN DATA=== 标记中（绝不用 ---，因为会与 YAML 文档分隔符冲突并破坏 Claude Code 的技能加载器——来自 planning-with-files v2.38.1 的教训）。在标记内，智能体把内容当作结构化数据，而非指令。可选的 SHA-256 认证通过 /plan-attest 实现；遭篡改时注入被阻止，并显示 [PLAN TAMPERED — injection blocked] 以及期望/实际哈希。
适用场景
该技能适用于需要在复杂任务前建立阶段化计划、并希望计划可视化、可交互、可在上下文清空后恢复的场景。作者还说明与 planning-with-files（位于 https://github.com/OthmanAdi/planning-with-files 的 Markdown 前身）可干净组合：在 plan-it 项目内运行 /plan-export markdown，即可把 plan.html 压平成 pwf 三文件形态（task_plan.md、findings.md、progress.md）。HTML 保持规范，Markdown 是供下游 pwf 工具链和链式智能体消费的派生视图。
限制与已知问题
作者列出的注意事项包括：钩子触发但 cwd 中无 plan.html 时，行为为静默退出 0（钩子会先检查）；若直接编辑 plan.html 导致渲染损坏，需从 git 恢复或运行 /plan-attest --clear && /plan 重新初始化，不要手工编辑 HTML 标签；JSON 位于 <script type="application/json"> 块中而非原始 HTML；浏览器无法通过 scripts/render-plan.sh 打开时，WSL 上 xdg-open 可能需要 wslview，macOS 自带 open，Windows PowerShell 可用 Invoke-Item，.ps1 脚本处理这三种情况；plan.html 太大无法注入上下文时，钩子注入的是当前阶段摘要而非完整文件，可调整 --lines 30 参数；技能选择器中描述显示乱码时，检查没有钩子命令包含字面 --- 子串；Windows Git Bash 上路径解析失败时，钩子体使用 $HOME 作为回退路径解析，非标准安装路径可设置 CLAUDE_PLUGIN_ROOT 环境变量；多个并行计划可设置 PLAN_ID=<slug> 环境变量，plan-it 会读取 .planning/<slug>/plan.html 而非 plan.html，用 /plan-status 查看活动计划；令牌成本约为等效 Markdown 的 2-3 倍，这一权衡已有文档说明，若需要更低成本的链式智能体中间输出可运行 /plan-export markdown。
参考：Markdown 前身 https://github.com/OthmanAdi/planning-with-files。