@dev-workflow/skill 0.1.0

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 (74) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +80 -0
  3. package/bin/cli.mjs +9 -0
  4. package/package.json +39 -0
  5. package/skills/artifact/README.md +23 -0
  6. package/skills/execution/devFlow/SKILL.md +341 -0
  7. package/skills/execution/devFlow/agents/openai.yaml +7 -0
  8. package/skills/execution/devFlow/domains/backend/references/api-tech.md +173 -0
  9. package/skills/execution/devFlow/domains/backend/scripts/check_api_tech_doc.mjs +170 -0
  10. package/skills/execution/devFlow/domains/backend/scripts/check_api_tech_doc.test.mjs +89 -0
  11. package/skills/execution/devFlow/domains/backend/templates/api-tech.md +164 -0
  12. package/skills/execution/devFlow/domains/frontend/references/contract-check.md +270 -0
  13. package/skills/execution/devFlow/domains/frontend/references/foundation-freeze.md +92 -0
  14. package/skills/execution/devFlow/domains/frontend/references/lightweight-flow.md +55 -0
  15. package/skills/execution/devFlow/domains/frontend/references/page-build.md +268 -0
  16. package/skills/execution/devFlow/domains/frontend/references/page-tech.md +414 -0
  17. package/skills/execution/devFlow/domains/frontend/references/product-design-specs/field-common.md +69 -0
  18. package/skills/execution/devFlow/domains/frontend/references/product-design-specs/fields-complex.md +105 -0
  19. package/skills/execution/devFlow/domains/frontend/references/product-design-specs/fields-id-code.md +44 -0
  20. package/skills/execution/devFlow/domains/frontend/references/product-design-specs/fields-number-date.md +106 -0
  21. package/skills/execution/devFlow/domains/frontend/references/product-design-specs/fields-relation.md +144 -0
  22. package/skills/execution/devFlow/domains/frontend/references/product-design-specs/fields-selectors.md +102 -0
  23. package/skills/execution/devFlow/domains/frontend/references/product-design-specs/fields-text.md +130 -0
  24. package/skills/execution/devFlow/domains/frontend/references/product-design-specs/index.md +42 -0
  25. package/skills/execution/devFlow/domains/frontend/references/product-design-specs/interaction.md +61 -0
  26. package/skills/execution/devFlow/domains/frontend/scripts/check_page_tech_doc.mjs +82 -0
  27. package/skills/execution/devFlow/domains/frontend/scripts/contract_check_static.mjs +145 -0
  28. package/skills/execution/devFlow/domains/frontend/scripts/generate_foundation_summary.mjs +224 -0
  29. package/skills/execution/devFlow/domains/frontend/templates/contract-report.md +66 -0
  30. package/skills/execution/devFlow/domains/frontend/templates/mini-plan-l0.md +7 -0
  31. package/skills/execution/devFlow/domains/frontend/templates/mini-plan-l1.md +9 -0
  32. package/skills/execution/devFlow/domains/frontend/templates/page-build/component.tsx.tpl +8 -0
  33. package/skills/execution/devFlow/domains/frontend/templates/page-build/constants.ts.tpl +5 -0
  34. package/skills/execution/devFlow/domains/frontend/templates/page-build/index.ts.tpl +1 -0
  35. package/skills/execution/devFlow/domains/frontend/templates/page-build/route.tsx.tpl +11 -0
  36. package/skills/execution/devFlow/domains/frontend/templates/page-build/service.ts.tpl +17 -0
  37. package/skills/execution/devFlow/domains/frontend/templates/page-build/types.ts.tpl +11 -0
  38. package/skills/execution/devFlow/domains/frontend/templates/page-tech.md +103 -0
  39. package/skills/execution/devFlow/domains/requirement/references/prd-review.md +129 -0
  40. package/skills/execution/devFlow/domains/requirement/templates/prd-review.md +57 -0
  41. package/skills/execution/figmaSync/SKILL.md +349 -0
  42. package/skills/execution/figmaSync/chapters/apply.md +177 -0
  43. package/skills/execution/figmaSync/chapters/plan.md +359 -0
  44. package/skills/execution/figmaSync/chapters/prepare.md +47 -0
  45. package/skills/execution/figmaSync/examples/native-css.md +129 -0
  46. package/skills/execution/figmaSync/examples/plan-doc-sample.md +39 -0
  47. package/skills/execution/figmaSync/scripts/_shared/session-log.mjs +82 -0
  48. package/skills/execution/figmaSync/scripts/_shared/token-resolver.mjs +132 -0
  49. package/skills/execution/figmaSync/scripts/_shared/token-source.mjs +145 -0
  50. package/skills/execution/figmaSync/scripts/figma-sync-report.mjs +448 -0
  51. package/skills/execution/figmaSync/scripts/icon-inventory.mjs +165 -0
  52. package/skills/execution/figmaSync/scripts/lookup-var.mjs +184 -0
  53. package/skills/execution/figmaSync/scripts/match-token.mjs +210 -0
  54. package/skills/execution/figmaSync/scripts/prepare-check.mjs +290 -0
  55. package/skills/execution/figmaSync/scripts/verify-plan.mjs +458 -0
  56. package/skills/execution/figmaSync/snapshots/README.md +13 -0
  57. package/skills/execution/figmaSync/snapshots/last-sync.md +1538 -0
  58. package/skills/execution/figmaSync/templates/PLAN.md.tpl +227 -0
  59. package/skills/review/consistency-checker/SKILL.md +112 -0
  60. package/skills/review/consistency-checker/rules/README.md +16 -0
  61. package/src/cli/agents.mjs +16 -0
  62. package/src/cli/copy.mjs +95 -0
  63. package/src/cli/install.mjs +131 -0
  64. package/src/cli/prompts.mjs +66 -0
  65. package/tools/lark/README.md +78 -0
  66. package/tools/lark/references/lark-doc.md +156 -0
  67. package/tools/lark/references/lark-read.md +235 -0
  68. package/tools/lark/references/prepare.md +147 -0
  69. package/tools/lark/scripts/lark_api.mjs +404 -0
  70. package/tools/lark/scripts/lark_api.test.mjs +63 -0
  71. package/tools/lark/scripts/lark_check_permissions.mjs +52 -0
  72. package/tools/lark/scripts/lark_publish_doc.mjs +299 -0
  73. package/tools/lark/scripts/lark_read_docx.mjs +328 -0
  74. package/tools/lark/scripts/markdown_to_lark_blocks.mjs +397 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Wenyari
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,80 @@
1
+ # dev-workflow-skill
2
+
3
+ 研发协作 AI 工具库。方法论基础:[研发协作方法论.md](./研发协作方法论.md)。
4
+
5
+ **核心思想**:AI 只生成结构化、可审核、可修改的初稿,人是文档与代码的最终决策者。
6
+
7
+ ## 安装到你的仓库
8
+
9
+ 一条命令把 skill 装到项目级目录:
10
+
11
+ ```bash
12
+ npx @dev-workflow/skill
13
+ ```
14
+
15
+ 跑起来后交互式选择:
16
+
17
+ 1. **目标 agent**:Claude Code(装到 `.claude/`)或 Codex(装到 `.agents/`)
18
+ 2. **冲突策略**:跳过已存在文件 / 全部覆盖 / 逐个决定
19
+
20
+ 装完的目录结构(以 Claude Code 为例):
21
+
22
+ ```
23
+ .claude/
24
+ ├── skills/
25
+ │ ├── execution/{devFlow, figmaSync}/
26
+ │ ├── review/consistency-checker/
27
+ │ └── artifact/
28
+ └── tools/lark/
29
+ ```
30
+
31
+ **装完请手动做两件事**:
32
+
33
+ 1. `git add .claude && git commit -m "chore: install @dev-workflow/skill"`(跟随仓库走,团队共享同一版本)
34
+ 2. 从本仓库把 [`HUMAN_AGENT_WORKFLOW.md`](./HUMAN_AGENT_WORKFLOW.md) 复制到目标项目根目录 —— `devFlow` / `prd-review` 依赖它判断 L0/L1/L2/L3 分档;CLI 检测到缺失会打印警告,但不会代你搬。
35
+
36
+ **升级**:重跑 `npx @dev-workflow/skill`,冲突策略选「全部覆盖」即可。npm 缓存会自动拉最新版;固定版本用 `npx @dev-workflow/skill@0.1.0`。
37
+
38
+ ## 我要开始用
39
+
40
+ - **第一次用** → [QUICKSTART.md](./QUICKSTART.md)
41
+ - **不确定用哪个** → [DECISION_TREE.md](./DECISION_TREE.md)
42
+ - **已经知道用哪个** → [CHEATSHEET.md](./CHEATSHEET.md)
43
+
44
+ ## 我要贡献
45
+
46
+ - **加 skill / tool** → [CONTRIBUTING.md](./CONTRIBUTING.md)
47
+ - **SKILL.md 模板** → [docs/skill-template/](./docs/skill-template/)
48
+
49
+ ## 仓库结构
50
+
51
+ ```
52
+ skills/
53
+ ├── review/ 评审层:AI 三角色规范(规划中)
54
+ │ ├── consistency-checker/ PM↔UI 一致性检查
55
+ │ ├── risk-scanner/ 需求评审风险扫描
56
+ │ └── contract-aligner/ 技术评审契约对齐
57
+ ├── execution/ 开发层:方案生成 + 代码落地
58
+ │ ├── devFlow/ 页面 / 后端方案 + 页面基建
59
+ │ └── figmaSync/ Figma → 原生 CSS
60
+ └── artifact/ 产物层:跨环节数据收口(规划中)
61
+ ├── open-issues/ 未闭环清单
62
+ └── calibration/ 校准清单 + 回喂
63
+
64
+ tools/ 共享能力(不对用户暴露)
65
+ ├── lark/ 飞书读写、Markdown 转 blocks、权限检查
66
+ ├── figma-mcp/ Figma 元数据封装(规划中)
67
+ ├── prd-loader/ PRD 全文加载(规划中)
68
+ └── rules/ 规则库、业务词表(规划中)
69
+
70
+ docs/ 维护者深度文档
71
+ ├── skill-template/ SKILL.md 五段式骨架
72
+ ├── adr/ 架构决策记录
73
+ └── superpowers/ 历史文档
74
+ ```
75
+
76
+ 分层依据见 [CONTRIBUTING.md](./CONTRIBUTING.md) 第 1 章。**用户使用时不需要感知分层**,直接查 QUICKSTART / DECISION_TREE 即可。
77
+
78
+ ## 相关文档
79
+
80
+ - [HUMAN_AGENT_WORKFLOW.md](./HUMAN_AGENT_WORKFLOW.md) — L0/L1/L2/L3 分级判断
package/bin/cli.mjs ADDED
@@ -0,0 +1,9 @@
1
+ #!/usr/bin/env node
2
+ // @dev-workflow/skill 入口
3
+ // 第一版只做纯交互,无 argv 解析。
4
+ import { run } from '../src/cli/install.mjs'
5
+
6
+ run().catch(err => {
7
+ console.error('\n❌ 安装失败:', err && err.message ? err.message : err)
8
+ process.exit(1)
9
+ })
package/package.json ADDED
@@ -0,0 +1,39 @@
1
+ {
2
+ "name": "@dev-workflow/skill",
3
+ "version": "0.1.0",
4
+ "description": "研发工作流 skill 库:一条 npx 命令把 devFlow / figmaSync / consistency-checker / artifact 等 skill 装到 Claude Code 或 Codex 的项目级目录。",
5
+ "type": "module",
6
+ "bin": {
7
+ "@dev-workflow/skill": "./bin/cli.mjs"
8
+ },
9
+ "files": [
10
+ "bin",
11
+ "src",
12
+ "skills",
13
+ "tools",
14
+ "README.md",
15
+ "LICENSE"
16
+ ],
17
+ "engines": {
18
+ "node": ">=18"
19
+ },
20
+ "publishConfig": {
21
+ "access": "public"
22
+ },
23
+ "keywords": [
24
+ "claude-code",
25
+ "codex",
26
+ "skill",
27
+ "dev-workflow",
28
+ "ai-workflow"
29
+ ],
30
+ "repository": {
31
+ "type": "git",
32
+ "url": "git+https://github.com/Wenyari/dev-workflow-skill.git"
33
+ },
34
+ "homepage": "https://github.com/Wenyari/dev-workflow-skill#readme",
35
+ "bugs": {
36
+ "url": "https://github.com/Wenyari/dev-workflow-skill/issues"
37
+ },
38
+ "license": "MIT"
39
+ }
@@ -0,0 +1,23 @@
1
+ # artifact 层(规划中)
2
+
3
+ 承载跨环节的数据产物,方法论定义两个:
4
+
5
+ - **未闭环清单**(open-issues):三个评审环节里所有"没当场闭环的疑点"的统一收口
6
+ - **校准清单**(calibration):自测阶段发现的遗漏 → 归因 → 反哺给一致性检查器扩规则
7
+
8
+ ## 分层原因
9
+
10
+ 未闭环清单、校准清单跨多个 skill 读写:
11
+
12
+ - `consistency-checker` 输出未认领项 → 未闭环清单
13
+ - 自测阶段发现遗漏 → 校准清单
14
+ - 校准清单回喂 → 扩展 consistency-checker 规则库
15
+
16
+ 多方读写必须独立成层,不能挂在任何单一 skill 下。
17
+
18
+ ## 现状
19
+
20
+ - `open-issues/` 未启动
21
+ - `calibration/` 未启动
22
+
23
+ 先建 `consistency-checker` 骨架并投产,再启动本层。字段 schema 已由方法论定义,实现时按方法论字段表落地。
@@ -0,0 +1,341 @@
1
+ ---
2
+ name: devFlow
3
+ description:
4
+ 研发工作流入口,覆盖前端、后端与需求。按子命令读取上下文、检查契约、生成方案、创建基建并发布可审核产物。适用于用户要求
5
+ Codex
6
+ 编写、审查、改进、标准化或落地研发文档、技术方案、页面开发技术方案、后端技术方案、页面基建、PRD
7
+ 审查、AI 生成文档模板时。前端子命令:page-tech 生成页面级前端技术方案,contract-check
8
+ 检查页面方案可落地性,page-build 根据已审核方案创建页面基建,foundation-freeze
9
+ 生成基建事实快照。后端子命令:api-tech 生成后端技术方案文档。需求子命令:prd-review
10
+ 审查 PRD 找缺失、风险、技术冲突并输出问题清单。共享子命令:lark-read
11
+ 读取飞书云文档作为上下文,lark-doc 发布到飞书 Wiki,prepare
12
+ 说明飞书环境变量配置。未来可扩展测试等 domain。
13
+ ---
14
+
15
+ # 研发工作流
16
+
17
+ ## 对齐边诊断
18
+
19
+ | 项 | 值 |
20
+ |---|---|
21
+ | 服务对齐边 | 后端↔前端(技术方案文档)· UI↔前端(page-build 落地)· 不涉及对齐边(lark-*、prepare 工具子命令) |
22
+ | 现状分级 | 健康(后端↔前端有 Apifox)/ 结构性不健康(UI↔前端) |
23
+ | AI 形态 | 少做(技术方案:只补语义 / 不改 API 契约本身)· 兜底 + 校准(page-build 落地) |
24
+ | 主战场 | 开发中 |
25
+
26
+ ## 这个 skill 解决什么问题
27
+
28
+ 开发环节的方案生成与代码落地:把 PRD / 设计稿 / 后端接口整理为可审核的技术方案,并在方案通过后生成前端页面基建骨架。
29
+
30
+ ## 什么时候用
31
+
32
+ - 用户显式输入 `$devFlow <subcommand>`
33
+ - 用户话术:"写页面开发技术方案 / 写后端技术方案 / 根据方案创建页面基建 / 检查方案能不能落地"
34
+ - 用户提供 PRD 链接并要求"生成落地方案"
35
+
36
+ ## 前置产物
37
+
38
+ | 产物 | 来源 | 是否必需 |
39
+ |---|---|---|
40
+ | PRD / 需求文档 | 人工提供 / `lark-read` 读取 | 必需 |
41
+ | 后端接口清单 | Apifox / 后端仓库 | page-tech 必需 |
42
+ | Figma 设计稿 | 人工提供 | page-tech 可选,page-build 推荐 |
43
+
44
+ ## 输出产物
45
+
46
+ | 产物 | 位置 | 下游消费者 |
47
+ |---|---|---|
48
+ | `page-tech.md` | 项目文档目录 | 人工评审 → contract-check |
49
+ | `contract-report.md` | 项目文档目录 | 人工评审 → page-build |
50
+ | 页面基建代码 | admin-fe 仓库 | 前端开发 |
51
+ | `foundation-summary.md` | 项目文档目录 | figmaSync plan |
52
+ | `api-tech.md` | 项目文档目录 | 后端评审 |
53
+
54
+ ## 下一步
55
+
56
+ - `page-tech` 完成 → `$devFlow contract-check`
57
+ - `contract-check` 通过 → `$devFlow page-build`
58
+ - `page-build` 完成 → `$devFlow foundation-freeze` → `figmaSync plan`
59
+ - `api-tech` 完成 → 提交后端技术评审
60
+
61
+ ## 明确不做
62
+
63
+ - 不做 PM↔UI 一致性检查:属于 `consistency-checker` skill 的对齐边
64
+ - 不做视觉还原:由 `figmaSync` 承担
65
+ - 不做未闭环 / 校准清单:由 `artifact/` 层承担
66
+ - 不做后端代码骨架生成:`api-tech` 只出方案不出 controller / service / dto / entity
67
+
68
+ ---
69
+
70
+ ## 详细规则
71
+
72
+ 本 Skill 是研发工作流统一入口,覆盖前端、后端与需求三个 domain,未来可扩展测试等。它负责识别任务类型、判断领域、选择子命令、加载对应规则和模板。具体子命令的详细执行规则不要堆在本文件中,应放入对应
73
+ `references/`。
74
+
75
+ ## 目录约定
76
+
77
+ - 飞书读写、环境准备等共享能力已下沉到仓库 `tools/lark/`(相对本 skill 为 `../../../tools/lark/`)。
78
+ - `domains/frontend/{references,templates,scripts}/`:前端专属规则、模板、脚本。
79
+ - `domains/backend/{references,templates,scripts}/`:后端专属规则、模板、脚本。
80
+ - `domains/requirement/{references,templates}/`:需求专属规则与模板;本 domain 目前无脚本。
81
+ - `agents/`:入口 agent 配置。
82
+
83
+ 新增 domain(如 `test`)时按同样结构建 `domains/<name>/{references,templates,scripts}/`。
84
+
85
+ ## 通用原则
86
+
87
+ - 使用中文输出。
88
+ - 文档的主要构建者和审核者是人,AI 只生成结构化、可审核、可修改的初稿。
89
+ - 必须基于用户提供的需求、设计、接口、仓库代码或明确说明写作。
90
+ - 不得臆想需求、接口字段、路径、组件、权限、指标、交互规则或 coding 细节。
91
+ - 代码事实优先:仓库可用时,接口、实体、schema、组件、路由必须基于真实代码;仓库不可用时不写具体路径、不声称某资源存在,缺失部分标记为待确认。
92
+ - 必需上下文缺失时,向用户确认,或明确写入待确认项。
93
+ - 可选上下文缺失时,可以写"不涉及"或跳过,不要硬写。
94
+ - 不写开发排期或任务拆分,除非具体子命令明确要求。
95
+ - 如果子命令需要使用产品设计规范,先读取对应规范索引,不要把规范正文写入入口文件。
96
+ - 读取或写入飞书云文档时,默认直接使用飞书 Open API 和环境变量,不需要初始化
97
+ `lark-cli`。
98
+ - 飞书读写、Markdown 转 Docx blocks、权限检查等重复且易错的操作必须优先使用
99
+ `../../../tools/lark/scripts/` 中的脚本;不要在对话中临时重写大段 Node API 脚本。
100
+
101
+ ## 领域判定
102
+
103
+ 用户请求进入子命令前必须判定领域(frontend / backend / requirement):
104
+
105
+ - 用户显式带前缀或指定领域("后端技术方案"、"前端页面方案"、"审查 PRD")时直接采用。
106
+ - 子命令名唯一映射到某个 domain 时直接采用:`page-tech` / `page-build` /
107
+ `contract-check` / `foundation-freeze` → frontend;`api-tech` → backend;`prd-review` → requirement。
108
+ - 子命令名不唯一但用户话语明确(例如"写技术方案")时,必须先向用户确认前端还是后端,不擅自二选一。
109
+ - 共享子命令 `prepare` / `lark-read` / `lark-doc` 不必判定领域;`lark-read` 供哪个下游使用时按下游领域输出对应结构(见 `../../../tools/lark/references/lark-read.md`)。
110
+
111
+ ## 前端专属工作流
112
+
113
+ - 先根据仓库根目录的 `HUMAN_AGENT_WORKFLOW.md` 判断 L0/L1/L2/L3。
114
+ - L0/L1 不强制生成 `page-tech.md`、`contract-report.md` 或
115
+ `foundation-summary.md`;只做最小计划、确认、修改、验证和总结。
116
+ - L2/L3 才进入
117
+ `page-tech -> contract-check -> page-build -> foundation-freeze -> figmaSync`
118
+ 标准链路。
119
+
120
+ ## 需求专属工作流
121
+
122
+ - L0 / L1 不跑 `prd-review`:小改动不需要 PRD 审查。
123
+ - L2 建议在 `page-tech` / `api-tech` 之前跑 `prd-review`;产物形态由用户选择(对话内出或落 `prd-review.md`)。
124
+ - L3 强制在 `page-tech` / `api-tech` 之前跑 `prd-review`,且必须落 `prd-review.md` 作为可审核产物。
125
+ - 🔴 阻塞项未消除,不得进入 `page-tech` / `api-tech`;🟡 严重项必须在下游文档的「风险与待确认项」中原样带过去。
126
+
127
+ ## 验证策略
128
+
129
+ - 纯 Markdown 或 Skill 文档改动不跑业务代码检查。
130
+ - L0 运行与改动直接相关的最小验证。
131
+ - L1 优先运行 TypeScript 或相关局部验证;涉及格式时运行格式检查。
132
+ - L2/L3 有代码改动后运行:
133
+
134
+ ```text
135
+ pnpm typecheck
136
+ pnpm format:check
137
+ pnpm lint
138
+ ```
139
+
140
+ - 格式问题使用 `pnpm format` 修复后重新检查。
141
+ - 无法运行验证时,必须说明原因和剩余风险。
142
+
143
+ ## 脚本优先
144
+
145
+ `../../../tools/lark/scripts/`(仓库共享工具):
146
+
147
+ - `lark_check_permissions.mjs`:检查飞书文档或 Wiki 父节点访问权限。
148
+ - `lark_read_docx.mjs`:读取 Wiki /
149
+ Docx,支持标题章节抽取、多章节一次读取、标题层级自动匹配和 5 分钟临时缓存。
150
+ - `markdown_to_lark_blocks.mjs`:将 Markdown 转为飞书 Docx blocks JSON。
151
+ - `lark_publish_doc.mjs`:创建 Wiki 子文档并分批写入 Markdown 正文。
152
+
153
+ `domains/frontend/scripts/`:
154
+
155
+ - `contract_check_static.mjs`:检查 route、components、service、types、constants 等机械规则,输出 JSON。
156
+ - `generate_foundation_summary.mjs`:扫描页面真实基建并生成
157
+ `foundation-summary.md` 机器快照。
158
+ - `check_page_tech_doc.mjs`:`page-tech` 生成后的静态自检。
159
+
160
+ `domains/backend/scripts/`:
161
+
162
+ - `check_api_tech_doc.mjs`:`api-tech` 生成后的静态自检。
163
+
164
+ 脚本只从环境变量读取密钥,不输出 secret。脚本输出 JSON,最终回复只摘取必要状态和链接。
165
+
166
+ ## 图表工作流
167
+
168
+ 技术文档需要图文并茂时,使用 Mermaid 作为图的源码,使用外部画图 Skill 落地渲染。
169
+
170
+ 通用规则:
171
+
172
+ - 文档正文负责说明为什么需要这张图、图表达什么结论。
173
+ - Mermaid 代码负责描述图结构,必须保留在文档中,便于后续修改。
174
+ - 复杂图、需要飞书落地的图,交给 `design-lark-chart`
175
+ 渲染到飞书画板或飞书文档可用产物。
176
+ - `devFlow` 不直接承担复杂图渲染,不把图做成不可维护的纯图片。
177
+ - 图必须服务于内容,不为了装饰而画图。
178
+ - 每张图都要有明确用途:流程、数据流、状态流转、接口链路、组件关系、权限判断或异常处理。
179
+
180
+ Mermaid 类型选择:
181
+
182
+ - 前端场景:
183
+ - 用户流程、权限判断、异常处理:优先 `flowchart`
184
+ - 页面结构、组件拆分、资源关系:优先 `flowchart LR`,模拟从左到右的 XMind 阅读方式。
185
+ - 前后端交互、提交链路:优先 `sequenceDiagram`
186
+ - 页面状态流转:优先 `stateDiagram-v2`
187
+ - 后端场景:
188
+ - 接口调用链路、多服务调用时序:优先 `sequenceDiagram`
189
+ - 业务流程、事务/幂等分支:优先 `flowchart`
190
+ - 数据实体关系:优先 `erDiagram`
191
+ - 领域对象或订单状态流转:优先 `stateDiagram-v2`
192
+ - 开发排期类内容:仅在对应子命令要求时使用 `gantt`。
193
+
194
+ 飞书交付规则:
195
+
196
+ - 需要粘贴到飞书文档时,正文保留 Mermaid 源码,另用 `design-lark-chart`
197
+ 生成图形产物。
198
+ - 如果用户只需要纯 Markdown 文档,可以只输出 Mermaid 代码块,不调用外部画图 Skill。
199
+ - 如果用户明确要求"画到飞书""同步到飞书""生成飞书画板",必须使用
200
+ `design-lark-chart`。
201
+ - `lark-cli` 只在 `design-lark-chart` 或飞书画板链路需要时再初始化;`lark-read`
202
+ 和 `lark-doc` 不要求初始化。
203
+
204
+ ## 子命令路由
205
+
206
+ 每个子命令块只列 **用途 + 触发方式 + 规则/模板/脚本索引**;具体执行规则见对应 references,agent 应在进入子命令后立即读取。
207
+
208
+ ### prepare(共享)
209
+
210
+ 用途:说明 `devFlow` 使用飞书读写能力前需要配置的环境变量和权限准备。
211
+
212
+ 触发方式:
213
+
214
+ - 用户显式输入 `$devFlow prepare`
215
+ - 用户要求"初始化 devFlow" / "配置 devFlow 飞书环境变量"
216
+ - 用户询问"devFlow 需要配置哪些飞书变量"
217
+ - 用户第一次使用 `lark-read` 或 `lark-doc` 前需要准备环境
218
+
219
+ 规则:`../../../tools/lark/references/prepare.md`
220
+
221
+ ### lark-read(共享)
222
+
223
+ 用途:读取飞书云文档或 Wiki 文档链接,提取内容作为后续研发工作流上下文。
224
+
225
+ 触发方式:
226
+
227
+ - 用户显式输入 `$devFlow lark-read`
228
+ - 用户提供飞书文档链接并要求"读取文档"
229
+ - 用户要求"根据这个飞书文档生成技术方案"
230
+ - 用户要求"先读 PRD / 设计说明 / 接口文档"
231
+ - 用户要求"把这个飞书文档作为上下文"
232
+
233
+ 规则:`../../../tools/lark/references/lark-read.md`
234
+ 脚本:`../../../tools/lark/scripts/lark_read_docx.mjs`
235
+
236
+ ### lark-doc(共享)
237
+
238
+ 用途:将已生成或即将生成的技术文档发布到飞书 Wiki 父节点下。
239
+
240
+ 触发方式:
241
+
242
+ - 用户显式输入 `$devFlow lark-doc`
243
+ - 用户要求"发布到飞书" / "写入飞书文档"
244
+ - 用户要求"落地到我的飞书个人笔记"
245
+ - 用户要求"在这个飞书 Wiki 节点下创建文档"
246
+
247
+ 规则:`../../../tools/lark/references/lark-doc.md`
248
+ 脚本:`../../../tools/lark/scripts/lark_publish_doc.mjs`
249
+
250
+ ### page-tech(前端)
251
+
252
+ 用途:生成页面级前端技术方案(页面开发落地方案)。
253
+
254
+ 触发方式:
255
+
256
+ - 用户显式输入 `$devFlow page-tech`
257
+ - 用户要求"写页面开发技术方案" / "写页面落地方案"
258
+ - 用户要求"根据前端仓库生成页面技术文档"
259
+ - 用户要求"让 AI 先生成页面方案,我再审核"
260
+
261
+ 规则:`domains/frontend/references/page-tech.md`
262
+ 模板:`domains/frontend/templates/page-tech.md`
263
+
264
+ ### page-build(前端)
265
+
266
+ 用途:根据已审核页面方案或可验证上下文,为 admin-fe 创建页面基建文件。
267
+
268
+ 触发方式:
269
+
270
+ - 用户显式输入 `$devFlow page-build`
271
+ - 用户要求"根据页面方案创建页面基建"
272
+ - 用户要求"根据 page-tech / 飞书文档 / API 文档落地页面骨架"
273
+ - 用户要求"先搭页面 route、components、service、types、constants"
274
+
275
+ 规则:`domains/frontend/references/page-build.md`
276
+ 模板:`domains/frontend/templates/page-build/`
277
+
278
+ ### contract-check(前端)
279
+
280
+ 用途:在 `page-tech` 和 `page-build` 之间检查页面方案是否具备落地条件,避免直接生成错误骨架。
281
+
282
+ 触发方式:
283
+
284
+ - 用户显式输入 `$devFlow contract-check`
285
+ - 用户要求"检查页面方案是否能落地"
286
+ - 用户要求"检查 page-tech 能不能进入 page-build"
287
+ - 用户要求"生成 contract-report"
288
+
289
+ 规则:`domains/frontend/references/contract-check.md`
290
+ 模板:`domains/frontend/templates/contract-report.md`
291
+ 脚本:`domains/frontend/scripts/contract_check_static.mjs`(辅助机械规则检查,不替代业务语义判断)
292
+
293
+ ### foundation-freeze(前端)
294
+
295
+ 用途:在 `page-build` 后、`figmaSync plan` 前生成页面基建事实快照,明确后续视觉阶段可修改范围。
296
+
297
+ 触发方式:
298
+
299
+ - 用户显式输入 `$devFlow foundation-freeze`
300
+ - 用户要求"生成 foundation-summary" / "冻结页面基建事实"
301
+ - `figmaSync plan` 前发现目标页面已有基建但缺少最新快照
302
+
303
+ 规则:`domains/frontend/references/foundation-freeze.md`
304
+ 脚本:`domains/frontend/scripts/generate_foundation_summary.mjs`
305
+
306
+ ### api-tech(后端)
307
+
308
+ 用途:生成后端技术方案文档(接口设计、数据模型 / 数据库设计、核心流程时序、边界与异常、风险与待确认项)。不生成 controller / service / dto / entity 代码骨架。
309
+
310
+ 触发方式:
311
+
312
+ - 用户显式输入 `$devFlow api-tech`
313
+ - 用户要求"写后端技术方案" / "写接口设计文档"
314
+ - 用户要求"根据 PRD 生成后端落地方案"
315
+
316
+ 规则:`domains/backend/references/api-tech.md`
317
+ 模板:`domains/backend/templates/api-tech.md`
318
+ 脚本:`domains/backend/scripts/check_api_tech_doc.mjs`(生成后自检)
319
+
320
+ ### prd-review(需求)
321
+
322
+ 用途:在需求进入 `page-tech` / `api-tech` 之前,按固定 checklist 审查一份 PRD,找出缺失、风险和技术冲突,产出分档(🔴 阻塞 / 🟡 严重 / 🟢 商榷)的问题清单。不改 PRD、不推方案、不做视觉一致性检查、不做业务价值评估。
323
+
324
+ 触发方式:
325
+
326
+ - 用户显式输入 `$devFlow prd-review`
327
+ - 用户要求"审查 PRD" / "看看这份需求有什么问题"
328
+ - 用户要求"找出 PRD 的缺失 / 风险 / 技术冲突"
329
+ - 用户要求"PRD 能不能进入技术方案阶段"
330
+ - 进入 `page-tech` / `api-tech` 前发现 PRD 尚未审查(L3 强制)
331
+
332
+ 规则:`domains/requirement/references/prd-review.md`
333
+ 模板:`domains/requirement/templates/prd-review.md`
334
+
335
+ ## 未实现子命令
336
+
337
+ 当前实现:
338
+ `prepare`、`lark-read`、`lark-doc`(共享);`page-tech`、`contract-check`、`page-build`、`foundation-freeze`(前端);`api-tech`(后端);`prd-review`(需求)。
339
+
340
+ 如果用户要求组件开发、重构方案、测试方案或其他技术文档类型,不要临时发挥。先说明当前
341
+ `devFlow` 尚未定义对应子命令或 domain,再与用户确认是否要扩展。
@@ -0,0 +1,7 @@
1
+ interface:
2
+ display_name: '研发工作流'
3
+ short_description: '读取上下文、检查契约、生成方案并创建可审核基建'
4
+ default_prompt: '使用 $devFlow page-tech 读取需求上下文,为当前前端页面生成技术方案,并按需进入 contract-check 和 page-build。'
5
+
6
+ policy:
7
+ allow_implicit_invocation: true