一个Mermaid.js扩展插件，用于创建Shape Up风格的Hill Chart进度图，让团队可以在文档中直接展示项目各阶段的进展和势头，特别适合AI Agent驱动的工作流。

Mermaid Hillchart：为Shape Up方法论打造的进度可视化工具\n\n## 什么是Hill Chart？\n\nHill Chart（山形图）是Basecamp提出的Shape Up产品开发方法论中的核心可视化工具。它将项目进度表示为一座山的形状，分为两个截然不同的阶段：\n\n上坡阶段（Uphill）：对应问题的解决阶段。在这个阶段，团队面对不确定性，需要探索、实验、理解问题空间。进度缓慢且充满未知，因为你不知道还有什么障碍等待着你。\n\n下坡阶段（Downhill）：对应方案的执行阶段。一旦问题被充分理解，解决方案明确，剩下的就是执行工作。这个阶段进度快速且可预测，因为你已经知道要做什么。\n\n这种可视化方式的价值在于它承认了"不确定性"是项目管理的固有组成部分，而非试图用虚假的精确百分比来掩盖它。\n\n## Mermaid Hillchart的技术实现\n\n本项目是一个Mermaid.js的外部图表扩展，允许用户在Mermaid图表语法中直接创建Hill Chart。\n\n### 核心语法设计\n\n\nhillchart\n title 通知系统重构\n scope \"邮件设计\": uphill 50\n scope \"邮件投递\": downhill 65\n scope \"应用内菜单\": uphill 20\n\n\n这段代码会渲染出一个标准的Hill Chart，显示三个工作范围的当前状态：\n\n- 邮件设计：处于上坡阶段，已完成约50%的探索\n- 邮件投递：已进入下坡阶段，执行完成65%\n- 应用内菜单：仍处于上坡早期，仅完成20%的问题理解\n\n### 技术架构\n\n该插件作为Mermaid的外部图表注册，遵循Mermaid的扩展API规范：\n\n1. 解析器：将hillchart DSL解析为内部数据结构\n2. 渲染引擎：使用SVG绘制山形曲线和标记点\n3. 配置系统：支持自定义padding、颜色主题等参数\n\n集成方式简洁明了：\n\ntypescript\nimport mermaid from \"mermaid\"\nimport hillChart from \"mermaid-hillchart\"\n\nawait mermaid.registerExternalDiagrams([hillChart])\nmermaid.initialize({\n startOnLoad: true,\n externalHillchart: {\n padding: 32,\n },\n})\n\n\n## 适用场景与价值主张\n\n### 1. 产品团队的Shape Up实践\n\n对于采用Shape Up方法论的团队，Hill Chart是每周进度同步的标准工具。传统的甘特图或看板无法表达"上坡"与"下坡"的本质区别，而Hill Chart将这种认知直接编码进可视化本身。\n\n### 2. AI Agent驱动的工作流\n\n项目README特别强调了一个新兴场景：AI Agent驱动的工作流。在这种模式下，Agent不仅执行任务，还需要报告进度和势头。Hill Chart提供了一种结构化的方式让Agent表达：\n\n- 当前处于探索阶段还是执行阶段\n- 问题的理解程度（上坡位置）\n- 执行的完成度（下坡位置）\n\n这种表达能力对于人机协作至关重要，因为它让Agent的"状态报告"有了标准化的语义。\n\n### 3. 技术文档与决策记录\n\n在架构决策记录（ADR）或技术RFC中，Hill Chart可以用来可视化各技术方案的成熟度。例如，展示"新数据库选型"、"API重构"、"前端框架升级"等并行工作的当前状态。\n\n## 安装与使用\n\n项目支持多种包管理器：\n\nbash\nnpm install mermaid mermaid-hillchart\n# 或\npnpm add mermaid mermaid-hillchart\n# 或\nyarn add mermaid mermaid-hillchart\n\n\n兼容性要求：\n- Mermaid版本：^10.0.0 || ^11.0.0\n- 宿主平台：必须支持Mermaid外部图表。GitHub和GitLab的原生Markdown渲染器通常不加载外部插件，建议在自定义文档站点或Mermaid Live Editor中使用。\n\n## 方法论背景：Shape Up简介\n\n理解Hill Chart的最佳方式是理解它诞生的上下文。Shape Up是Basecamp（现为37signals）开发的产品管理方法论，与传统敏捷开发有显著不同：\n\n固定周期，可变范围：Shape Up使用6周的固定周期（Cycle），但范围是可调整的。如果6周结束时工作未完成，整个项目被取消而非延期。这种"刀架在脖子上"的设计强迫团队在周期早期就做出艰难决策。\n\n** betting而非backlog**：产品团队不维护无限的待办列表，而是在每个周期前进行"下注"（betting），选择最有价值的几个项目投入6周时间。\n\n** 设计 upfront**：开发者有完整的6周不受打扰的时间，周期开始前由设计师和策略师完成足够详细的设计。\n\n** Hill Chart作为真相来源**：每周团队更新Hill Chart，展示各项目在上坡/下坡的位置。这比"完成了80%"这样的虚假精确度要诚实得多。\n\n## 开源生态与许可证\n\n本项目是独立的Mermaid插件，与Mermaid.js官方团队无隶属关系。代码采用MIT许可证，与Mermaid.js保持一致。\n\n值得注意的是，项目鼓励社区贡献解析器和渲染引擎的改进。对于希望自定义视觉风格或添加交互功能的开发者，项目提供了清晰的扩展点。\n\n## 总结\n\nMermaid Hillchart填补了一个特定的工具空白：将Shape Up的Hill Chart方法论引入到基于Markdown的文档工作流中。对于已经使用Mermaid绘制架构图、流程图的技术团队，这是一个自然的扩展。\n\n更重要的是，它展示了如何将管理方法论编码成可复用的工具。Hill Chart不仅仅是一张图，它是对"项目进度本质上是关于不确定性管理"这一认知的技术表达。在AI Agent日益参与工作流的今天，这种结构化的进度表达方式可能会成为人机协作的重要接口。

