growork 1.0.1 → 1.1.2

package/docs/prd-1.1.1.md

@@ -0,0 +1,215 @@
+# GroWork 1.1.0 PRD
+
+## 概述
+
+| 项目     | 内容                          |
+| -------- | ----------------------------- |
+| 产品名称 | GroWork                       |
+| 版本     | 1.1.0                         |
+| 状态     | ✅ 已完成                      |
+| 产品形态 | CLI                           |
+| 核心改动 | 引入版本和 feature 层级结构    |
+
+## 背景与目标
+
+### 背景
+
+当前 1.0.0 配置是扁平的 docs 列表，没有版本和 features 概念，不便于按功能模块组织文档。实际开发中，每个功能都是按 feature 闭环的，包含 PRD、设计、接口、测试等多种文档。
+
+### 目标
+
+1. 引入 **版本 → feature → 文档类型** 的层级结构
+2. 简化配置，最简情况只需写 URL
+3. 支持全局文档（不归属版本）
+
+## 用户场景
+
+使用 Claude Code 等 Agent 工具的开发者，希望同步远程文档到本地，让 AI 直接读取进行开发。文档按版本和功能模块组织，便于 AI 理解项目结构。
+
+## 功能需求
+
+### 文档类型定义
+
+| 类型     | 说明                       |
+| -------- | -------------------------- |
+| `prd`    | 产品需求文档               |
+| `design` | 设计稿/交互文档            |
+| `api`    | 接口/技术方案              |
+| `test`   | 测试用例                   |
+| `custom` | 全局文档，不归属任何版本   |
+
+### 配置文件格式
+
+```yaml
+# growork.config.yaml
+feishu:
+  appId: "cli_xxx"
+  appSecret: "xxx"
+  domain: "feishu"    # feishu(中国版) 或 lark(国际版)
+
+notion:
+  token: "ntn_xxx"
+
+# 输出根目录（默认 "docs"）
+outputDir: "docs"
+
+# 全局文档（不跟版本）
+custom:
+  - https://feishu.cn/xxx           # 最简写法，name 从文档标题获取
+  - url: https://notion.so/yyy
+    name: 技术架构                   # 可选：自定义名称
+
+# 版本化文档
+versions:
+  v1.2:
+    用户登录:                        # feature 名称
+      prd:
+        - https://feishu.cn/xxx
+      design:
+        - https://feishu.cn/yyy
+      api:
+        - https://feishu.cn/zzz
+      test:
+        - https://feishu.cn/aaa
+
+    # 简单 feature 可不分类
+    小优化:
+      - https://feishu.cn/bbb
+```
+
+### 输出目录结构
+
+```
+docs/
+├── custom/                      # 全局文档
+│   ├── 项目总览.md
+│   └── 技术架构.md
+└── v1.2/
+    ├── 用户登录/
+    │   ├── prd/
+    │   │   └── {文档标题}.md
+    │   ├── design/
+    │   │   └── {文档标题}.md
+    │   ├── api/
+    │   │   └── {文档标题}.md
+    │   └── test/
+    │       └── {文档标题}.md
+    └── 小优化/
+        └── {文档标题}.md
+```
+
+### 默认值规则
+
+| 字段      | 默认值                                              |
+| --------- | --------------------------------------------------- |
+| outputDir | `docs`                                              |
+| name      | 从文档标题自动获取，自动去除特殊字符                 |
+| output    | `{outputDir}/{version}/{feature}/{type}/{name}.md`  |
+| type      | 自动从 URL 推断（feishu.cn/larksuite.com → feishu，notion.so/notion.site → notion）|
+
+### 文件名处理
+
+文档标题作为文件名时，自动去除以下特殊字符：
+- 文件系统保留字符：`/ \ : * ? " < > |`
+- 空格替换为 `-`
+- 连续的 `-` 合并为单个
+- 首尾 `-` 去除
+
+示例：`用户登录 / 注册流程 (v1.0)` → `用户登录-注册流程-v1.0.md`
+
+### 命令列表
+
+| 命令 | 说明 | 状态 |
+|-----|-----|-----|
+| `growork init` | 生成 1.1.0 配置文件模板 | ✅ |
+| `growork sync` | 同步所有文档 | ✅ |
+| `growork sync --ver <version>` | 只同步指定版本 | ✅ |
+| `growork sync -f <feature>` | 只同步指定 feature | ✅ |
+| `growork sync -c` | 只同步全局文档 | ✅ |
+| `growork list` | 列出所有文档（按层级展示） | ✅ |
+| `growork migrate` | 将 1.0.0 配置迁移到 1.1.0 | ✅ |
+
+### 同步命令参数
+
+```bash
+growork sync                    # 同步全部
+growork sync --ver v1.2         # 只同步指定版本（避免与 --version 冲突）
+growork sync -f 用户登录         # 只同步指定 feature
+growork sync -c                 # 只同步全局文档
+```
+
+> 注：使用 `--ver` 而非 `--version` 是因为 commander 保留了 `--version` 用于显示版本号
+
+### 核心流程
+
+1. 用户编辑 `growork.config.yaml`
+2. 运行 `growork sync` 命令
+3. 工具解析配置，按层级同步文档
+4. 文档输出到对应目录，name 从远程文档标题获取
+
+## 技术设计
+
+### 配置解析
+
+```typescript
+// 文档输入支持字符串（URL）或对象形式
+type DocInput = string | { url: string; name?: string }
+
+// feature 可以是数组（简单形式）或分类对象
+type FeatureValue = DocInput[] | {
+  prd?: DocInput[]
+  design?: DocInput[]
+  api?: DocInput[]
+  test?: DocInput[]
+}
+
+interface GroworkConfigV2 {
+  feishu?: {
+    appId: string
+    appSecret: string
+    domain?: 'feishu' | 'lark'
+  }
+  notion?: { token: string }
+  outputDir?: string           // 输出根目录，默认 "docs"
+  custom?: DocInput[]
+  versions?: {
+    [version: string]: {
+      [feature: string]: FeatureValue
+    }
+  }
+}
+
+// 同步选项
+interface SyncOptions {
+  version?: string
+  feature?: string
+  custom?: boolean
+}
+```
+
+### 兼容性
+
+- 1.1.0 配置格式与 1.0.0 不兼容
+- ✅ 提供 `growork migrate` 命令将 1.0.0 配置迁移到 1.1.0
+- 迁移时自动备份原配置到 `growork.config.yaml.v1.backup`
+
+## 验收标准
+
+- [x] 支持 custom 全局文档同步
+- [x] 支持 versions 层级配置解析
+- [x] 支持 prd/design/api/test 四种文档类型
+- [x] 支持简写（只写 URL）和完整写法
+- [x] name 默认从文档标题获取（从 Markdown 内容提取 H1 标题）
+- [x] 输出目录按 `版本/feature/类型/` 结构
+- [x] `--ver` 参数过滤指定版本
+- [x] `-f/--feature` 参数过滤指定功能
+- [x] `-c/--custom` 参数只同步全局文档
+- [x] `growork migrate` 命令支持 1.0.0 到 1.1.0 迁移
+- [x] `growork list` 命令按层级展示文档列表
+- [x] 支持自定义输出根目录（outputDir 配置）
+
+## 开放问题
+
+- [ ] 是否需要支持多个配置文件？
+- [ ] 是否支持增量同步（仅同步有变更的文档）？
+- [ ] 凭证是否改用环境变量？

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/docs/prd-template.md

