growork 1.0.1 → 1.1.1

package/{docs/test → tests}/test-cases.md

@@ -16,9 +16,9 @@ node --import tsx --test tests/notion.test.ts
 
 | 文件 | 测试内容 | 用例数 |
 |-----|---------|-------|
-| `tests/config.test.ts` | 配置文件解析和验证 | 12 |
-| `tests/feishu.test.ts` | 飞书 URL 解析、Markdown 转换 | 34 |
-| `tests/notion.test.ts` | Notion URL 解析、属性提取 | 28 |
+| `tests/config.test.ts` | 配置文件解析、验证、V2.0 配置规范化 | 34 |
+| `tests/feishu.test.ts` | 飞书 URL 解析、Markdown 转换 | 31 |
+| `tests/notion.test.ts` | Notion URL 解析、属性提取 | 34 |
 
 ## 回归测试流程
 
@@ -32,8 +32,9 @@ npm test
 
 预期输出：
 ```
-ℹ tests 74
-ℹ pass 74
+ℹ tests 99
+ℹ suites 29
+ℹ pass 99
 ℹ fail 0
 ```
 
@@ -59,12 +60,12 @@ npm test
 
 ### config.test.ts
 
-**配置解析**
+**V1.0 配置解析**
 - 有效 YAML 配置解析
 - Notion 配置解析
 - 混合配置（飞书 + Notion）
 
-**配置验证**
+**V1.0 配置验证**
 - 空文档配置 → 报错
 - 缺少飞书凭证 → 报错
 - 缺少 Notion 凭证 → 报错
@@ -72,6 +73,41 @@ npm test
 - 只有 Notion 文档 → 无需飞书凭证
 - 混合文档 → 需要所有相关凭证
 
+**V2.0 文档类型推断**
+- `feishu.cn` URL → feishu
+- `larksuite.com` URL → feishu
+- `notion.so` URL → notion
+- `notion.site` URL → notion
+- 未知域名 → 报错
+
+**V2.0 文件名清理**
+- 移除文件系统保留字符
+- 空格替换为连字符
+- 合并连续空格
+- 移除首尾连字符
+- 处理复杂标题
+- 处理纯特殊字符
+
+**V2.0 文档输入解析**
+- 字符串输入 → `{ url }`
+- 对象输入（只有 url）
+- 对象输入（带 name）
+
+**V2.0 配置规范化**
+- custom 文档处理
+- 带 name 的 custom 文档
+- versions 中的简单 feature
+- versions 中的分类型 feature（prd/design/api/test）
+- 自定义 outputDir
+- version 过滤
+- feature 过滤
+- custom 选项（只获取 custom 文档）
+- 默认返回所有文档
+- 多版本多 feature 处理
+
+**V2.0 YAML 配置解析**
+- 完整 V2.0 配置结构解析
+
 ### feishu.test.ts
 
 **URL 解析**
@@ -155,34 +191,48 @@ assert.throws(() => fn(), /错误信息/);
 assert.doesNotThrow(() => fn());
 ```
 
-## 端到端测试（手动）
+## 端到端测试
+
+自动化测试覆盖纯函数逻辑，E2E 测试验证完整流程。
 
-自动化测试覆盖纯函数逻辑，以下场景需要手动验证：
+### 快速验证（本地开发）
 
-### init 命令
+修改代码后，运行以下命令验证：
 
 ```bash
-# 在空目录执行
-mkdir /tmp/test-growork && cd /tmp/test-growork
-growork init
+# 1. 构建
+npm run build
 
-# 验证
-ls -la docs/          # 应有 product/design/api/tech/test
-cat growork.config.yaml  # 应有默认配置
-cat .gitignore        # 应包含 growork.config.yaml
+# 2. 同步文档（需要已配置 growork.config.yaml）
+node dist/index.js sync
+
+# 或者如果已全局安装
+growork sync
 ```
 
-### sync 命令
+### 完整 E2E 流程
 
 ```bash