Mermaid Hillchart：为Shape Up方法论打造的进度可视化工具\n\n什么是Hill Chart？\n\nHill Chart（山形图）是Basecamp提出的Shape Up产品开发方法论中的核心可视化工具。它将项目进度表示为一座山的形状，分为两个截然不同的阶段：\n\n上坡阶段（Uphill）：对应问题的解决阶段。在这个阶段，团队面对不确定性，需要探索、实验、理解问题空间。进度缓慢且充满未知，因为你不知道还有什么障碍等待着你。\n\n下坡阶段（Downhill）：对应方案的执行阶段。一旦问题被充分理解，解决方案明确，剩下的就是执行工作。这个阶段进度快速且可预测，因为你已经知道要做什么。\n\n这种可视化方式的价值在于它承认了"不确定性"是项目管理的固有组成部分，而非试图用虚假的精确百分比来掩盖它。\n\nMermaid Hillchart的技术实现\n\n本项目是一个Mermaid.js的外部图表扩展，允许用户在Mermaid图表语法中直接创建Hill Chart。\n\n核心语法设计\n\n\nhillchart\n title 通知系统重构\n scope \"邮件设计\": uphill 50\n scope \"邮件投递\": downhill 65\n scope \"应用内菜单\": uphill 20\n\n\n这段代码会渲染出一个标准的Hill Chart，显示三个工作范围的当前状态：\n\n- 邮件设计：处于上坡阶段，已完成约50%的探索\n- 邮件投递：已进入下坡阶段，执行完成65%\n- 应用内菜单：仍处于上坡早期，仅完成20%的问题理解\n\n技术架构\n\n该插件作为Mermaid的外部图表注册，遵循Mermaid的扩展API规范：\n\n1. 解析器：将hillchart DSL解析为内部数据结构\n2. 渲染引擎：使用SVG绘制山形曲线和标记点\n3. 配置系统：支持自定义padding、颜色主题等参数\n\n集成方式简洁明了：\n\ntypescript\nimport mermaid from \"mermaid\"\nimport hillChart from \"mermaid-hillchart\"\n\nawait mermaid.registerExternalDiagrams([hillChart])\nmermaid.initialize({\n startOnLoad: true,\n externalHillchart: {\n padding: 32,\n },\n})\n\n\n适用场景与价值主张\n\n1. 产品团队的Shape Up实践\n\n对于采用Shape Up方法论的团队，Hill Chart是每周进度同步的标准工具。传统的甘特图或看板无法表达"上坡"与"下坡"的本质区别，而Hill Chart将这种认知直接编码进可视化本身。\n\n2. AI Agent驱动的工作流\n\n项目README特别强调了一个新兴场景：AI Agent驱动的工作流。在这种模式下，Agent不仅执行任务，还需要报告进度和势头。Hill Chart提供了一种结构化的方式让Agent表达：\n\n- 当前处于探索阶段还是执行阶段\n- 问题的理解程度（上坡位置）\n- 执行的完成度（下坡位置）\n\n这种表达能力对于人机协作至关重要，因为它让Agent的"状态报告"有了标准化的语义。\n\n3. 技术文档与决策记录\n\n在架构决策记录（ADR）或技术RFC中，Hill Chart可以用来可视化各技术方案的成熟度。例如，展示"新数据库选型"、"API重构"、"前端框架升级"等并行工作的当前状态。\n\n安装与使用\n\n项目支持多种包管理器：\n\nbash\nnpm install mermaid mermaid-hillchart\n或\npnpm add mermaid mermaid-hillchart\n或\nyarn add mermaid mermaid-hillchart\n\n\n兼容性要求：\n- Mermaid版本：^10.0.0 || ^11.0.0\n- 宿主平台：必须支持Mermaid外部图表。GitHub和GitLab的原生Markdown渲染器通常不加载外部插件，建议在自定义文档站点或Mermaid Live Editor中使用。\n\n方法论背景：Shape Up简介\n\n理解Hill Chart的最佳方式是理解它诞生的上下文。Shape Up是Basecamp（现为37signals）开发的产品管理方法论，与传统敏捷开发有显著不同：\n\n固定周期，可变范围：Shape Up使用6周的固定周期（Cycle），但范围是可调整的。如果6周结束时工作未完成，整个项目被取消而非延期。这种"刀架在脖子上"的设计强迫团队在周期早期就做出艰难决策。\n\n** betting而非backlog**：产品团队不维护无限的待办列表，而是在每个周期前进行"下注"（betting），选择最有价值的几个项目投入6周时间。\n\n** 设计 upfront**：开发者有完整的6周不受打扰的时间，周期开始前由设计师和策略师完成足够详细的设计。\n\n** Hill Chart作为真相来源**：每周团队更新Hill Chart，展示各项目在上坡/下坡的位置。这比"完成了80%"这样的虚假精确度要诚实得多。\n\n开源生态与许可证\n\n本项目是独立的Mermaid插件，与Mermaid.js官方团队无隶属关系。代码采用MIT许可证，与Mermaid.js保持一致。\n\n值得注意的是，项目鼓励社区贡献解析器和渲染引擎的改进。对于希望自定义视觉风格或添加交互功能的开发者，项目提供了清晰的扩展点。\n\n总结\n\nMermaid Hillchart填补了一个特定的工具空白：将Shape Up的Hill Chart方法论引入到基于Markdown的文档工作流中。对于已经使用Mermaid绘制架构图、流程图的技术团队，这是一个自然的扩展。\n\n更重要的是，它展示了如何将管理方法论编码成可复用的工具。Hill Chart不仅仅是一张图，它是对"项目进度本质上是关于不确定性管理"这一认知的技术表达。在AI Agent日益参与工作流的今天，这种结构化的进度表达方式可能会成为人机协作的重要接口。