@feng-h/pdca-skill 1.0.8 → 1.0.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/CLAUDE.md +209 -93
  2. package/README.md +33 -27
  3. package/package.json +1 -1
package/CLAUDE.md CHANGED
@@ -2,107 +2,223 @@
2
2
 
3
3
  This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
4
 
5
- ## Project Overview
5
+ ---
6
6
 
7
- PDCA-with-AI is an **AI-driven workflow system** based on the PDCA (Plan-Do-Check-Act) cycle, not a traditional software codebase. The system integrates with Feishu (Lark) tools (Wiki, Bitable, Calendar, Task, Sheet) to provide structured problem-solving workflows for manufacturing and quality improvement scenarios.
7
+ ## 项目概述 / Project Overview
8
8
 
9
- **Key distinction:** This project consists primarily of markdown files that define AI agents, workflows, and templates. There is no TypeScript/JavaScript source code to build or test.
9
+ **PDCA-with-AI** 是一个基于 PDCA 循环的 AI 驱动型工作流系统，专为 **OpenClaw + 飞书（Feishu/Lark）** 深度集成设计。
10
10
 
11
- ## Architecture
11
+ **核心特点**：
12
+ - 非 traditional 软件代码库，主要由 markdown 文件定义 AI agents、workflows 和 templates
13
+ - 深度依赖飞书 API（Wiki、Bitable、Calendar、Task、Sheet）
14
+ - 遵循 [superpowers:writing-skills](https://github.com/obra/superpowers) 标准
12
15
 
13
- ### Entry Point
14
- - **`pdca/SKILL.md`** — The main skill definition. When the `pdca` skill is invoked, this file contains the primary logic for project evaluation and creation.
16
+ ---
15
17
 
16
- ### Core System Files (`_系统/`)
17
- - **`Agent/PDCA控制器.md`** — Central orchestrator managing the PDCA time flow, phase transitions, and rollback mechanisms
18
- - **`Agent/PlanAgent.md`**, **`DoAgent.md`**, **`CheckAgent.md`**, **`ActAgent.md`** — Phase-specific AI agents
19
- - **`规范/核心规范.md`** — Core system standards, including the principle that **Bitable is the single source of truth for all data**
20
- - **`规范/Validators/smart.md`** — SMART goal validation standards
21
- - **`规范/Validators/logic.md`** — Causal logic chain validation
18
+ ## 当前状态 / Current Status
22
19
 
23
- ### Reference Documentation (`pdca/references/`)
24
- - **`feishu-integration.md`** — Complete Feishu API integration patterns (Wiki, Bitable, Calendar, Task, Sheet)
25
- - **`cron-driving.md`** — Automated inspection loop logic (The Loop: Scrape → Load → Verify → Message)
26
- - **`transition-checklist.md`** — Phase transition requirements
27
- - **`exception-handling.md`** — Exception handling patterns
20
+ | 项目 | 状态 |
21
+ |------|------|
22
+ | **GitHub** | https://github.com/Feng-H/PDCA-with-AI |
23
+ | **npm 包** | @feng-h/pdca-skill |
24
+ | **最新版本** | v1.0.9 |
25
+ | **安装方式** | `npx skills add Feng-H/PDCA-with-AI --agent skills` |
26
+
27
+ ---
28
+
29
+ ## 项目结构 / Project Structure
28
30
 
29
- ### Project Structure
30
31
  ```
31
32
  PDCA-with-AI/
32
- ├── pdca/ # Skill package (frontend interface layer)
33
- │ ├── SKILL.md # Main skill entry point
34
- │ ├── references/ # Detailed guides
35
- │ └── tests/ # Baseline tests
36
- ├── _系统/ # Core engine (backend specifications)
37
- │ ├── Agent/ # Agent definitions
38
- │ ├── 规范/ # Standards and validators
39
- │ └── 工具/ # Operational guides
40
- └── 项目/ # Active project instances
33
+ ├── SKILL.md # OpenClaw/Gemini 技能入口（主要文件）
34
+ ├── .claude/skills/ # Claude Code 参考文档（非执行）
35
+ ├── assets/ # 详细文档与测试
36
+ │ ├── references/ # 飞书 API 集成指南
37
+ │ ├── tests/ # 基线测试与质量验证
38
+ │ └── templates/ # 项目模板
39
+ ├── system/ # 核心引擎层
40
+ │ ├── Agent/ # Plan/Do/Check/Act Agent 提示词
41
+ │ ├── 规范/ # SMART 校验与因果逻辑模组
42
+ │ ├── 工具/ # Bitable 配置、工作流等
43
+ │ └── 模板/ # 系统模板
44
+ ├── bin/ # npx 可执行文件
45
+ ├── package.json # npm 包配置
46
+ └── README.md # 项目说明（中/英/日）
41
47
  ```
42
48
 
43
- ## Key Workflows
44
-
45
- ### Three Primary Commands
46
- The system is invoked through three main intents (defined in `_系统/项目管理系统.md`):
47
-
48
- | Command | Purpose | Output |
49
- |---------|---------|--------|
50
- | `new` | Initialize a new project | Creates Feishu Wiki + Bitable + Calendar resources |
51
- | `ongoing` | Manage active projects | Progress check + status update + alerts |
52
- | `achieve` | Search experience library | Best practice recommendations + template matching |
53
-
54
- ### Phase Transition Logic
55
- Phase transitions are **strictly sequential** and require:
56
- 1. Completion of all mandatory tasks in current phase
57
- 2. Verification against `_系统/工具/阶段转换检查表.md`
58
- 3. Explicit user confirmation (via Feishu interactive cards)
59
-
60
- ### The Loop (Automated Inspection)
61
- The PDCA Controller runs a 4-step inspection cycle:
62
- 1. **Scrape (Wiki)**: Fetch all project documents from Feishu Wiki
63
- 2. **Load (Logic)**: Load phase-specific "required conditions" and "deliverables checklist"
64
- 3. **Verify**: Compare Wiki content against requirements, identify gaps or logic conflicts
65
- 4. **Message (Card)**: Send Feishu interactive card (green/yellow/red based on severity)
66
-
67
- ## Quality Standards
68
-
69
- This project follows [superpowers:writing-skills](https://github.com/obra/superpowers) standards:
70
- - **RED-GREEN-REFACTOR**: All skills validated via baseline tests
71
- - **Rationalization Defense**: Explicit prohibitions against common agent shortcuts
72
- - **Red Flags**: Stop-and-restart signals when quality is at risk
73
-
74
- ### Critical Red Flags
75
- When you encounter these signals, **STOP immediately** and return to Plan phase:
76
- - Goals without specific numbers
77
- - "We'll adjust during execution"
78
- - "Quick fix is enough"
79
- - "Boss is rushing, let's start"
80
- - "Already spent X weeks" (sunk cost fallacy)
81
- - Accepting user-provided causes without Why/verification
82
-
83
- ### Rationalization Defenses
84
- Common excuses that must be rejected:
85
- - "Time is tight, need to launch quickly" → Fast launch without clear goals = accelerating in wrong direction
86
- - "No project manager, use simple approach" → Simple approach still needs SMART foundation
87
- - "User already identified the cause" → User provides symptoms, not root causes
88
- - "Plan took 3 weeks, too long" → Time is not a reason to skip quality checks
89
-
90
- ## Important Constraints
91
-
92
- 1. **Single Source of Truth**: Feishu Bitable is the only authoritative source for project status data
93
- 2. **User Decision Required**: All phase transitions and project closures require explicit user confirmation
94
- 3. **Immediate Alerting**: When inspection finds logic deviations or progress stagnation, immediately send Feishu interactive card
95
- 4. **No Shortcuts**: SMART validation and causal logic verification are mandatory, not optional
96
-
97
- ## Testing
98
-
99
- Baseline test scenarios are in `pdca/tests/baseline-test-scenarios.md`. These verify behavior WITHOUT the skill loaded to identify problems that the skill should solve.
100
-
101
- ## Feishu Integration Notes
102
-
103
- Key Feishu API patterns from `feishu-integration.md`:
104
- - **Bitable person fields**: Must be `[{id: "ou_xxx"}]`, not strings
105
- - **Bitable date fields**: Millisecond timestamps, not seconds
106
- - **Bitable hyperlink fields (type=15)**: Do NOT pass `property` parameter on create
107
- - **Calendar events**: Always pass `user_open_id` from SenderId so user can see the event
108
- - **No concurrent writes**: Bitable does not support concurrent writes, call serially with 0.5-1s delay
49
+ **路径变更说明**：
50
+ - 原 `pdca/` → 现 `assets/`
51
+ - 原 `_系统/` → 现 `system/`
52
+
53
+ ---
54
+
55
+ ## 核心依赖 / Core Dependencies
56
+
57
+ ### 必需平台 / Required Platform
58
+
59
+ | 组件 | 说明 | 获取方式 |
60
+ |------|------|---------|
61
+ | **OpenClaw** | AI CLI 框架 | https://github.com/open-claw/open-claw |
62
+ | **飞书插件** | 提供 feishu-* API | OpenClaw 官方插件 |
63
+
64
+ ### 关键 API 列表
65
+
66
+ 本技能包依赖以下飞书 API（**仅 OpenClaw 飞书插件提供**）：
67
+
68
+ | API | 功能 |
69
+ |-----|------|
70
+ | `feishu-create-doc` | 创建 Wiki 文档 |
71
+ | `feishu-update-doc` | 更新文档内容 |
72
+ | `feishu-fetch-doc` | 读取文档内容 |
73
+ | `feishu-bitable` | 多维表格 CRUD（27种字段类型） |
74
+ | `feishu-calendar` | 日程管理 |
75
+ | `feishu-task` | 任务管理 |
76
+ | `feishu-sheet` | 电子表格 |
77
+ | `feishu-im-read` | 消息读取 |
78
+
79
+ ---
80
+
81
+ ## 核心工作流 / Core Workflows
82
+
83
+ ### 三大命令
84
+
85
+ | 命令 | 功能 | 输出 |
86
+ |------|------|------|
87
+ | `new` | 启动新项目 | 创建 Wiki + Bitable 应用 + Calendar |
88
+ | `ongoing` | 管理活跃项目 | 进度检查 + 状态更新 + 预警 |
89
+ | `achieve` | 检索经验库 | 最佳实践推荐 + 模板匹配 |
90
+
91
+ ### 阶段转换逻辑
92
+
93
+ 阶段转换**严格按顺序**，需要：
94
+ 1. 当前阶段所有必选任务完成
95
+ 2. 对照 `system/工具/阶段转换检查表.md` 验证
96
+ 3. 用户通过飞书交互式卡片确认
97
+
98
+ ### The Loop（自治巡检）
99
+
100
+ PDCA 控制器运行的 4 步巡检循环：
101
+ 1. **Scrape (Wiki)**：获取所有项目文档
102
+ 2. **Load (Logic)**：加载阶段特定的"必需条件"和"交付物清单"
103
+ 3. **Verify**：对比 Wiki 内容与要求，识别差距或逻辑冲突
104
+ 4. **Message (Card)**：发送飞书交互式卡片（绿/黄/红基于严重程度）
105
+
106
+ ---
107
+
108
+ ## 质量标准 / Quality Standards
109
+
110
+ ### Red Flags - 立即停止
111
+
112
+ 遇到以下信号时，**立即停止**并返回 Plan 阶段：
113
+ - 目标没有具体数字
114
+ - "执行中再调整"
115
+ - "快速补救一下"
116
+ - "老板在催，先开始吧"
117
+ - "已经花了 X 周了"（沉没成本谬误）
118
+ - 直接接受用户提供的原因而不验证
119
+
120
+ ### Rationalization 防御
121
+
122
+ | 借口 | 现实 |
123
+ |------|------|
124
+ | "时间紧，需要快速上线" | 没有清晰目标的快速上线 = 朝错误方向加速 |
125
+ | "没有项目经理，用简单方式" | 简单方式仍需 SMART 基础 |
126
+ | "用户已经说了原因" | 用户说的是症状，不是根因 |
127
+
128
+ ---
129
+
130
+ ## 重要约束 / Important Constraints
131
+
132
+ 1. **Single Source of Truth**：飞书 Bitable 是项目状态的唯一权威数据源
133
+ 2. **User Decision Required**：所有阶段转换和项目结项需用户确认
134
+ 3. **Immediate Alerting**：巡检发现逻辑偏差或进度停滞，立即发送飞书交互式卡片
135
+ 4. **No Shortcuts**：SMART 校验和因果逻辑验证是强制的，不可跳过
136
+
137
+ ---
138
+
139
+ ## 飞书 API 注意事项 / Feishu API Notes
140
+
141
+ ### 关键坑位
142
+
143
+ | 字段类型 | 注意事项 |
144
+ |---------|---------|
145
+ | **人员字段** | 必须是 `[{id: "ou_xxx"}]`，不能是字符串 |
146
+ | **日期字段** | 毫秒时间戳，不是秒 |
147
+ | **超链接字段 (type=15)** | 创建时不要传 `property` 参数 |
148
+ | **日历事件** | 必须传 `user_open_id` 让用户能看到日程 |
149
+ | **并发写入** | Bitable 不支持并发写，串行调用 + 0.5-1s 延迟 |
150
+
151
+ ---
152
+
153
+ ## 测试 / Testing
154
+
155
+ 基线测试场景：`assets/tests/baseline-test-scenarios.md`
156
+
157
+ 这些验证**不加载技能时的行为**，以识别技能应该解决的问题。
158
+
159
+ ---
160
+
161
+ ## 使用后优化指南 / Optimization Guide
162
+
163
+ ### 当你发现问题时
164
+
165
+ 1. **问题分类**：
166
+ - **内容问题**（SKILL.md 描述不清、流程有误）
167
+ - **API 问题**（飞书 API 调用错误、参数不对）
168
+ - **逻辑问题**（阶段转换条件、验证规则）
169
+ - **格式问题**（文档结构、路径引用）
170
+
171
+ 2. **对应文件**：
172
+ | 问题类型 | 修改文件 |
173
+ |---------|---------|
174
+ | 内容问题 | `SKILL.md`, `system/Agent/*.md` |
175
+ | API 问题 | `assets/references/feishu-integration.md` |
176
+ | 逻辑问题 | `system/规范/Validators/*.md` |
177
+ | 格式问题 | `README.md`, `CLAUDE.md` |
178
+
179
+ 3. **修改后操作**：
180
+ ```bash
181
+ # 1. 提交到 GitHub
182
+ git add -A && git commit -m "fix: 描述修改内容"
183
+ git push origin main
184
+
185
+ # 2. 发布新版本
186
+ npm version patch # 或 minor/major
187
+ ```
188
+
189
+ 这会自动推送 + 发布到 npm（配置了 postversion hook）
190
+
191
+ ### 快速进入状态
192
+
193
+ 当你下次来优化时，需要检查：
194
+ 1. **npm 版本**：`npm view @feng-h/pdca-skill version`
195
+ 2. **文档结构**：`ls -la assets/ system/`
196
+ 3. **用户反馈**：具体问题描述
197
+
198
+ ---
199
+
200
+ ## 最近变更 / Recent Changes
201
+
202
+ | 版本 | 日期 | 变更 |
203
+ |------|------|------|
204
+ | v1.0.9 | 2026-04-06 | 添加 OpenClaw 对比表格，说明 Lark-CLI 可能性 |
205
+ | v1.0.8 | 2026-04-06 | 说明为什么需要 OpenClaw + 飞书 |
206
+ | v1.0.7 | 2026-04-06 | 添加中/英/日多语言 README |
207
+ | v1.0.6 | 2026-04-06 | 添加 Claude Code 技能支持 |
208
+ | v1.0.5 | 2026-04-06 | 添加 npx bin 可执行文件 |
209
+ | v1.0.0-v1.0.4 | 2026-04-06 | 初始版本，项目结构重构 |
210
+
211
+ ---
212
+
213
+ ## 发布流程 / Release Process
214
+
215
+ ```bash
216
+ # 一键发布（自动推送到 GitHub + npm）
217
+ npm run release:patch # 补丁版本 (1.0.9 → 1.0.10)
218
+ npm run release:minor # 次要版本 (1.0.9 → 1.1.0)
219
+ npm run release:major # 主要版本 (1.0.9 → 2.0.0)
220
+ ```
221
+
222
+ ---
223
+
224
+ **Designed for OpenClaw + Feishu** / **专为 OpenClaw + 飞书设计**
package/README.md CHANGED
@@ -27,15 +27,17 @@ This is a specialized skill package with **deep Feishu/Lark API integration**, d
27
27
 
28
28
  本技能包的核心功能依赖于以下**飞书专属 API**，这些 API 只有 OpenClaw 飞书插件提供：
29
29
 
30
- | API 调用 | 功能 | Claude Code | Gemini | Codex |
31
- |---------|------|-------------|--------|-------|
32
- | `feishu-create-doc` | 创建云文档到 Wiki/知识库 | ❌ | ❌ | ❌ |
33
- | `feishu-update-doc` | 局部更新文档内容 | ❌ | ❌ | ❌ |
34
- | `feishu-bitable` | 多维表格 CRUD (27种字段类型) | ❌ | ❌ | ❌ |
35
- | `feishu-calendar` | 日程管理和事件创建 | ❌ | ❌ | ❌ |
36
- | `feishu-task` | 任务创建、查询、更新 | ❌ | ❌ | ❌ |
37
- | `feishu-sheet` | 电子表格操作 | ❌ | ❌ | ❌ |
38
- | `feishu-im-read` | 群聊/私聊历史读取 | ❌ | ❌ | ❌ |
30
+ | API 调用 | 功能 | OpenClaw | Claude Code | Gemini | Codex |
31
+ |---------|------|----------|-------------|--------|-------|
32
+ | `feishu-create-doc` | 创建云文档到 Wiki/知识库 | ✅ | ⚠️* | ⚠️* | ⚠️* |
33
+ | `feishu-update-doc` | 局部更新文档内容 | ✅ | ⚠️* | ⚠️* | ⚠️* |
34
+ | `feishu-bitable` | 多维表格 CRUD (27种字段类型) | ✅ | ⚠️* | ⚠️* | ⚠️* |
35
+ | `feishu-calendar` | 日程管理和事件创建 | ✅ | ⚠️* | ⚠️* | ⚠️* |
36
+ | `feishu-task` | 任务创建、查询、更新 | ✅ | ⚠️* | ⚠️* | ⚠️* |
37
+ | `feishu-sheet` | 电子表格操作 | ✅ | ⚠️* | ⚠️* | ⚠️* |
38
+ | `feishu-im-read` | 群聊/私聊历史读取 | ✅ | ⚠️* | ⚠️* | ⚠️* |
39
+
40
+ > *⚠️ 理论上可通过 Lark-CLI 等第三方工具实现，但未经测试。本技能包仅针对 OpenClaw 飞书插件进行验证。*
39
41
 
40
42
  **关键特性**：
41
43
  - **一个项目 = 一个文件夹 = 一个 Bitable 应用** — 飞书原生架构
@@ -51,15 +53,17 @@ This is a specialized skill package with **deep Feishu/Lark API integration**, d
51
53
 
52
54
  This skill package relies on the following **Feishu-exclusive APIs**, only available via OpenClaw Feishu Plugin:
53
55
 
54
- | API Call | Function | Claude Code | Gemini | Codex |
55
- |---------|----------|-------------|--------|-------|
56
- | `feishu-create-doc` | Create docs in Wiki/Knowledge Base | ❌ | ❌ | ❌ |
57
- | `feishu-update-doc` | Partial document updates | ❌ | ❌ | ❌ |
58
- | `feishu-bitable` | Bitable CRUD (27 field types) | ❌ | ❌ | ❌ |
59
- | `feishu-calendar` | Calendar & event management | ❌ | ❌ | ❌ |
60
- | `feishu-task` | Task creation, query, update | ❌ | ❌ | ❌ |
61
- | `feishu-sheet` | Spreadsheet operations | ❌ | ❌ | ❌ |
62
- | `feishu-im-read` | Group/private chat history | ❌ | ❌ | ❌ |
56
+ | API Call | Function | OpenClaw | Claude Code | Gemini | Codex |
57
+ |---------|----------|----------|-------------|--------|-------|
58
+ | `feishu-create-doc` | Create docs in Wiki/Knowledge Base | ✅ | ⚠️* | ⚠️* | ⚠️* |
59
+ | `feishu-update-doc` | Partial document updates | ✅ | ⚠️* | ⚠️* | ⚠️* |
60
+ | `feishu-bitable` | Bitable CRUD (27 field types) | ✅ | ⚠️* | ⚠️* | ⚠️* |
61
+ | `feishu-calendar` | Calendar & event management | ✅ | ⚠️* | ⚠️* | ⚠️* |
62
+ | `feishu-task` | Task creation, query, update | ✅ | ⚠️* | ⚠️* | ⚠️* |
63
+ | `feishu-sheet` | Spreadsheet operations | ✅ | ⚠️* | ⚠️* | ⚠️* |
64
+ | `feishu-im-read` | Group/private chat history | ✅ | ⚠️* | ⚠️* | ⚠️* |
65
+
66
+ > *⚠️ Theoretically achievable via third-party tools like Lark-CLI, but untested. This skill package is only validated for OpenClaw Feishu Plugin.*
63
67
 
64
68
  **Key Features**:
65
69
  - **One Project = One Folder = One Bitable App** — Native Feishu architecture
@@ -75,15 +79,17 @@ These features are built on deep integration with Feishu toolchain and cannot be
75
79
 
76
80
  このスキルパッケージは、以下の **Feishu 専用 API** に依存しており、OpenClaw Feishu プラグイン経由でのみ利用可能です：
77
81
 
78
- | API 呼び出し | 機能 | Claude Code | Gemini | Codex |
79
- |-------------|------|-------------|--------|-------|
80
- | `feishu-create-doc` | Wiki/ナレッジベースにドキュメント作成 | ❌ | ❌ | ❌ |
81
- | `feishu-update-doc` | ドキュメントの部分更新 | ❌ | ❌ | ❌ |
82
- | `feishu-bitable` | Bitable CRUD（27種のフィールドタイプ） | ❌ | ❌ | ❌ |
83
- | `feishu-calendar` | カレンダーとイベント管理 | ❌ | ❌ | ❌ |
84
- | `feishu-task` | タスク作成、照会、更新 | ❌ | ❌ | ❌ |
85
- | `feishu-sheet` | スプレッドシート操作 | ❌ | ❌ | ❌ |
86
- | `feishu-im-read` | グループ/プライベートチャット履歴 | ❌ | ❌ | ❌ |
82
+ | API 呼び出し | 機能 | OpenClaw | Claude Code | Gemini | Codex |
83
+ |-------------|------|----------|-------------|--------|-------|
84
+ | `feishu-create-doc` | Wiki/ナレッジベースにドキュメント作成 | ✅ | ⚠️* | ⚠️* | ⚠️* |
85
+ | `feishu-update-doc` | ドキュメントの部分更新 | ✅ | ⚠️* | ⚠️* | ⚠️* |
86
+ | `feishu-bitable` | Bitable CRUD（27種のフィールドタイプ） | ✅ | ⚠️* | ⚠️* | ⚠️* |
87
+ | `feishu-calendar` | カレンダーとイベント管理 | ✅ | ⚠️* | ⚠️* | ⚠️* |
88
+ | `feishu-task` | タスク作成、照会、更新 | ✅ | ⚠️* | ⚠️* | ⚠️* |
89
+ | `feishu-sheet` | スプレッドシート操作 | ✅ | ⚠️* | ⚠️* | ⚠️* |
90
+ | `feishu-im-read` | グループ/プライベートチャット履歴 | ✅ | ⚠️* | ⚠️* | ⚠️* |
91
+
92
+ > *⚠️ 理論的には Lark-CLI などのサードパーティツールで実現可能ですが、未テストです。このスキルパッケージは OpenClaw Feishu プラグインでのみ検証されています。*
87
93
 
88
94
  **主な機能**：
89
95
  - **1プロジェクト = 1フォルダ = 1 Bitable アプリ** — Feishu ネイティブアーキテクチャ
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@feng-h/pdca-skill",
3
- "version": "1.0.8",
3
+ "version": "1.0.10",
4
4
  "description": "PDCA project management system for Feishu/Lark integration with AI-driven workflow",
5
5
  "keywords": [
6
6
  "skills",