@geeseeker/easyai-dev 3.0.0-alpha.1 → 3.0.0

package/skeleton/.trellis/spec/guides/external-cli-guide.md

@@ -0,0 +1,253 @@
+---
+title: 外部 CLI 集成指南
+version: "1.0"
+category: guides
+status: active
+---
+
+# 外部 CLI 集成指南
+
+> **版本**：v1.0（M05 创建）
+> **适用角色**：PM（调度）、Worker（执行时参考）
+> **架构依据**：`easyAI-底层架构设计.md` §5.4
+
+---
+
+## 1. 安全约束
+
+### 1.1 核心原则：代码主权
+
+外部 CLI（Codex / Claude Code / Gemini CLI）= **外包资源池**，不是项目成员。
+
+- 外部 CLI **不能直接写主工作区**，只能输出到 `.trellis/tasks/Txxx/cli/{cli-name}/`
+- 外部 CLI 产出视为 **Prototype**，主控 AI 需重构后才能合入代码库
+- 主控 AI 重构时须确保：对齐项目编码规范、去除冗余、验证类型安全
+
+### 1.2 输出目录规范
+
+```
+.trellis/tasks/T001-xxx/
+└── cli/
+    ├── codex/          ← Codex CLI 产出
+    │   ├── review.md   ← 审查报告
+    │   └── patch.diff  ← 代码建议（diff 格式）
+    ├── claude-code/    ← Claude Code 产出
+    │   ├── review.md
+    │   └── patch.diff
+    └── gemini/         ← Gemini CLI 产出
+        ├── review.md
+        └── patch.diff
+```
+
+### 1.3 调用前检查清单
+
+每次调用外部 CLI 前，PM/Worker 必须确认：
+
+- [ ] 明确调用目的（审查 / 执行 / 分析）
+- [ ] 限定输出范围（哪些文件、哪些维度）
+- [ ] 指定输出格式（Markdown 报告 / unified diff / JSON）
+- [ ] 设置合理超时
+
+---
+
+## 2. 统一调用模板
+
+### 2.1 Codex CLI（后端/逻辑方向）
+
+**适用场景**：逻辑审查、算法分析、后端代码生成、安全检查
+
+```yaml
+调用工具：mcp_codexmcp_codex
+参数：
+  PROMPT: |
+    任务：{调用目的}
+    任务 ID：{task_id}
+    
+    ## 上下文
+    {相关代码或文件路径}
+    
+    ## 约束
+    {来自 task.md 的约束集}
+    
+    ## 输出要求
+    - 格式：{Markdown 报告 / unified diff patch}
+    - 输出路径（如有文件写入）：.trellis/tasks/{task_id}/cli/codex/
+    - 语言：中文
+  cd: /home/GeeSeeker/projects/easyAI-dev
+  sandbox: read-only  # 审查模式；需写入 cli/ 时用 workspace-write
+```
+
+> **超时说明**：Codex CLI 无显式超时参数，复杂任务通常在 5–10 分钟内完成。
+
+### 2.2 Claude Code
+
+**适用场景**：代码审查、重构建议、文档生成、多文件分析
+
+```yaml
+调用工具：mcp_claude-code-mcp_claude_code
+参数：
+  prompt: |
+    任务：{调用目的}
+    任务 ID：{task_id}
+    
+    ## 上下文
+    {相关代码或文件路径}
+    
+    ## 约束
+    {来自 task.md 的约束集}
+    
+    ## 输出要求
+    - 格式：{Markdown 报告 / unified diff patch}
+    - 如需写入文件，仅允许写入 .trellis/tasks/{task_id}/cli/claude-code/
+    - 语言：中文
+    
+    注意：不要修改项目源代码，只提供分析报告或建议。
+  workFolder: /home/GeeSeeker/projects/easyAI-dev
+```
+
+> **说明**：Claude Code MCP 工具无显式 sandbox 参数，通过 prompt 中的指令约束写入行为。复杂任务通常 5–10 分钟完成。
+
+### 2.3 Gemini CLI（前端/集成方向）
+
+**适用场景**：前端审查、可维护性分析、模式一致性检查
+
+```yaml
+调用工具：mcp_geminimcp_gemini
+参数：
+  PROMPT: |
+    任务：{调用目的}
+    任务 ID：{task_id}
+    
+    ## 上下文
+    {相关代码或文件路径}
+    
+    ## 约束
+    {来自 task.md 的约束集}
+    
+    ## 输出要求
+    - 格式：{Markdown 报告 / unified diff patch}
+    - 如需写入文件，仅允许写入 .trellis/tasks/{task_id}/cli/gemini/
+    - 语言：中文
+  cd: /home/GeeSeeker/projects/easyAI-dev
+  sandbox: true  # 沙箱模式，防止意外修改
+```
+
+> **超时说明**：Gemini CLI 无显式超时参数，复杂任务通常在 5–10 分钟内完成。
+
+---
+
+## 3. 多模型交叉审查流程
+
+### 3.1 流程概述
+
+```
+Stage 1：并行审查（产出互不可见）
+  ├─ CLI-A 审查产出 → 生成 review-A.md
+  └─ CLI-B 审查产出 → 生成 review-B.md
+
+Stage 2：主控 AI 综合（分级处理）
+  └─ 合并两份报告 → 去重 → 分级
+
+Stage 3：决策与修复
+  ├─ Critical → 必须修复
+  ├─ Warning → 建议修复
+  └─ Info → 酌情处理
+```
+
+### 3.2 执行步骤
+
+#### Stage 1：并行审查
+
+同时调用两个不同 CLI 审查同一产出。**关键**：两个 CLI 的输入互不可见（不给 CLI-B 看 CLI-A 的报告），确保独立判断。
+
+推荐组合：
+- **Codex + Gemini**（互补：后端逻辑 vs 前端模式）
+- **Codex + Claude Code**（互补：执行优化 vs 架构视角）
+
+审查维度模板：
+
+```markdown
+## 审查维度
+
+### Spec 合规
+- 约束集中每条约束是否被满足？
+- 验收标准是否全部覆盖？
+
+### 代码质量
+- 命名规范、类型安全、错误处理
+- 单一职责、DRY 原则
+
+### 模式一致性
+- 是否与项目现有代码风格一致？
+- 是否遵循项目架构约定？
+
+### 安全
+- 输入验证、注入防护、认证/授权
+- 敏感信息暴露风险
+
+## 输出格式（JSON）
+{
+  "findings": [
+    {
+      "severity": "Critical | Warning | Info",
+      "dimension": "spec | quality | patterns | security",
+      "file": "path/to/file.ts",
+      "line": 42,
+      "description": "问题描述",
+      "fix_suggestion": "修复建议"
+    }
+  ],
+  "passed_checks": ["通过的检查项"],
+  "summary": "总体评估"
+}
+```
+
+#### Stage 2：综合报告
+
+主控 AI 收到两份审查报告后：
+
+1. 合并所有 findings
+2. 去重（同一位置同一问题只保留一条）
+3. 交叉验证（两个 CLI 都发现的问题 → 提升严重程度）
+4. 生成综合报告：
+
+```markdown
+## 交叉审查报告：T{xxx}
+
+### Critical（X 项）— 必须修复
+- [ ] [SPEC] file.ts:42 — 约束 C1 未满足：{描述}
+- [ ] [SEC] api.ts:15 — 输入未校验：{描述}
+
+### Warning（Y 项）— 建议修复
+- [ ] [QUA] utils.ts:88 — 命名不一致：{描述}
+
+### Info（Z 项）— 酌情处理
+- [ ] [PAT] helper.ts:20 — 建议抽取函数：{描述}
+
+### 已通过检查
+- ✅ 约束集 C1-C5 全部满足
+- ✅ 无安全漏洞
+```
+
+#### Stage 3：决策
+
+- **Critical > 0**：必须修复后才能进入验收
+- **Critical = 0, Warning > 0**：建议修复，但可由 PM 判断是否接受
+- **全部 Info**：可直接进入验收
+
+---
+
+## 4. 使用场景指南
+
+| 场景 | 使用方式 | CLI 选择 | sandbox 设置 |
+|------|----------|----------|-------------|
+| 独立审核 | CLI 读取代码，产出审核报告 | 按领域选择 | read-only |
+| 边界清晰的执行 | CLI 按 spec 生成代码 | 按领域选择 | workspace-write |
+| 多模型交叉审查 | 两个 CLI 分别审查 | Codex + Gemini | read-only |
+| 快速分析 | 单 CLI 分析特定问题 | 按问题类型 | read-only |
+
+### 注意事项
+
+1. **workspace-write 模式**：仅当确实需要 CLI 写入 `cli/` 目录时使用，且需确保 CLI 只写入指定目录
+2. **超时控制**：复杂任务建议设置较长超时，避免中途中断
+3. **产出重构**：所有外部 CLI 产出在合入前必须经主控 AI 重构对齐项目规范（代码主权原则）

