md-to-mowen 1.4.0 → 1.4.1

package/.claude/skills/e2e-dev/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: e2e-dev
+description: >
+  端到端开发闭环：从需求拆解到 Issue 关闭的全自动化流程。
+  当用户说"端到端"、"e2e"、"帮我把这个需求做完"、"处理这个 issue"、
+  "从头到尾搞定"、"全流程开发"时触发此 skill。
+  支持输入 Issue 编号或需求描述文本。
+---
+
+# 端到端开发（e2e-dev）
+
+以 Issue 为驱动，自动执行从需求拆解到代码合并、Issue 关闭的完整开发闭环。
+
+## 输入
+
+用户通过 `/e2e-dev` 调用时，提供以下任一输入：
+
+- **Issue 编号**：如 `#7`，直接读取 Issue 内容
+- **需求描述**：自由文本，skill 会先创建 Issue 再继续
+- **无输入**：提示用户提供需求或 Issue 编号
+
+## 流程总览
+
+```
+Phase 1: 需求拆解 → Phase 2: 代码开发 → Phase 3: 测试验证
+                    ↑                    ↑
+                    └────── 修复 ─────────┘
+                                        ↓
+                 Phase 6: 关闭 Issue ← Phase 5: 复测合并 ← Phase 4: 审核修复
+```
+
+每个阶段完成后向用户汇报进展，获得确认后进入下一阶段。
+遇到无法自行解决的问题时，**暂停并请求人工协助**，不要猜测或卡死。
+
+---
+
+## Phase 1: 需求拆解与验收
+
+**目标**：以产品视角理解需求，拆解为可测试的验收条件。
+
+### 步骤
+
+1. **读取 Issue**
+
+   ```bash
+   gh issue view <number>
+   ```
+
+   若用户给的是需求描述而非 Issue 编号，先创建 Issue：
+
+   ```bash
+   gh issue create --title "<标题>" --body "<描述>" --label "enhancement"
+   ```
+
+2. **拆解验收条件**
+   从 Issue 描述中提取：
+   - **功能需求**：要做什么
+   - **非功能需求**：性能、兼容性等约束
+   - **验收标准**（AC）：每条必须可测试、可验证
+
+3. **向用户确认**
+   展示拆解结果，格式：
+
+   ```
+   📋 需求拆解：#<number> <标题>
+
+   ## 验收条件
+   - [ ] AC1: ...
+   - [ ] AC2: ...
+   - [ ] AC3: ...
+
+   请确认以上拆解是否准确，或补充修改。
+   ```
+
+4. **等待用户确认** 后进入 Phase 2
+
+### 暂停条件
+
+- Issue 描述模糊，无法拆解出明确的验收条件
+- 需求涉及项目中不熟悉的领域
+
+---
+
+## Phase 2: 代码开发
+
+**目标**：基于验收条件，用 TDD 方式完成功能开发。
+
+### 步骤
+
+1. **创建特征分支**
+
+   ```bash
+   git checkout dev
+   git pull origin dev
+   git checkout -b <issueId>-<中文slug>
+   ```
+
+   分支命名示例：`7-支持代码块渲染`
+
+2. **先写测试**（TDD）
+   - 根据验收条件编写测试用例，放在 `tests/` 对应目录下
+   - 测试文件命名：`<feature-name>.test.ts`
+   - 确保测试**先失败**（红）
+
+3. **实现功能**
+   - 编写最小代码使测试通过（绿）
+   - 重构代码保持质量（重构）
+   - 遵循项目的 TypeScript 规范和已有代码风格
+
+4. **提交代码**
+   遵循提交信息规范：
+   ```bash
+   git add <具体文件>
+   git commit -m "feat: <中文描述> (closes #<issueId>)"
+   ```
+   > `closes #<issueId>` 会在 PR 合并后自动关闭 Issue
+
+### 暂停条件
+
+- 实现方案有多种选择，需要用户决策
+- 需要修改不熟悉的核心模块
+- 遇到阻塞性的技术问题
+
+---
+
+## Phase 3: 测试验证
+
+**目标**：确保所有测试通过，代码质量检查无误。
+
+### 步骤
+
+1. **运行完整检查**
+
+   ```bash
+   npm test              # 单元测试
+   npm run check         # TypeScript 类型检查
+   npm run lint:pii      # PII 扫描
+   ```
+
+2. **分析结果**
+   - **全部通过** → 进入 Phase 4
+   - **有失败** → 分析失败原因，回到 Phase 2 修复
+
+3. **回到 Phase 2 的条件**
+   - 测试断言失败：修改代码逻辑
+   - 类型错误：修复类型定义
+   - PII 告警：脱敏处理
+
+### 循环规则
+
+Phase 2 ↔ Phase 3 构成内循环，直到所有检查通过。
+最多循环 **3 轮**，仍未解决则暂停请求人工协助。
+
+---
+
+## Phase 4: 审核与修复
+
+**目标**：自审代码质量，评估风险，发现潜在问题。
+
+### 步骤
+
+1. **执行 Code Review**
+   读取 `references/review-checklist.md`，逐项检查：
+   - 代码质量：命名、结构、重复、错误处理
+   - 架构合理性：是否符合项目分层、是否引入不当耦合
+   - 测试覆盖：验收条件是否全部覆盖、边界情况
+   - 安全性：PII 泄露、注入风险、依赖安全
+
+2. **输出审核报告**
+
+   ```
+   🔍 Code Review 报告
+
+   ## 发现的问题
+   - [严重] ...
+   - [建议] ...
+
+   ## 风险评估
+   - 低/中/高
+
+   ## 结论
+   - ✅ 无阻塞问题，可进入合并
+   - ⚠️ 有 N 个问题需修复后重新提交
+   ```
+
+3. **处理审核结果**
+   - **无问题** → 进入 Phase 5
+   - **有问题** → 修复后回到 Phase 2，重新走 Phase 3
+
+### 暂停条件
+
+- 涉及架构级改动，需要人工决策
+- 存在安全风险，需要人工确认
+- 代码改动范围超出预期，需要重新评估需求
+
+---
+
+## Phase 5: 复测与合并
+
+**目标**：最终验证，创建 PR 并合并到 dev 分支。
+
+### 步骤
+
+1. **最终测试**（确保 Phase 4 的修复没有引入新问题）
+
+   ```bash
+   npm test
+   npm run check
+   npm run lint:pii
+   ```
+
+2. **推送分支**
+
+   ```bash
+   git push origin <branch-name>
+   ```
+
+3. **创建 PR**
+
+   ```bash
+   gh pr create --base dev --title "feat: <描述> (#<issueId>)" --body "..."
+   ```
+
+   PR body 包含：
+   - 关联的 Issue：`Closes #<issueId>`
+   - 改动摘要
+   - 测试结果
+
+4. **合并 PR**
+
+   ```bash
+   gh pr merge --squash --delete-branch
+   ```
+
+5. **切换回 dev 并拉取最新**
+   ```bash
+   git checkout dev
+   git pull origin dev
+   ```
+
+### 暂停条件
+
+- CI 检查失败，需要排查
+- PR 存在合并冲突，需要手动解决
+
+---
+
+## Phase 6: 关闭 Issue
+
+**目标**：记录完成状态，干净退出。
+
+### 步骤
+
+1. **添加完成评论**
+
+   ```bash
+   gh issue comment <number> --body "✅ 已完成，PR #<pr-number> 已合并到 dev。"
+   ```
+
+2. **关闭 Issue**（如果 commit message 中没有 `closes` 关键字）
+
+   ```bash
+   gh issue close <number>
+   ```
+
+3. **输出总结**
+
+   ```
+   🎉 端到端完成！
+
+   Issue:    #<number> <title>
+   PR:       #<pr-number>
+   分支:     <branch-name> (已删除)
+   状态:     ✅ 已关闭
+
+   改动文件：
+   - src/...
+   - tests/...
+   ```
+
+---
+
+## 异常处理
+
+### 测试持续失败
+
+Phase 2 ↔ Phase 3 循环 3 轮后仍未通过：
+
+```
+⚠️ 测试在 3 轮修复后仍未通过，需要人工协助。
+
+失败的测试：<test-name>
+错误信息：<error-message>
+
+请检查：
+1. 验收条件是否理解有误？
+2. 实现方案是否需要调整？
+3. 测试用例本身是否有问题？
+```
+
+### 审核发现阻塞问题
+
+Phase 4 发现严重问题但无法自行修复：
+
+```
+⚠️ Code Review 发现阻塞性问题，需要人工决策。
+
+问题：<description>
+影响范围：<scope>
+建议方案：<suggestion>
+
+请确认如何处理。
+```
+
+### 合并冲突
+
+Phase 5 遇到合并冲突：
+
+```
+⚠️ 分支存在合并冲突，需要手动解决。
+
+冲突文件：
+- <file1>
+- <file2>
+
+建议：请先解决冲突后告诉我继续，或我尝试自动解决。
+```
+
+---
+
+## 项目约定
+
+本 skill 运行时自动遵循项目的 `CLAUDE.md` 中定义的规则：
+
+- **分支策略**：`dev` 为开发主分支，特征分支 `{issueId}-{slug}`
+- **提交规范**：`feat:` / `fix:` / `chore:` / `docs:` / `test:`
+- **版本管理**：semantic-release 自动管理，禁止手动改版本号
+- **PII 规则**：绝对路径、API Key、`.env` 追踪等均会被拦截