@@ -0,0 +1,65 @@
+# [产品名称] v[版本] PRD
+
+## 概述
+
+| 项目 | 内容 |
+|-----|-----|
+| 产品名称 | xxx |
+| 版本 | v1.0 |
+| 产品形态 | CLI / Web / App |
+
+## 背景与目标
+
+### 背景
+
+为什么做？当前痛点是什么？
+
+### 目标
+
+做成什么样？成功标准是什么？
+
+## 用户场景
+
+谁在什么场景下用？解决什么问题？
+
+## 功能需求
+
+### 功能列表
+
+| 功能 | 说明 | 优先级 |
+|-----|-----|-------|
+| 功能A | 做什么 | P0 |
+| 功能B | 做什么 | P1 |
+
+### 核心流程
+
+```
+用户操作 → 系统处理 → 输出结果
+```
+
+## 技术设计
+
+### 技术选型
+
+| 用途 | 选择 |
+|-----|-----|
+| 语言 | xxx |
+| 框架 | xxx |
+
+### 项目结构
+
+```
+project/
+├── src/
+└── docs/
+```
+
+## 验收标准
+
+- [ ] 场景1：预期结果
+- [ ] 场景2：预期结果
+
+## 开放问题
+
+- [ ] 待确认问题1
+- [ ] 待确认问题2

package/growork.config.yaml

@@ -1,43 +1,46 @@
-# Growork 配置文件
+# Growork v2.0 配置文件（从 v1.0 迁移）
 
-# 飞书应用凭证
 feishu:
   appId: "cli_a9f679f7d8389ed1"
   appSecret: "M75JzaxTI8kAn50Ss1GgEbBVAIP551RX"
-  domain: "lark"  # 使用国际版 Lark
+  domain: "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"
+# 输出根目录
+outputDir: "test_export"
 
-  # 后端AI文档 (飞书)
-  - name: backend-ai
-    type: feishu
-    url: "https://romangic.sg.larksuite.com/wiki/ZiCuw4GnXiBsPnkN159lNE0mgLe"
-    output: "test/backend-ai.md"
+# 原 docs 列表（可手动整理到 versions 中）
+custom:
+  - url: "https://romangic.sg.larksuite.com/wiki/UrBKwmmJNizGlzkoFU3l90wxgOd"
+    name: "prd-5spread"
+  - url: "https://romangic.sg.larksuite.com/wiki/ZiCuw4GnXiBsPnkN159lNE0mgLe"
+    name: "backend-ai"
+  - url: "https://romangic.sg.larksuite.com/wiki/EB9NwMUP2ipF0Pk0SZBlXOS5gcb"
+    name: "push"
+  - url: "https://www.notion.so/2f91190afab5806aa853c073a24edd28"
+    name: "push-prd-notion"
+  - url: "https://romangic.sg.larksuite.com/wiki/QtUuwKpXyiFmAckrIaOlqRDNgJe"
+    name: "backend-api"
+  - url: "https://www.notion.so/2f91190afab580a8acf1daf80ae02ac6"
+    name: "test-cases"
 
