growork 1.1.1 → 1.1.2

package/docs/developer-notes.md

@@ -0,0 +1,67 @@
+# 开发者说
+
+## AI 时代的开发范式
+
+GroWork 是一个 **零手写代码** 的项目。从第一行代码到现在，所有实现都由 AI 完成，人只负责写文档和提示词。
+
+## 核心洞察：后端最贴合 AI
+
+后端开发是目前最适合 AI 全流程接管的领域：
+
+- **输入输出明确** - API 契约清晰，不涉及主观审美
+- **逻辑可验证** - 单元测试可以客观判断对错
+- **文档驱动** - PRD、API 文档天然适合作为 AI 的上下文
+
+相比之下，前端涉及 UI/UX 审美判断，AI 难以完全替代人的决策。
+
+## AI All-in-One 闭环
+
+```
+PRD 文档 → 架构设计 → 测试用例 → 代码实现 → Code Review → 发布
+   ↑                                                      │
+   └──────────────────── 迭代反馈 ←────────────────────────┘
+```
+
+每个环节都由 AI 执行，人只在关键节点做决策。
+
+## 多 Tab 工作流
+
+将 Claude Code 分为多个独立 Tab，各司其职：
+
+| Tab              | 职责                               |
+| ---------------- | ---------------------------------- |
+| **doc**    | 生成/更新文档（PRD、架构、README） |
+| **code**   | 编写实现代码                       |
+| **test**   | 编写和运行测试用例                 |
+| **review** | 代码审查，检查规范和潜在问题       |
+| **git**    | 提交、推送、PR 管理                |
+
+这种分离让每个 Tab 保持专注的上下文，避免单一会话过载。
+
+## 人的角色转变
+
+在这个模式下，开发者的工作变成了：
+
+1. **写文档** - PRD 描述需求，架构文档描述设计
+2. **写提示词** - 精准表达意图，引导 AI 输出
+3. **做决策** - 在多个方案中选择，把控方向
+4. **验收成果** - 确认 AI 的输出符合预期
+
+代码不再是手写的，而是「生成」的。
+
+## 实践心得
+
+1. **文档质量决定代码质量** - 垃圾文档进，垃圾代码出
+2. **小步快跑** - 每次只让 AI 做一件小事，而不是一次性生成大量代码
+3. **测试先行** - 先让 AI 写测试用例，再写实现，AI 更容易做对
+4. **持续 Review** - AI 会犯错，定期审查避免技术债累积
+
+## 展望
+
+这只是开始。随着 AI 能力提升，未来的开发模式会更加极致：
+
+- 需求直接生成可运行的代码
+- 自动修复 bug，自动优化性能
+- 人只需要描述「想要什么」，而不是「怎么做」
+
+GroWork 本身就是这个未来的一个小小实验。

package/docs/prd-1.1.2.md

