@chenguangyao/devflow-kit 0.1.43

package/docs/RFC-002-workflow-kernel.md

@@ -0,0 +1,134 @@
+# RFC-002: Workflow Kernel 与结构化 Checkpoint
+
+- **状态**: Draft / incremental implementation
+- **创建日期**: 2026-05-11
+- **目标版本**: v0.2.x
+
+## 摘要
+
+devflow-kit 早期主要依靠阶段 skill 约束 agent 行为。这个模式能快速覆盖完整流程，但在真实使用中暴露出几个整体性问题：agent 可能漏展示问题卡或下一步卡，plan 生成后可能越过用户审查直接 apply，多轮 review/apply 后用户不知道下一步，编译/测试失败也容易和历史基线问题混在一起。
+
+RFC-002 引入一个轻量 Workflow Kernel：把用户决策点、下一步卡片、风险和证据抽象成结构化 checkpoint。Skill 仍负责判断和解释，CLI/state machine 负责记录、渲染和拒绝越级推进。
+
+## 背景问题
+
+当前流程的问题不只是"编译测试空转"，而是阶段控制太依赖自然语言纪律：
+
+- **用户决策点分散**：复杂度分级、涉及项目、Round 问题、plan 审查、review 返工、baseline 风险分别写在不同 skill 中。
+- **卡片输出不稳定**：skill 文档写了要展示，但 agent 漏读或上下文过长时仍可能只输出变更列表。
+- **状态不可产品化**：`state.json.checkpoints` 之前只是简单数组，缺少统一字段，UI/CLI 很难稳定渲染。
+- **证据和风险割裂**：测试报告、部署报告、baseline failure、review finding 都有自己的表达，用户需要自己拼上下文。
+
+## 目标
+
+1. 把"需要用户确认什么"变成一等状态，而不是对话里的临时句子。
+2. 让 CLI 能统一渲染下一步卡片，减少每个 skill 手写格式的漂移。
+3. 为后续 phase gate 提供可机械检查的字段。
+4. 保留现有 markdown 工作流，不一次性重写所有阶段。
+
+## 非目标
+
+- 本 RFC 不引入 Web UI。
+- 本 RFC 不要求所有 phase 一次性迁移到 checkpoint。
+- 本 RFC 不替代 `requirement.md` / `design.md` / `plan.md` 等文件优先产物。
+
+## 数据模型
+
+Checkpoint 存在 `state.json.checkpoints[]`：
+
+```json
+{
+  "id": "plan_review-3f4a9c12",
+  "type": "plan_review",
+  "phase": "plan",
+  "status": "pending",
+  "summary": "plan.md 已生成 3 个 task",
+  "question": "是否接受计划并进入 apply？",
+  "options": [
+    { "id": "accept", "label": "接受计划", "command": "devflow apply" },
+    { "id": "revise", "label": "修改计划", "command": "devflow plan --edit" }
+  ],
+  "defaultOption": "accept",
+  "nextAction": "devflow apply",
+  "risks": [],
+  "evidence": [],
+  "createdAt": "2026-05-11T00:00:00.000Z"
+}
+```
+
+状态：
+
+- `pending`：正在等待用户确认；`devflow status` 应展示下一步卡片。
+- `resolved`：用户已选择，写入 `decision` 和 `resolvedAt`。
+- `cancelled`：该确认点被后续流程替代或废弃。
+
+## CLI
+
+新增命令：
+
+```bash
+devflow checkpoint show --slug=<slug>
+devflow checkpoint add --slug=<slug> \
+  --type=plan_review \
+  --phase=plan \
+  --summary="plan.md 已生成 3 个 task" \
+  --question="是否接受计划并进入 apply？" \
+  --options="accept=devflow apply;revise=devflow plan --edit"
+devflow checkpoint resolve --slug=<slug> --id=<checkpoint-id> --decision=accept
+devflow checkpoint cancel --slug=<slug> --id=<checkpoint-id> --reason="superseded"
+```
+
+`devflow status` 会显示最新 pending checkpoint 的标准下一步卡片。
+
+## 下一步卡片格式
+
+CLI 渲染的基础格式：
+
+```markdown
+## 下一步
+状态：NEEDS_INPUT
+检查点：plan_review
+阶段：plan
+摘要：plan.md 已生成 3 个 task
+需要你确认：是否接受计划并进入 apply？
+选项：
+- accept — 接受计划 — 命令：`devflow apply`
+- revise — 修改计划 — 命令：`devflow plan --edit`
+命令：`devflow apply`
+```
+
+## 修改原因
+
+- **减少 agent 漏步骤**：把"问不问用户"从自由文本变成状态。
+- **减少用户迷路**：每个停顿点都有固定下一步卡片。
+- **方便 UI 渲染**：Codex/Cursor/Claude 等 IDE 可以按同一字段展示卡片。
+- **方便测试**：流程规则可以通过 `state.json` 和 CLI 输出测试，而不是靠人工看对话。
+
+## 修改好处
+
+- plan 生成后不会只靠 skill 记忆"等用户审查"。
+- requirement 的问题卡、项目确认、复杂度分级可以迁移成统一 checkpoint，其中问题卡和项目确认已接入第一版 CLI gate。
+- apply / review 中的 `DONE_WITH_CONCERNS` 可以把风险和接受选项结构化。
+- verify / deliver 可以读取 unresolved checkpoint，拒绝越级推进。
+- 长期可以把多 agent 并行、baseline failure、review finding 都挂到同一个 evidence/risk 模型上。
+
+## 渐进迁移路线
+
+1. **v0.2.x**：落地 `src/core/checkpoint.js`、`devflow checkpoint`、`devflow status` 渲染 pending checkpoint。
+2. **plan gate（已接入）**：`devflow plan` 创建 `plan_review`；`devflow apply` 在该 checkpoint pending 时拒绝启动，除非 `--force --reason` 审计绕过。
+3. **intake/requirement gate（已接入）**：`devflow new/ingest` 创建 `problem_card`；`devflow requirement` 在该 checkpoint pending 时拒绝启动，除非 `--force --reason` 审计绕过。
+4. **project gate（已接入）**：`devflow requirement` 自动路由项目后创建 `project_confirmation`；`devflow design` 在该 checkpoint pending 时拒绝启动，除非 `--force --reason` 审计绕过。
+5. **review gate（已接入）**：`devflow review --round` 创建 `review_fix` / `review_blocked`；`devflow apply` 接受返工 checkpoint，review pass / force-pass 解析返工 checkpoint。
+6. **verify/deliver gate（已接入）**：`devflow verify finalize` 缺报告时创建 `verification_evidence`；`devflow deliver` 检查未解决的 review/evidence/risk checkpoint。
+7. **UI 友好（已接入）**：`devflow checkpoint show --json` 输出机器可读 `checkpoint_confirmation_surface`，包含 pending checkpoint、confirmationCard 和 nextAction，供 IDE 直接渲染问题卡/下一步卡。
+8. **证据统一**：review finding、baselineKnownFailures、test reports 逐步接入更细的 `evidence` / `risks` 模型。
+
+## 与 skill 的关系
+
+Skill 继续保留，但职责调整：
+
+- Skill：判断该停在哪里、给出问题/选项、解释原因。
+- CLI：写入 checkpoint、渲染卡片、维护状态和审计日志。
+- State machine：决定 unresolved checkpoint 是否阻止进入下一 phase。
+
+这能把 devflow-kit 从"一组流程说明"推进到"有结构化工作流内核的 CLI + Skills 套件"。