package/skeleton/.trellis/spec/guides/task-workflow.md

@@ -0,0 +1,34 @@
+---
+title: 任务工作流规范
+version: 1.0.0
+category: guides
+status: active
+---
+
+# 任务工作流规范
+
+## 概述
+
+定义 easyAI 任务从创建到归档的完整工作流程。
+
+## 任务生命周期
+
+```
+pending → in_progress → under_review → completed → archived
+                                    ↘ rejected → in_progress
+             任意非归档状态 → cancelled
+```
+
+## PM 职责
+
+1. 使用 `pm-brainstorm` Skill 澄清需求
+2. 使用 `pm-task-planning` Skill 生成约束集
+3. 调用 `task_create()` 创建任务
+4. 使用 `pm-task-review` Skill 验收任务
+
+## Worker 职责
+
+1. 调用 `task_get()` 读取任务详情
+2. 按约束集逐步执行（TDD 流程）
+3. 使用 `worker-check` Skill 生成验证标记
+4. 调用 `task_transition(under_review)` 提交验收

package/skeleton/.trellis/spec/guides/testing.md

@@ -0,0 +1,32 @@
+---
+title: 测试规范
+version: 1.0.0
+category: guides
+status: active
+---
+
+# 测试规范
+
+## 概述
+
+定义 easyAI 项目的测试标准和流程。
+
+## 测试分层
+
+1. **单元测试**：覆盖核心逻辑和工具函数
+2. **集成测试**：验证 MCP Tool 端到端行为
+3. **验收测试**：通过 verification.md 三标记验证
+
+## TDD 流程
+
+遵循 worker-implement Skill 的 TDD 铁律：
+- 🔴 RED：先写失败测试
+- 🟢 GREEN：最小通过代码
+- 🔵 REFACTOR：重构优化
+
+## 验证标记
+
+每次提交必须包含：
+- LINT_PASS / LINT_NA
+- TEST_PASS / TEST_NA
+- MANUAL_PASS / MANUAL_NA