@@ -0,0 +1,136 @@
+# GroWork 1.1.2 PRD
+
+## 概述
+
+| 项目     | 内容                          |
+| -------- | ----------------------------- |
+| 产品名称 | GroWork                       |
+| 版本     | 1.1.2                         |
+| 状态     | 📝 待开发                      |
+| 产品形态 | CLI                           |
+| 核心改动 | design 字段支持 Figma 链接     |
+
+## 背景与目标
+
+### 背景
+
+当前 design 字段只支持飞书/Notion 文档链接，但设计稿通常在 Figma 中。开发者希望在 design 字段直接配置 Figma 地址，同步时自动生成包含链接的 MD 文件。
+
+### 目标
+
+1. design 字段支持 Figma URL
+2. Figma URL 直接生成 MD 文件（不下载），内容为链接本身
+3. 保持现有配置结构不变
+
+## 功能需求
+
+### 配置文件格式
+
+```yaml
+# growork.config.yaml（结构不变）
+
+versions:
+  v1.9:
+    QuickCard:
+      prd:
+        - "https://xxx.feishu.cn/docx/xxx"   # 飞书：下载内容
+      design:
+        - "https://www.figma.com/design/xxx?node-id=1-20"  # Figma：生成链接
+        - "https://www.figma.com/design/xxx?node-id=1-30"
+      api:
+        - "https://xxx.feishu.cn/docx/yyy"   # 飞书：下载内容
+```
+
+### URL 类型识别
+
+| URL 特征 | 类型 | 处理方式 |
+|---------|------|---------|
+| `feishu.cn` / `larksuite.com` | 飞书 | 调用 API 下载内容 |
+| `notion.so` / `notion.site` | Notion | 调用 API 下载内容 |
+| `figma.com` | Figma | 直接生成链接 MD |
+
+### 输出目录结构
+
+```
+docs/
+└── v1.9/
+    └── QuickCard/
+        ├── prd/
+        │   └── xxx.md              # 飞书文档内容
+        ├── design/
+        │   └── design.md           # Figma 链接列表
+        └── api/
+            └── yyy.md              # 飞书文档内容
+```
+
+### 生成的 design.md 内容
+
+```markdown
+# QuickCard 设计稿
+
+- https://www.figma.com/design/xxx?node-id=1-20
+- https://www.figma.com/design/xxx?node-id=1-30
+```
+
+## 技术设计
+
+### inferDocType 扩展
+
+```typescript
+export function inferDocType(url: string): 'feishu' | 'notion' | 'figma' {
+  if (url.includes('feishu.cn') || url.includes('larksuite.com')) {
+    return 'feishu';
+  }
+  if (url.includes('notion.so') || url.includes('notion.site')) {
+    return 'notion';
+  }
+  if (url.includes('figma.com')) {
+    return 'figma';
+  }
+  throw new Error(`无法从 URL 推断文档类型: ${url}`);
+}
+```
+
+### 同步逻辑调整
+
+```typescript
+// sync.ts
+for (const doc of docs) {
+  if (doc.type === 'figma') {
+    // Figma：直接写入链接，不调用 API
+    // 同一 feature 的多个 Figma URL 合并到一个 design.md
+    continue;
+  }
+  // 飞书/Notion：调用 API 下载内容
+  // ...现有逻辑
+}
+```
+
+### Figma 文档合并
+
+同一 feature 下的多个 Figma URL 合并到一个 `design.md` 文件：
+
+```typescript
+// 按 outputPath 分组 Figma 文档
+const figmaGroups = new Map<string, string[]>();
+for (const doc of figmaDocs) {
+  const dir = path.dirname(doc.outputPath);
+  const urls = figmaGroups.get(dir) || [];
+  urls.push(doc.url);
+  figmaGroups.set(dir, urls);
+}
+
+// 生成合并后的 design.md
+for (const [dir, urls] of figmaGroups) {
+  const content = `# 设计稿\n\n${urls.map(u => `- ${u}`).join('\n')}\n`;
+  writeFile(`${dir}/design.md`, content);
+}
+```
+
+## 验收标准
+
+- [ ] `inferDocType` 支持识别 Figma URL
+- [ ] Figma URL 不调用 API，直接生成 MD
+- [ ] 同一 feature 的多个 Figma URL 合并到一个 `design.md`
+- [ ] 飞书/Notion 文档同步逻辑不受影响
+- [ ] `--ver` 和 `-f` 参数对 Figma 同样有效

package/growork.config.yaml

@@ -39,3 +39,8 @@ versions:
         - "https://romangic.sg.larksuite.com/wiki/EB9NwMUP2ipF0Pk0SZBlXOS5gcb"
       test:
         - "https://www.notion.so/2f91190afab580a8acf1daf80ae02ac6"
+  v1.9:
+    QuickCard:
+      design:
+        - "https://www.figma.com/design/xxx?node-id=1-20"
+        - "https://www.figma.com/design/xxx?node-id=1-30"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "growork",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "description": "将飞书文档同步到本地，为 AI Agent 提供完整上下文",
   "main": "dist/index.js",
   "type": "module",

package/src/commands/sync.ts

@@ -28,12 +28,16 @@ export async function syncCommand(options: SyncOptions = {}): Promise<void> {
     return;
   }
 
+  // 分组：普通文档 vs Figma 文档
+  const normalDocs = docs.filter(d => d.type !== 'figma');
+  const figmaDocs = docs.filter(d => d.type === 'figma');
+
   const feishuService = config.feishu ? new FeishuService(config.feishu) : null;
   const notionService = config.notion ? new NotionService(config.notion) : null;
 
-  // 检查凭证
-  const hasFeishuDocs = docs.some(d => d.type === 'feishu');
-  const hasNotionDocs = docs.some(d => d.type === 'notion');
+  // 检查凭证（只针对普通文档）
+  const hasFeishuDocs = normalDocs.some(d => d.type === 'feishu');
+  const hasNotionDocs = normalDocs.some(d => d.type === 'notion');
 
   if (hasFeishuDocs && !feishuService) {
     throw new Error('配置文件缺少飞书凭证 (feishu.appId, feishu.appSecret)');
@@ -46,7 +50,19 @@ export async function syncCommand(options: SyncOptions = {}): Promise<void> {
 
   let successCount = 0;
 
-  for (const doc of docs) {
+  // Figma 文档按目录分组
+  const figmaGroups = new Map<string, { feature: string; urls: string[] }>();
+  for (const doc of figmaDocs) {
+    const dir = path.dirname(doc.outputPath);
+    const feature = path.basename(path.dirname(dir));
+    if (!figmaGroups.has(dir)) {
+      figmaGroups.set(dir, { feature, urls: [] });
+    }
+    figmaGroups.get(dir)!.urls.push(doc.url);
+  }
+
+  // 处理普通文档（feishu/notion）
+  for (const doc of normalDocs) {
     const displayName = doc.name || doc.url.slice(-20);
     process.stdout.write(chalk.gray(`  ⏳ ${displayName}`));
 
@@ -82,10 +98,23 @@ export async function syncCommand(options: SyncOptions = {}): Promise<void> {
     }
   }
 
+  // 处理 Figma 文档：生成 design.md
+  for (const [dir, { feature, urls }] of figmaGroups) {
+    const content = `# ${feature} 设计稿\n\n${urls.map(u => `- ${u}`).join('\n')}\n`;
+    const outputPath = path.join(process.cwd(), dir, 'design.md');
+
+    fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+    fs.writeFileSync(outputPath, content, 'utf-8');
+
+    console.log(chalk.green(`  ✓ design.md → ${path.relative(process.cwd(), outputPath)}`));
+    successCount++;
+  }
+
   console.log('');
