@mathripper/ideal-cli 1.0.0

package/README.md

@@ -0,0 +1,263 @@
+# Claude Code 中心化团队工作流设计方案
+
+## 一、项目背景
+
+以 Claude Code 为中心重构团队工作流，实现从产品设计、前端设计到开发、测试、上线的全流程自动化。核心目标是让团队成员只需：**提需求、做评审、反馈意见**，其他工作由 Claude Code 自动完成。
+
+---
+
+## 二、核心架构
+
+### 2.1 统一存储结构
+
+采用 **Git 仓库 + Obsidian vault 统一存储** 方案，`docs/` 目录即为 Obsidian vault，文档与代码在同一仓库中版本同步。
+
+```
+{项目名称}/                       # Git 仓库根目录
+│
+├── .claude/                       # Claude Code 相关
+│   ├── skills/                    # 定制化 skills（项目级）
+│   │   ├── ideal-brainstorm/      # 头脑风暴（通用）
+│   │   ├── ideal-requirement/     # 需求编写（通用）
+│   │   ├── ideal-dev-solution/    # 技术方案（开发领域）
+│   │   ├── ideal-dev-plan/        # 计划生成（开发领域）
+│   │   ├── ideal-test-case/       # 测试用例（测试领域）
+│   │   ├── ideal-dev-review/      # 代码审查（开发领域）
+│   │   ├── ideal-wiki/            # 维基生成（通用）
+│   │   └── ...
+│   └── plans/                     # 编码计划（临时文件）
+│
+├── src/                           # 源代码
+│   └── orchestrator/              # 流程编排器
+│
+├── tests/                         # 测试代码
+│
+├── templates/                     # 所有模板
+│   └── docs/                      # 文档模板
+│       ├── 需求文档.md
+│       ├── 技术方案.md
+│       ├── 编码计划.md
+│       ├── 测试用例.md
+│       └── 测试报告.md
+│
+├── docs/                          # Obsidian vault（文档中心）
+│   ├── .obsidian/                 # Obsidian 配置
+│   ├── .automation/               # 自动化配置
+│   │   └── config.yaml
+│   │
+│   ├── 项目状态.md                 # 项目状态看板
+│   ├── 产品愿景.md
+│   ├── 产品路线图.md
+│   │
+│   ├── 迭代/                      # 按需求命名
+│   │   └── {需求名称}/
+│   │       ├── P1-需求文档.md
+│   │       ├── P3-技术方案.md
+│   │       ├── P5-编码计划.md
+│   │       ├── P7-测试用例.md
+│   │       ├── P11-测试报告.md
+│   │       ├── 流程状态.md         # 状态控制文件
+│   │       └── stories/           # 故事文件（P5 生成）
+│   │           ├── index.md       # 故事索引
+│   │           └── 0XX-*.md       # 原子化故事
+│   │
+│   └── Wiki/                      # 维基文档
+│       ├── 用户文档/
+│       ├── 开发文档/
+│       └── 接口文档/
+│
+├── .gitignore
+├── .gitlab-ci.yml
+└── README.md                      # 仓库说明
+```
+
+### 2.2 职责划分
+
+| 维度 | docs/ (Obsidian vault) | src/ + 根目录 |
+|------|------------------------|---------------|
+| **定位** | 文档中心、流程控制、决策记录 | 代码执行层 |
+| **人类交互** | 产品/设计/管理者（Obsidian 界面） | 开发者评审代码 |
+| **Claude 交互** | 读写文档、生成方案 | 读写代码、执行计划 |
+| **版本控制** | Git（通过 Obsidian Git 插件） | Git |
+
+### 2.3 Obsidian Git 插件配置
+
+团队使用 Obsidian Git 插件实现文档的自动同步：
+- 自动备份间隔：每 5 分钟
+- 自动拉取间隔：每 5 分钟
+- 冲突处理：先 pull 再 push
+
+---
+
+## 三、阶段流程定义（P1-P15）
+
+### 3.1 阶段总览
+
+```mermaid
+flowchart LR
+    %% 主流程
+    P1((P1<br/>需求编写)):::claude --> P2((P2<br/>需求评审)):::human
+    P2 --> P3((P3<br/>技术方案)):::claude
+    P3 --> P4((P4<br/>方案评审)):::human
+    P4 --> P5((P5<br/>计划生成)):::claude
+    P5 --> P6((P6<br/>计划评审)):::human
+
+    P6 --> P7((P7<br/>测试用例)):::claude
+    P7 --> P8((P8<br/>用例评审)):::human
+    P8 --> P9((P9<br/>开发执行)):::claude
+    P9 --> P10((P10<br/>代码评审)):::human
+    P10 --> P11((P11<br/>测试执行)):::claude
+    P11 --> P12((P12<br/>测试评审)):::human
+
+    P12 --> P13((P13<br/>维基更新)):::claude
+    P13 --> P14((P14<br/>维基评审)):::human
+    P14 --> P15((P15<br/>成果提交)):::claude
+
+    %% 样式定义
+    classDef human fill:#fff2cc,stroke:#d6b656,stroke-width:2px,color:#000
+    classDef claude fill:#d5e8d4,stroke:#82b366,stroke-width:2px,color:#000
+    classDef auto fill:#dae8fc,stroke:#6c8ebf,stroke-width:2px,color:#000
+
+    %% 图例
+    subgraph legend[图例]
+        L1((人工)):::human
+        L2((Claude)):::claude
+        L3((自动)):::auto
+    end
+```
+
+### 3.2 阶段详情
+
+| 阶段  | 名称   | 执行者    | 输入                | 输出             | 审核人       |
+| --- | ---- | ------ | ----------------- | -------------- | --------- |
+| P1  | 需求编写 | 产品/设计  | 需求想法              | 需求文档.md + 原型代码 | -         |
+| P2  | 需求评审 | 人工     | 需求文档.md           | 评审意见/通过        | 产品+技术负责人  |
+| P3  | 技术方案 | Claude | 需求文档.md           | 技术方案.md        | -         |
+| P4  | 方案评审 | 人工     | 技术方案.md           | 评审意见/通过        | 技术负责人+架构师 |
+| P5  | 计划生成 | Claude | 技术方案.md           | 编码计划.md（原子任务）  | -         |
+| P6  | 计划评审 | 人工     | 编码计划.md           | 评审意见/通过        | 开发负责人     |
+| P7  | 测试用例 | Claude | 需求文档.md + 编码计划.md | 测试用例.md        | -         |
+| P8  | 用例评审 | 人工     | 测试用例.md           | 评审意见/通过        | 测试负责人     |
+| P9  | 开发执行 | Claude | 编码计划.md           | 代码 + MR        | -         |
+| P10 | 代码评审 | 人工     | MR                | Approve/修改意见   | 开发团队      |
+| P11 | 测试执行 | Claude | 测试用例.md           | 测试报告.md        | -         |
+| P12 | 测试评审 | 人工     | 测试报告.md           | 通过/修复          | 测试负责人     |
+| P13 | 维基更新 | Claude | 代码 + 需求文档.md      | 维基文档           | -         |
+| P14 | 维基评审 | 人工     | 维基文档              | 发布许可           | 产品+技术     |
+| P15 | 成果提交 | Claude | 全部通过              | 合并代码、删除 worktree、提交 PR | - |
+
+> 注：上线部署由 CI/CD 自动化完成，P15 成果提交后自动触发 CI/CD 流水线。
+
+---
+
+## 四、触发机制
+
+### 4.1 自动触发
+- 文件变化监听（fswatch/chokidar）
+- 流程状态.md 中的状态字段变更
+- GitLab Webhook（MR 状态变化）
+
+### 4.2 手动触发
+- 修改 流程状态.md 中的审核状态字段
+- 命令行：`automation trigger --project 项目名 --phase P7`
+- Obsidian 内按钮（Templater 插件）
+
+### 4.3 状态控制示例
+
+```markdown
+# 流程状态.md
+---
+current_phase: P6
+plan_review: pending    # 改为 approved 触发 P7
+---
+```
+
+---
+
+## 五、通知服务
+
+- **邮件**：关键节点通知
+- **即时通讯**：钉钉/企业微信机器人
+- **Obsidian 内**：README.md 状态看板自动更新
+
+---
+
+## 六、维基管理
+
+### 6.1 文档分类
+
+| 类型 | 内容 | 生成时机 |
+|------|------|----------|
+| 用户文档 | 使用指南、常见问题、更新日志 | 上线后 P15 |
+| 开发文档 | 架构说明、部署文档 | 方案确认后 + 上线后 |
+| 接口文档 | REST/GraphQL 文档 | 代码合并后自动提取 |
+
+### 6.2 发布方式
+- GitLab Wiki（自动同步）
+- 静态站点（VitePress/Docusaurus，可选）
+
+---
+
+## 七、技术组件
+
+### 7.1 流程调度器
+- 文件监听器（watcher）
+- 状态机（state machine）
+- 任务队列（task queue）
+- 通知服务（notify）
+
+### 7.2 执行器
+- Claude Code 命令行调用
+- GitLab 接口集成
+- 持续集成流水线触发
+
+---
+
+## 八、后续实施任务
+
+| 优先级 | 任务 | 说明 |
+|--------|------|------|
+| 高 | 定义需求文档模板和编写指南 | 产品文档规范 |
+| 高 | 定义技术方案模板 | 基于 Superpowers |
+| 高 | 定义编码计划模板 | 参考 Superpowers writing-plans |
+| 高 | 实现文件监听器 | chokidar/fswatch |
+| 高 | 实现状态机 | 阶段流转控制 |
+| 高 | GitLab 接口集成 | Issue/MR 管理 |
+| 中 | 定义测试用例模板 | 测试规范 |
+| 中 | 实现通知服务 | 邮件 + 即时通讯 |
+| 中 | 定义产品级文档模板 | 愿景/路线图 |
+| 低 | 维基静态站点构建 | VitePress 集成 |
+
+---
+
+## 九、关键决策记录
+
+1. **存储架构**：Git 仓库与 Obsidian vault 统一存储，`docs/` 目录即为 vault
+2. **文档格式**：全量 Markdown
+3. **Claude 调用方式**：Claude Code 命令行
+4. **人工干预**：关键决策点 + 每阶段审核
+5. **Bug 管理**：直接在 GitLab Issue，不存 Obsidian
+6. **需求与 Issue**：一对一对应
+7. **编码计划位置**：仓库根目录 `.claude/plans/`，临时文件
+8. **Skills 位置**：`.claude/skills/`，Claude Code 标准位置
+9. **Skills 命名规范**：`ideal-{领域?}-{功能}`，如 `ideal-brainstorm`、`ideal-dev-plan`
+10. **模板位置**：`templates/docs/`，按类型统一管理
+11. **迭代命名**：按需求名称命名，如 `迭代/用户登录/`
+
+---
+
+## 十、验证方式
+
+1. 选择一个简单功能（如用户登录）
+2. 按照流程从 P1 到 P15 走一遍
+3. 验证各阶段文档生成质量
+4. 验证触发机制是否正常
+5. 验证通知是否到位
+
+---
+
+## 参考资源
+
+- [Superpowers GitHub](https://github.com/obra/Superpowers)
+- [Superpowers writing-plans skill](https://github.com/obra/Superpowers/blob/master/skills/writing-plans/SKILL.md)
+- [Jesse Vincent's Blog - How I'm using coding agents](https://blog.fsck.com/2025/10/09/superpowers/)

package/dist/index.d.ts

@@ -0,0 +1,186 @@
+/**
+ * 技术栈类型
+ */
+type TechStack = 'React' | 'Vue' | 'Node.js' | 'Python' | 'Other';
+/**
+ * 项目配置
+ */
+interface ProjectConfig {
+    /** 项目名称 */
+    projectName: string;
+    /** Git 主分支名称 */
+    gitBranch: string;
+    /** 技术栈类型 */
+    techStack: TechStack;
+    /** 工作流配置 */
+    workflow: {
+        /** 模板仓库 */
+        templateRepo: string;
+        /** 模板分支 */
+        templateBranch: string;
+        /** 最后更新时间 */
+        lastUpdated: string;
+    };
+    /** 初始化时间 */
+    initializedAt: string;
+}
+
+/**
+ * 模板文件类型
+ */
+type TemplateFileType = 'agent' | 'skill' | 'config' | 'script';
+/**
+ * 模板文件信息
+ */
+interface TemplateFile {
+    /** 相对于项目根目录的路径 */
+    path: string;
+    /** MD5 哈希值 */
+    hash: string;
+    /** 文件大小（字节） */
+    size: number;
+    /** 文件类型 */
+    type: TemplateFileType;
+    /** 文件版本（可选） */
+    version?: string;
+}
+/**
+ * 模板版本信息
+ */
+interface TemplateMeta {
+    /** 语义化版本号 */
+    version: string;
+    /** 发布日期 */
+    releasedAt: string;
+    /** 版本变更说明 */
+    changelog?: string;
+    /** 最低兼容 CLI 版本 */
+    minCliVersion: string;
+    /** 文件清单 */
+    files?: TemplateFile[];
+}
+/**
+ * 下载的模板文件
+ */
+interface DownloadedFile {
+    /** 文件路径 */
+    path: string;
+    /** 文件内容 */
+    content: string;
+    /** 文件类型 */
+    type: TemplateFileType;
+}
+
+/**
+ * 检查结果状态
+ */
+type CheckStatus = 'pass' | 'warning' | 'error';
+/**
+ * 检查结果
+ */
+interface CheckResult {
+    /** 检查项名称 */
+    name: string;
+    /** 检查状态 */
+    status: CheckStatus;
+    /** 检查消息 */
+    message: string;
+    /** 详细信息 */
+    details?: string;
+}
+/**
+ * 诊断结果
+ */
+interface DoctorResult {
+    /** 检查结果列表 */
+    checks: CheckResult[];
+    /** 摘要统计 */
+    summary: {
+        /** 通过数量 */
+        passed: number;
+        /** 警告数量 */
+        warnings: number;
+        /** 错误数量 */
+        errors: number;
+    };
+}
+
+/**
+ * 元数据类型定义
+ *
+ * 用于跟踪模板文件的安装和更新状态
+ */
+/**
+ * 单个文件的元数据
+ */
+interface FileMetadata {
+    /** 原始文件哈希（安装时的哈希） */
+    originalHash: string;
+    /** 远程模板版本 */
+    remoteVersion: string;
+    /** 最后同步时间 */
+    lastSyncedAt?: string;
+    /** 文件大小（字节） */
+    size?: number;
+}
+/**
+ * 项目元数据
+ */
+interface ProjectMetadata {
+    /** 元数据格式版本 */
+    version: string;
+    /** 项目初始化时间 */
+    initializedAt: string;
+    /** 模板版本 */
+    templateVersion: string;
+    /** 文件元数据映射（相对路径 -> 文件元数据） */
+    files: Record<string, FileMetadata>;
+    /** 最后更新时间 */
+    lastUpdatedAt?: string;
+}
+/**
+ * 文件差异状态
+ */
+type FileDiffStatus = 'unchanged' | 'modified' | 'added' | 'deleted' | 'remote-new' | 'conflict';
+/**
+ * 文件差异信息
+ */
+interface FileDiff {
+    /** 文件路径 */
+    path: string;
+    /** 差异状态 */
+    status: FileDiffStatus;
+    /** 本地哈希（如果存在） */
+    localHash?: string;
+    /** 远程哈希（如果存在） */
+    remoteHash?: string;
+    /** 原始哈希（如果存在） */
+    originalHash?: string;
+    /** 本地版本（如果存在） */
+    localVersion?: string;
+    /** 远程版本（如果存在） */
+    remoteVersion?: string;
+}
+/**
+ * 差异比较结果
+ */
+interface DiffResult {
+    /** 是否有变化 */
+    hasChanges: boolean;
+    /** 未修改的文件数量 */
+    unchangedCount: number;
+    /** 用户修改的文件数量 */
+    modifiedCount: number;
+    /** 新增的文件数量 */
+    addedCount: number;
+    /** 删除的文件数量 */
+    deletedCount: number;
+    /** 远程新增的文件数量 */
+    remoteNewCount: number;
+    /** 冲突的文件数量 */
+    conflictCount: number;
+    /** 所有文件差异列表 */
+    diffs: FileDiff[];
+}
+
+export type { CheckResult, CheckStatus, DiffResult, DoctorResult, DownloadedFile, FileDiff, FileDiffStatus, FileMetadata, ProjectConfig, ProjectMetadata, TechStack, TemplateFile, TemplateFileType, TemplateMeta };