package/skeleton/.trellis/spec/spec-schema.json

@@ -0,0 +1,64 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://easyai.dev/schemas/spec-schema.json",
+  "title": "easyAI Spec File Schema",
+  "description": "定义 .trellis/spec/ 下规范文件 YAML frontmatter 的格式约束。",
+  "type": "object",
+  "required": ["title", "version", "category"],
+  "properties": {
+    "title": {
+      "type": "string",
+      "description": "规范标题"
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+\\.\\d+$",
+      "description": "规范版本号（SemVer 格式）"
+    },
+    "category": {
+      "type": "string",
+      "enum": ["frontend", "backend", "guides", "general"],
+      "description": "规范分类"
+    },
+    "status": {
+      "type": "string",
+      "enum": ["draft", "active", "deprecated"],
+      "default": "draft",
+      "description": "规范状态"
+    },
+    "lastUpdated": {
+      "type": "string",
+      "format": "date",
+      "description": "最近更新日期"
+    },
+    "owner": {
+      "type": "string",
+      "description": "规范维护者"
+    },
+    "content": {
+      "type": "string",
+      "description": "规范正文（Markdown 格式）"
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "标签列表，用于 context_generate 关键词匹配"
+    },
+    "dependencies": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "规范间依赖关系（引用其他 spec 的路径）"
+    },
+    "minTokenEstimate": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "最小 Token 估算值（辅助上下文预算管理）"
+    },
+    "maxTokenEstimate": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "最大 Token 估算值（辅助上下文预算管理）"
+    }
+  },
+  "additionalProperties": false
+}

package/skeleton/README.md