-  if (successCount === docs.length) {
-    console.log(chalk.green(`✅ 同步完成，共 ${docs.length} 个文档`));
+  const totalCount = normalDocs.length + figmaGroups.size;
+  if (successCount === totalCount) {
+    console.log(chalk.green(`✅ 同步完成，共 ${totalCount} 个文档`));
   } else {
-    console.log(chalk.yellow(`⚠️  同步完成: ${successCount}/${docs.length} 个文档成功`));
+    console.log(chalk.yellow(`⚠️  同步完成: ${successCount}/${totalCount} 个文档成功`));
   }
 }

package/src/utils/config.ts

@@ -35,7 +35,7 @@ export interface GroworkConfigV2 {
 export interface NormalizedDoc {
   url: string;
   name?: string;
-  type: 'feishu' | 'notion';
+  type: 'feishu' | 'notion' | 'figma';
   outputPath: string;  // 含 {title} 占位符
 }
 
@@ -55,13 +55,16 @@ export function configExists(): boolean {
   return fs.existsSync(getConfigPath());
 }
 
-export function inferDocType(url: string): 'feishu' | 'notion' {
+export function inferDocType(url: string): 'feishu' | 'notion' | 'figma' {
   if (url.includes('feishu.cn') || url.includes('larksuite.com')) {
     return 'feishu';
   }
   if (url.includes('notion.so') || url.includes('notion.site')) {
     return 'notion';
   }
+  if (url.includes('figma.com')) {
+    return 'figma';
+  }
   throw new Error(`无法从 URL 推断文档类型: ${url}`);
 }
 

package/tests/config.test.ts

@@ -58,7 +58,7 @@ interface GroworkConfigV2 {
 interface NormalizedDoc {
   url: string;
   name?: string;
-  type: 'feishu' | 'notion';
+  type: 'feishu' | 'notion' | 'figma';
   outputPath: string;
 }
 
@@ -68,13 +68,16 @@ interface SyncOptions {
   custom?: boolean;
 }
 
-function inferDocType(url: string): 'feishu' | 'notion' {
+function inferDocType(url: string): 'feishu' | 'notion' | 'figma' {
   if (url.includes('feishu.cn') || url.includes('larksuite.com')) {
     return 'feishu';
   }
   if (url.includes('notion.so') || url.includes('notion.site')) {
     return 'notion';
   }
+  if (url.includes('figma.com')) {
+    return 'figma';
+  }
   throw new Error(`无法从 URL 推断文档类型: ${url}`);
 }
 
@@ -326,6 +329,14 @@ describe('文档类型推断', () => {
     assert.strictEqual(inferDocType('https://myworkspace.notion.site/abc123'), 'notion');
   });
 
+  it('应识别 Figma URL', () => {
+    assert.strictEqual(inferDocType('https://www.figma.com/design/abc123'), 'figma');
+  });
+
+  it('应识别 Figma 文件 URL', () => {
+    assert.strictEqual(inferDocType('https://figma.com/file/abc123/My-Design'), 'figma');
+  });
+
   it('应拒绝未知域名', () => {
     assert.throws(
       () => inferDocType('https://example.com/doc/123'),

package/tests/feishu.test.ts

@@ -239,6 +239,16 @@ describe('Block 转 Markdown', () => {
         return `## ${textElementsToMarkdown(block.heading2?.elements)}\n`;
       case 5: // Heading3
         return `### ${textElementsToMarkdown(block.heading3?.elements)}\n`;
+      case 6: // Heading4
+        return `#### ${textElementsToMarkdown(block.heading4?.elements)}\n`;
+      case 7: // Heading5
+        return `##### ${textElementsToMarkdown(block.heading5?.elements)}\n`;
+      case 8: // Heading6
+        return `###### ${textElementsToMarkdown(block.heading6?.elements)}\n`;
+      case 9: // Heading7
+      case 10: // Heading8
+      case 11: // Heading9
+        return `###### ${textElementsToMarkdown(block[`heading${blockType - 6}`]?.elements)}\n`;
       case 12: // Bullet
         return `- ${textElementsToMarkdown(block.bullet?.elements)}`;
       case 13: // Ordered
@@ -254,6 +264,12 @@ describe('Block 转 Markdown', () => {
         return `- [${checked}] ${textElementsToMarkdown(block.todo?.elements)}`;
       case 18: // Divider
         return '---\n';
+      case 19: // Image
+        const imageToken = block.image?.token;
+        return imageToken ? `![image](${imageToken})\n` : '';
+      case 30: // Sheet
+        const sheetToken = block.sheet?.token;
+        return sheetToken ? `[嵌入表格: ${sheetToken}]\n` : '';
       default:
         return null;
     }
@@ -342,4 +358,175 @@ describe('Block 转 Markdown', () => {
   it('应转换分割线', () => {
     assert.strictEqual(blockToMarkdown({ block_type: 18 }), '---\n');
   });
+
+  it('应转换 Heading4', () => {
+    assert.strictEqual(
+      blockToMarkdown({ block_type: 6, heading4: { elements: [{ text_run: { content: 'H4' } }] } }),
+      '#### H4\n'
+    );
+  });
+
+  it('应转换 Heading5', () => {
+    assert.strictEqual(
+      blockToMarkdown({ block_type: 7, heading5: { elements: [{ text_run: { content: 'H5' } }] } }),
+      '##### H5\n'
+    );
+  });
+
+  it('应转换 Heading6', () => {
+    assert.strictEqual(
+      blockToMarkdown({ block_type: 8, heading6: { elements: [{ text_run: { content: 'H6' } }] } }),
+      '###### H6\n'
+    );
+  });
+
+  it('应转换 Heading7-9 为 H6', () => {
+    // Heading7-9 都映射为 ###### (H6)
+    assert.strictEqual(
+      blockToMarkdown({ block_type: 9, heading3: { elements: [{ text_run: { content: 'H7' } }] } }),
+      '###### H7\n'
+    );
+    assert.strictEqual(
+      blockToMarkdown({ block_type: 10, heading4: { elements: [{ text_run: { content: 'H8' } }] } }),
+      '###### H8\n'
+    );
+    assert.strictEqual(
+      blockToMarkdown({ block_type: 11, heading5: { elements: [{ text_run: { content: 'H9' } }] } }),
+      '###### H9\n'
+    );
+  });
+
+  it('应转换图片块', () => {
+    const block = {
+      block_type: 19,
+      image: { token: 'img_token_123' }
+    };
+    assert.strictEqual(blockToMarkdown(block), '![image](img_token_123)\n');
+  });
+
+  it('应处理无 token 的图片块', () => {
+    const block = { block_type: 19, image: {} };
+    assert.strictEqual(blockToMarkdown(block), '');
+  });
+
+  it('应转换嵌入表格', () => {
+    const block = {
+      block_type: 30,
+      sheet: { token: 'sheet_token_456' }
+    };
+    assert.strictEqual(blockToMarkdown(block), '[嵌入表格: sheet_token_456]\n');
+  });
+
+  it('应处理无 token 的嵌入表格', () => {
+    const block = { block_type: 30, sheet: {} };
+    assert.strictEqual(blockToMarkdown(block), '');
+  });
+
+  it('应对未知块类型返回 null', () => {
+    assert.strictEqual(blockToMarkdown({ block_type: 999 }), null);
+  });
+});
+
+describe('表格转 Markdown', () => {
+  function getCellContent(cellBlock: any, blockMap: Map<string, any>): string {
+    if (!cellBlock) return '';
+    const children = cellBlock.children || [];
+    const contents: string[] = [];
+    for (const childId of children) {
+      const child = blockMap.get(childId);
+      if (!child) continue;
+      if (child.block_type === 2) {
+        contents.push(textElementsToMarkdown(child.text?.elements));
+      }
+    }
+    return contents.join(' ').replace(/\|/g, '\\|').replace(/\n/g, ' ');
+  }
+
+  function tableToMarkdown(tableBlock: any, blockMap: Map<string, any>): string {
+    const table = tableBlock.table;
+    if (!table) return '';
+    const colSize = table.property?.column_size || 0;
+    const rowSize = table.property?.row_size || 0;
+    const cellIds = table.cells || [];
+    if (colSize === 0 || rowSize === 0) return '';
+
+    const rows: string[][] = [];
+    for (let row = 0; row < rowSize; row++) {
+      const rowCells: string[] = [];
+      for (let col = 0; col < colSize; col++) {
+        const cellIndex = row * colSize + col;
+        const cellId = cellIds[cellIndex];
+        const cellBlock = blockMap.get(cellId);
+        const cellContent = getCellContent(cellBlock, blockMap);
+        rowCells.push(cellContent);
+      }
+      rows.push(rowCells);
+    }
+
+    const lines: string[] = [];
+    if (rows.length > 0) {
+      lines.push('| ' + rows[0].join(' | ') + ' |');
+      lines.push('| ' + rows[0].map(() => '---').join(' | ') + ' |');
+    }
+    for (let i = 1; i < rows.length; i++) {
+      lines.push('| ' + rows[i].join(' | ') + ' |');
+    }
+    return lines.join('\n') + '\n';
+  }
+
+  it('应转换简单表格', () => {
+    const blockMap = new Map<string, any>();
+    // 创建单元格内容块
+    blockMap.set('text1', { block_type: 2, text: { elements: [{ text_run: { content: 'Header1' } }] } });
+    blockMap.set('text2', { block_type: 2, text: { elements: [{ text_run: { content: 'Header2' } }] } });
+    blockMap.set('text3', { block_type: 2, text: { elements: [{ text_run: { content: 'Cell1' } }] } });
+    blockMap.set('text4', { block_type: 2, text: { elements: [{ text_run: { content: 'Cell2' } }] } });
+    // 创建单元格
+    blockMap.set('cell1', { children: ['text1'] });
+    blockMap.set('cell2', { children: ['text2'] });
+    blockMap.set('cell3', { children: ['text3'] });
+    blockMap.set('cell4', { children: ['text4'] });
+
+    const tableBlock = {
+      block_type: 31,
+      table: {
+        property: { column_size: 2, row_size: 2 },
+        cells: ['cell1', 'cell2', 'cell3', 'cell4']
+      }
+    };
+
+    const result = tableToMarkdown(tableBlock, blockMap);
+    assert.strictEqual(result, '| Header1 | Header2 |\n| --- | --- |\n| Cell1 | Cell2 |\n');
+  });
+
+  it('应处理空表格', () => {
+    const blockMap = new Map<string, any>();
+    const tableBlock = {
+      block_type: 31,
+      table: { property: { column_size: 0, row_size: 0 }, cells: [] }
+    };
+    assert.strictEqual(tableToMarkdown(tableBlock, blockMap), '');
+  });
+
+  it('应处理无 table 属性的块', () => {
+    const blockMap = new Map<string, any>();
+    assert.strictEqual(tableToMarkdown({ block_type: 31 }, blockMap), '');
+  });
+
+  it('应转义单元格中的管道符', () => {
+    const blockMap = new Map<string, any>();
+    blockMap.set('text1', { block_type: 2, text: { elements: [{ text_run: { content: 'A|B' } }] } });
+    blockMap.set('cell1', { children: ['text1'] });
+
+    const tableBlock = {
+      block_type: 31,
+      table: {
+        property: { column_size: 1, row_size: 1 },
+        cells: ['cell1']
+      }
+    };
+
+    const result = tableToMarkdown(tableBlock, blockMap);
+    assert.ok(result.includes('A\\|B'));
+  });
 });

package/tests/notion.test.ts

@@ -102,6 +102,87 @@ describe('Notion URL 解析', () => {
   });
 });
 
+describe('Notion 页面标题提取', () => {
+  function getPageTitle(page: any): string {
+    const properties = page.properties;
+    if (!properties) return '未命名';
+
+    for (const key of Object.keys(properties)) {
+      const prop = properties[key];
+      if (prop.type === 'title' && prop.title?.length > 0) {
+        return prop.title.map((t: any) => t.plain_text).join('');
+      }
+    }
+
+    return '未命名';
+  }
+
+  it('应提取标准 title 属性', () => {
+    const page = {
+      properties: {
+        Name: {
+          type: 'title',
+          title: [{ plain_text: 'My Page Title' }]
+        }
+      }
+    };
+    assert.strictEqual(getPageTitle(page), 'My Page Title');
+  });
+
+  it('应合并多个 title 片段', () => {
+    const page = {
+      properties: {
+        Title: {
+          type: 'title',
+          title: [{ plain_text: 'Hello ' }, { plain_text: 'World' }]
+        }
+      }
+    };
+    assert.strictEqual(getPageTitle(page), 'Hello World');
+  });
+
+  it('应处理空 properties', () => {
+    const page = { properties: {} };
+    assert.strictEqual(getPageTitle(page), '未命名');
+  });
+
+  it('应处理无 properties 的页面', () => {
+    const page = {};
+    assert.strictEqual(getPageTitle(page), '未命名');
+  });
+
+  it('应处理空 title 数组', () => {
+    const page = {
+      properties: {
+        Name: { type: 'title', title: [] }
+      }
+    };
+    assert.strictEqual(getPageTitle(page), '未命名');
+  });
+
+  it('应跳过非 title 类型属性', () => {
+    const page = {
+      properties: {
+        Status: { type: 'select', select: { name: 'Done' } },
+        Name: { type: 'title', title: [{ plain_text: 'Actual Title' }] }
+      }
+    };
+    assert.strictEqual(getPageTitle(page), 'Actual Title');
+  });
+
+  it('应处理自定义属性名的 title', () => {
+    const page = {
+      properties: {
+        '页面标题': {
+          type: 'title',
+          title: [{ plain_text: '中文标题' }]
+        }
+      }
+    };
+    assert.strictEqual(getPageTitle(page), '中文标题');
+  });
+});
+
 describe('Notion 属性值提取', () => {
   describe('title 属性', () => {
     it('应提取 title 文本', () => {