package/docs/enterprise-integration-supplement.md

@@ -0,0 +1,274 @@
+# 企业集成能力补充说明
+
+本文补充说明 devflow-kit 新增的企业内网集成能力:YAPI 同步、Jenkins job 智能匹配、SLS/OSS 日志检索、调用链一致性验证。
+
+这些能力的共同原则是:核心流程不绑定任何公司内网系统,只定义 provider、命令入口和报告形状；具体地址、token、项目映射都放在 `~/.devflow/providers.json` 或 `~/.devflow/projects.json`。
+
+## 一、能力总览
+
+| 能力 | 命令 / 配置 | 产物 | 解决的问题 |
+| --- | --- | --- | --- |
+| YAPI 同步 | `devflow sync yapi --file=<file>` + `api.yapi` provider | YAPI 接口文档 | 避免代码改了、接口契约文档没同步 |
+| Jenkins job 智能匹配 | `devflow deploy <env> --project=<name>` | `reports/test-report.md#deploy` | 项目多、job 命名不统一时,降低找错 job 的概率 |
+| SLS / OSS 日志检索 | `devflow logs query ...` + `observability.*` provider | 命令输出 / 可贴入测试报告 | 提测、联调、回归时快速拿到 traceId/requestId 证据 |
+| 调用链一致性验证 | `devflow test contract --cmd="..."` | `reports/test-report.md#contract` | 验证接口提供方、调用方、回调、跳转、日志链路是否一致 |
+
+## 二、整体流程
+
+```mermaid
+flowchart TD
+  A["design.md\n接口契约 / 核心流程 / 调用链"] --> B["devflow sync yapi\n同步 YAPI / OpenAPI"]
+  A --> C["devflow test contract\n调用链一致性验证"]
+  C --> D["reports/test-report.md#contract"]
+  E["devflow deploy test\nJenkins job 智能匹配 + 部署"] --> F["reports/test-report.md#deploy"]
+  F --> G["devflow test remote / joint / smoke"]
+  G --> H["devflow logs query\nSLS / OSS 检索 traceId/requestId"]
+  H --> I["补充到 #contract / #remote / #self-test 证据"]
+  D --> J["devflow verify finalize"]
+  I --> J
+```
+
+## 三、Provider 配置
+
+运行交互式配置:
+
+```bash
+devflow provider setup
+```
+
+当前会提供这些新增项:
+
+- `api.yapi`
+- `observability.sls`
+- `observability.oss`
+
+也可以手动写入 `~/.devflow/providers.json`。注意 token 必须优先使用 `${env:VAR}`。
+
+```jsonc
+{
+  "api.yapi": {
+    "type": "api",
+    "driver": "yapi",
+    "config": {
+      "baseUrl": "https://yapi.example.com",
+      "token": "${env:YAPI_TOKEN}",
+      "projectId": "${env:YAPI_PROJECT_ID}",
+      "syncPath": "/api/open/import_data"
+    }
+  },
+  "observability.sls": {
+    "type": "observability",
+    "driver": "sls",
+    "config": {
+      "endpoint": "${env:SLS_ENDPOINT}",
+      "project": "${env:SLS_PROJECT}",
+      "logstore": "${env:SLS_LOGSTORE}",
+      "accessKeyId": "${env:ALIYUN_ACCESS_KEY_ID}",
+      "accessKeySecret": "${env:ALIYUN_ACCESS_KEY_SECRET}",
+      "queryCommand": "aliyunlog log get_log_all --project=${project} --logstore=${logstore} --query '${query}'"
+    }
+  },
+  "observability.oss": {
+    "type": "observability",
+    "driver": "oss",
+    "config": {
+      "endpoint": "${env:OSS_ENDPOINT}",
+      "bucket": "${env:OSS_BUCKET}",
+      "prefix": "logs/",
+      "accessKeyId": "${env:ALIYUN_ACCESS_KEY_ID}",
+      "accessKeySecret": "${env:ALIYUN_ACCESS_KEY_SECRET}",
+      "queryCommand": "ossutil grep oss://${bucket}/${prefix} '${query}'"
+    }
+  }
+}
+```
+
+## 四、YAPI 同步
+
+### 使用方式
+
+```bash
+devflow sync yapi --file=./openapi.json --dry-run
+devflow sync yapi --file=./openapi.json --provider=api.yapi
+```
+
+支持输入:
+
+- OpenAPI / Swagger JSON
+- 接口说明 markdown
+
+### 流程位置
+
+YAPI 同步属于 design / verify 之间的契约同步动作:
+
+1. `design.md` 写清接口契约。
+2. 产出或整理 `openapi.json` / `api.md`。
+3. 先跑 `--dry-run` 看识别到的接口数量。
+4. 确认后同步到 YAPI。
+5. 在 `test-report.md#contract` 或 `verify.md` 记录同步结果。
+
+### 价值
+
+- 避免提测后 QA 看到旧接口文档。
+- 让接口契约从 design 进入可复查的外部文档系统。
+- 后续可以继续接 YAPI diff,把“文档是否落后实现”变成 verify 检查。
+
+## 五、Jenkins Job 智能匹配
+
+### 当前匹配规则
+
+devflow 会基于 git remote 的 `group/project`、项目名和环境名生成候选:
+
+- `group-project`
+- `group-project-test`
+- `group-test-project`
+- `project-test`
+- `project-test2`
+- `project-deploy-test`
+- `deploy/project`
+- `deploy/project-test`
+- `test/project`
+
+并降低 rollback job 的优先级。
+
+### 使用方式
+
+```bash
+devflow provider import publish-code --from=./publish-code-config.json
+devflow deploy test --project=member
+devflow deploy test --project=member --merge-to=test --preflight
+```
+
+### 为什么需要
+
+很多内部 Jenkins 命名并不统一。智能匹配不能替代人工配置,但可以:
+
+- 初始化时给出更靠谱的 job 候选。
+- 导入老配置时兼容多种命名。
+- 降低把 rollback / staging / 其他项目 job 当成测试部署 job 的概率。
+
+最终触发哪个 job 仍以 `~/.devflow/projects.json` 中项目 profile 为准。
+
+## 六、SLS / OSS 日志检索
+
+### 使用方式
+
+```bash
+devflow logs query --provider=observability.sls --trace-id=<traceId>
+devflow logs query --provider=observability.sls --request-id=<requestId>
+devflow logs query --provider=observability.oss --query="orderNo=123"
+```
+
+### 建议检索字段
+
+| 字段 | 用途 |
+| --- | --- |
+| `traceId` | 串起入口、服务调用、RPC、异步消息 |
+| `requestId` | 定位单次 HTTP 请求或网关请求 |
+| `orderNo` / `contractNo` / `signNo` | 业务链路定位 |
+| `userId` / `memberId` | 用户维度问题定位 |
+| `pay_channel` / `channel` | 渠道分支问题定位 |
+
+### 证据放哪里
+
+日志检索输出不要直接写进多个散文件。建议整理到:
+
+- `reports/test-report.md#contract`:调用链一致性证据
+- `reports/test-report.md#remote`:远程 API 验收证据
+- `reports/test-report.md#self-test`:提测自测补充说明
+
+不要把 token、cookie、完整手机号、身份证号等敏感信息写入报告。
+
+## 七、调用链一致性验证
+
+### 使用方式
+
+```bash
+devflow test contract --cmd="npm run test:contract"
+devflow test contract --cmd="go test ./... -run Contract"
+```
+
+报告写入:
+
+```text
+reports/test-report.md#contract
+```
+
+### 验证内容
+
+调用链一致性验证不是单纯的接口单测。它关注的是“链路中的每个参与者是否对同一个契约有一致理解”。
+
+应覆盖:
+
+- 提供方接口字段、枚举、状态语义。
+- 调用方解析字段是否一致。
+- `returnUrl` / `redirect` / `callback` / query 参数是否丢失或被误用。
+- 前端轮询 key、后端签约号、订单号、渠道字段来源是否一致。
+- traceId / requestId 是否贯穿入口、下游调用、回调和日志。
+- YAPI / OpenAPI 文档是否与实现一致。
+
+### 什么时候需要
+
+| Level | 是否需要 |
+| --- | --- |
+| L0 | 通常不需要 |
+| L1 | 只有接口契约变化时补 |
+| L2 | 有调用方、回调、跳转、前后端消费者时补 |
+| L3 | 跨服务核心链路默认补 |
+
+## 八、Design 模板新增内容
+
+`design.md` 现在会提示补充:
+
+```markdown
+### YAPI / OpenAPI 同步
+
+- 契约文件：
+- 同步命令：`devflow sync yapi --file=<openapi.json|api.md> --dry-run`
+
+### 调用链一致性验证
+
+- traceId / requestId 传递点：
+- 调用方 / 回调 / redirect / query 参数：
+- 日志检索：`devflow logs query --trace-id=<id>` 或 `--request-id=<id>`
+- 验证命令：`devflow test contract --cmd="<contract/check command>"`
+```
+
+这部分的目标不是让每个需求都填满,而是提醒 agent 和开发者:只要涉及接口、回调、跳转、异步链路或跨服务消费者,就不能只写“后端改接口”,必须说明消费者和验证证据。
+
+## 九、推荐执行顺序
+
+```bash
+# 1. 设计阶段
+devflow design
+
+# 2. 接口契约同步
+devflow sync yapi --file=./openapi.json --dry-run
+devflow sync yapi --file=./openapi.json
+
+# 3. 实现后验证调用链
+devflow test contract --cmd="npm run test:contract"
+
+# 4. 部署测试环境
+devflow deploy test --project=<project> --merge-to=test --preflight
+
+# 5. 远程 / 联调 / 冒烟
+devflow test remote --api-base-url=<url> --cmd="..."
+devflow test joint --backend-url=<url> --frontend-url=<url> --cmd="..."
+devflow test smoke --cmd="curl -fsS <url>/health"
+
+# 6. 检索日志证据
+devflow logs query --trace-id=<traceId>
+
+# 7. 汇总验证
+devflow report self-test
+devflow verify finalize
+```
+
+## 十、后续可扩展点
+
+- YAPI diff:同步前比较 YAPI 现有接口与本次 OpenAPI,把破坏性变更转成 verify warning。
+- Jenkins live discovery:通过 Jenkins API 拉取 job 列表后用 `rankJenkinsJobs()` 排序,让 CLI 交互选择。
+- SLS 原生签名:当前支持 `queryCommand` 模板,后续可内置阿里云 SLS API 签名。
+- OSS 原生检索:当前支持 `queryCommand` 模板,后续可接 OSS SDK 或 `ossutil` 封装。
+- trace report:把一次 traceId 的多服务日志整理为链路表,直接写入 `test-report.md#contract`。