growork 1.0.0

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

@@ -0,0 +1,418 @@
+# 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/ 目录下的文档
+```

package/docs/test/test-cases.md

@@ -0,0 +1,188 @@
+# GroWork 测试指南
+
+## 运行测试
+
+```bash
+# 运行所有测试
+npm test
+
+# 运行单个测试文件
+node --import tsx --test tests/config.test.ts
+node --import tsx --test tests/feishu.test.ts
+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 |
+
+## 回归测试流程
+
+修改代码后，按以下步骤回归：
+
+### 1. 运行全量测试
+
+```bash
+npm test
+```
+
+预期输出：
+```
+ℹ tests 74
+ℹ pass 74
+ℹ fail 0
+```
+
+### 2. 根据修改范围选择性测试
+
+| 修改的文件 | 需要运行的测试 |
+|-----------|--------------|
+| `src/utils/config.ts` | `tests/config.test.ts` |
+| `src/services/feishu.ts` | `tests/feishu.test.ts` |
+| `src/services/notion.ts` | `tests/notion.test.ts` |
+| `src/commands/*.ts` | 全量测试 |
+
+### 3. 失败用例处理
+
+测试失败时会显示：
+- 失败的用例名称
+- 期望值 vs 实际值
+- 错误堆栈和源码位置
+
+根据错误信息修复代码或更新测试用例。
+
+## 测试覆盖详情
+
+### config.test.ts
+
+**配置解析**
+- 有效 YAML 配置解析
+- Notion 配置解析
+- 混合配置（飞书 + Notion）
+
+**配置验证**
+- 空文档配置 → 报错
+- 缺少飞书凭证 → 报错
+- 缺少 Notion 凭证 → 报错
+- 只有飞书文档 → 无需 Notion 凭证
+- 只有 Notion 文档 → 无需飞书凭证
+- 混合文档 → 需要所有相关凭证
+
+### feishu.test.ts
+
+**URL 解析**
+- `feishu.cn/docx/xxx` → type=docx
+- `larksuite.com/docx/xxx` → type=docx
+- `feishu.cn/wiki/xxx` → type=wiki
+- 带查询参数的 URL
+- 无效路径格式 → 报错
+
+**语言代码映射**
+- 常用语言：python、javascript、typescript、go、rust 等
+- 未知代码 → 空字符串
+
+**文本样式转换**
+- 普通文本、粗体、斜体、删除线
+- 行内代码、链接
+- 组合样式（如粗斜体）
+- @用户、文档引用
+
+**Block 转换**
+- 文本块、标题（H1-H3）
+- 无序列表、有序列表
+- 代码块（含语言标识）
+- 引用块、待办事项、分割线
+
+### notion.test.ts
+
+**URL 解析**
+- 32 位十六进制 ID
+- UUID 格式（带连字符）
+- 带工作区前缀的 URL
+- 带查询参数的 URL
+- 无效格式 → 报错
+
+**属性值提取**
+- title、rich_text → 文本
+- select → 选项名
+- multi_select → 逗号分隔
+- number → 字符串
+- checkbox → ✓ 或空
+- date → 开始日期
+- url → 原始 URL
+- files → 文件名列表
+
+## 添加新测试
+
+### 测试文件结构
+
+```typescript
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+
+describe('功能模块', () => {
+  it('应该做某事', () => {
+    const result = someFunction(input);
+    assert.strictEqual(result, expected);
+  });
+
+  it('应该拒绝无效输入', () => {
+    assert.throws(
+      () => someFunction(invalidInput),
+      /错误信息/
+    );
+  });
+});
+```
+
+### 常用断言
+
+```typescript
+// 相等
+assert.strictEqual(actual, expected);
+
+// 深度相等（对象/数组）
+assert.deepStrictEqual(actual, expected);
+
+// 抛出异常
+assert.throws(() => fn(), /错误信息/);
+
+// 不抛出异常
+assert.doesNotThrow(() => fn());
+```
+
+## 端到端测试（手动）
+
+自动化测试覆盖纯函数逻辑，以下场景需要手动验证：
+
+### init 命令
+
+```bash
+# 在空目录执行
+mkdir /tmp/test-growork && cd /tmp/test-growork
+growork init
+
+# 验证
+ls -la docs/          # 应有 product/design/api/tech/test
+cat growork.config.yaml  # 应有默认配置
+cat .gitignore        # 应包含 growork.config.yaml
+```
+
+### sync 命令
+
+```bash
+# 配置真实凭证和文档后
+growork sync          # 同步所有
+growork sync prd      # 同步指定文档
+growork sync invalid  # 应报错并列出可用文档
+```
+
+### list 命令
+
+```bash
+growork list          # 显示文档列表和同步状态
+```

package/growork.config.yaml

@@ -0,0 +1,43 @@
+# Growork 配置文件
+
+# 飞书应用凭证
+feishu:
+  appId: "cli_a9f679f7d8389ed1"
+  appSecret: "M75JzaxTI8kAn50Ss1GgEbBVAIP551RX"
+  domain: "lark"  # 使用国际版 Lark
+
+# Notion 凭证
+notion:
+  token: "ntn_B47151172375xyBGfoq9heNvlzfhvgSBQymC4zO7f997XO"
+
+# 文档同步配置
+docs:
+  # 五牌阵需求文档 (飞书)
+  - name: prd-5spread
+    type: feishu
+    url: "https://romangic.sg.larksuite.com/wiki/UrBKwmmJNizGlzkoFU3l90wxgOd"
+    output: "test/prd-5spread.md"
+
+  # 后端AI文档 (飞书)
+  - name: backend-ai
+    type: feishu
+    url: "https://romangic.sg.larksuite.com/wiki/ZiCuw4GnXiBsPnkN159lNE0mgLe"
+    output: "test/backend-ai.md"
+
+  # Push 需求文档 (飞书)
+  - name: push
+    type: feishu
+    url: "https://romangic.sg.larksuite.com/wiki/EB9NwMUP2ipF0Pk0SZBlXOS5gcb"
+    output: "test/push.md"
+
+  # Push PRD (Notion)
+  - name: push-prd-notion
+    type: notion
+    url: "https://www.notion.so/2f91190afab5806aa853c073a24edd28"
+    output: "test/push-prd-notion.md"
+
+  # 后端接口文档 (飞书)
+  - name: backend-api
+    type: feishu
+    url: "https://romangic.sg.larksuite.com/wiki/QtUuwKpXyiFmAckrIaOlqRDNgJe"
+    output: "test/backend-api.md"

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "growork",
+  "version": "1.0.0",
+  "description": "将飞书文档同步到本地，为 AI Agent 提供完整上下文",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "growork": "./bin/growork.js"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --watch",
+    "start": "node dist/index.js",
+    "test": "node --import tsx --test tests/**/*.test.ts"
+  },
+  "keywords": [
+    "feishu",
+    "lark",
+    "sync",
+    "markdown",
+    "ai",
+    "agent"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@larksuiteoapi/node-sdk": "^1.58.0",
+    "@notionhq/client": "^5.9.0",
+    "@types/node": "^25.1.0",
+    "chalk": "^5.6.2",
+    "commander": "^14.0.2",
+    "notion-to-md": "^3.1.9",
+    "typescript": "^5.9.3",
+    "yaml": "^2.8.2"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}