-  # 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"
+# 版本化文档
+versions:
+  v1.0:
+    五牌阵:
+      prd:
+        - "https://romangic.sg.larksuite.com/wiki/UrBKwmmJNizGlzkoFU3l90wxgOd"
+      api:
+        - "https://romangic.sg.larksuite.com/wiki/ZiCuw4GnXiBsPnkN159lNE0mgLe"
+    Push通知:
+      prd:
+        - "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.0.1",
+  "version": "1.1.2",
   "description": "将飞书文档同步到本地，为 AI Agent 提供完整上下文",
   "main": "dist/index.js",
   "type": "module",

package/src/commands/init.ts

@@ -4,11 +4,7 @@ import chalk from 'chalk';
 import { getConfigPath, configExists, getDefaultConfig } from '../utils/config.js';
 
 const DIRS_TO_CREATE = [
-  'docs/product',
-  'docs/design',
-  'docs/api',
-  'docs/tech',
-  'docs/test',
+  'docs/custom',
 ];
 
 export async function initCommand(): Promise<void> {

package/src/commands/list.ts

@@ -1,7 +1,10 @@
-import * as fs from 'fs';
-import * as path from 'path';
 import chalk from 'chalk';
-import { loadConfig, configExists } from '../utils/config.js';
+import { configExists, loadConfigV2, parseDocInput } from '../utils/config.js';
+
+function shortenUrl(url: string, maxLen: number = 40): string {
+  if (url.length <= maxLen) return url;
+  return url.slice(0, maxLen - 3) + '...';
+}
 
 export async function listCommand(): Promise<void> {
   if (!configExists()) {
@@ -9,29 +12,59 @@ export async function listCommand(): Promise<void> {
     process.exit(1);
   }
 
-  const config = loadConfig();
-  const cwd = process.cwd();
+  const config = loadConfigV2();
 
   console.log(chalk.blue('📋 文档列表\n'));
 
-  console.log(chalk.gray('  名称'.padEnd(18) + '类型'.padEnd(10) + '输出路径'.padEnd(30) + '状态'));
-  console.log(chalk.gray('  ' + '-'.repeat(70)));
+  let totalCount = 0;
 
-  for (const doc of config.docs) {
-    const outputPath = path.join(cwd, doc.output);
-    const exists = fs.existsSync(outputPath);
+  // 显示 custom 文档
+  if (config.custom && config.custom.length > 0) {
+    console.log(chalk.cyan('📁 custom (全局文档)'));
+    for (const input of config.custom) {
+      const { url, name } = parseDocInput(input);
+      const displayName = name || shortenUrl(url);
+      console.log(chalk.gray(`    - ${displayName}`));
+      totalCount++;
+    }
+    console.log('');
+  }
 
-    const status = exists
-      ? chalk.green('已同步')
-      : chalk.yellow('未同步');
+  // 显示 versions 文档
+  if (config.versions) {
+    for (const [version, features] of Object.entries(config.versions)) {
+      console.log(chalk.cyan(`📁 ${version}`));
 
-    const name = `  ${doc.name}`.padEnd(18);
-    const type = doc.type.padEnd(10);
-    const output = doc.output.padEnd(30);
+      for (const [feature, value] of Object.entries(features)) {
+        if (Array.isArray(value)) {
+          // 简单 feature
+          console.log(chalk.white(`  └─ ${feature}`));
+          for (const input of value) {
+            const { url, name } = parseDocInput(input);
+            const displayName = name || shortenUrl(url, 30);
+            console.log(chalk.gray(`       - ${displayName}`));
+            totalCount++;
+          }
+        } else {
+          // 分类型的 feature
+          console.log(chalk.white(`  └─ ${feature}`));
+          for (const docType of ['prd', 'design', 'api', 'test'] as const) {
+            const docInputs = value[docType];
+            if (!docInputs || docInputs.length === 0) continue;
 
-    console.log(`${name}${chalk.gray(type)}${output}${status}`);
+            console.log(chalk.yellow(`       ${docType}:`));
+            for (const input of docInputs) {
+              const { url, name } = parseDocInput(input);
+              const displayName = name || shortenUrl(url, 25);
+              console.log(chalk.gray(`         - ${displayName}`));
+              totalCount++;
+            }
+          }
+        }
+      }
+      console.log('');
+    }
   }
 
-  console.log('');
-  console.log(chalk.gray(`共 ${config.docs.length} 个文档配置`));
+  console.log(chalk.gray(`共 ${totalCount} 个文档配置`));
 }