growork 1.1.1 → 1.1.2

package/.claude/settings.local.json

@@ -12,7 +12,8 @@
       "WebSearch",
       "NotebookEdit",
       "mcp__*",
-      "mcp__dart__*"
+      "mcp__dart__*",
+      "mcp__figma__*"
     ]
   },
   "enableAllProjectMcpServers": true,

package/README.md

@@ -4,58 +4,40 @@
 
 这样 AI 工具（如 Claude、Cursor、Windsurf）就能直接读取你的产品文档，帮你写代码。
 
----
+[![npm](https://img.shields.io/npm/v/growork)](https://www.npmjs.com/package/growork)
 
-## 这个工具能做什么？
+## 功能
 
-✅ 自动下载飞书文档，转成 Markdown 格式
-✅ 自动下载 Notion 页面，转成 Markdown 格式
-✅ 按**版本 → 功能 → 文档类型**组织文档，AI 更容易理解
-✅ 一条命令同步所有文档
-✅ 文档更新后，重新运行命令即可获取最新内容
+- 自动下载飞书文档，转成 Markdown 格式
+- 自动下载 Notion 页面，转成 Markdown 格式
+- 支持 Figma 设计稿链接，自动生成链接文档
+- 按**版本 → 功能 → 文档类型**组织文档，AI 更容易理解
+- 一条命令同步所有文档
 
----
+> ⚠️ **每个版本都是破坏性更新**，不保证向后兼容。升级前请查看更新日志，必要时重新初始化配置文件。
 
-## 版本说明
+## 安装
 
-⚠️ **每个版本都是破坏性更新**，不保证向后兼容。升级前请查看更新日志，必要时重新初始化配置文件。
+### 1. 安装 Node.js
 
----
-
-## 安装步骤
-
-### 第一步：安装 Node.js
-
-GroWork 需要 Node.js 才能运行。如果你还没安装：
+GroWork 需要 Node.js >= 18。如果你还没安装：
 
 1. 打开 https://nodejs.org/
 2. 点击绿色的 **"LTS"** 按钮下载
 3. 双击下载的文件，按提示完成安装
 
-**检查是否安装成功：**
-
-打开「终端」（Mac）或「命令提示符」（Windows），输入：
+检查是否安装成功：
 
 ```bash
 node -v
 ```
 
-如果显示类似 `v18.17.0` 的版本号，说明安装成功。
-
----
-
-### 第二步：安装 GroWork
-
-在终端中输入：
+### 2. 安装 GroWork
 
 ```bash
 npm install -g growork
 ```
 
-等待安装完成即可。
-
----
-
 ## 使用方法
 
 ### 1. 初始化项目
@@ -68,14 +50,10 @@ growork init
 
 这会在当前目录创建一个 `growork.config.yaml` 配置文件。
 
----
-
 ### 2. 获取飞书凭证（如果你要同步飞书文档）
 
 你需要在飞书开放平台创建一个应用，获取「App ID」和「App Secret」。
 
-**详细步骤：**
-
 1. **打开飞书开放平台**
    - 国际版 Lark：https://open.larksuite.com/
    - 国内版飞书：https://open.feishu.cn/
@@ -83,41 +61,26 @@ growork init
 2. **创建应用**
    - 点击「创建企业自建应用」
    - 填写应用名称（随便起，比如「文档同步」）
-   - 点击「创建」
 
 3. **获取凭证**
    - 在应用详情页，找到「凭证与基础信息」
-   - 复制 **App ID**（以 `cli_` 开头）
-   - 复制 **App Secret**
+   - 复制 **App ID**（以 `cli_` 开头）和 **App Secret**
 
 4. **开通权限**
    - 点击左侧「权限管理」
-   - 搜索并开通以下权限：
-     - `docx:document:readonly`（读取文档）
-     - `wiki:wiki:readonly`（读取知识库）
-   - 点击「批量开通」
+   - 搜索并开通：`docx:document:readonly`、`wiki:wiki:readonly`
 
 5. **发布应用**
-   - 点击「版本管理与发布」
-   - 点击「创建版本」，填写版本号（如 1.0.0）
-   - 提交审核（企业内部应用一般自动通过）
-
----
+   - 点击「版本管理与发布」→「创建版本」→ 提交审核
 
 ### 3. 获取 Notion 凭证（如果你要同步 Notion 页面）
 
-**详细步骤：**
-
 1. **创建 Integration**
    - 打开 https://www.notion.so/my-integrations
-   - 点击「New integration」
-   - 填写名称（随便起，比如「文档同步」）
-   - 选择你的 Workspace
-   - 点击「Submit」
+   - 点击「New integration」，填写名称，选择 Workspace
 
 2. **复制 Token**
-   - 在 Integration 详情页，点击「Show」查看 Token
-   - 复制这个 Token（以 `ntn_` 或 `secret_` 开头）
+   - 在 Integration 详情页，复制 Token（以 `ntn_` 或 `secret_` 开头）
 
 3. **给页面授权**（重要！）
    - 打开你要同步的 Notion 页面
@@ -125,8 +88,6 @@ growork init
    - 选择你刚创建的 Integration
    - **每个要同步的页面都需要做这一步！**
 
----
-
 ### 4. 编辑配置文件
 
 用任意文本编辑器打开 `growork.config.yaml`，填入你的凭证和文档链接：
@@ -157,8 +118,9 @@ versions:
     用户登录:                    # 功能名称
       prd:                       # PRD 文档
         - "https://xxx.feishu.cn/docx/xxxxx"
-      design:                    # 设计文档
-        - "https://xxx.feishu.cn/docx/yyyyy"
+      design:                    # 设计文档（支持 Figma 链接）
+        - "https://www.figma.com/design/xxx?node-id=1-20"
+        - "https://www.figma.com/design/xxx?node-id=1-30"
       api:                       # 接口文档
         - "https://xxx.feishu.cn/docx/zzzzz"
       test:                      # 测试用例
@@ -171,26 +133,23 @@ versions:
 
 **配置说明：**
 
-| 区域 | 说明 |
-| --- | --- |
-| `custom` | 全局文档，不属于任何版本（如技术架构、编码规范） |
-| `versions` | 按版本和功能组织的文档 |
-| `prd` | 产品需求文档 |
-| `design` | 设计稿/交互文档 |
-| `api` | 接口/技术方案 |
-| `test` | 测试用例 |
+| 区域       | 说明                                             |
+| ---------- | ------------------------------------------------ |
+| `custom`   | 全局文档，不属于任何版本（如技术架构、编码规范） |
+| `versions` | 按版本和功能组织的文档                           |
+| `prd`      | 产品需求文档                                     |
+| `design`   | 设计稿（支持 Figma 链接，自动生成链接文档）      |
+| `api`      | 接口/技术方案                                    |
+| `test`     | 测试用例                                         |
 
 **如何获取文档链接？**
 
 - **飞书**：打开文档，直接复制浏览器地址栏的链接
 - **Notion**：打开页面，点击右上角「Share」→「Copy link」
-
----
+- **Figma**：打开设计稿，复制浏览器地址栏的链接（可带 `node-id` 参数定位到具体页面）
 
 ### 5. 同步文档
 
-运行以下命令，自动下载所有文档：
-
 ```bash
 growork sync
 ```
@@ -207,7 +166,7 @@ docs/
     │   ├── prd/
     │   │   └── 用户登录PRD.md
     │   ├── design/
-    │   │   └── 登录页设计.md
+    │   │   └── design.md      # Figma 链接自动合并到此文件
     │   └── api/
     │       └── 登录接口文档.md
     └── 小优化/
@@ -222,17 +181,28 @@ growork sync --ver v1.0       # 只同步 v1.0 版本
 growork sync -f 用户登录       # 只同步「用户登录」功能
 ```
 
-**查看所有已配置的文档：**
+## 命令速查
 
-```bash
-growork list
-```
+| 命令                        | 说明           |
+| --------------------------- | -------------- |
+| `growork init`              | 创建配置文件   |
+| `growork sync`              | 同步所有文档   |
+| `growork sync -c`           | 只同步全局文档 |
+| `growork sync --ver v1.0`   | 只同步指定版本 |
+| `growork sync -f 功能名`    | 只同步指定功能 |
+| `growork list`              | 查看文档列表   |
 
----
+## 支持的文档类型
+
+| 平台   | 支持的内容                                     | 处理方式             |
+| ------ | ---------------------------------------------- | -------------------- |
+| 飞书   | 普通文档 (`/docx/`)、知识库 (`/wiki/`)         | 调用 API 下载内容    |
+| Notion | 任意页面（包含数据库的页面会自动转为表格）     | 调用 API 下载内容    |
+| Figma  | 设计稿链接 (`figma.com/design/...`)            | 直接生成链接文档     |
 
 ## 常见问题
 
-### Q: 提示「权限不足」或「401」错误
+### 提示「权限不足」或「401」错误
 
 **飞书文档：**
 - 确认应用已开通 `docx:document:readonly` 和 `wiki:wiki:readonly` 权限
@@ -240,13 +210,9 @@ growork list
 - 确认你有权限访问该文档
 
 **Notion 页面：**
-- 确认你已经把 Integration 连接到了该页面（见上面第 3 步的「给页面授权」）
-
----
+- 确认你已经把 Integration 连接到了该页面
 
-### Q: 提示「找不到命令」或「command not found」
-
-Node.js 可能没有正确安装，或者 npm 全局路径没有加入系统 PATH。
+### 提示「找不到命令」或「command not found」
 
 尝试重新安装 Node.js，或者使用 `npx` 运行：
 
@@ -254,61 +220,27 @@ Node.js 可能没有正确安装，或者 npm 全局路径没有加入系统 PAT
 npx growork sync
 ```
 
----
-
-### Q: 同步后文档是空的
+### 同步后文档是空的
 
 - 检查文档链接是否正确
 - 检查你是否有权限访问该文档
 - 飞书知识库文档需要使用 `/wiki/` 格式的链接
 
----
-
-### Q: 如何更新已同步的文档？
+### 如何更新已同步的文档？
 
 直接再次运行 `growork sync`，会自动覆盖本地文件。
 
----
-
-### Q: 文件名是怎么生成的？
+### 文件名是怎么生成的？
 
 文件名会自动从文档标题获取，并处理特殊字符：
+
 - `用户登录 / 注册流程 (v1.0)` → `用户登录-注册流程-v1.0.md`
 
 你也可以在配置中用 `name` 字段自定义名称。
 
----
-
-## 命令速查
-
-| 命令 | 说明 |
-| --- | --- |
-| `growork init` | 创建配置文件 |
-| `growork sync` | 同步所有文档 |
-| `growork sync -c` | 只同步全局文档 |
-| `growork sync --ver v1.0` | 只同步指定版本 |
-| `growork sync -f 功能名` | 只同步指定功能 |
-| `growork list` | 查看文档列表 |
-
----
-
-## 支持的文档类型
-
-| 平台 | 支持的内容 |
-| --- | --- |
-| 飞书 | 普通文档 (`/docx/`)、知识库 (`/wiki/`) |
-| Notion | 任意页面（包含数据库的页面会自动转为表格） |
-
----
-
 ## 需要帮助？
 
-如果遇到问题，可以：
-
-1. 在 GitHub 上提 Issue：https://github.com/anthropics/growork/issues
-2. 检查上面的「常见问题」部分
-
----
+- [GitHub Issues](https://github.com/ThinkerJack/GroWork/issues)
 
 ## License
 

package/claude.md

@@ -41,11 +41,16 @@ feishu:
 notion:
   token: "ntn_xxx"
 
-docs:
-  - name: prd          # 唯一标识
-    type: feishu       # feishu | notion | notion-database
-    url: "https://..."
-    output: "docs/prd.md"
+outputDir: "docs"  # 输出根目录
+
+custom:  # 全局文档
+  - "https://xxx.feishu.cn/docx/xxxxx"
+
+versions:  # 版本化文档
+  v1.0:
+    用户登录:
+      prd:
+        - "https://xxx.feishu.cn/docx/xxxxx"
 ```
 
 ## 常用命令
@@ -59,11 +64,36 @@ node dist/index.js sync [name]  # 同步文档
 ## 关键类型
 
 ```typescript
-interface DocConfig {
-  name: string;
-  type: 'feishu' | 'notion' | 'notion-database';
+// 文档输入格式
+type DocInput = string | { url: string; name?: string };
+
+// 功能下的文档分类
+type FeatureValue = DocInput[] | {
+  prd?: DocInput[];
+  design?: DocInput[];
+  api?: DocInput[];
+  test?: DocInput[];
+};
+
+// 配置文件结构
+interface GroworkConfigV2 {
+  feishu?: FeishuConfig;
+  notion?: NotionConfig;
+  outputDir?: string;
+  custom?: DocInput[];
+  versions?: {
+    [version: string]: {
+      [feature: string]: FeatureValue;
+    };
+  };
+}
+
+// 标准化后的文档
+interface NormalizedDoc {
   url: string;
-  output: string;
+  name?: string;
+  type: 'feishu' | 'notion';
+  outputPath: string;  // 含 {title} 占位符
 }
 ```
 
@@ -194,7 +224,7 @@ src/
 
 ### 命名
 
-- 文件名：小写 + 连字符，如 `feishu-sync.ts`
+- 文件名：小写，如 `feishu.ts`, `config.ts`
 - 函数名：动词开头，如 `syncDoc`, `parseConfig`
 - 布尔变量：is/has/should 开头，如 `isValid`
 

package/dist/index.js

@@ -26,6 +26,9 @@ function inferDocType(url) {
   if (url.includes("notion.so") || url.includes("notion.site")) {
     return "notion";
   }
+  if (url.includes("figma.com")) {
+    return "figma";
+  }
   throw new Error(`\u65E0\u6CD5\u4ECE URL \u63A8\u65AD\u6587\u6863\u7C7B\u578B: ${url}`);
 }
 function sanitizeFileName(title) {
@@ -677,10 +680,12 @@ async function syncCommand(options = {}) {
     console.log(chalk2.yellow("\u26A0\uFE0F  \u6CA1\u6709\u627E\u5230\u5339\u914D\u7684\u6587\u6863"));
     return;
   }
+  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("\u914D\u7F6E\u6587\u4EF6\u7F3A\u5C11\u98DE\u4E66\u51ED\u8BC1 (feishu.appId, feishu.appSecret)");
   }
@@ -689,7 +694,16 @@ async function syncCommand(options = {}) {
   }
   console.log(chalk2.blue("\u{1F4C4} \u5F00\u59CB\u540C\u6B65\u6587\u6863...\n"));
   let successCount = 0;
-  for (const doc of docs) {
+  const figmaGroups = /* @__PURE__ */ new Map();
+  for (const doc of figmaDocs) {
+    const dir = path3.dirname(doc.outputPath);
+    const feature = path3.basename(path3.dirname(dir));
+    if (!figmaGroups.has(dir)) {
+      figmaGroups.set(dir, { feature, urls: [] });
+    }
+    figmaGroups.get(dir).urls.push(doc.url);
+  }
+  for (const doc of normalDocs) {
     const displayName = doc.name || doc.url.slice(-20);
     process.stdout.write(chalk2.gray(`  \u23F3 ${displayName}`));
     try {
@@ -716,11 +730,23 @@ async function syncCommand(options = {}) {
       console.log(chalk2.red(`  \u2717 ${displayName.padEnd(25)} \u2192 ${errorMessage}`));
     }
   }
+  for (const [dir, { feature, urls }] of figmaGroups) {
+    const content = `# ${feature} \u8BBE\u8BA1\u7A3F
+
+${urls.map((u) => `- ${u}`).join("\n")}
+`;
+    const outputPath = path3.join(process.cwd(), dir, "design.md");
+    fs3.mkdirSync(path3.dirname(outputPath), { recursive: true });
+    fs3.writeFileSync(outputPath, content, "utf-8");
+    console.log(chalk2.green(`  \u2713 design.md \u2192 ${path3.relative(process.cwd(), outputPath)}`));
+    successCount++;
+  }
   console.log("");
-  if (successCount === docs.length) {
-    console.log(chalk2.green(`\u2705 \u540C\u6B65\u5B8C\u6210\uFF0C\u5171 ${docs.length} \u4E2A\u6587\u6863`));
+  const totalCount = normalDocs.length + figmaGroups.size;
+  if (successCount === totalCount) {
+    console.log(chalk2.green(`\u2705 \u540C\u6B65\u5B8C\u6210\uFF0C\u5171 ${totalCount} \u4E2A\u6587\u6863`));
   } else {
-    console.log(chalk2.yellow(`\u26A0\uFE0F  \u540C\u6B65\u5B8C\u6210: ${successCount}/${docs.length} \u4E2A\u6587\u6863\u6210\u529F`));
+    console.log(chalk2.yellow(`\u26A0\uFE0F  \u540C\u6B65\u5B8C\u6210: ${successCount}/${totalCount} \u4E2A\u6587\u6863\u6210\u529F`));
   }
 }
 

package/docs/architecture.md

@@ -0,0 +1,175 @@
+# GroWork 技术架构
+
+## 概述
+
+GroWork 是一个文档同步 CLI 工具，将飞书文档、Notion 页面和 Figma 设计稿同步到本地 Markdown 文件。
+
+## 项目结构
+
+```
+src/
+├── index.ts           # CLI 入口
+├── commands/
+│   ├── init.ts        # growork init
+│   ├── sync.ts        # growork sync
+│   └── list.ts        # growork list
+├── services/
+│   ├── feishu.ts      # 飞书 API 服务
+│   └── notion.ts      # Notion API 服务
+└── utils/
+    └── config.ts      # 配置解析
+```
+
+## 核心模块
+
+### 1. CLI 入口 (`src/index.ts`)
+
+使用 `commander` 定义命令：
+
+- `growork init` - 初始化配置文件
+- `growork sync` - 同步文档，支持 `--ver`、`-f`、`-c` 过滤
+- `growork list` - 列出所有文档
+
+### 2. 配置模块 (`src/utils/config.ts`)
+
+**核心类型：**
+
+```typescript
+// 文档输入格式
+type DocInput = string | { url: string; name?: string };
+
+// 标准化后的文档
+interface NormalizedDoc {
+  url: string;
+  name?: string;
+  type: 'feishu' | 'notion' | 'figma';
+  outputPath: string;  // 含 {title} 占位符
+}
+```
+
+**核心函数：**
+
+| 函数 | 作用 |
+|-----|------|
+| `loadConfigV2()` | 加载并解析 YAML 配置文件 |
+| `normalizeConfig()` | 将配置转为标准化的 `NormalizedDoc[]` |
+| `inferDocType()` | 根据 URL 推断文档类型 |
+| `sanitizeFileName()` | 处理文件名特殊字符 |
+
+### 3. 同步命令 (`src/commands/sync.ts`)
+
+**处理流程：**
+
+```
+loadConfigV2() → normalizeConfig() → 分组处理
+                                        ├── 飞书文档 → FeishuService.getDocumentAsMarkdown()
+                                        ├── Notion 页面 → NotionService.getPageAsMarkdown()
+                                        └── Figma 链接 → 直接生成 design.md
+```
+
+**Figma 处理逻辑：**
+
+同一 feature 下的多个 Figma URL 会合并到一个 `design.md` 文件：
+
+```typescript
+// 按目录分组
+const figmaGroups = new Map<string, { feature: string; urls: string[] }>();
+
+// 生成内容
+const content = `# ${feature} 设计稿\n\n${urls.map(u => `- ${u}`).join('\n')}\n`;
+```
+
+### 4. 飞书服务 (`src/services/feishu.ts`)
+
+**职责：** 调用飞书 API 获取文档内容，转换为 Markdown。
+
+**核心方法：**
+
+| 方法 | 作用 |
+|-----|------|
+| `getDocumentAsMarkdown(url)` | 主入口，返回完整 Markdown |
+| `parseDocumentId(url)` | 解析 URL 中的文档 ID |
+| `resolveDocumentId(url)` | Wiki 链接需要额外解析真实 ID |
+| `getAllBlocks(docId)` | 分页获取所有 block |
+| `blockToMarkdown(block)` | 将单个 block 转为 Markdown |
+
+**支持的 block 类型：**
+
+| blockType | 类型 | 输出 |
+|-----------|------|------|
+| 2 | Text | 普通文本 |
+| 3-11 | Heading1-9 | `#` ~ `######` |
+| 12 | Bullet | `- item` |
+| 13 | Ordered | `1. item` |
+| 14 | Code | ` ```lang ``` ` |
+| 15 | Quote | `> text` |
+| 17 | TodoList | `- [ ] task` |
+| 18 | Divider | `---` |
+| 19 | Image | `![image](token)` |
+| 31 | Table | Markdown 表格 |
+
+### 5. Notion 服务 (`src/services/notion.ts`)
+
+**职责：** 调用 Notion API 获取页面内容，使用 `notion-to-md` 库转换。
+
+**核心方法：**
+
+| 方法 | 作用 |
+|-----|------|
+| `getPageAsMarkdown(url)` | 主入口，返回完整 Markdown |
+| `parsePageId(url)` | 从 URL 提取 page ID |
+| `setupCustomTransformers()` | 自定义 child_database 转换 |
+
+**数据库处理：**
+
+内嵌数据库（child_database）会自动转为 Markdown 表格，支持的字段类型：
+
+- title, rich_text, select, multi_select
+- number, checkbox, date, url, files
+
+## 数据流
+
+```
+┌─────────────────┐
+│ growork.config  │  YAML 配置文件
+│     .yaml       │
+└────────┬────────┘
+         │ loadConfigV2()
+         ▼
+┌─────────────────┐
+│ GroworkConfigV2 │  原始配置对象
+└────────┬────────┘
+         │ normalizeConfig(options)
+         ▼
+┌─────────────────┐
+│ NormalizedDoc[] │  标准化文档列表
+└────────┬────────┘
+         │
+    ┌────┴────┬──────────┐
+    ▼         ▼          ▼
+ Feishu    Notion     Figma
+    │         │          │
+    ▼         ▼          ▼
+┌─────────────────────────────┐
+│     Markdown 文件写入本地     │
+└─────────────────────────────┘
+```
+
+## 技术栈
+
+| 用途 | 依赖 |
+|-----|------|
+| CLI 框架 | commander |
+| 飞书 API | @larksuiteoapi/node-sdk |
+| Notion API | @notionhq/client |
+| Notion 转 MD | notion-to-md |
+| YAML 解析 | yaml |
+| 终端颜色 | chalk |
+| 构建工具 | tsup |
+
+## 设计原则
+
+1. **最少代码** - 不提前抽象，只实现当前需求
+2. **扁平结构** - 目录层级不超过 2 层
+3. **错误自然抛出** - 在顶层统一处理，不过度防御
+4. **依赖成熟库** - 不重复造轮子