package/.claude/skills/e2e-dev/references/review-checklist.md

@@ -0,0 +1,92 @@
+# Code Review 检查清单
+
+在 Phase 4（审核与修复）阶段使用此清单逐项检查。每项标记 ✅ 通过 / ❌ 不通过 / ⏭️ 不适用。
+
+---
+
+## 1. 代码质量
+
+| #   | 检查项            | 说明                                       |
+| --- | ----------------- | ------------------------------------------ |
+| 1.1 | 命名清晰          | 变量、函数、类型名能自解释，不用缩写       |
+| 1.2 | 函数职责单一      | 每个函数只做一件事，不超过 50 行           |
+| 1.3 | 无重复代码        | 相同逻辑已提取为公共函数/工具              |
+| 1.4 | 错误处理完整      | 异步操作有 try-catch，API 调用有错误码处理 |
+| 1.5 | 无魔法数字/字符串 | 常量已提取并命名                           |
+| 1.6 | 类型安全          | 无 `any` 滥用，泛型使用合理                |
+
+## 2. 架构与设计
+
+| #   | 检查项       | 说明                                                               |
+| --- | ------------ | ------------------------------------------------------------------ |
+| 2.1 | 符合项目分层 | 遵循 `src/` 下的模块划分（pipeline / publish / noteatom / shared） |
+| 2.2 | 无不当耦合   | 新代码没有反向依赖（如 shared 模块依赖 publish）                   |
+| 2.3 | 接口设计合理 | 导出的 API 签名稳定、向后兼容                                      |
+| 2.4 | 依赖合理     | 没有引入不必要的第三方依赖                                         |
+| 2.5 | 副作用可控   | 文件 I/O、网络请求等副作用集中在明确的位置                         |
+
+## 3. 测试覆盖
+
+| #   | 检查项         | 说明                                             |
+| --- | -------------- | ------------------------------------------------ |
+| 3.1 | 验收条件全覆盖 | Phase 1 拆解的每条 AC 都有对应测试               |
+| 3.2 | 边界情况       | 空输入、异常输入、边界值都有测试                 |
+| 3.3 | 测试独立       | 每个测试用例不依赖其他用例的执行顺序             |
+| 3.4 | 测试可读       | 测试名描述了行为（`should do X when Y`）         |
+| 3.5 | 无硬编码路径   | 测试中使用 `tmp` 目录或 mock，不依赖本机绝对路径 |
+
+## 4. 安全性
+
+| #   | 检查项        | 说明                                      |
+| --- | ------------- | ----------------------------------------- |
+| 4.1 | 无 PII 泄露   | 代码中无本机绝对路径、API Key、Token      |
+| 4.2 | `.env` 未追踪 | `.env` 在 `.gitignore` 中，未被 `git add` |
+| 4.3 | 输入校验      | 外部输入（文件路径、用户参数）有校验      |
+| 4.4 | 依赖安全      | 新依赖无已知漏洞（`npm audit`）           |
+
+## 5. 可维护性
+
+| #   | 检查项     | 说明                                     |
+| --- | ---------- | ---------------------------------------- |
+| 5.1 | 注释有价值 | 复杂逻辑有注释说明"为什么"，而非"做什么" |
+| 5.2 | 文档同步   | 新增的公共 API 有 JSDoc / README 说明    |
+| 5.3 | 日志适当   | 关键路径有日志输出，便于调试             |
+| 5.4 | 配置外置   | 可变参数通过配置/环境变量传入，非硬编码  |
+
+## 6. 提交规范
+
+| #   | 检查项       | 说明                                          |
+| --- | ------------ | --------------------------------------------- |
+| 6.1 | 提交信息格式 | 符合 `feat:` / `fix:` / `test:` 等前缀规范    |
+| 6.2 | 提交粒度合理 | 一个提交完成一个逻辑变更，不混杂无关改动      |
+| 6.3 | 无调试残留   | `console.log`、`debugger`、注释掉的代码已清理 |
+
+---
+
+## 审核结论模板
+
+```markdown
+## Code Review 结果
+
+### 通过项
+
+- ✅ 1.1 命名清晰
+- ✅ 1.2 函数职责单一
+- ...
+
+### 问题项
+
+- ❌ 3.2 缺少边界测试：未测试空数组输入
+- ❌ 4.1 路径泄露：`src/foo.ts:42` 包含 `/Users/xxx/`
+
+### 风险评估
+
+- **低风险**：无阻塞问题
+- **中风险**：有 1-2 个需修复的问题
+- **高风险**：有架构或安全阻塞问题
+
+### 建议
+
+- 修复以上 ❌ 项后重新提交
+- 或确认 ⏭️ 项为不适用
+```

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "md-to-mowen",
-  "version": "1.2.1",
+  "version": "1.4.0",
   "description": "将 Markdown（GFM）转换为墨问笔记的 CLI 工具，支持一键发布、智能编辑、图片处理、表格渲染等功能",
   "skills": [
     {

package/README.md

@@ -1,169 +1,126 @@
 # md-to-mowen
 
-[![npm version](https://img.shields.io/npm/v/md-to-mowen.svg)](https://www.npmjs.com/package/md-to-mowen)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+将 Markdown（GFM）转换为墨问笔记的 CLI 工具。
 
-将 Markdown（GFM）一键发布为墨问笔记的 CLI 工具。
-
-![image-20260514130051810](./images/readme_header.png)
-
-## 功能特性
-
-- **一键发布** — 单文件或整个目录批量发布
-- **智能编辑** — 自动追踪文件与笔记映射，再次发布自动进入编辑模式
-- **图片处理** — 本地图片/远程 URL 自动上传到墨问 OSS
-- **表格渲染** — Markdown 表格自动渲染为高清 PNG 图片
-- **双向转换** — 支持 NoteAtom JSON 导出为 Markdown
-- **隐私控制** — 独立命令设置笔记公开/私密状态
-- **配置持久化** — 保存常用选项，无需每次重复输入
-
-## 快速开始
-
-### 安装
+## 安装
 
 ```bash
 npm install -g md-to-mowen
 ```
 
-### 配置 API Key
+或使用 npx：
 
 ```bash
-md-to-mowen config
+npx md-to-mowen --version
 ```
 
-按提示在微信小程序「墨问」中获取 API Key：个人主页 → 开发者 → 我的 API Key
+## 使用
 
-### 发布笔记
+### 发布文章
 
 ```bash
-# 发布单个文件
-md-to-mowen publish -i article.md
+# 基本发布
+md-to-mowen publish article.md
 
-# 发布整个目录（递归扫描子目录）
-md-to-mowen publish -i ./posts
+# 指定封面图
+md-to-mowen publish article.md --cover cover.png
 
-# 添加标签
-md-to-mowen publish -i article.md --tags "tech,ai"
+# 严格模式
+md-to-mowen publish article.md --strict
 
-# 自动发布（非草稿）
-md-to-mowen publish -i article.md --auto-publish
+# 跳过表格转换
+md-to-mowen publish article.md --no-table
 ```
 
-发布成功后会显示笔记 ID 和访问地址。再次发布同一文件会自动更新已有笔记。
+### 检查文章质量
 
-## CLI 命令
+```bash
+# 基本检查
+md-to-mowen lint article.md
 
-### `publish` — 发布笔记
+# 严格模式
+md-to-mowen lint article.md --strict
 
-```bash
-md-to-mowen publish -i <path> [options]
+# 自定义字数范围
+md-to-mowen lint article.md --min-chars 200 --max-chars 5000
 ```
 
-| 选项                         | 说明                                   |
-| ---------------------------- | -------------------------------------- |
-| `-i, --input <path>`         | Markdown 文件路径或目录（必填）        |
-| `--note-id <id>`             | 编辑已有笔记（全量替换内容）           |
-| `--tags <tags>`              | 标签，逗号分隔（如 `tech,ai`）         |
-| `--auto-publish`             | 自动发布，非草稿状态                   |
-| `--dry-run`                  | 走完流水线但不调用 API                 |
-| `--cache-dir <dir>`          | 保存流水线产物用于调试                 |
-| `--code-block-style <style>` | 代码块样式：`paragraph` 或 `codeblock` |
-| `--no-recursive`             | 批量发布时不递归扫描子目录             |
-
-### `privacy` — 设置隐私状态
+### 上传图片
 
 ```bash
-# 通过笔记 ID
-md-to-mowen privacy --note-id <id> --visibility public|private
-
-# 通过文件路径（需要元数据支持）
-md-to-mowen privacy -i article.md --visibility public
+md-to-mowen upload image.png
 ```
 
-### `to-markdown` — NoteAtom 转 Markdown
+## 配置
 
-```bash
-md-to-mowen to-markdown -i note.json -o output.md
-```
+### API Key
 
-### `config` — 配置 API Key
+设置环境变量：
 
 ```bash
-md-to-mowen config
+export MOWEN_API_KEY=your-api-key
 ```
 
-## 配置文件
+或在命令中指定：
 
-在 Markdown 文件同目录下创建 `.md-to-mowen.json` 保存常用选项：
-
-```json
-{
-  "defaultTags": "tech,programming",
-  "autoPublish": false,
-  "cacheDir": "./.cache",
-  "codeBlockStyle": "paragraph"
-}
+```bash
+md-to-mowen publish article.md --api-key your-api-key
 ```
 
-CLI 参数优先级高于配置文件。
-
-## Markdown 支持
-
-| 语法                           | 输出                        |
-| ------------------------------ | --------------------------- |
-| 标题 H1-H6                     | 粗体段落（层级丢失）        |
-| 有序/无序列表                  | 带前缀的段落                |
-| 引用块                         | 墨问引用块                  |
-| **粗体** / _斜体_ / ~~删除线~~ | 对应标记                    |
-| `行内代码`                     | 代码标记                    |
-| [链接](url)                    | 链接标记                    |
-| 图片                           | 上传后插入                  |
-| 代码块                         | 每行带代码标记 / 渲染为图片 |
-| 表格                           | 渲染为 PNG 图片             |
-
-## 项目结构
+## 质量检查项
 
-```
-md-to-mowen/
-├── src/
-│   ├── cli/                    # CLI 入口
-│   ├── commands/               # 命令实现
-│   ├── pipeline/               # Markdown → HAST → MAST
-│   ├── mast/                   # 中间 AST 类型与序列化
-│   ├── noteatom/               # NoteAtom 类型和双向转换
-│   ├── mowen/                  # API 客户端和上传
-│   ├── publish/                # 发布流水线编排
-│   └── shared/                 # 工具函数
-├── tests/                      # 单元测试
-└── docs/                       # 学习指南与架构文档
-```
+1. **配图检查** - 必须有封面图或内嵌图片
+2. **表格检查** - 有表格必须已转换为图片
+3. **标题层级** - H1→H2→H3，不能跳级
+4. **文章长度** - 建议 100-10000 字
+5. **特殊标记** - 无 TODO/FIXME 等占位符
 
 ## 开发
 
 ```bash
+# 克隆仓库
+git clone https://github.com/momolibrary/md-to-mowen.git
+cd md-to-mowen
+
 # 安装依赖
 npm install
 
-# 运行测试
-npm test
-
-# 类型检查
-npm run check
-
 # 构建
 npm run build
 
-# 本地链接
-npm link
+# 测试
+npm test
+
+# 代码检查
+npm run lint
 ```
 
-## 相关链接
+## 项目结构
 
-- [墨问开放 API 文档](https://mowen.apifox.cn/)
-- [学习指南与架构文档](docs/README.md)
+```
+md-to-mowen/
+├── src/
+│   ├── cli.ts              # CLI 入口
+│   ├── index.ts            # 核心导出
+│   ├── commands/
+│   │   └── publish.ts      # 发布命令
+│   └── core/
+│       ├── api.ts          # 墨问 API
+│       ├── auth.ts         # 授权管理
+│       ├── extract-prompt.ts # 提示词提取
+│       ├── lint.ts         # 质量检查
+│       ├── markdown.ts     # Markdown 转换
+│       ├── table.ts        # 表格处理
+│       └── upload.ts       # 图片上传
+├── tests/
+│   ├── fixtures/           # 测试种子
+│   ├── unit/               # 单元测试
+│   └── integration/        # 集成测试
+└── skill/
+    ├── SKILL.md            # Claude Code Skill
+    └── publish.sh          # Skill wrapper
+```
 
 ## License
 
 MIT
-
-# md-to-mowen

package/dist/cli/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":""}

package/dist/cli/index.js

@@ -361,3 +361,4 @@ program
     }
 });
 program.parse();
+//# sourceMappingURL=index.js.map