diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md new file mode 100644 index 0000000..097c9f7 --- /dev/null +++ b/ARCHITECTURE.md @@ -0,0 +1,396 @@ +# EP Code AI · 整体架构 + +> Sprint 6 ① 产出。用一张图 + 四张子图 + 一份技术盘点清单,让新成员 15 分钟内**看懂全局**。 +> +> **读者**: 新加入的研发 / 想 contribute 的外部贡献者 / 评估是否采用本框架的团队。 +> +> 配套文档: +> - [信息共享模式](./docs/architecture/information-sharing.md)(本文"数据流"章的深化) +> - [UI/UX 设计稿](./docs/design/ui/)(应用层的详细设计) +> - [PLAN.md](./PLAN.md)(建设路线图) +> - [用户手册](./docs/manual/)(怎么用) + +--- + +## 一、全局四层视图 + +EP Code AI 由**四层**组成,每一层对上层提供能力,对下层提出约束: + +```mermaid +graph TB + subgraph L4 ["🖥 应用层 (User-facing)"] + APP[桌面应用 app/
macOS ✅ · Linux ⏳ · Windows ⏳] + SITE[文档站 docs-site/
Docusaurus · GitHub Pages] + MANUAL[用户手册 docs/manual/
install · 速查 · 角色指南] + end + + subgraph L3 ["🔗 集成层 (Enterprise)"] + JIRA[Jira / 禅道 / TAPD] + IM[企业微信 / 钉钉 / 飞书 / Slack] + CONF[Confluence] + GITLAB[GitLab / GitHub] + K8S[Kubernetes / Alertmanager] + end + + subgraph L2 ["🧰 工具链层 (Tooling)"] + CLI[tools/cli/ · epcode CLI
10 个子命令] + SCRIPTS[tools/cross-platform/scripts/
15 个零依赖脚本] + METRICS[tools/metrics/
四场景 collect + dashboard] + INTEG[tools/integrations/
9 个系统连接器] + end + + subgraph L1 ["📚 方法论层 (Foundation)"] + CHAP[docs/chapters/
00 接入模式 · 01-05 四场景] + TPL[templates/
24 个 Markdown 模板] + SKILL[skills/
29 个 AI Prompt] + ADOPT[4 种接入模式
A 绿地 · B 开发中 · C 迭代中 · D 稳态] + end + + APP --> CLI + APP --> INTEG + SITE --> CHAP + MANUAL --> CHAP + + CLI --> SCRIPTS + CLI --> INTEG + CLI --> METRICS + SCRIPTS --> TPL + + INTEG --> JIRA + INTEG --> IM + INTEG --> CONF + INTEG --> GITLAB + INTEG --> K8S + + METRICS --> CHAP + SKILL --> TPL + TPL --> CHAP + ADOPT --> CHAP + + style L1 fill:#e8f5e9,stroke:#1b5e20 + style L2 fill:#e3f2fd,stroke:#0d47a1 + style L3 fill:#fff3e0,stroke:#e65100 + style L4 fill:#f3e5f5,stroke:#4a148c +``` + +### 分层原则 + +| 层 | 核心命题 | 稳定性 | 变更频率 | +|----|---------|--------|---------| +| L1 方法论 | **什么是对的** | 最稳定 | 季度级 | +| L2 工具链 | **如何自动化** | 中等 | 月级 | +| L3 集成 | **连到企业系统** | 依赖外部 | 按需 | +| L4 应用 | **人类怎么用** | 最活跃 | 周级 | + +**依赖方向**: L4 → L3 → L2 → L1,不跨层反向依赖。 + +--- + +## 二、数据流图 · Markdown 在四场景间流动 + +```mermaid +flowchart LR + subgraph 业务 + PRD[PRD.md] --> US[user-stories.md] + US --> RULES[business-rules.md] + end + + subgraph 开发 + DESIGN[design.md] --> ADR[ADR-NNNN.md] + ADR --> API[api-contract.md] + end + + subgraph 测试 + STRATEGY[test-strategy.md] --> CASES[test-cases.md] + CASES --> SUBMISSION[submission.md] + SUBMISSION --> REPORT[test-report.md] + end + + subgraph 运维 + PLAN[release-plan.md] --> RUNBOOK[runbook.md] + RUNBOOK --> INC[INC-xxx.md] + INC --> PM[postmortem.md] + end + + RULES -.->|PRD 变更
link-prd-to-design.js| DESIGN + API -.->|开发变更
recommend-regression.js| CASES + REPORT -.->|测试准出
generate-release-plan.js| PLAN + PM -.->|改进项
incident-to-requirement.js| PRD + + style 业务 fill:#e8f5e9 + style 开发 fill:#e3f2fd + style 测试 fill:#fff3e0 + style 运维 fill:#f3e5f5 +``` + +**关键观察**: +- **实线**: 场景内部产出物演进 +- **虚线**: 跨场景联动(Sprint 4 的 4 个联动脚本) +- **闭环**: 运维 → 业务(复盘改进项回流需求池),形成**完整回路** +- 每个节点都是 **Git 里的 Markdown 文件**,不是数据库记录 + +详细扩展见 [docs/architecture/information-sharing.md](./docs/architecture/information-sharing.md)。 + +--- + +## 三、组件依赖图 · CLI 如何调工具 + +```mermaid +flowchart TD + User[👤 用户] + UserGUI[🖥 GUI / npx epcode] + + User -->|命令行| CLI + User -->|GUI 按钮| UserGUI + UserGUI -->|spawn| CLI + + CLI[tools/cli/bin/epcode.js] + CLI --> Init[commands/init.js] + CLI --> PRD[commands/prd.js] + CLI --> ADR[commands/adr.js] + CLI --> Metrics[commands/metrics.js] + CLI --> Linkage[commands/linkage.js] + CLI --> Jira[commands/jira.js] + + Init --> SCAFFOLD[tools/cli/scaffolds/
mode-a/b/c/d/] + PRD --> CheckPRD[scripts/check-prd.js] + PRD --> ScoreT[scripts/score-testability.js] + ADR --> GenIdx[scripts/generate-adr-index.js] + Metrics --> CollectAll[metrics/collect.js] + CollectAll --> Business[metrics/business/collect.js] + CollectAll --> Dev[metrics/development/collect.js] + CollectAll --> Test[metrics/testing/collect.js] + CollectAll --> Ops[metrics/operations/collect.js] + Metrics --> Dashboard[metrics/generate-dashboard.js] + + Linkage --> LinkPRD[scripts/link-prd-to-design.js] + Linkage --> Regression[scripts/recommend-regression.js] + Linkage --> Release[scripts/generate-release-plan.js] + + Jira --> JiraCreate[integrations/jira/create-issue.js] + Jira --> JiraSync[integrations/jira/sync-from-markdown.js] + + CheckPRD --> TPL[templates/business/prd-template.md] + ScoreT --> SkillsCheck[skills/business/prompts/
prd-testability-check.md] + CollectAll --> Git[(Git Log)] + JiraCreate --> JiraAPI[(Jira REST API)] + + style CLI fill:#2962ff,color:white + style User fill:#00c853,color:white + style UserGUI fill:#00c853,color:white +``` + +**核心架构**: +- CLI 是**薄 router**,每个子命令 `require` 现成的 `tools/cross-platform/scripts/*.js` +- 脚本全部**零 npm 依赖**,只用 Node 18+ 内置 `fetch` / `fs` / `child_process` +- GUI(桌面应用)在底层也 spawn 同一批 CLI 命令,保证 GUI 和 CLI 行为一致 + +--- + +## 四、部署架构 + +```mermaid +flowchart LR + subgraph Dev ["开发者本地"] + Repo[(Git Repo)] + CLI1[epcode CLI] + App1[桌面应用] + end + + subgraph GH ["GitHub"] + Main[(main branch)] + PRs[Pull Requests] + Actions[GitHub Actions] + Pages[GitHub Pages] + Releases[Releases · tag] + end + + subgraph CI ["CI 门禁"] + Lint[check-links
markdown-lint
commit-lint] + Quality[prd-check
coverage-check
config-audit] + Build[Docusaurus Build] + Metrics[Weekly Metrics] + end + + subgraph Users ["终端用户"] + DocsSite[📘 文档站] + Download[⬇️ 应用下载
Sprint 7+] + end + + Dev -->|git push| PRs + PRs -->|CI 触发| Actions + Actions --> Lint + Actions --> Quality + Actions --> Build + Actions --> Metrics + Lint -->|全绿| Main + Quality -->|全绿| Main + Main --> Releases + Build --> Pages + Pages --> DocsSite + Releases --> Download + + style Main fill:#2962ff,color:white + style DocsSite fill:#00c853,color:white +``` + +**关键特性**: +- **零服务端成本**: GitHub Pages(Docusaurus)+ GitHub Actions(CI)全免费(公开仓库) +- **单一真实源**: `main` branch 是所有产出物的权威来源 +- **自动部署**: Docusaurus 文档站每次 main 变动时自动发布 +- **Release**: 打 tag v0.x.0 → GitHub Release 页面 + 后续桌面应用安装包 + +--- + +## 五、技术盘点清单 · 还缺什么 + +> **方法**: 从技术视角审视每一层,找出"还没有但应该有"的部分。按优先级分为 P0/P1/P2。 + +### L1 方法论层 + +| 项 | 现状 | 差距 | 优先级 | 目标 Sprint | +|----|------|------|--------|-----------| +| 四场景方法论 | ✅ 完整 | - | - | - | +| 4 接入模式 | ✅ 完整 | - | - | - | +| 模板库 | ✅ 24 个 | - | - | - | +| Prompt 库 | ✅ 29 个 | 🟡 缺 frontmatter(GUI 用) | P1 | S7 | +| **术语表 / 词汇表** | ❌ 无 | 新人不知道专有词含义 | P1 | S8 | +| **角色职责矩阵** | 🟡 分散在篇章 | 没单页速查 | P2 | S10 | + +### L2 工具链层 + +| 项 | 现状 | 差距 | 优先级 | 目标 | +|----|------|------|--------|-----| +| CLI 10 个命令 | ✅ | - | - | - | +| 脚本 15 个 | ✅ | - | - | - | +| 度量 4 场景 | ✅ | - | - | - | +| **类型定义(TS 或 JSON Schema)** | ❌ 纯 JS | 模板/PRD/用例无结构校验 Schema | P1 | S8 | +| **插件机制** | ❌ | 企业想加自己的 check 要 fork | P2 | Phase 3 | +| **观测性(日志/追踪)** | 🟡 console | CI 排障靠 raw log | P2 | Phase 3 | +| **性能基准(benchmark)** | ❌ | 不知道脚本在大仓库是否够快 | P2 | Phase 3 | +| **测试覆盖** | 🟡 手工 dogfood | 脚本没自动化测试 | P1 | S7 | + +### L3 集成层 + +| 项 | 现状 | 差距 | 优先级 | 目标 | +|----|------|------|--------|-----| +| Jira / 禅道 / TAPD | ✅ | - | - | - | +| Confluence | ✅ | - | - | - | +| IM 5 种 | ✅ | - | - | - | +| GitLab / GitHub | ✅ | - | - | - | +| K8s / Alertmanager | ✅ | - | - | - | +| **OIDC / SAML SSO** | ❌ | 企业身份打通 | P1 | S9 RFC | +| **Prometheus exporter** | ❌ | 把 metrics 暴露给企业监控 | P2 | Phase 3 | +| **OpenTelemetry** | ❌ | 跨系统追踪 | P2 | Phase 3 | + +### L4 应用层 + +| 项 | 现状 | 差距 | 优先级 | 目标 | +|----|------|------|--------|-----| +| 桌面应用(macOS Swift) | 🟡 骨架 | 未打包 / 未签名 / 无自动更新 | P0 | S7 | +| Linux 桌面应用 | ❌ | 需跨平台栈决策 | P0 | S7-S8 | +| Windows 桌面应用 | ❌ | 同 Linux | P0 | S7-S8 | +| 文档站(Docusaurus) | ✅ 已上线 | 搜索 / 版本切换 | P1 | S8 | +| 用户手册 | 🟡 起步 | 完整三平台安装 + 角色指南 | P0 | S6-S8 | +| **多语言(英文)** | ❌ 仅中文 | 对外开源需要 | P2 | Phase 3 | +| **离线 AI 模型** | ❌ | 企业禁外网时无 AI | P2 | Phase 3 | + +### 横向能力(贯穿各层) + +| 项 | 现状 | 差距 | 优先级 | +|----|------|------|--------| +| **审计日志** | ❌ 无 | 合规场景要审计谁改了啥 | P1 (S9 RFC) | +| **服务端同步** | ❌ Git-only | 跨机器共享项目上下文难 | P1 (S9 RFC) | +| **用户身份 / 权限** | 🟡 设计稿 | GUI 设计稿有,后端没有 | P0 (S7 落地 GUI) | +| **OTA 客户端更新** | ❌ | 无法远程推更新给用户 | P1 (S9 RFC) | +| **数据备份 / 恢复** | 🟡 依赖 Git | Artifact 大文件超出 Git 能力 | P2 | +| **可观测性仪表板** | 🟡 METRICS.md | 静态 Markdown,无实时仪表板 | P2 | + +--- + +## 六、三种部署拓扑(按企业需求) + +### 6.1 最小部署 · 单人开发者 / 小团队 + +``` + [本地 Git] ─ push ─► [GitHub/GitLab 仓库] + │ + └─► 成员 clone/pull + [本地桌面应用] ─ spawn ─► [CLI] ─ 读 ─► [本地 Git] +``` + +零依赖。适合: 个人项目 / 初创 / 独立项目组。 + +### 6.2 企业部署 · 有现成协作系统 + +``` + [本地 Git] ─ push ─► [企业 GitLab] + │ + └── CI (.gitlab-ci.yml) ──► [Jira / Confluence] + [企业微信/钉钉/飞书] + + [桌面应用] ─► [Jira API] (本地存储默认) + [Confluence API] + [SSO (OIDC/SAML)] (Phase 3) +``` + +企业系统是**镜像/广播**,Git 仍是权威。 + +### 6.3 完整企业服务化 · Phase 3 规划中 + +``` + [多成员桌面应用] ──► [企业网关] + │ + ├── [EP Code AI 后端服务] (PLAN § ④) + │ ├── 用户 / 项目 / 事件流 + │ ├── 审计日志 + │ ├── 客户端 OTA + │ └── 跨成员协同 + │ + ├── [Git] + ├── [Jira / 禅道] + └── [Confluence] +``` + +需要专门开发服务端,见 PLAN.md § Phase 2 ④ 服务端同步服务 RFC。 + +--- + +## 七、不做什么(关键的负约束) + +**本框架不会做的事**(避免范围蔓延): + +| ❌ 不做 | 理由 | +|--------|------| +| 自己做 IDE | VS Code / JetBrains 已足够;我们做 "**在 IDE 外** 的方法论 + 协作" | +| 自己做 Git 托管 | GitHub / GitLab 已完美;我们是它们的**消费方** | +| 自己做监控系统 | Prometheus / Datadog 已成熟;我们是**消费监控数据**的一方 | +| 自己做 AI 模型 | 我们依赖 Claude 等大模型;不做模型训练 | +| 替代现有流程工具 | Jira / 禅道用户继续用,我们做**结构化数据注入** | +| 无 AI 模式 | 核心价值来自 AI 辅助;纯手工模式不是目标 | + +## 八、关键技术决策一览 + +这些决策在 `docs/adr/` 和本仓库的 history 里已有,这里提炼速查: + +| 决策 | 选择 | 原因 | +|------|------|------| +| 文档格式 | Markdown | Git 友好 / 工具链成熟 / 跨平台 | +| 脚本语言 | Node.js 18+ 内置(零 npm) | 跨平台 / 零依赖 / 易学 | +| 桌面应用首平台 | macOS Swift | 团队熟悉 / 原生体验;后续决策跨平台栈 | +| 文档站 | Docusaurus v3 | 社区成熟 / MDX 支持 / GitHub Pages 直接部署 | +| CI | GitHub Actions | 公开仓免费 / 生态完整 | +| AI | Claude API(Anthropic 官方)优先 | 代码能力强 / 支持长上下文 | +| 用户身份(Phase 2) | 本地 Keychain | 单用户 / 不依赖服务端 | +| 用户身份(Phase 3) | 企业 SSO (OIDC) | 正规企业必备 | + +--- + +## 九、进一步阅读 + +- [PLAN.md](./PLAN.md) · 5 Sprint 建设计划 + Phase 2 落地规划 +- [docs/architecture/information-sharing.md](./docs/architecture/information-sharing.md) · 数据流详述 +- [docs/design/ui/](./docs/design/ui/) · UI/UX 设计稿 +- [docs/chapters/00-adoption/](./docs/chapters/00-adoption/) · 4 种接入模式详情 +- [CHANGELOG.md](./CHANGELOG.md) · 每个 Sprint 的具体产出 +- [RELEASE_PROCESS.md](./RELEASE_PROCESS.md) · 发布 SOP diff --git a/CHANGELOG.md b/CHANGELOG.md index 3a5fd47..143e85a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -10,9 +10,24 @@ --- -## [Unreleased] · Phase 2 进行中 +## [Unreleased] · Sprint 7 进行中 -进入真实落地与产品化期。详见 [PLAN.md § Phase 2](./PLAN.md#phase-2--落地与产品化新增2026-04-18)。 +Phase 2 第一 Sprint (S6) 完成。S7 启动: macOS Beta 打包 + 跨平台栈决策。 + +### [0.7.0-draft] · Sprint 6 完成(2026-04-20) + +**主题**: 架构盘点 + UI/UX 设计稿 + 信息共享文档化 + 用户手册起步 + +- 🎨 **UI/UX 设计稿完整铺开**(17 个 HTML 原型 + 10 wireframes + 5 Mermaid flows + 映射表): + - 核心页面(10):主视图 / 向导 / 设置 / 命令面板 / Artifact / 供应商切换 / 搜索 / 右键菜单 / 空态 / 状态栏 + - 用户旅程:**登录 → 项目列表 → 新建项目(4 模式 A/B/C/D)→ 主视图** + - 四大场景工作流(业务/开发/测试/运维)含 Prompt 一键操作 + - 跨平台约束 + 原型↔模块↔Swift 文件 映射 +- 🏛 **ARCHITECTURE.md**: 全局四层视图 / 数据流 / 组件依赖 / 部署拓扑 / 技术盘点 20+ 项 / 负约束 / 关键决策 +- 🔄 **信息共享模式** (`docs/architecture/information-sharing.md`): Git+Markdown+CI 模型详述 / 四场景流向 / 优缺点分析 / 反模式 / 何时上服务端 +- 📖 **用户手册起步** (`docs/manual/`): README 索引 + 00-install 三平台步骤 + 99-cheatsheet 一页速查 + +小步迭代: Sprint 6 只发起步 2 篇手册,完整角色/场景指南延后到 Sprint 8。 --- diff --git a/PLAN.md b/PLAN.md index 70b9d4f..b6cd3d9 100644 --- a/PLAN.md +++ b/PLAN.md @@ -14,8 +14,8 @@ > | S3 | 测试 + 运维场景工具补齐 | ✅ 完成（2026-04-18） | > | S4 | 场景联动 + 度量闭环 | ✅ 完成（2026-04-18） | > | S5 | 统一 CLI + 对外发布 + 试点复盘 | ✅ 完成（2026-04-18） 🎉 | -> | **S6** | **架构盘点 + UI/UX 设计稿 + 手册起步 + 信息流文档化** | **📋 Phase 2 计划中** | -> | S7 | macOS Beta 打包 + 跨平台栈决策 | 📋 Phase 2 计划中 | +> | S6 | 架构盘点 + UI/UX 设计稿 + 手册起步 + 信息流文档化 | ✅ 完成（2026-04-20） | +> | **S7** | **macOS Beta 打包 + 跨平台栈决策** | **📋 Phase 2 计划中** | > | S8 | 用户手册完整版 + v1.0 正式发布 | 📋 Phase 2 计划中 | > | S9 | 服务端 RFC + OTA 协议设计（不实现） | 📋 Phase 2 计划中 | > | S10 | 真实试点项目复盘 | 📋 Phase 2 计划中 | diff --git a/README.md b/README.md index 2cfe27d..e77ebda 100644 --- a/README.md +++ b/README.md @@ -11,7 +11,9 @@ > 📍 **最新进展**: Phase 1 完成(v0.6.0 · 整体 98%)。Phase 2 · Sprint 6 ⑥ UI/UX 扩展中 · **[🎨 17 个 HTML 原型](./docs/design/ui/prototype/)**(完整用户旅程: 登录 → 选项目/新建(4 模式)→ 主视图 → 场景工作流 + Prompt 一键操作)。 > > - 🧰 [统一 CLI · epcode](./tools/cli/) · 10 个子命令,零依赖 `npx epcode --help` -> - 🌐 **[文档站 · epcode-ai.github.io/ep-code-ai](https://epcode-ai.github.io/ep-code-ai/)** ✅ 已上线 · 首页以 4 接入模式为一等公民 +> - 🌐 **[文档站 · epcode-ai.github.io/ep-code-ai](https://epcode-ai.github.io/ep-code-ai/)** ✅ 已上线 +> - 🏛 [**ARCHITECTURE.md** · 整体架构(4 层 · 数据流 · 技术盘点)](./ARCHITECTURE.md) 🆕 Sprint 6 +> - 📖 [**用户手册** · 安装 + 速查表 · docs/manual/](./docs/manual/) 🆕 Sprint 6 > - 📋 [完整建设计划 PLAN.md](./PLAN.md) · 5 Sprint × 4 接入模式 × 验收标准 > - 🗺️ [实施路线图 ROADMAP.md](./ROADMAP.md) · 概览 + 里程碑 > - 📝 [变更日志 CHANGELOG.md](./CHANGELOG.md) · 每个版本的具体产出 diff --git a/ROADMAP.md b/ROADMAP.md index afbb10a..ddb9475 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -18,7 +18,7 @@ | S4 | Week 4 | 场景联动 + 度量闭环 | ✅ 完成 | | S5 | Week 5 | 统一 CLI + 对外发布 + 试点复盘 | ✅ 完成 | | **Phase 2 · 落地与产品化** | | | | -| S6 | Week 6 | 架构图 + UI/UX 设计稿 + 信息流 + 手册起步 | 📋 计划中 | +| S6 | Week 6 | 架构图 + UI/UX 设计稿 + 信息流 + 手册起步 | ✅ 完成 | | S7 | Week 7 | macOS Beta(对齐设计稿)+ 跨平台栈决策 | 📋 计划中 | | S8 | Week 8 | 用户手册完整版 + Linux/Win Beta + v1.0 GA | 📋 计划中 | | S9 | Week 9 | 服务端同步 RFC + OTA 协议设计（不实现） | 📋 计划中 | @@ -28,6 +28,15 @@ ## 近期变更 +### 2026-04-20（Sprint 6 完成 · Phase 2 第一 Sprint） +- **⑥ UI/UX 设计稿**: 17 张 HTML 原型 + 10 wireframes + 5 Mermaid flows + modules map + - 核心: 主视图 / 向导 / 设置 / 命令面板 / Artifact / 供应商切换 / 搜索 / 右键菜单 / 空态 / 状态栏 + - 角色: 登录 / 项目列表 / 新建项目向导(4 模式 A/B/C/D) · 四大场景工作流(业务/开发/测试/运维 + Prompt 一键操作) +- **① 架构图 + 技术盘点**: `ARCHITECTURE.md` 含 4 张 Mermaid(四层 / 数据流 / 依赖 / 部署)+ 技术盘点清单 20+ 项 +- **⑤ 信息共享模式**: `docs/architecture/information-sharing.md` 固化 Git+Markdown+CI 模型,含优缺点 / 反模式 / 何时上服务端 +- **② 用户手册起步**: `docs/manual/` README + 00-install(三平台)+ 99-cheatsheet(一页速查) +- **③ 桌面应用**: 未启动,推迟到 Sprint 7 实施 + ### 2026-04-18（Sprint 5 完成） - `tools/cli/` — 统一 `epcode` CLI,10 个子命令（init/adopt/migrate/check/prd/adr/metrics/incident/linkage/jira） - `tools/cli/scaffolds/mode-{a,b,c,d}/` — 4 种接入模式的脚手架模板 diff --git a/docs/architecture/information-sharing.md b/docs/architecture/information-sharing.md new file mode 100644 index 0000000..49305f3 --- /dev/null +++ b/docs/architecture/information-sharing.md @@ -0,0 +1,221 @@ +# 当前阶段信息共享模式 + +> Sprint 6 ⑤ 产出。把 PLAN.md 里讨论的"Git + Markdown + CI 三件套"固化成正式文档。 +> +> **读者**: 想知道"没有服务端时,怎么做跨场景 / 跨成员协作" 的人。 + +--- + +## 一、核心模型 + +``` +┌────────────────────────────────────────────────────────────────┐ +│ 当前信息共享模式(无中心化服务端) │ +├────────────────────────────────────────────────────────────────┤ +│ │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │ 产品 │ → │ 开发 │ → │ 测试 │ → │ 运维 │ │ +│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ +│ │ │ │ │ │ +│ PRD.md 设计+ADR 用例+提测单 Runbook/复盘 │ +│ 业务规则 API 契约 Bug 报告 发布计划 │ +│ │ │ │ │ │ +│ └─────────────┴─────────────┴─────────────┘ │ +│ ↓ │ +│ ┌──────────────┐ │ +│ │ Git 仓库 │ ← 唯一真实源 │ +│ │ main branch │ │ +│ └──────┬───────┘ │ +│ ↓ │ +│ ┌───────────────────────┐ │ +│ │ CI 门禁 │ │ +│ │ + 跨场景联动脚本 │ ← 自动触发下一环 │ +│ │ + 度量采集 (每周) │ │ +│ └──────────┬────────────┘ │ +│ ↓ │ +│ ┌───────────────────────┐ │ +│ │ Jira / 禅道 / IM / │ ← 可选镜像/广播 │ +│ │ Confluence / Slack │ (非权威源) │ +│ └───────────────────────┘ │ +└────────────────────────────────────────────────────────────────┘ +``` + +## 二、四个核心特征 + +### 2.1 Git = 唯一真实源 + +- 所有产出物都是 Git 里的 **Markdown 文件**(或 YAML / JSON) +- 不存在"数据库里有一份、仓库里有另一份"的双写 +- diff / blame / revert / branch 这些 Git 原生能力**全部白嫖** + +### 2.2 PR / MR = 协作边界 + +- 改动必须走 Pull Request(本仓库 branch protection 强制) +- 评审在 Git 平台(GitHub / GitLab)完成,不在 Jira 评论里 +- `CODEOWNERS` 自动分派评审人 +- CI 不绿不许合 + +### 2.3 CI = 触发器 + 门禁 + +每次 PR 自动跑: +- **门禁类**(不过 → 阻塞合入): `check-prd` · `coverage-check` · `config-audit` · `commit-lint` +- **提示类**(不过 → warning): `markdown-lint` · `check-links` +- **联动类**(PR 改了 PRD → 自动提示测试): `link-prd-to-design` +- **归档类**(main 上): `adr-index-sync` 自动重建 ADR 索引 + +每周一定时: +- `metrics-weekly` 跑 4 场景 collect 脚本 + 生成 METRICS.md 看板 + +### 2.4 企业系统 = 镜像 / 广播层 + +Jira / Confluence / 企业微信 / 钉钉 等**是镜像**,不是权威: +- Git 里的 PRD → `epcode jira sync` 同步到 Jira Issue(便于 PM 跟进) +- Git 里的故障复盘 → 用 IM 机器人广播到群(便于全员周知) +- **Git 改了,Jira 自动追**(反向不成立) + +这样做的代价: Jira 有的,Git 里不一定有(如:某些 issue 的讨论);Git 有的,Jira 里一定会追上。 + +--- + +## 三、按场景详述产出物流向 + +### 3.1 业务产出 + +| 产出物 | 生产者 | 消费者 | 消费方式 | +|-------|--------|--------|---------| +| `docs/prd/*.md` | 产品 | 测试(可测性评审)
开发(需求理解) | 读文件 + CI `check-prd` 自动提示 | +| `docs/business/user-stories/*.md` | 产品 | 开发(拆任务)
测试(写用例) | 读文件 | +| `docs/business/business-rules/*.md` | 产品 | 开发(编码)
测试(边界) | 读文件 | +| `CHANGE-LOG.md` | 产品(CR 管理) | 全员 | 读文件 + IM 广播 | + +### 3.2 开发产出 + +| 产出物 | 生产者 | 消费者 | 消费方式 | +|-------|--------|--------|---------| +| `docs/design/*.md` | 开发 / 架构 | 测试(设计评审)
运维(部署评估) | 读文件 | +| `docs/adr/NNNN-*.md` | 开发 / 架构 | 未来的开发 / 新人 | 读文件 + `generate-adr-index` 索引 | +| `docs/api/*.md` | 开发 | 测试(契约用例)
其他系统(对接) | 读文件 + CI 契约冲突检测 | +| `RELEASE-NOTE.md` | 开发 | 运维(发布)
用户 | 读文件 + IM 广播 | + +### 3.3 测试产出 + +| 产出物 | 生产者 | 消费者 | 消费方式 | +|-------|--------|--------|---------| +| `docs/test/strategy-*.md` | 测试负责人 | 全员(评审) | 读文件 + 评审会议 | +| `docs/test/cases/*.md` | 测试 | 开发(交叉审)
测试 CI | 读文件 + `coverage-analysis` 脚本 | +| `docs/test/submission-*.md` | 开发(提交)
测试(审核) | 测试(决定接不接) | 读文件 + CI `submission-check` | +| `docs/test/bug-reports/*.md` | 测试 | 开发(修) | 读文件 + `epcode jira sync` 同步 | +| `docs/test/report-*.md` | 测试负责人 | 运维(发布决策) | 读文件 + `generate-release-plan` | + +### 3.4 运维产出 + +| 产出物 | 生产者 | 消费者 | 消费方式 | +|-------|--------|--------|---------| +| `docs/ops/release-plan-*.md` | SRE / 发布人 | 全员 | 读文件 + IM 广播 | +| `docs/ops/runbooks/*.md` | SRE | 值班人员(出事看) | 读文件 + 告警附带链接 | +| `docs/ops/incidents/INC-*.md` | 值班 / SRE | 全员 | 读文件 + IM 广播 | +| `docs/ops/postmortems/*.md` | 事件负责人 | 全员 + 业务 backlog | 读文件 + `incident-to-requirement` | +| `METRICS-operations.md` | CI 自动 | 管理层 / SRE 团队 | 读文件(每周更新) | + +--- + +## 四、跨场景联动(Sprint 4 产出) + +4 个脚本把上面的"单向流动"串成**闭环**: + +```mermaid +flowchart LR + PRD[业务: PRD.md] + Design[开发: design+ADR] + Cases[测试: 用例] + Plan[运维: 发布计划] + Actions[业务: Backlog] + + PRD -->|link-prd-to-design| Design + Design -->|recommend-regression| Cases + Cases -->|generate-release-plan| Plan + Plan -->|incident-to-requirement| Actions + Actions -->|人工触发| PRD +``` + +| 联动 | 脚本 | 触发时机 | 产出 | +|------|------|---------|------| +| 业务 → 开发 | `link-prd-to-design.js` | PRD PR 里 | 受影响设计清单(+评审建议) | +| 开发 → 测试 | `recommend-regression.js` | 代码 PR 里 | 建议回归用例列表 | +| 测试 → 运维 | `generate-release-plan.js` | 准出后 | 发布计划草稿 | +| 运维 → 业务 | `incident-to-requirement.js` | 复盘时 | GH Issue / Jira Task 批量 | + +触发方式: +- 手动: `epcode linkage ` +- 自动: 在 CI workflow 里配置相应 `changes` 过滤 + +--- + +## 五、优点 vs 缺点 · 坦诚分析 + +### ✅ 优点 + +| 优点 | 说明 | +|------|------| +| **零后端成本** | 每个项目私仓 = 自己的数据库,无需运维 | +| **完全离线可用** | 除通知类集成外,整套可在 air-gapped 环境跑 | +| **Diff / Blame / Revert 天然支持** | Git 40 年积累的能力全部可用 | +| **工具链成熟** | Markdown / Git / CI 生态极其丰富 | +| **跨工具互操作** | Obsidian / VS Code / Typora / Logseq 都能读 Markdown | +| **数据主权清晰** | 数据在自己仓库,企业不担心外泄 | + +### ❌ 缺点(诚实面对) + +| 缺点 | 说明 | 缓解 / 解决 | +|------|------|-----------| +| **跨仓库统计难** | 公司 100 个项目,想看全局指标要 100 次 clone | Phase 3 服务端聚合 | +| **全员审计难做** | Git 只能看 commit,看不到"张三昨天点了多少次 /prd" | Phase 3 服务端事件流 | +| **Git 对非技术人员有门槛** | PM / 业务同学 `git pull` 不顺手 | 桌面应用(Sprint 7+)封装 | +| **非文本产出支持弱** | 设计稿 / 视频 / 音频 不适合 Git(LFS 能缓解但不完美) | 外链 + Git 存引用 | +| **权限粒度粗** | Git 层是"能读整个仓或读不了整个仓",不分文件 | 接入企业 SSO + CODEOWNERS 缓解 | +| **离线协作难** | 没网时,改动无法推送给别人 | 本地 Git 分支 + 恢复后 push | + +### 何时考虑上服务端(Phase 3) + +以下**任一**条件满足时,值得投资 Phase 3 服务端(PLAN § ④): +- 公司有 **10+ 项目**同时使用本框架,需要跨项目看板 +- 有合规要求(金融 / 医疗等)需要**完整审计日志** +- 团队里 **50%+ 非技术人员**(PM / 业务 / 运维)用不惯 Git +- 需要**实时协同**(两人同时编辑一个 PRD) +- 需要**OTA 推送**强制客户端升级(安全漏洞时) + +--- + +## 六、最小起步 · 某团队用这套方法论的 Day 1 + +**假设**: 一个 5 人团队,有 GitHub 企业账号,用企业微信。 + +1. **Day 1 上午**: 在 GitHub 建仓库 → `git clone` → 跑 `npx epcode init --mode=A --name=<项目>` +2. **Day 1 下午**: 产品用模板写 PRD 初稿 → 推 PR +3. **Day 2**: PR 触发 CI,`prd-check` 自动评审结构 → 测试同学在 PR 里留可测性意见 +4. **Day 3**: 合入,`adr-index-sync` 自动建 ADR 索引 → 开发开始写设计 ADR +5. **Week 1 周五**: `metrics-weekly` 自动生成第一份周报 → IM 机器人推到群 + +**这就是全部**。没装过服务端,没配过单独的数据库。 + +--- + +## 七、反模式 · 不要这样用 + +| ❌ 反模式 | 为什么不行 | 正确做法 | +|---------|----------|---------| +| 把 Jira 当权威源,Git 里的 Markdown 是 "给 AI 看的" | 双写必然不一致 | 反过来: Git 权威,Jira 用 `sync` 脚本镜像 | +| 手工同步 PRD 变更到 Confluence | 人必然忘 | `epcode jira sync` / Confluence publish 脚本 | +| 在 Slack 里讨论技术决策,不写 ADR | 3 个月后没人记得为什么这么选 | 讨论后必须落 ADR | +| 不跑 CI 就合 PR | 方法论失效 | branch protection 强制 | +| 改了 PRD 不通知测试 | 测试漏评审,上线出问题 | CI 自动跑 `link-prd-to-design` 提示 | + +--- + +## 八、相关文档 + +- [ARCHITECTURE.md](../../ARCHITECTURE.md) · 本文的上层视图(四层架构) +- [PLAN.md § Phase 2 ⑤](../../PLAN.md) · 本文的初稿来源 +- [docs/chapters/](../chapters/) · 每场景方法论详情 +- [tools/cli/](../../tools/cli/) · `epcode` CLI 入口 +- [examples/leave-management-system/](../../examples/leave-management-system/) · 端到端实例 diff --git a/docs/manual/00-install.md b/docs/manual/00-install.md new file mode 100644 index 0000000..6beddd8 --- /dev/null +++ b/docs/manual/00-install.md @@ -0,0 +1,246 @@ +# 00 · 安装(三平台) + +> **目标**: 10 分钟内,装好 CLI + 桌面应用 + 能跑 `epcode --help`。 +> +> **三种使用方式,按需选**: +> 1. **只用 CLI**(最快,1 分钟)· 适合开发 / 自动化 +> 2. **CLI + 文档站**(看方法论)· 推荐新用户 +> 3. **完整桌面应用**(GUI)· Sprint 7 起可用 + +--- + +## 一、前置依赖(所有方式都需要) + +| 工具 | 最低版本 | 检查命令 | +|------|---------|---------| +| **Node.js** | 18.0+ | `node --version` | +| **Git** | 2.30+ | `git --version` | +| **Claude Code** | 1.0+ | `claude --version` | + +如果缺,按下面平台章节的"前置安装"装。 + +--- + +## 二、macOS 安装 + +### 2.1 前置(用 Homebrew) + +```bash +# 装 Node + Git +brew install node git + +# 装 Claude Code +npm install -g @anthropic-ai/claude-code + +# 如果需要(首次用 Xcode 工具) +xcode-select --install +``` + +### 2.2 装 epcode CLI + +**方式 A · 用 npx(推荐,无需 clone)**: + +```bash +# 直接跑,不装 +npx epcode --help +npx epcode init --mode=A --name=my-project +``` + +**方式 B · clone 仓库本地跑**: + +```bash +git clone https://github.com/epcode-ai/ep-code-ai.git +cd ep-code-ai +node tools/cli/bin/epcode.js --help +``` + +### 2.3 装桌面应用(Sprint 7 之后) + +```bash +# 从 GitHub Releases 下载最新 .dmg +# https://github.com/epcode-ai/ep-code-ai/releases + +# 双击 .dmg → 拖到 Applications → 首次打开右键"打开"绕过 Gatekeeper +``` + +### 2.4 验证 + +```bash +npx epcode --help +# 应看到 10 个子命令:init / adopt / migrate / check / prd / adr / metrics / incident / linkage / jira + +node tools/cross-platform/scripts/check-all.js +# 应看到"✅ 全部通过" +``` + +--- + +## 三、Linux 安装(Ubuntu / Debian) + +### 3.1 前置 + +```bash +# Node 18+ (官方 APT 源) +curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - +sudo apt-get install -y nodejs + +# Git +sudo apt-get install -y git + +# Claude Code +sudo npm install -g @anthropic-ai/claude-code +``` + +### 3.2 装 CLI + +同 macOS 2.2 节,`npx epcode` 或 clone 都可以。 + +### 3.3 一键脚本(本仓库提供) + +```bash +git clone https://github.com/epcode-ai/ep-code-ai.git +cd ep-code-ai +bash platforms/linux/scripts/install.sh +``` + +### 3.4 桌面应用(Sprint 8 之后) + +```bash +# AppImage(通用,不依赖包管理器) +wget https://github.com/epcode-ai/ep-code-ai/releases/latest/download/ep-code-ai-linux-x86_64.AppImage +chmod +x ep-code-ai-linux-x86_64.AppImage +./ep-code-ai-linux-x86_64.AppImage + +# 或 .deb(Ubuntu/Debian) +sudo dpkg -i ep-code-ai-linux-amd64.deb +``` + +### 3.5 验证 + +```bash +bash platforms/linux/scripts/check-environment.sh +# 应看到各项依赖 ✅ +``` + +--- + +## 四、Windows 安装 + +### 4.1 前置 + +**推荐 PowerShell 管理员窗口**执行: + +```powershell +# 用 winget +winget install OpenJS.NodeJS +winget install Git.Git + +# 装 Claude Code +npm install -g @anthropic-ai/claude-code +``` + +### 4.2 装 CLI + +```powershell +# 方式 A · npx +npx epcode --help + +# 方式 B · clone +git clone https://github.com/epcode-ai/ep-code-ai.git +cd ep-code-ai +node tools\cli\bin\epcode.js --help +``` + +### 4.3 一键脚本(本仓库提供) + +```powershell +git clone https://github.com/epcode-ai/ep-code-ai.git +cd ep-code-ai +.\platforms\windows\scripts\install.ps1 +``` + +### 4.4 桌面应用(Sprint 8 之后) + +```powershell +# 从 GitHub Releases 下 .msi +# 双击运行安装向导 +``` + +### 4.5 验证 + +```powershell +.\platforms\windows\scripts\check-environment.ps1 +``` + +### 4.6 WSL 用户 + +如果用 WSL 2,**建议直接在 WSL 里跑 Linux 版本**(第 3 节),体验更顺。 +Windows 原生版在 PowerShell / cmd 里跑,适合不想装 WSL 的用户。 + +--- + +## 五、首次启动(装完后做这三件事) + +### 5.1 检查环境 + +```bash +# 自动检测 Node / npm / git / Claude Code 等 +npx epcode check +``` + +如有异常,按提示修复。 + +### 5.2 第一个项目 + +```bash +# 用 A 模式(绿地)初始化 +npx epcode init --mode=A --name=hello-epcode +cd hello-epcode +cat README.md # 看起步清单 +``` + +### 5.3 看看命令能干什么 + +```bash +# PRD 结构校验(对任意 .md) +npx epcode prd docs/prd/hello.md + +# 四场景度量 + 看板 +npx epcode metrics --since "7 days ago" + +# 命令面板(字面意思:打开所有子命令) +npx epcode --help +``` + +--- + +## 六、配置 AI 供应商(首次使用前) + +**桌面应用**: 首次启动的 Setup Wizard 第 3 步自动引导。 + +**纯 CLI 用户**: 只要你的本机的 `claude` CLI 已登录(`claude auth login`),本仓库的脚本就会用它。 + +如果想用不同供应商(Bedrock / Vertex / 代理),参考 Claude Code 官方文档: https://docs.anthropic.com/claude-code + +--- + +## 七、完全离线可跑 + +以下场景**不需要网络**: +- `epcode init` / `epcode adopt` / `epcode migrate` +- `epcode check` · `epcode prd` · `epcode adr index` · `epcode metrics` +- 所有 `tools/cross-platform/scripts/*.js` + +需要网络的: +- 调 AI (Claude / Bedrock 等) +- `epcode jira sync` · 同步到企业系统 +- `npx epcode`(首次下载 npm 包)· 装完后可离线 + +--- + +## 八、下一步 + +- 📘 手册: [99-cheatsheet.md](./99-cheatsheet.md) 一页速查表 +- 📖 方法论: [docs/chapters/00-adoption/](../chapters/00-adoption/) 看你的项目该用哪种模式 +- 🧰 命令: `npx epcode --help` 看所有子命令 +- 🆘 问题: [GitHub Issues](https://github.com/epcode-ai/ep-code-ai/issues) diff --git a/docs/manual/99-cheatsheet.md b/docs/manual/99-cheatsheet.md new file mode 100644 index 0000000..e5fe743 --- /dev/null +++ b/docs/manual/99-cheatsheet.md @@ -0,0 +1,160 @@ +# 99 · 速查表 · 一页看懂 + +> 打印贴墙用。最常用的命令 / 文件位置 / 术语对照。 + +--- + +## 🧰 CLI 速查 · `npx epcode` + +| 命令 | 做什么 | 示例 | +|------|------|------| +| `init --mode=A|B|C|D --name=` | 按接入模式起项目 | `init --mode=A --name=order` | +| `adopt --level=<1..5>` | 模式 C 渐进启用 | `adopt --level=2` | +| `migrate --from=existing-code` | 模式 B 反向生成 API | - | +| `check` | 跑全部校验 | - | +| `prd ` | PRD 结构 + 可测性 | `prd docs/prd/v1.md` | +| `adr index [--check]` | ADR 索引重建 / 校验 | `adr index --target docs/adr/` | +| `metrics [--since]` | 四场景度量 + 看板 | `metrics --since "7 days ago"` | +| `incident new/to-requirement` | 故障处理 | `incident new --id INC-001` | +| `linkage ` | 跨场景联动 | `linkage release-plan --report r.md` | +| `jira sync/create-issue/list` | Jira 集成 | `jira sync bugs.md` | + +--- + +## 📁 目录速查 + +``` +ep-code-ai/ +├── docs/ +│ ├── chapters/ 方法论(为什么这么做) +│ │ ├── 00-adoption/ ⭐ 接入模式(从哪读起) +│ │ ├── 01-overview/ 总览 +│ │ ├── 02-business/ 业务篇 +│ │ ├── 03-development/开发篇 +│ │ ├── 04-testing/ 测试篇 +│ │ └── 05-operations/ 运维篇 +│ ├── manual/ 用户手册(怎么做) +│ ├── architecture/ 架构文档 +│ ├── design/ui/ UI/UX 设计 + HTML 原型 +│ └── adr/ 架构决策记录 +├── templates/ 24 个 Markdown 模板 +│ ├── business/ PRD / 用户故事 / 业务规则 等 +│ ├── development/ 设计 / ADR / 代码评审 等 +│ ├── testing/ 测试策略 / 用例 / Bug 等 +│ └── operations/ 发布 / Runbook / 复盘 等 +├── skills/ 29 个 AI Prompt +├── tools/ 零依赖脚本 + CLI +│ ├── cli/ epcode 命令 +│ ├── cross-platform/ 15 个通用脚本 +│ ├── metrics/ 四场景度量 +│ └── integrations/ 企业系统连接器(9 个) +└── platforms/ 三操作系统适配 + ├── macos/ + ├── linux/ + └── windows/ +``` + +--- + +## ⌨️ 快捷键(桌面应用,Sprint 7+) + +| 功能 | macOS | Linux/Win | +|------|-------|-----------| +| 新会话 | `⌘N` | `Ctrl+N` | +| 全局搜索 | `⌘K` | `Ctrl+K` | +| 设置 | `⌘,` | `Ctrl+,` | +| 切换供应商 | `⌘⇧P` | `Ctrl+Shift+P` | +| 切换角色 | `⌘⇧R` | `Ctrl+Shift+R` | +| 命令面板 | `/` | `/`(输入框首字符) | +| 发送消息 | `⌘↵` | `Ctrl+Enter` | + +--- + +## 🧑‍🤝‍🧑 4 种接入模式速选 + +| 你的项目 | 选模式 | 入口 | +|---------|--------|------| +| 刚立项,未编码 | **A · 绿地** | `epcode init --mode=A` | +| 代码已写未上线 | **B · 开发中** | `epcode init --mode=B` | +| 已上线,定期迭代 | **C · 迭代中** | `epcode init --mode=C` | +| 稳态运维 1 年+ | **D · 稳态** | `epcode init --mode=D` | + +详情: [docs/chapters/00-adoption/](../chapters/00-adoption/) + +--- + +## 🔄 四场景工作流速选 + +| 你是 | 主要看 | CLI 高频 | +|------|--------|---------| +| 产品 / BA | [业务篇](../chapters/02-business/) | `prd` · `linkage prd-to-design` | +| 开发 | [开发篇](../chapters/03-development/) | `adr` · `check` · `linkage regression` | +| 测试 / QA | [测试篇](../chapters/04-testing/) | `prd`(可测性)· `linkage release-plan` | +| SRE / 运维 | [运维篇](../chapters/05-operations/) | `incident new` · `metrics` | + +--- + +## 🧠 术语速查 + +| 术语 | 含义 | +|------|------| +| **ADR** | Architecture Decision Record · 架构决策记录 | +| **AC** | Acceptance Criteria · 验收标准 | +| **PRD** | Product Requirements Document · 产品需求文档 | +| **CR** | Change Request · 变更请求 | +| **REQ-NNN** | 需求 ID(PRD 里每个功能点) | +| **US-NNN** | User Story ID | +| **INC-xxx** | Incident 事件 / 故障编号 | +| **Runbook** | 某类告警的处置手册 | +| **Postmortem** | 故障复盘(blameless) | +| **Artifact** | AI 产出的代码 / 文档(中文称"产出物") | +| **接入模式 A/B/C/D** | 按项目阶段分的四种嵌入策略 | + +--- + +## 🆘 常见错误 → 怎么办 + +| 错误 | 怎么办 | +|------|--------| +| `epcode: command not found` | 用 `npx epcode` 而不是 `epcode`;或 `npm install -g @epcode-ai/cli` | +| `fetch is not defined` | Node 版本太低,升级到 18+ | +| CI `prd-check` 失败 | 跑 `npx epcode prd ` 看具体问题 | +| CI `config-audit` 失败退出 2 | prod 配置里有明文敏感值 → 用 `ENC()` / `vault:` 占位 | +| Docusaurus build 报 MDX 错 | 表格里的 `<60` 要写 `<60` | +| `gh pr merge` 被拒 | 检查 branch protection:Required approvals / Code Owner review | + +--- + +## 🔗 重要链接 + +- 项目首页: https://github.com/epcode-ai/ep-code-ai +- 文档站: https://epcode-ai.github.io/ep-code-ai/ +- HTML 原型: https://raw.githack.com/epcode-ai/ep-code-ai/main/docs/design/ui/prototype/index.html +- CHANGELOG: [../../CHANGELOG.md](../../CHANGELOG.md) +- PLAN.md(路线图): [../../PLAN.md](../../PLAN.md) +- ARCHITECTURE.md(架构): [../../ARCHITECTURE.md](../../ARCHITECTURE.md) + +--- + +## 🎯 "我 5 分钟入门" + +```bash +# 1. 看能不能跑 +npx epcode --help + +# 2. 起第一个项目 +npx epcode init --mode=A --name=hello + +# 3. 写个 PRD(复制模板填) +cd hello +cp ../templates/business/prd-template.md docs/prd/hello-v0.1.md +# ... 填内容 ... + +# 4. 校验 +npx epcode prd docs/prd/hello-v0.1.md + +# 5. 看度量 +npx epcode metrics +``` + +**好了,你已经在用这套方法论。** diff --git a/docs/manual/README.md b/docs/manual/README.md new file mode 100644 index 0000000..f8fe21f --- /dev/null +++ b/docs/manual/README.md @@ -0,0 +1,68 @@ +# 用户使用手册 + +> Sprint 6 ② 起步 · Sprint 8 完整发布。 +> +> **这是什么**: 面向"拿起来就用"的用户手册。区别于 [docs/chapters/](../chapters/)(讲"为什么"的方法论)。 +> +> **这不是什么**: 不是开发者手册(如何改 CLI / 改工具链)。那个见 [ARCHITECTURE.md](../../ARCHITECTURE.md)。 + +--- + +## 按你的需求选起点 + +### 🆕 "我是新用户,0 基础" + +1. [**00-install.md**](./00-install.md) · 三操作系统安装步骤(含桌面应用 + CLI) +2. [**99-cheatsheet.md**](./99-cheatsheet.md) · 一页速查表(打印贴墙) +3. `01-first-project.md`(S8 补) · 第一个项目手把手(Sprint 8 补) + +### 🎭 "我是特定角色,直奔我的部分" + +| 角色 | 入口(Sprint 8 补全) | +|------|---------------------| +| 产品经理 / BA | `02-by-role/product.md`(S8 补) | +| 开发工程师 | `02-by-role/developer.md`(S8 补) | +| 测试 / QA | `02-by-role/qa.md`(S8 补) | +| SRE / 运维 | `02-by-role/sre.md`(S8 补) | + +### 📍 "我的项目处于某阶段,给我完整流程" + +| 阶段 | 入口(Sprint 8 补全) | +|------|---------------------| +| 刚立项 · 从零建 | `03-by-scenario/greenfield-journey.md`(S8 补) | +| 老项目接入 | `03-by-scenario/adopt-to-legacy.md`(S8 补) | + +### 🆘 "我遇到问题了" + +- `04-troubleshooting.md` · 常见错误诊断(Sprint 8 补)·临时看 [99-cheatsheet](./99-cheatsheet.md#-常见错误--怎么办) +- [GitHub Issues](https://github.com/epcode-ai/ep-code-ai/issues) · 找不到答案时来这里提 + +--- + +## 当前状态(Sprint 6 起步) + +| 文件 | 状态 | 计划 Sprint | +|------|------|-----------| +| README.md | ✅ | S6 | +| 00-install.md | ✅ | S6 | +| 99-cheatsheet.md | ✅ | S6 | +| 01-first-project.md | 📋 | S8 | +| 02-by-role/{product,developer,qa,sre}.md | 📋 | S8 | +| 03-by-scenario/{greenfield,legacy}.md | 📋 | S8 | +| 04-troubleshooting.md | 📋 | S8 | + +按 PLAN § Phase 2 的"小步迭代"原则,先发起步最重要的两篇,后续 Sprint 持续补。 + +--- + +## 与方法论文档的关系 + +| | 用户手册 (`docs/manual/`) | 方法论 (`docs/chapters/`) | +|--|------------------------|-------------------------| +| 回答 | **怎么做** | **为什么这么做** | +| 风格 | 手把手步骤 + 截图 + 故障诊断 | 原则 + 对照 + 案例分析 | +| 读完时长 | 5-20 分钟 | 每章 1-2 小时 | +| 例子 | "装好后在终端输这行" | "提测为什么是重要的门禁" | +| 更新频率 | 随版本 / 随反馈 | 季度级稳定 | + +两者配合: 先读方法论搞明白"值不值得做",再读手册"怎么下手"。