7.8 KiB
7.8 KiB
Project Process — DK Forge（pi-desktop）开发流程规范
本文档是本仓库项目开发的强制流程。做任何项目需求（新功能、修复、重构、UI 改动、IPC/契约变更、发布）时，都必须按本流程的阶段执行：进入每个阶段先读对应章节，满足要求、遵守规则（Rule）、按输出规范产出交付物，检查清单全过才算完成本阶段。
- 版本：v1.2 · 2026-09-04
- 适用范围：本仓库（
pi-desktop，发布名 DK Forge）全部功能开发，包括 Electron 宿主（src/main/）、renderer SPA（packages/web-ui/）、服务主体与 SDK 包（packages/agent-sdk等）、E2E 与发布。仓库硬约束以AGENTS.md为准，本文档是执行流程（不与其冲突） - 来源：本规范由既有工程规则体系沉淀提炼（spec-structure / Agent Work Loop / Software Fluency / DESIGN.md Contract / Harness Engineering，规则参考
vendor/better-harness/），并按本仓技术栈（Electron + Node.js + React + TypeScript strict ESM monorepo）与AGENTS.md既有约定适配（v1.1：清除上游仓库残留引用，对齐本仓目录/契约/测试/发布事实） - 语言约定：流程文档正文用中文；标识符、类型、API、命令、文件路径一律用英文
1. 流程全景（八个阶段）
① 需求与规格 ─→ ② 架构设计 ─→ ③ 详细设计 ─→ ④ UI Spec ─→ ⑤ 实现
│
⑥ 验证与质量门 ←─────────────────────────────────────┘
│
⑦ 交付与发布 ─→ ⑧ 学习与沉淀
| 阶段 | 文档 | 一句话定义 | 核心输出 |
|---|---|---|---|
| ① 需求与规格 | 01-requirement.md | 把意图变成一份"实现者无需猜"的规格（scope + 规则 id + 验收标准） | 规格文档（BR/E/AC 编号） |
| ② 架构设计 | 02-architecture.md | 定分层、模块边界、数据流与关键技术决策 | 架构文档 + ADR + 架构图 |
| ③ 详细设计 | 03-detailed-design.md | 把架构落到可实现的接口、数据结构、状态机与异常处理 | 详细设计文档 + 接口/数据契约 |
| ④ UI Spec | 04-ui-spec.md | 定义每个交付面的 UI 规则与约束（骨架/状态机/动作权限 + 设计系统 token） | DESIGN.md / 表面规格 / i18n 约束 |
| ⑤ 实现 | 05-implementation.md | 小步、可验证、范围受控地把设计变成代码 | 代码 + colocated 测试 + 变更同步 |
| ⑥ 验证与质量门 | 06-validation.md | 用最小且相关的检查验证最终改动，失败可诊断、修复后复验 | 测试/门禁/审查记录 |
| ⑦ 交付与发布 | 07-delivery.md | 在真实交付边界被接受，高风险有审批，可回滚 | 构建产物 + 发布记录 + 审计 |
| ⑧ 学习与沉淀 | 08-learning.md | 识别重复工作与熵增，沉淀可复用改进并长期验证 | 学习捕获（docs/skills/memory） |
规模适配：小改动（一行修复、文案调整）不必产出全部文档——规格/设计可合并为短说明（见各阶段"轻量路径"）。但要求与规则始终有效，越级必须有理由并记录。
2. 全局规则（所有阶段适用）
以下规则跨阶段生效，任何阶段不得违反：
- G-1 唯一事实源：跨进程/跨模块的类型与契约只定义一处（本仓：
packages/api/src/contracts.ts），宿主与各包只import type，禁止本地镜像。文档不覆盖代码，代码与测试是运行时事实。 - G-2 可追溯：一切行为、规则、异常、验收标准都有稳定 id（如
BR-01、E-01、AC-01）。id 只追加不重排；废弃时标记 withdrawn，保留编号。 - G-3 配置≠行为：存在一个文件/命令/规则 ≠ 它被使用。任何"机制存在"的结论必须有打开的证据（被调用、被测试、被门禁执行）。
- G-4 不越界：只做请求范围内的事；发现无关问题只提不改；改动逐行可追溯到本次请求。越界扩展必须显式批准并记录。
- G-5 小步可回滚：一次只做可验证的一步；优先狭窄、可回滚的改动；
trash优于rm。 - G-6 机械规则优先于文档规则：能用 lint/typecheck/测试/CI 门禁强制的，不许只写进文档。
- G-7 文档随变更同步：改了什么，必须同步改对应的架构/接口/流程文档（见 05-implementation.md 变更矩阵）。
- G-8 提交与评审规范：Conventional Commits（规范见
AGENTS.md规则 6；commit 生成见skills/builtin/dk-commit）；PR 必须带测试，至少 1 人评审，主分支是build。
3. 遵守机制（如何保证被遵守）
- 启动即读：接手本仓的开发 agent（编码执行者）开工前先读本
README.md+ 目标阶段文档。 - 阶段门禁：每个阶段的"完成条件（DoD）"检查清单未全过，不得进入下一阶段；上一阶段的输出是本阶段的输入。
- 合并前审查：PR 评审人按 06-validation.md 的质量门核对，未过门禁的 PR 打回。
- 演进：本流程本身也在 ⑧ 学习与沉淀 的范围内——流程缺陷、重复摩擦、新反模式，应更新对应文档（带版本号与变更记录）。
4. 文档索引
| 路径 | 内容 |
|---|---|
| 01-requirement.md | 需求与规格：7 段结构、BR/E/AC 编号、六道完备性门 |
| 02-architecture.md | 架构设计：分层/边界/数据流/决策记录、架构图规范 |
| 03-detailed-design.md | 详细设计：接口契约/状态机/异常/迁移/边界条件 |
| 04-ui-spec.md | UI Spec：表面规格（骨架/组件/状态机/权限）+ 设计系统（DESIGN.md） |
| 05-implementation.md | 实现：编码规则、规模红线、变更矩阵、自测 |
| 06-validation.md | 验证与质量门：分层验证、失败诊断与复验、评审 |
| 07-delivery.md | 交付与发布：构建/签名/发布记录/回滚 |
| 08-learning.md | 学习与沉淀：循环工程、知识捕获、长期验证 |
| templates/（模板库） | 产品/文档模板：URD-Template.md（用户需求文档模板，产品级需求描述，软件项目通用；HTML 看板） |
快速开始：新需求 → 读 01-requirement.md；涉及 UI → 同时读 04-ui-spec.md；改动进入实现前 → 过 01-requirement.md 的完备性门 + 03-detailed-design.md 的契约检查；提交前 → 过 06-validation.md 门禁。
变更记录
- v1.3（2026-09-05）：新增 §4 模板库索引——
templates/URD-Template.md（URD 模板，含使用说明/编号规则/章节结构）及其 HTML 看板；模板为软件项目产品级需求文档的通用起点（输入到阶段 ①）。 - v1.2（2026-09-04）：阶段 ⑦ 发布流程按本仓真实编译打包链路重写——离线门禁（ci-local 八步）→ release.mjs 九步编排 → pack-audit/install-acceptance → sign-local 签名公证 → OTA manifest，全部对齐
docs/release-process.md。 - v1.1（2026-09-04）：适配本仓（pi-desktop / DK Forge）事实——清除上游仓库残留（decokee-deck / Vue2 /
src/shared/ CONTRIBUTING 等引用），目录、契约、测试、发布与文档引用对齐AGENTS.md。 - v1.0（2026-08-16）：初始版本，基于既有工程规则体系建立八阶段流程。