Cunzhi

# 寸止协议 (Cunzhi Protocol)

## 概念
"寸止"（cunzhi）源自武术概念，意为"在最后一寸停止"。在 VibeCoding 中，寸止是 AI 在关键节点暂停并等待用户确认的机制。

## 核心原则
1. **必须调用工具**: 不能只输出文字
2. **真正暂停**: 调用后等待用户响应
3. **结构化输出**: 提供清晰的状态摘要

## 工具优先级
```yaml
1. cunzhi MCP (优先)
   - 专门的寸止工具
   - 最佳用户体验
   
2. mcp-feedback-enhanced (降级)
   - 通用反馈工具
   - 可实现暂停等待
   
3. 文字输出 (最后手段)
   - 仅当工具都不可用时
   - 用户需手动确认
```

## 寸止点定义

### [PLAN_READY]
```yaml
时机: TODO 生成完成后
适用: Path B, Path C
目的: 用户确认执行计划

输出内容:
  - 任务数量
  - 阶段划分 (Path C)
  - 预计耗时
  - 首要任务预览
```

### [DESIGN_FREEZE]
```yaml
时机: 架构设计完成后
适用: Path C
目的: 用户确认设计方案

输出内容:
  - 架构概览
  - 模块划分
  - 技术选型
  - 风险评估
```

### [PHASE_DONE]
```yaml
时机: 每个阶段完成后
适用: Path C
目的: 确认阶段成果，决定是否继续

输出内容:
  - 阶段完成摘要
  - 验证结果
  - 下一阶段预览
```

### [TASK_DONE]
```yaml
时机: 所有任务完成后
适用: 所有路径
目的: 用户最终验收

输出内容:
  - 完成摘要
  - 验证结果
  - 后续建议
```

### [VERIFICATION_FAILED]
```yaml
时机: 验证失败时
适用: 所有路径
目的: 报告问题，请求决策

输出内容:
  - 问题描述
  - 影响范围
  - 建议方案
```

### [CLARIFY]
```yaml
时机: 需求不明确时
适用: 所有路径
目的: 请求用户澄清

输出内容:
  - 不明确的点
  - 可能的理解
  - 具体问题
```

## 调用示例

### cunzhi MCP
```javascript
cunzhi_pause({
  token: "PLAN_READY",
  summary: {
    title: "计划生成完成",
    tasks: 5,
    phases: 2,
    estimated_time: "2小时"
  },
  details: "详细计划内容...",
  options: ["确认执行", "修改计划", "取消"]
})
```

### mcp-feedback-enhanced
```javascript
mcp_feedback({
  type: "checkpoint",
  stage: "PLAN_READY",
  message: `
## 计划生成完成

### 摘要
- 任务数: 5
- 阶段: 2
- 预计: 2小时

### 详情
[计划内容]

请确认是否执行?
  `,
  require_response: true
})
```

### 文字输出 (降级)
```markdown
---
## [PLAN_READY] 寸止点

### 计划摘要
- 任务: 5个
- 阶段: 2个
- 预计: 2小时

### 等待确认
请回复以下选项之一:
1. 确认执行
2. 修改计划
3. 取消任务

⏸️ 等待您的响应...
---
```

## 禁止行为
```
❌ 只输出 [TASK_DONE] 文字但不调用工具
❌ 调用工具后不等待响应继续执行
❌ 跳过应有的寸止点
❌ 寸止输出内容不完整
```

## 最佳实践

### 寸止前准备
```yaml
1. 完成当前阶段所有工作
2. 整理状态摘要
3. 准备清晰的选项
4. 更新状态文件
```

### 寸止后响应
```yaml
收到用户确认后:
  - 确认执行 → 继续下一阶段
  - 修改请求 → 根据反馈调整
  - 取消 → 清理状态，结束任务
```

## 状态同步
```yaml
每次寸止前更新:
  - active_context.md: 当前状态
  - kanban.md: 任务状态
  - TODO.md: 完成标记

确保: 即使会话中断，状态可恢复
```