growork 1.0.1 → 1.1.2

package/.claude/commands/review.md

@@ -0,0 +1,62 @@
+---
+allowed-tools: Bash, Read, Grep, Glob
+description: 代码审查，检查变更是否符合项目规范
+---
+
+## 代码审查
+
+审查当前变更，核心原则：**用最少的代码实现功能**。
+
+### 当前变更
+
+!`git diff --stat HEAD`
+
+### 审查清单
+
+读取变更内容 `git diff HEAD`，逐条检查：
+
+#### 1. 删除未使用的代码
+- [ ] 未使用的函数、变量、导入
+- [ ] 注释掉的代码
+- [ ] 未使用的 TODO 注释
+
+#### 2. 不要提前抽象
+- [ ] 只用一次的代码不需要封装成函数
+- [ ] 不要写 Factory、Manager、Helper 等过度抽象
+- [ ] 三行重复代码比一个过早抽象更好
+
+#### 3. 不要写"可能用到"的代码
+- [ ] 只实现当前需求
+- [ ] 不要预留"将来可能需要"的接口
+- [ ] 不要添加未使用的配置项
+
+#### 4. 错误处理要简洁
+- [ ] 不要过度防御（检查不可能发生的情况）
+- [ ] 让错误自然抛出，顶层统一处理
+- [ ] 不要给每种错误类型都写 catch 分支
+
+#### 5. 避免过度配置化
+- [ ] 不要添加不会用到的选项
+- [ ] 硬编码比过度灵活更好
+- [ ] 一个功能只需要一种实现方式
+
+#### 6. 依赖和结构
+- [ ] 能用标准库就不引入新依赖
+- [ ] 目录结构保持扁平
+- [ ] 一个函数只做一件事
+
+### 输出格式
+
+```
+## 审查结果
+
+✅ 通过 / ⚠️ 需要修改
+
+### 问题列表（如有）
+
+1. `文件:行号` - 违反了什么原则 - 如何简化
+
+### 可删除的代码
+
+- `文件:行号` - 原因
+```

package/.claude/settings.local.json

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

package/README.md

@@ -4,51 +4,40 @@
 
 这样 AI 工具（如 Claude、Cursor、Windsurf）就能直接读取你的产品文档，帮你写代码。
 
