growork 1.0.1 → 1.1.1

package/docs/product/prd-1.0.0.md

@@ -0,0 +1,86 @@
+# GroWork 1.0.0 PRD
+
+## 概述
+
+| 项目 | 内容 |
+|-----|-----|
+| 产品名称 | GroWork |
+| 版本 | 1.0.0 |
+| 产品形态 | CLI 命令行工具 |
+| 技术栈 | Node.js / TypeScript |
+
+## 背景与目标
+
+### 背景
+
+AI Agent 开发时代，PRD、设计稿、接口文档、技术方案分散在 Lark/Notion/Figma 等平台，无法在一个工程内闭环。
+
+### 目标
+
+实现产品开发全流程文档在一个文件夹下闭环，让 AI Agent 一次性获取完整上下文。
+
+## 用户场景
+
+使用 Claude Code 等 Agent 工具的开发者，希望同步远程文档到本地，让 AI 直接读取进行开发。
+
+## 功能需求
+
+### 功能列表
+
+| 命令 | 说明 | 状态 |
+|-----|-----|-----|
+| `growork init` | 生成配置文件和目录结构 | ✅ |
+| `growork sync` | 同步所有配置的文档 | ✅ |
+| `growork sync <name>` | 同步指定文档 | ✅ |
+| `growork list` | 列出所有文档及状态 | ✅ |
+
+### 支持的文档类型
+
+| 类型 | 说明 |
+|-----|-----|
+| `feishu` | Lark 文档和知识库 |
+| `notion` | Notion 页面（含内嵌数据库） |
+
+### 核心流程
+
+```
+growork init → 编辑配置文件 → growork sync → AI 读取 docs/ 目录
+```
+
+## 技术设计
+
+### 技术选型
+
+| 用途 | 选择 |
+|-----|-----|
+| CLI 框架 | Commander.js |
+| Lark SDK | @larksuiteoapi/node-sdk |
+| Notion SDK | @notionhq/client + notion-to-md |
+| 配置解析 | yaml |
+| 构建工具 | tsup |
+
+### 项目结构
+
+```
+src/
+├── index.ts           # CLI 入口
+├── commands/          # 命令实现
+├── services/          # Lark/Notion API
+└── utils/             # 配置解析
+```
+
+## 验收标准
+
+- [x] 能同步 Lark 文档和知识库到本地 Markdown
+- [x] 能同步 Notion 页面到本地 Markdown
+- [x] 支持批量同步和单个同步
+- [x] 单文档同步 < 5 秒
+
+## 开放问题
+
+- [ ] 是否支持增量同步？
+- [ ] 凭证是否改用环境变量？
+
+## 后续版本
+
+1.1.0 已发布，引入版本和 feature 层级结构，详见 [prd-1.1.0.md](./prd-1.1.0.md)

package/docs/product/prd-1.1.0.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/product/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,41 @@
-# 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"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "growork",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "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} 个文档配置`));
 }

package/src/commands/sync.ts

@@ -1,7 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
-import { loadConfig } from '../utils/config.js';
+import { loadConfigV2, normalizeConfig, sanitizeFileName, SyncOptions, NormalizedDoc } from '../utils/config.js';
 import { FeishuService } from '../services/feishu.js';
 import { NotionService } from '../services/notion.js';
 
@@ -14,44 +14,58 @@ function clearLine(): void {
   }
 }
 