@@ -0,0 +1,25 @@
+# 我的项目
+
+> 由 [easyAI](https://github.com/GeeSeeker/easyAI-dev) 框架驱动。
+
+## 快速开始
+
+1. 在 Antigravity IDE 中打开此项目
+2. 输入 `/pm` 启动项目经理
+3. 向 PM 描述你的需求，开始开发！
+
+## 项目结构
+
+```
+.
+├── .agents/        ← AI 角色层（规则、工作流、Skills）
+├── .trellis/       ← 数据持久层（配置、规范、任务、日志）
+├── .docs/          ← 用户文档空间
+└── ...             ← 你的项目代码
+```
+
+## 框架升级
+
+```bash
+npx @geeseeker/easyai-dev update .
+```

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2025 GeeSeeker
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/src/cli/index.js

@@ -1,40 +0,0 @@
-import { Command } from "commander";
-import { init } from "../commands/init.js";
-import { update } from "../commands/update.js";
-
-const program = new Command();
-
-program
-  .name("easyai-dev")
-  .description("AI Agent 协作框架 — 为 Antigravity IDE 打造的 AI 团队工作流")
-  .version("3.0.0-alpha.1", "-v, --version", "输出版本号");
-
-program
-  .command("init")
-  .description("在当前项目中初始化 easyAI 框架")
-  .option("-f, --force", "覆盖已存在的文件")
-  .option("-s, --skip-existing", "跳过已存在的文件")
-  .action(async (options) => {
-    try {
-      await init(options);
-    } catch (error) {
-      console.error("Error:", error instanceof Error ? error.message : error);
-      process.exit(1);
-    }
-  });
-
-program
-  .command("update")
-  .description("更新当前项目中的 easyAI 框架文件到最新版本")
-  .option("--dry-run", "预览变更，不实际执行")
-  .option("-f, --force", "强制覆盖所有变更文件")
-  .action(async (options) => {
-    try {
-      await update(options);
-    } catch (error) {
-      console.error("Error:", error instanceof Error ? error.message : error);
-      process.exit(1);
-    }
-  });
-
-program.parse();

package/src/commands/init.js

@@ -1,37 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-
-/**
- * easyai-dev init — 在当前项目中初始化 easyAI 框架
- *
- * 将 templates/ 中的文件复制到用户项目：
- * - templates/agents/ → .agents/
- * - templates/trellis/ → .trellis/
- */
-export async function init(options = {}) {
-  const cwd = process.cwd();
-
-  console.log("\n🚀 easyAI-dev 初始化\n");
-
-  // 检查是否已初始化
-  const agentsDir = path.join(cwd, ".agents");
-  const trellisDir = path.join(cwd, ".trellis");
-
-  if (fs.existsSync(agentsDir) && !options.force) {
-    console.log("⚠️  .agents/ 目录已存在。使用 --force 强制覆盖。");
-    return;
-  }
-
-  // TODO: 实现模板复制逻辑
-  // 1. 定位 templates/ 目录（npm 包内）
-  // 2. 递归复制 templates/agents/ → .agents/
-  // 3. 递归复制 templates/trellis/ → .trellis/
-  // 4. 追加 .gitignore 条目
-
-  console.log("📁 创建 .agents/ ...");
-  console.log("📁 创建 .trellis/ ...");
-  console.log("\n✅ easyAI-dev 初始化完成！");
-  console.log("\n后续步骤：");
-  console.log("  1. 在 Antigravity 中打开项目");
-  console.log("  2. 输入 /项目经理 开始工作\n");
-}

package/src/commands/update.js

@@ -1,33 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-
-/**
- * easyai-dev update — 更新当前项目的 easyAI 框架文件到最新版本
- *
- * 对比 templates/ 与用户项目中 .agents/ 和 .trellis/ 的差异，
- * 仅更新框架文件（不覆盖用户自定义内容）。
- */
-export async function update(options = {}) {
-  const cwd = process.cwd();
-
-  console.log("\n🔄 easyAI-dev 更新检查\n");
-
-  // 检查是否已初始化
-  const agentsDir = path.join(cwd, ".agents");
-  if (!fs.existsSync(agentsDir)) {
-    console.log("❌ 未检测到 .agents/ 目录。请先运行 easyai-dev init");
-    return;
-  }
-
-  // TODO: 实现更新逻辑
-  // 1. 读取用户项目中的 .agents/.version
-  // 2. 对比 templates/ 中的版本
-  // 3. 差异对比，列出变更文件
-  // 4. 按策略更新（force / skip / ask）
-
-  if (options.dryRun) {
-    console.log("📋 预览模式 — 不会实际修改文件\n");
-  }
-
-  console.log("✅ 已是最新版本，无需更新。\n");
-}

package/templates/README.md

@@ -1,22 +0,0 @@
-# easyAI 模板目录
-
-此目录包含 `easyai-dev init` 命令初始化时复制到用户项目的模板文件。
-
-## 结构
-
-```
-templates/
-├── agents/          → 复制为用户项目的 .agents/
-│   ├── rules/       #   Always-On Rule
-│   ├── workflows/   #   角色切换 workflow
-│   ├── skills/      #   全部 skill 链
-│   ├── templates/   #   任务模板
-│   └── scripts/     #   辅助脚本
-└── trellis/         → 复制为用户项目的 .trellis/
-    ├── workflow.md   #   任务生命周期
-    ├── spec/         #   规范知识库（初始结构）
-    ├── workspace/    #   会话记忆
-    └── tasks/        #   任务看板
-```
-
-> **注意**：模板内容将在后续开发任务中逐步填充。

package/templates/agents/README.md

@@ -1,4 +0,0 @@
-# easyAI Agents 模板
-
-> 此目录在 `easyai-dev init` 时会被复制为用户项目的 `.agents/` 目录。
-> 模板内容将在后续开发任务中从 `easyAI-dev/.agents/` 提炼填充。

package/templates/trellis/README.md

@@ -1,4 +0,0 @@
-# easyAI Trellis 模板
-
-> 此目录在 `easyai-dev init` 时会被复制为用户项目的 `.trellis/` 目录。
-> 模板内容将在后续开发任务中从 `easyAI-dev/.trellis/` 提炼填充。