----
+[![npm](https://img.shields.io/npm/v/growork)](https://www.npmjs.com/package/growork)
 
-## 这个工具能做什么？
+## 功能
 
-✅ 自动下载飞书文档，转成 Markdown 格式
-✅ 自动下载 Notion 页面，转成 Markdown 格式
-✅ 一条命令同步所有文档
-✅ 文档更新后，重新运行命令即可获取最新内容
+- 自动下载飞书文档，转成 Markdown 格式
+- 自动下载 Notion 页面，转成 Markdown 格式
+- 支持 Figma 设计稿链接，自动生成链接文档
+- 按**版本 → 功能 → 文档类型**组织文档，AI 更容易理解
+- 一条命令同步所有文档
 
----
+> ⚠️ **每个版本都是破坏性更新**，不保证向后兼容。升级前请查看更新日志，必要时重新初始化配置文件。
 
-## 安装步骤
+## 安装
 
-### 第一步：安装 Node.js
+### 1. 安装 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. 初始化项目
@@ -61,14 +50,10 @@ growork init
 
 这会在当前目录创建一个 `growork.config.yaml` 配置文件。
 
----
-
 ### 2. 获取飞书凭证（如果你要同步飞书文档）
 
 你需要在飞书开放平台创建一个应用，获取「App ID」和「App Secret」。
 
-**详细步骤：**
-
 1. **打开飞书开放平台**
    - 国际版 Lark：https://open.larksuite.com/
    - 国内版飞书：https://open.feishu.cn/
@@ -76,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 页面
@@ -118,8 +88,6 @@ growork init
    - 选择你刚创建的 Integration
    - **每个要同步的页面都需要做这一步！**
 
----
-
 ### 4. 编辑配置文件
 
 用任意文本编辑器打开 `growork.config.yaml`，填入你的凭证和文档链接：
@@ -127,63 +95,114 @@ growork init
 ```yaml
 # 飞书配置（如果不用飞书，可以删除这部分）
 feishu:
-  appId: "cli_你的AppID"        # 替换成你的 App ID
-  appSecret: "你的AppSecret"     # 替换成你的 App Secret
+  appId: "cli_你的AppID"
+  appSecret: "你的AppSecret"
   domain: "lark"                # 国际版用 lark，国内版用 feishu
 
 # Notion 配置（如果不用 Notion，可以删除这部分）
 notion:
-  token: "ntn_你的Token"         # 替换成你的 Token
-
-# 要同步的文档列表
-docs:
-  # 飞书文档示例
-  - name: prd                    # 给文档起个名字（英文，方便记忆）
-    type: feishu                 # 类型：feishu
-    url: "https://xxx.larksuite.com/wiki/xxxxx"  # 文档链接
-    output: "docs/prd.md"        # 保存到哪里
-
-  # Notion 页面示例
-  - name: design                 # 给文档起个名字
-    type: notion                 # 类型：notion
-    url: "https://notion.so/xxxxx"  # 页面链接
-    output: "docs/design.md"     # 保存到哪里
+  token: "ntn_你的Token"
+
+# 输出目录（默认是 docs）
+outputDir: "docs"
+
+# 全局文档（不跟版本走的公共文档）
+custom:
+  - "https://xxx.feishu.cn/docx/xxxxx"           # 直接写链接
+  - url: "https://www.notion.so/xxxxx"
+    name: "技术架构"                              # 可选：自定义名称
+
+# 版本化文档（按功能模块组织）
+versions:
+  v1.0:
+    用户登录:                    # 功能名称
+      prd:                       # PRD 文档
+        - "https://xxx.feishu.cn/docx/xxxxx"
+      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:                      # 测试用例
+        - "https://www.notion.so/aaaaa"
+
+    # 简单功能可以不分类
+    小优化:
+      - "https://xxx.feishu.cn/docx/bbbbb"
 ```
 
+**配置说明：**
+
+| 区域       | 说明                                             |
+| ---------- | ------------------------------------------------ |
+| `custom`   | 全局文档，不属于任何版本（如技术架构、编码规范） |
+| `versions` | 按版本和功能组织的文档                           |
+| `prd`      | 产品需求文档                                     |
+| `design`   | 设计稿（支持 Figma 链接，自动生成链接文档）      |
+| `api`      | 接口/技术方案                                    |
+| `test`     | 测试用例                                         |
+
 **如何获取文档链接？**
 
 - **飞书**：打开文档，直接复制浏览器地址栏的链接
 - **Notion**：打开页面，点击右上角「Share」→「Copy link」
-
----
+- **Figma**：打开设计稿，复制浏览器地址栏的链接（可带 `node-id` 参数定位到具体页面）
 
 ### 5. 同步文档
 
-运行以下命令，自动下载所有文档：
-
 ```bash
 growork sync
 ```
 
-同步完成后，文档会保存到你配置的 `output` 路径。
+同步完成后，文档会按以下结构保存：
 
-**只同步某一个文档：**
-
-```bash
-growork sync prd
+```
+docs/
+├── custom/                    # 全局文档
+│   ├── 技术架构.md
+│   └── 编码规范.md
+└── v1.0/                      # 版本目录
+    ├── 用户登录/              # 功能目录
+    │   ├── prd/
+    │   │   └── 用户登录PRD.md
+    │   ├── design/
+    │   │   └── design.md      # Figma 链接自动合并到此文件
+    │   └── api/
+    │       └── 登录接口文档.md
+    └── 小优化/
+        └── 优化说明.md
 ```
 
-**查看所有已配置的文档：**
+**只同步特定内容：**
 
 ```bash
-growork list
+growork sync -c               # 只同步全局文档
+growork sync --ver v1.0       # 只同步 v1.0 版本
+growork sync -f 用户登录       # 只同步「用户登录」功能
 ```
 
----
+## 命令速查
+
+| 命令                        | 说明           |
+| --------------------------- | -------------- |
+| `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` 权限
@@ -191,13 +210,9 @@ growork list
 - 确认你有权限访问该文档
 
 **Notion 页面：**
-- 确认你已经把 Integration 连接到了该页面（见上面第 3 步的「给页面授权」）
+- 确认你已经把 Integration 连接到了该页面
 
----
-
-### Q: 提示「找不到命令」或「command not found」
-
-Node.js 可能没有正确安装，或者 npm 全局路径没有加入系统 PATH。
+### 提示「找不到命令」或「command not found」
 
 尝试重新安装 Node.js，或者使用 `npx` 运行：
 
@@ -205,39 +220,27 @@ Node.js 可能没有正确安装，或者 npm 全局路径没有加入系统 PAT
 npx growork sync
 ```
 
----
-
-### Q: 同步后文档是空的
+### 同步后文档是空的
 
 - 检查文档链接是否正确
 - 检查你是否有权限访问该文档
 - 飞书知识库文档需要使用 `/wiki/` 格式的链接
 
----
-
-### Q: 如何更新已同步的文档？
+### 如何更新已同步的文档？
 
 直接再次运行 `growork sync`，会自动覆盖本地文件。
 
----
+### 文件名是怎么生成的？
 
-## 支持的文档类型
+文件名会自动从文档标题获取，并处理特殊字符：
 
-| 平台 | 支持的内容 |
-| --- | --- |
-| 飞书 | 普通文档 (`/docx/`)、知识库 (`/wiki/`) |
-| Notion | 任意页面（包含数据库的页面会自动转为表格） |
+- `用户登录 / 注册流程 (v1.0)` → `用户登录-注册流程-v1.0.md`
 
----
+你也可以在配置中用 `name` 字段自定义名称。
 
 ## 需要帮助？
 
-如果遇到问题，可以：
-
-1. 在 GitHub 上提 Issue：https://github.com/你的仓库/issues
-2. 检查上面的「常见问题」部分
-
----
+- [GitHub Issues](https://github.com/ThinkerJack/GroWork/issues)
 
 ## License
 

package/claude.md

@@ -1,4 +1,105 @@
-# GroWork 架构原则
+# GroWork
+
+无需关注test_export下的内容
+
+## 项目简介
+
+GroWork 是一个文档同步 CLI 工具，将飞书文档和 Notion 页面自动下载到本地，转为 Markdown 格式，便于 AI 工具（Claude、Cursor 等）读取。
+
+## 项目结构
+
+```
+src/
+├── index.ts           # CLI 入口，使用 commander 定义命令
+├── commands/
+│   ├── init.ts        # growork init - 初始化配置文件
+│   ├── sync.ts        # growork sync [name] - 同步文档
+│   └── list.ts        # growork list - 列出所有文档
+├── services/
+│   ├── feishu.ts      # 飞书 API，转换飞书 block 为 Markdown
+│   └── notion.ts      # Notion API，使用 notion-to-md 库
+└── utils/
+    └── config.ts      # 配置文件解析和类型定义
+```
+
+## 技术栈
+
+- **Runtime**: Node.js >= 18, ESM 模块
+- **构建**: tsup
+- **依赖**: commander (CLI), @larksuiteoapi/node-sdk (飞书), @notionhq/client + notion-to-md (Notion), yaml (配置), chalk (终端颜色)
+
+## 配置文件
+
+`growork.config.yaml` 结构：
+
+```yaml
+feishu:
+  appId: "cli_xxx"
+  appSecret: "xxx"
+  domain: "lark"  # lark(国际版) 或 feishu(国内版)
+
+notion:
+  token: "ntn_xxx"
+
+outputDir: "docs"  # 输出根目录
+
+custom:  # 全局文档
+  - "https://xxx.feishu.cn/docx/xxxxx"
+
+versions:  # 版本化文档
+  v1.0:
+    用户登录:
+      prd:
+        - "https://xxx.feishu.cn/docx/xxxxx"
+```
+
+## 常用命令
+
+```bash
+npm run build          # 构建
+npm run dev            # 开发模式
+node dist/index.js sync [name]  # 同步文档
+```
+
+## 关键类型
+
+```typescript
+// 文档输入格式
+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;
+  name?: string;
+  type: 'feishu' | 'notion';
+  outputPath: string;  // 含 {title} 占位符
+}
+```
+
+---
+
+# 架构原则
 
 ## 核心原则：用最少的代码实现功能
 
@@ -123,7 +224,7 @@ src/
 
 ### 命名
 
-- 文件名：小写 + 连字符，如 `feishu-sync.ts`
+- 文件名：小写，如 `feishu.ts`, `config.ts`
 - 函数名：动词开头，如 `syncDoc`, `parseConfig`
 - 布尔变量：is/has/should 开头，如 `isValid`