-# 配置真实凭证和文档后
-growork sync          # 同步所有
-growork sync prd      # 同步指定文档
-growork sync invalid  # 应报错并列出可用文档
-```
+# 1. 构建并本地安装
+npm run build
+npm link
 
-### list 命令
+# 2. 测试 init 命令
+mkdir /tmp/test-growork && cd /tmp/test-growork
+growork init
+ls docs/                 # 应有 product/design/api/tech/test
+cat growork.config.yaml  # 应有默认配置
 
-```bash
-growork list          # 显示文档列表和同步状态
+# 3. 配置真实凭证后测试 sync
+# 编辑 growork.config.yaml，填入真实的飞书/Notion 凭证
+growork sync             # 同步所有文档
+growork sync prd         # 同步指定文档
+growork sync invalid     # 应报错并列出可用文档
+
+# 4. 测试 list 命令
+growork list             # 显示文档列表和同步状态
+
+# 5. 清理
+cd ~ && rm -rf /tmp/test-growork
+npm unlink -g growork
 ```

package/docs/product/prd-v1.0.md

@@ -1,418 +0,0 @@
-# GroWork v1.0 产品需求文档 (PRD)
-
-## 1. 概述
-
-| 项目     | 内容                 |
-| -------- | -------------------- |
-| 产品名称 | GroWork              |
-| 版本     | v1.0                 |
-| 产品形态 | CLI 命令行工具       |
-| 技术栈   | Node.js / TypeScript |
-| 发布日期 | 2025-01-30           |
-
-## 2. 背景与目标
-
-### 2.1 背景描述
-
-AI Code 时代，放大 Claude Code 这类 Agent Coding 工具的能力，提供更多的上下文，让 AI 在一个目录下搞定所有的需求。
-
-常规的开发流程，
-
-#### 准备阶段
-
-需求侧："需求评审，文档在 Lark，设计稿评审，地址在 Figma
-技术方案侧：后端出技术方案，包含业务接口后端和ai通信后端
-客户端侧：客户端根据需求和技术方案，产出自己的技术方案和项目排期，结合项目的时间节点，给出项目时间
-
-#### 开发阶段
-
-根据准备阶段手机到的东西，不断的抽象成feature，流程就是 方案（prompt）+ code + 自测，提交
-提测之前会测试会产出测试用例
-
-#### 测试阶段
-
-测试会把 bug 维护到 Lark 文档上，开发看到 bug，根据 bug 写方案（prompt）+ code + 自测，提交，修改 bug 状态
-最后上线
-
-全流程没有打通
-
-已经做到的部分，desgin to code，通过fimga mcp + 设计元素的脚本自动化，让ai能够还原设计稿
-api to dart ,通过swagger实现flutter自动生成dart代码
-
-### 2.2 产品目标
-
-实现产品开发测试全流程在一个文件夹下闭环。
-
-### 2.3 成功指标
-
-自己成功闭环需求。
-
-## 3. 用户分析
-
-### 3.1 目标用户
-
-使用 Agent 开发工具的开发团队。
-
-### 3.2 用户痛点
-
-App 开发时，产品 PRD、设计稿、接口文档、后端技术方案、测试用例方案分散在不同平台，不能在一个工程内闭环，需要来回切换：
-
-| 文档类型     | 当前存放位置  |
-| ------------ | ------------- |
-| 产品 PRD     | Lark / Notion |
-| 设计稿       | Figma         |
-| 接口文档     | Lark / Notion |
-| 后端技术方案 | Lark / Notion |
-| 测试用例     | Lark / Notion |
-| 需求数据库   | Notion        |
-
-### 3.3 用户场景
-
-日常开发工作中，希望 AI Agent 能一次性获取完整上下文进行开发。
-
-## 4. 功能需求
-
-### 4.1 版本规划
-
-**第一版（MVP）：** 聚焦 Lark 和 Notion 文档同步，打通客户端开发场景。
-
-**后续版本：** Figma 设计稿同步、更多平台支持。
-
-### 4.2 第一版功能列表
-
-| 命令                    | 作用                                      | 状态      |
-| ----------------------- | ----------------------------------------- | --------- |
-| `growork init`        | 生成配置文件模板 + 标准目录结构           | ✅ 已实现 |
-| `growork sync`        | 同步所有配置的文档                        | ✅ 已实现 |
-| `growork sync <name>` | 只同步指定的文档，如 `growork sync prd` | ✅ 已实现 |
-| `growork list`        | 列出所有配置的文档及同步状态              | ✅ 已实现 |
-
-### 4.2.1 批量文档同步
-
-**核心能力**：在 `growork.config.yaml` 中配置多个文档，一键同步到本地。
-
-```yaml
-docs:
-  - name: prd
-    type: feishu
-    url: "https://xxx.larksuite.com/wiki/xxxxx"
-    output: "docs/product/prd.md"
-
-  - name: api
-    type: feishu
-    url: "https://xxx.larksuite.com/wiki/xxxxx"
-    output: "docs/api/api-spec.md"
-
-  - name: test
-    type: feishu
-    url: "https://xxx.larksuite.com/wiki/xxxxx"
-    output: "docs/test/test-cases.md"
-```
-
-执行 `growork sync` 后，所有配置的文档会被同步到指定路径，转换为 AI 友好的 Markdown 格式。
-
-**支持的文档类型**：
-
-| 类型       | 说明                             | URL 格式                       |
-| ---------- | -------------------------------- | ------------------------------ |
-| `feishu` | Lark 文档 (docx) 和知识库 (wiki) | `/docx/xxx` 或 `/wiki/xxx` |
-| `notion` | Notion 页面（含内嵌数据库）      | 包含 32 位 ID 的 URL           |
-
-### 4.3 配置文件设计
-
-用户在项目根目录维护 `growork.config.yaml` 配置文件：
-
-```yaml
-# Lark 应用凭证
-feishu:
-  appId: "cli_xxxx"
-  appSecret: "xxxx"
-  domain: "lark"
-
-# Notion 凭证
-notion:
-  token: "ntn_xxxx"
-
-# 文档同步配置
-docs:
-  # 产品文档（Lark 知识库）
-  - name: prd
-    type: feishu
-    url: "https://xxx.larksuite.com/wiki/xxxxx"
-    output: "docs/product/prd.md"
-
-  # 产品文档（Notion 页面）
-  - name: prd-notion
-    type: notion
-    url: "https://www.notion.so/xxxxx"
-    output: "docs/product/prd-notion.md"
-
-  # 接口文档（Lark）
-  - name: api
-    type: feishu
-    url: "https://xxx.larksuite.com/docx/xxxxx"
-    output: "docs/api/api-spec.md"
-
-  # 后端技术方案
-  - name: backend
-    type: feishu
-    url: "https://xxx.larksuite.com/docx/xxxxx"
-    output: "docs/tech/backend.md"
-
-  # 测试用例
-  - name: test-cases
-    type: feishu
-    url: "https://xxx.larksuite.com/docx/xxxxx"
-    output: "docs/test/test-cases.md"
-```
-
-### 4.4 标准目录结构
-
-执行 `growork init` 后生成：
-
-```
-project/
-├── growork.config.yaml     # 配置文件
-├── docs/
-│   ├── product/            # 产品文档
-│   │   └── prd.md
-│   ├── design/             # 设计稿（后续版本）
-│   ├── api/                # 接口文档
-│   │   └── api-spec.md
-│   ├── tech/               # 技术方案
-│   │   └── backend.md
-│   └── test/               # 测试用例
-│       └── test-cases.md
-└── src/                    # 代码目录
-```
-
-### 4.5 使用流程
-
-```
-1. npm install -g growork   # 安装 CLI 工具
-2. growork init             # 生成配置文件和目录结构
-3. 编辑 growork.config.yaml，填入 Lark 凭证和文档链接
-4. growork sync             # 一键同步所有文档
-```
-
-### 4.6 同步输出示例
-
-```
-$ growork sync
-
-📄 Syncing documents...
-
-  ✓ prd          → docs/product/prd.md
-  ✓ api          → docs/api/api-spec.md
-  ✓ backend      → docs/tech/backend.md
-  ✗ test-cases   → 获取失败：文档无权限
-
-Synced 3/4 documents.
-```
-
-## 5. 非功能需求
-
-### 5.1 性能要求
-
-- 单个文档同步时间 < 5 秒
-
-### 5.2 安全要求
-
-- Lark 凭证不应提交到 Git，配置文件应加入 .gitignore 或支持环境变量
-
-### 5.3 兼容性要求
-
-- 支持 macOS / Linux / Windows
-- Node.js >= 18
-
-## 6. 技术设计
-
-### 6.1 项目结构
-
-```
-growork/
-├── package.json
-├── tsconfig.json
-├── src/
-│   ├── index.ts           # CLI 入口
-│   ├── commands/
-│   │   ├── init.ts        # growork init
-│   │   ├── sync.ts        # growork sync
-│   │   └── list.ts        # growork list
-│   ├── services/
-│   │   ├── feishu.ts      # Lark API 封装 + Markdown 转换
-│   │   └── notion.ts      # Notion API 封装 + Markdown 转换
-│   └── utils/
-│       └── config.ts      # 配置文件读取
-└── bin/
-    └── growork            # CLI 可执行文件入口
-```
-
-### 6.2 技术选型
-
-| 用途        | 选择                    |
-| ----------- | ----------------------- |
-| 语言        | TypeScript              |
-| CLI 框架    | Commander.js            |
-| Lark SDK    | @larksuiteoapi/node-sdk |
-| Notion SDK  | @notionhq/client        |
-| Notion 转换 | notion-to-md            |
-| 配置解析    | yaml                    |
-| 构建工具    | tsup                    |
-
-### 6.3 Lark 同步流程
-
-```
-读取 growork.config.yaml
-    ↓
-遍历 docs 配置
-    ↓
-解析 Lark 文档 URL，提取 document_id
-    ↓
-调用 Lark API 获取文档内容
-    ↓
-转换为 Markdown 格式
-    ↓
-写入到配置的 output 路径
-```
-
-### 6.4 Notion 同步流程
-
-```
-读取 growork.config.yaml
-    ↓
-遍历 docs 配置（type: notion）
-    ↓
-解析 Notion URL，提取 page_id
-    ↓
-调用 Notion API 获取页面内容
-    ↓
-使用 notion-to-md 转换为 Markdown
-（内嵌数据库自动转换为表格）
-    ↓
-写入到配置的 output 路径
-```
-
-## 7. 导出格式支持
-
-### 7.1 支持的导出格式
-
-| 格式        | 说明                         | 使用场景              |
-| ----------- | ---------------------------- | --------------------- |
-| Markdown    | Block API 直接转换，结构清晰 | AI Agent 读取（推荐） |
-| Word (docx) | Lark 原生导出                | 人工阅读、存档        |
-| PDF         | Lark 原生导出                | 分享、打印            |
-
-### 7.2 Markdown 转换能力
-
-支持的 Lark 文档元素：
-
-| 元素             | Markdown 输出                             |
-| ---------------- | ----------------------------------------- |
-| 标题 H1-H6       | `# ~ ######`                            |
-| 正文文本         | 普通段落                                  |
-| 无序列表         | `- item`                                |
-| 有序列表         | `1. item`                               |
-| 待办事项         | `- [ ] / - [x]`                         |
-| 代码块           | ` ```lang ``` `                         |
-| 引用             | `> text`                                |
-| 表格             | Markdown 表格                             |
-| 分割线           | `---`                                   |
-| 粗体/斜体/删除线 | `**bold**` / `*italic*` / `~~del~~` |
-| 链接             | `[text](url)`                           |
-| 高亮块 (Callout) | 递归转换内容                              |
-| 分栏布局 (Grid)  | 递归转换内容                              |
-| 嵌入表格         | `[嵌入表格: token]` 提示                |
-
-## 8. 开放问题
-
-- [ ] 是否需要支持增量同步（只同步有变更的文档）？
-- [ ] 配置文件中的凭证是否改用环境变量更安全？
-- [ ] 是否需要支持独立的 Notion 数据库同步（目前仅支持页面内嵌数据库）？
-- [X] ~~是否需要支持 Lark 知识库/Wiki？~~ → 已支持
-- [X] ~~是否需要支持 Notion？~~ → v1.2 已支持页面（含内嵌数据库转换）
-
-## 9. 附录
-
-### 9.1 Lark 开放平台配置
-
-使用前需要：
-
-1. 在 [Lark 开放平台](https://open.larksuite.com/) 创建应用
-2. 获取 App ID 和 App Secret
-3. 开通以下权限：
-
-**必需权限（Markdown 同步）**：
-
-- `docx:document:readonly` - 读取文档内容
-- `wiki:wiki:readonly` - 读取知识库
-
-**可选权限（导出 Word/PDF）**：
-
-- `drive:drive:export` - 导出云文档
-- 需要将应用添加为知识库成员
-
-### 9.2 Notion 配置
-
-使用前需要：
-
-1. 在 [Notion Integrations](https://www.notion.so/my-integrations) 创建一个 Integration
-2. 获取 Internal Integration Token（以 `ntn_` 开头）
-3. 在需要同步的页面中，点击右上角「...」→「Add connections」→ 选择你的 Integration
-
-**支持的 URL 格式**：
-
-- `https://www.notion.so/页面ID`
-- `https://www.notion.so/workspace/页面标题-页面ID`
-- `https://notion.so/页面ID?v=xxx`
-
-**注意**：页面内嵌入的数据库会自动转换为 Markdown 表格。
-
-### 9.3 配置文件示例
-
-```yaml
-# growork.config.yaml
-
-# Lark 应用凭证
-feishu:
-  appId: "cli_xxxx"
-  appSecret: "xxxx"
-  domain: "lark"
-
-# Notion 凭证
-notion:
-  token: "ntn_xxxx"
-
-# 文档同步配置
-docs:
-  - name: prd
-    type: feishu
-    url: "https://xxx.larksuite.com/wiki/xxxxx"
-    output: "docs/product/prd.md"
-
-  - name: api
-    type: feishu
-    url: "https://xxx.larksuite.com/wiki/xxxxx"
-    output: "docs/api/api-spec.md"
-
-  - name: design-spec
-    type: notion
-    url: "https://www.notion.so/xxxxx"
-    output: "docs/design/spec.md"
-```
-
-### 9.4 AI Agent 使用场景
-
-配置好文档后，AI Agent（如 Claude Code）可以：
-
-1. 读取 `docs/` 目录下的所有 Markdown 文档
-2. 获取完整的产品需求、接口规范、技术方案
-3. 基于上下文进行开发、测试、问题排查
-
-```bash
-# 同步最新文档
-growork sync
-
-# AI Agent 读取上下文
-# Claude Code 会自动读取 docs/ 目录下的文档
-```