# WorkflowProgram-CN

[中文](README.md) | [English](README.en.md)

面向 Claude Code 工作区的**元工作流引擎**。它不提供业务代码，而是帮你把 workflow 做成可交付、可验证、可迭代的产品。

## 它解决什么问题

大多数 Claude Code workflow 最初都是"一个 SKILL.md + 几个 agent + 手工改 settings.json"。这样做能跑，但很快会遇到：

- 文档和实际行为脱节，没有统一真源
- 步骤顺序靠模型记忆，容易跳步漏步
- 目标项目被直接覆盖，冲突无法恢复
- 失败后无法分层定位，也没有结构化证据
- 经验留在聊天记录里，下次还是从零开始

WorkflowProgram 用四层设计系统性地回应这些问题：**真源** / **控制面** / **验证层** / **闭环层**。

## 教程

- [HTML 版教程](https://logic70.github.io/WorkflowProgram/docs/workflowprogram-101-html/) -- 可视化、循序渐进
- [HTML Tutorial (English)](docs/workflowprogram-101-html/index.en.html)
- [单页版 Markdown](docs/workflowprogram-101.md) -- 快速扫一遍全貌
- [Single-page Markdown (English)](docs/workflowprogram-101.en.md)
- [章节版 Markdown](docs/workflowprogram-101/index.md) -- 逐章深入
- [Chapter Guide (English)](docs/workflowprogram-101-en/index.md)

## 安装

**前置要求**：Python 3.10+、`pyyaml`

```bash
git clone https://github.com/Logic-70/WorkflowProgram-CN
cd WorkflowProgram-CN
pip install pyyaml
python tools/build_plugin.py
```

构建完成后，`dist/plugin/` 即为可用的插件目录。

## 使用

在你的目标项目目录中启动 Claude Code 并加载插件：

```bash
cd your-project
claude --plugin-dir /path/to/WorkflowProgram-CN/dist/plugin
```

然后用自然语言描述你的需求：

```
"为当前项目设计一个 code review workflow"
"审计当前项目的 workflow 结构"
"验证当前项目的 workflow 资产"
```

`workflowprogram-orchestrate` 会自动路由到正确的入口技能。你也可以直接调用：

| 入口 | 用途 |
|------|------|
| `workflowprogram-develop` | 从需求到交付的完整设计流程 |
| `workflowprogram-audit` | 审计已有 workflow 的结构和模式 |
| `workflowprogram-validate` | 对 workflow 资产做一次验证判定 |
| `workflowprogram-iterate` | 从 lessons 中提炼改进建议 |

## 核心概念

### 三根目录

| 目录 | 角色 | 说明 |
|------|------|------|
| `PLUGIN_ROOT` | 能力来源 | WorkflowProgram 的 skills、脚本、模板（`dist/plugin/`）。只读。 |
| `TARGET_ROOT` | 交付目标 | 用户的项目根目录。最终的 `.claude/` 资产写在这里。只通过 managed apply 写入。 |
| `RUN_ROOT` | 运行证据 | 单次运行的隔离空间（`TARGET_ROOT/.workflowprogram/runs/<run-id>/`）。 |

### 阶段模型 S0..S6

| 阶段 | 职责 |
|------|------|
| S0 | 路由：识别用户意图，准备目标环境 |
| S1 | 需求澄清：多轮对话确保规格无歧义 |
| S2 | 上下文研究：分析目标项目现有结构 |
| S3 | 设计与审批：生成 `workflow-spec.yaml`，用户审批后才进入下一步 |
| S4 | 受控写入：候选资产生成 &rarr; managed apply &rarr; runner 执行 |
| S5 | 验证判定：S5 judge 消费 test_contract 给出 verdict |
| S6 | 经验回流：提炼 lessons 和约束候选 |

不同意图走不同阶段：develop 走 S1-S6，audit 走 S5-S6，validate 只走 S5，iterate 只走 S6。

### AI 和 Python 的分工

- **AI**：理解需求、补充设计、在每个节点内生成候选资产。
- **Python**：`workflow-entry.py` 串联固定脚本链，`workflow-runner.py` 控制状态转移，`workflow-s5-judge.py` 给出判定。

编排顺序由程序决定，不由模型"记住"。

### 受控写入

AI 不直接写目标项目。而是：

1. 候选资产写到 `RUN_ROOT/outputs/candidate/`
2. `managed-assets.py plan` 生成变更计划
3. `managed-assets.py apply-staged` 执行受控写入
4. 冲突时保留副本，不静默覆盖

### 三层验证

| 层 | 职责 | 关键文件 |
|----|------|---------|
| Runner | 控制面硬约束（边界、证据、值域） | `state.json`, `events.jsonl` |
| S5 Judge | workflow 级 verdict（消费 test_contract） | `s5-validation-summary.json`, `validation-runtime-report.md` |
| Runtime Smoke | 动态端到端 harness | `tools/runtime_smoke.py` |

### 经验闭环

- `lessons.md`：追加式日志，记录失败经验和待提炼约束
- `constraints.md`：长期 ALWAYS/NEVER 规则，新会话只加载这个文件
- `s6-lessons-delta.md`：单次运行增量，由 `validate-lessons-delta.py` 校验

## 项目结构

```
WorkflowProgram-CN/
├── CLAUDE.md                    # 项目协作说明
├── README.md
├── lessons.md                   # 经验日志
├── .claude/
│   ├── settings.json            # 命令与技能注册表
│   ├── commands/                # 6 个编排入口命令
│   ├── skills/                  # 12 个技能（含 5 个主产品技能）
│   ├── agents/                  # 8 个专家 agent 定义
│   ├── rules/constraints.md     # 长期约束规则
│   └── scripts/                 # 16 个 Python 脚本 + lib/ 共享库
├── .claude-plugin/              # 插件元数据
├── dist/plugin/                 # 构建产物（--plugin-dir 加载点）
├── docs/                        # 设计文档、教程、实现计划
├── tests/                       # fixtures、expectations、transcripts
└── tools/                       # 构建、烟雾测试、mock host
```

## 开发与验证

```bash
# 仓库结构校验
python .claude/scripts/validate-workflow.py

# 烟雾测试（单场景）
python tools/runtime_smoke.py --fixture empty-project --runtime-provider fixture_host

# 烟雾测试（完整矩阵）
python tools/runtime_smoke_matrix.py

# 重新构建插件
python tools/build_plugin.py
```

## 许可

MIT