-export async function syncCommand(docName?: string): Promise<void> {
-  const config = loadConfig();
+function extractTitleFromMarkdown(content: string): string {
+  const match = content.match(/^#\s+(.+)$/m);
+  return match ? match[1].trim() : '未命名文档';
+}
+
+export async function syncCommand(options: SyncOptions = {}): Promise<void> {
+  const config = loadConfigV2();
+  const docs = normalizeConfig(config, options);
+
+  if (docs.length === 0) {
+    console.log(chalk.yellow('⚠️  没有找到匹配的文档'));
+    return;
+  }
+
   const feishuService = config.feishu ? new FeishuService(config.feishu) : null;
   const notionService = config.notion ? new NotionService(config.notion) : null;
 
-  let docsToSync = config.docs;
+  // 检查凭证
+  const hasFeishuDocs = docs.some(d => d.type === 'feishu');
+  const hasNotionDocs = docs.some(d => d.type === 'notion');
 
-  if (docName) {
-    const doc = config.docs.find(d => d.name === docName);
-    if (!doc) {
-      console.log(chalk.red(`❌ 未找到名为 "${docName}" 的文档配置`));
-      console.log(chalk.gray(`可用的文档: ${config.docs.map(d => d.name).join(', ')}`));
-      process.exit(1);
-    }
-    docsToSync = [doc];
+  if (hasFeishuDocs && !feishuService) {
+    throw new Error('配置文件缺少飞书凭证 (feishu.appId, feishu.appSecret)');
+  }
+  if (hasNotionDocs && !notionService) {
+    throw new Error('配置文件缺少 Notion 凭证 (notion.token)');
   }
 
   console.log(chalk.blue('📄 开始同步文档...\n'));
 
   let successCount = 0;
 
-  for (const doc of docsToSync) {
-    process.stdout.write(chalk.gray(`  ⏳ ${doc.name.padEnd(15)} → ${doc.output}`));
+  for (const doc of docs) {
+    const displayName = doc.name || doc.url.slice(-20);
+    process.stdout.write(chalk.gray(`  ⏳ ${displayName}`));
 
     try {
       let content: string;
       if (doc.type === 'feishu') {
-        if (!feishuService) throw new Error('飞书服务未配置');
-        content = await feishuService.getDocumentAsMarkdown(doc.url);
-      } else if (doc.type === 'notion') {
-        if (!notionService) throw new Error('Notion 服务未配置');
-        content = await notionService.getPageAsMarkdown(doc.url);
+        content = await feishuService!.getDocumentAsMarkdown(doc.url);
       } else {
-        throw new Error(`不支持的文档类型: ${doc.type}`);
+        content = await notionService!.getPageAsMarkdown(doc.url);
       }
 
-      const outputPath = path.join(process.cwd(), doc.output);
+      // 从 markdown 提取标题
+      const title = doc.name || extractTitleFromMarkdown(content);
+      const safeTitle = sanitizeFileName(title);
+
+      // 替换占位符生成最终路径
+      const outputPath = path.join(process.cwd(), doc.outputPath.replace('{title}', safeTitle));
       const outputDir = path.dirname(outputPath);
+
       if (!fs.existsSync(outputDir)) {
         fs.mkdirSync(outputDir, { recursive: true });
       }
@@ -59,19 +73,19 @@ export async function syncCommand(docName?: string): Promise<void> {
       fs.writeFileSync(outputPath, content, 'utf-8');
 
       clearLine();
-      console.log(chalk.green(`  ✓ ${doc.name.padEnd(15)} → ${doc.output}`));
+      console.log(chalk.green(`  ✓ ${safeTitle.padEnd(25)} → ${path.relative(process.cwd(), outputPath)}`));
       successCount++;
     } catch (error) {
       clearLine();
       const errorMessage = error instanceof Error ? error.message : String(error);
-      console.log(chalk.red(`  ✗ ${doc.name.padEnd(15)} → ${errorMessage}`));
+      console.log(chalk.red(`  ✗ ${displayName.padEnd(25)} → ${errorMessage}`));
     }
   }
 
   console.log('');
-  if (successCount === docsToSync.length) {
-    console.log(chalk.green(`✅ 同步完成，共 ${docsToSync.length} 个文档`));
+  if (successCount === docs.length) {
+    console.log(chalk.green(`✅ 同步完成，共 ${docs.length} 个文档`));
   } else {
-    console.log(chalk.yellow(`⚠️  同步完成: ${successCount}/${docsToSync.length} 个文档成功`));
+    console.log(chalk.yellow(`⚠️  同步完成: ${successCount}/${docs.length} 个文档成功`));
   }
 }