@aigne/doc-smith 0.9.8-alpha.0 → 0.9.8-alpha.10

package/CLAUDE.md

@@ -0,0 +1,43 @@
+# 项目自定义要求
+
+## 项目概述
+
+本项目用于维护和管理 Claude Code Agent Skills。
+
+## 核心规则
+
+1. **项目结构**
+   - 每个文件夹是一个独立的 Skill
+   - 每个 Skill 必须包含 `SKILL.md` 文件作为主文档
+
+2. **语言要求**
+   - 所有 Skill 的提示词必须使用中文编写
+
+3. **开发规范**
+   - 创建或修改 Skill 时，必须使用 `/skill-creator` 获取最佳实践和开发指导
+   - 遵循 skill-creator 中定义的所有规范和要求
+
+## 工作流程
+
+### 创建新 Skill
+
+```bash
+# 1. 使用 skill-creator 获取指导
+/skill-creator
+
+# 2. 按照 skill-creator 的指导创建 Skill 文件夹和内容
+```
+
+### 修改现有 Skill
+
+```bash
+# 1. 如需要，使用 skill-creator 获取更新指导
+/skill-creator
+
+# 2. 编辑 Skill 文件
+```
+
+## 重要提醒
+
+- 具体的 Skill 开发规范、文件结构、内容要求等，请通过 `/skill-creator` 动态获取
+- skill-creator 会提供最新的最佳实践和详细指导

package/README.md

@@ -1,302 +1,200 @@
-[![GitHub stars](https://img.shields.io/github/stars/AIGNE-io/aigne-doc-smith?style=flat-square)](https://github.com/AIGNE-io/aigne-doc-smith/stargazers)
-[![NPM Version](https://img.shields.io/npm/v/@aigne/doc-smith?style=flat-square)](https://www.npmjs.com/package/@aigne/doc-smith)
-[![NPM Downloads](https://img.shields.io/npm/dm/@aigne/doc-smith?style=flat-square)](https://www.npmjs.com/package/@aigne/doc-smith)
-[![Open Issues](https://img.shields.io/github/issues-raw/AIGNE-io/aigne-doc-smith?style=flat-square)](https://github.com/AIGNE-io/aigne-doc-smith/issues)
-[![License](https://img.shields.io/github/license/AIGNE-io/aigne-doc-smith?style=flat-square)](https://github.com/AIGNE-io/aigne-doc-smith/blob/main/LICENSE)
-[![codecov](https://codecov.io/gh/AIGNE-io/aigne-doc-smith/graph/badge.svg?token=95TQO2NKYC)](https://codecov.io/gh/AIGNE-io/aigne-doc-smith)
+# DocSmith Skill
 
-# AIGNE DocSmith
+从工作区数据源生成全面的结构化文档的 Claude Code Skill。
 
-> 🚀 **AI-powered documentation that understands your code**
+## 功能特性
 
-AIGNE DocSmith is a powerful, AI-driven documentation tool built on the [AIGNE Framework](https://www.aigne.io/en/framework). It automatically analyzes your codebase to generate comprehensive, structured, and multi-language documentation that stays in sync with your code.
+DocSmith 可以帮助你：
+- 📚 从代码仓库、文本文件和媒体资源生成全面的文档
+- 🏗️ 构建有组织的文档结构和文档站点
+- 📝 分析工作区内容并生成结构化的文档
+- 🔄 将代码/项目内容转换为可读的文档
 
-## 🎯 Why DocSmith?
+支持生成：
+- 技术文档
+- 用户指南
+- API 参考
+- 教程和示例
+- 产品文档
 
-- **🧠 Intelligent Analysis**: Understands your code's structure, patterns, and intent.
-- **📚 Comprehensive Coverage**: Generates everything from API references to user guides.
-- **🌍 Global Ready**: Supports 12 languages with professional-grade translation.
-- **🔄 Always Current**: Automatically detects changes and updates documentation accordingly.
-- **⚡ Zero Config**: Works out of the box with smart defaults and auto-detection.
+### 用户意图分析
 
-## AIGNE Ecosystem
+DocSmith 会自动分析工作区内容，推断：
+- **目标用户** - 文档的主要受众（开发者、运维人员、最终用户等）
+- **使用场景** - 用户查阅文档的情境（首次接触、开发集成、问题排查等）
+- **文档侧重点** - 文档类型（使用指南、API 参考、快速上手、架构说明等）
 
-DocSmith is part of the [AIGNE](https://www.aigne.io) ecosystem, a comprehensive AI application development platform.
+推断结果会展示给用户确认，支持多轮调整直到满意。
 
-![AIGNE Ecosystem Architecture](https://docsmith.aigne.io/image-bin/uploads/def424c20bbdb3c77483894fe0e22819.png)
+### 结构确认机制
 
-As shown in the diagram, DocSmith integrates seamlessly with other [AIGNE](https://www.aigne.io) components, leveraging the platform's AI capabilities and infrastructure.
+在生成文档前，DocSmith 会展示规划的文档结构：
+- 文档总数和层次关系
+- 每个文档的标题、描述和来源文件
+- 清晰的 emoji 标识便于快速浏览
 
-## ✨ Features
+用户可以：
+- 删除/添加文档
+- 调整层次结构（合并、拆分、调整父子关系）
+- 修改内容范围
 
-### 🤖 AI-Powered Generation
+只有在用户确认结构后，才会开始生成实际内容。
 
-- **Smart Structure Planning**: Analyzes your codebase to create a logical and comprehensive documentation structure.
-- **Intelligent Content Creation**: Generates detailed, contextual content that explains both the "what" and the "why."
-- **Adaptive Writing Styles**: Supports multiple documentation styles, including Technical, User-Friendly, and Developer-Focused.
+## 项目结构
 
-### 🌍 Multi-Language Support
-
-- **12 Language Support**: English, Chinese (Simplified & Traditional), Japanese, Korean, Spanish, French, German, Portuguese, Russian, Italian, and Arabic.
-- **Professional Translation**: Provides context-aware translations that maintain technical accuracy.
-- **Glossary Integration**: Ensures consistent terminology across all languages.
-
-### 🔗 Seamless Integration
-
-- **AIGNE Hub Integration**: Use the [AIGNE Hub](https://www.aigne.io/en/hub) without API keys and switch between Google Gemini, OpenAI GPT, Claude, and more.
-- **Multiple LLM Support**: Bring your own API keys for OpenAI, Anthropic, Google, and other providers.
-- **One-Click Publishing**: Publish your docs and generate shareable links for your team. Publish to [docsmith.aigne.io](https://docsmith.aigne.io/app/) or your own [Discuss Kit](https://www.web3kit.rocks/discuss-kit) instance.
-
-### 🔄 Smart Updates
-
-- **Change Detection**: Automatically identifies code changes and updates the relevant documentation.
-- **Targeted Regeneration**: Updates specific sections with custom feedback and requirements.
-- **Version Awareness**: Maintains a history of your documentation and tracks changes over time.
-
-## 🚀 Quick Start
-
-### Prerequisites
-
-- Node.js 20+ and npm/pnpm
-- No API keys required (uses the AIGNE Hub by default).
-
-### 📦 Installation
-
-Install the AIGNE CLI globally:
-
-```bash
-npm install -g @aigne/cli
-```
-
-Verify the installation:
-
-```bash
-aigne doc --help
 ```
-
-### 🎉 Generate Your First Documentation
-
-Navigate to your project directory and run:
-
-```bash
-# One command to generate your documentation
-aigne doc create
+doc-smith-skill/
+├── CLAUDE.md              # Claude Code 项目说明
+├── doc-smith/             # Skill 主目录
+│   ├── SKILL.md           # Skill 主文档（中文）
+│   └── references/        # 参考文档
+│       ├── document-structure-schema.md   # 文档结构 Schema
+│       ├── structure-confirmation-guide.md # 结构确认指南
+│       ├── structure-planning-guide.md    # 结构规划指南
+│       └── user-intent-guide.md           # 用户意图指南
+├── scripts/               # 安装/卸载脚本
+│   ├── install.sh         # 安装脚本
+│   ├── uninstall.sh       # 卸载脚本
+│   └── README.md          # 脚本使用说明
+└── README.md              # 本文件
 ```
 
-DocSmith will:
-
-1. 🔍 Auto-detect your project's structure and tech stack.
-2. 🎯 Guide you through an interactive setup (first time only).
-3. 📝 Generate comprehensive documentation.
-4. 🌍 Optionally translate it into multiple languages.
-5. 🚀 Publish it to your preferred platform.
-
-## 🔧 Advanced Configuration
-
-### LLM Providers
+## 快速开始
 
-DocSmith supports multiple AI providers:
+### 1. 安装 Skill
 
-**🎯 AIGNE Hub (Recommended)**
-
-- ✅ No API keys required.
-- ✅ Easy model switching.
-- ✅ Built-in rate limiting and optimization.
+运行安装脚本将 doc-smith 安装到全局 skills 目录：
 
 ```bash
-# Switch models effortlessly
-aigne doc create --model google:gemini-2.5-pro
-aigne doc create --model anthropic:claude-sonnet-4-5
-aigne doc create --model openai:gpt-4o
+./scripts/install.sh -y
 ```
 
-**🔑 Custom API Keys**
-Configure your own API keys for direct provider access:
-
-- OpenAI GPT models
-- Anthropic Claude models
-- Google Gemini models
-- and more...
+### 2. 使用 Skill
 
-## 📖 Usage Guide
+#### Workspace 模式 (推荐)
 
-### Core Commands
+DocSmith 现在使用独立 workspace 目录，不会污染源仓库。
 
-#### 📝 Generate Documentation
+**创建并使用 workspace：**
 
 ```bash
-# Smart generation with auto-configuration
-aigne doc create
+# 1. 创建空目录作为 workspace
+mkdir my-docs-workspace
+cd my-docs-workspace
 
-# Force a complete regeneration of the documentation
-aigne doc create --forceRegenerate
-
-# Generate with custom feedback
-aigne doc create --feedback "Add more API examples and troubleshooting sections"
+# 2. 打开 Claude Code 并执行 doc-smith
+# 输入: 使用 doc-smith 生成文档
 ```
 
-#### 🔄 Update Existing Documents
+**初始化流程：**
+DocSmith 会引导你完成初始化：
+1. 询问输出语言（如：zh、en）
+2. 询问源仓库 Git URL（可选，如果源代码在本地可不提供）
+3. 自动创建目录结构
+4. 自动添加源仓库为 git submodule（如果提供了 URL）
+5. 生成 config.yaml 配置文件
+6. 初始化 git 仓库并提交
+
+**后续操作：**
+DocSmith 会：
+1. 分析源仓库内容
+2. 推断用户意图
+3. 规划文档结构
+4. 生成结构化的 Markdown 文档
+5. 询问是否提交到 Git
+
+### 3. Workspace 目录结构
 
-```bash
-# Interactively select and update a document
-aigne doc update
-
-# Update specific document with feedback
-aigne doc update --docs overview.md --feedback "Add comprehensive FAQ section"
 ```
-
-#### 🌍 Multi-Language Translation
-
-```bash
-# Interactive translation with smart language selection
-aigne doc localize
-
-# Translate specific documents into multiple languages
-aigne doc localize --langs zh --langs ja --docs examples.md --docs overview.md
-
-# Translate with a custom glossary for consistent terminology
-aigne doc localize --glossary @path/to/glossary.md --feedback "Use technical terminology consistently"
+my-docs-workspace/              # 独立 workspace 目录
+├── config.yaml                 # workspace 配置文件
+├── sources/                    # 源仓库 (git submodule)
+│   └── my-project/
+├── intent/
+│   └── user-intent.md          # 用户意图描述
+├── planning/
+│   └── document-structure.yaml # 文档结构计划
+├── docs/                       # 生成的文档
+│   ├── overview.md
+│   ├── getting-started.md
+│   └── api/
+│       └── authentication.md
+└── cache/                      # 临时数据 (不纳入 git)
 ```
 
-#### 🚀 Publishing & Deployment
-
-```bash
-# Interactive publishing with platform selection
-aigne doc publish
-
-# Publish to a custom Discuss Kit instance
-aigne doc publish --appUrl https://your-discuss-kit-instance.com
-```
+### 4. 版本管理
 
-#### ⚙️ Configuration Management
+Workspace 是一个独立的 Git 仓库，支持完整的版本管理：
 
 ```bash
-# Interactive configuration setup
-aigne doc init
+# 查看历史
+git log
 
-# View the current configuration
-aigne doc prefs
-```
+# 查看变更
+git diff
 
-### Configuration Options
+# 回滚版本
+git revert <commit-hash>
 
-DocSmith automatically detects your project's structure, but you can customize it to your needs:
-
-- **📝 Documentation Styles**: Technical, User-Friendly, Developer-Focused, Academic
-- **🎯 Target Audiences**: Developers, End Users, System Administrators, Business Users
-- **🌍 Languages**: Choose from 12 supported languages.
-- **📁 Source Paths**: Customize which files and directories to analyze.
-- **📤 Output Settings**: Configure the documentation structure and formatting.
-
-## 🌐 Supported Languages
-
-DocSmith provides professional-grade translations for 12 languages:
-
-| Language  | Code    | Support Level |
-| --------- | ------- | ------------- |
-| English   | `en`    | ✅ Native     |
-| 简体中文  | `zh-CN` | ✅ Full       |
-| 繁體中文  | `zh-TW` | ✅ Full       |
-| 日本語    | `ja`    | ✅ Full       |
-| 한국어    | `ko`    | ✅ Full       |
-| Español   | `es`    | ✅ Full       |
-| Français  | `fr`    | ✅ Full       |
-| Deutsch   | `de`    | ✅ Full       |
-| Português | `pt-BR` | ✅ Full       |
-| Русский   | `ru`    | ✅ Full       |
-| Italiano  | `it`    | ✅ Full       |
-| العربية   | `ar`    | ✅ Full       |
-
-## 🤝 Contributing
-
-We welcome contributions from the community! Here's how you can help:
+# 推送到远程仓库（可选）
+git remote add origin <your-repo-url>
+git push -u origin main
+```
 
-### 🐛 Reporting Issues
+## 文档说明
 
-- 🔍 [Search existing issues](https://github.com/AIGNE-io/aigne-doc-smith/issues) first.
-- 📝 Use our issue templates for bug reports and feature requests.
-- 🚨 Include clear reproduction steps and details about your environment.
+- **SKILL.md** - Skill 完整使用指南，包含工作流程、最佳实践等
+- **references/**
+  - **document-structure-schema.md** - 文档结构 YAML 的完整 Schema 说明
+  - **structure-planning-guide.md** - 文档结构规划指南
+  - **structure-confirmation-guide.md** - 结构确认流程指南
+  - **user-intent-guide.md** - 用户意图理解指南
 
-### 💡 Feature Requests
+所有文档均已翻译为中文，方便理解和编辑。
 
-- 🌟 Share your ideas in [GitHub Discussions](https://github.com/AIGNE-io/aigne-doc-smith/discussions).
-- 📋 Check our [roadmap](https://github.com/AIGNE-io/aigne-doc-smith/projects) for planned features.
-- 🗳️ Vote on existing feature requests.
+## 卸载
 
-### 🔧 Development Setup
+如需移除 skill：
 
 ```bash
-# Clone the repository
-git clone https://github.com/AIGNE-io/aigne-doc-smith.git
-cd aigne-doc-smith
-
-# Install dependencies
-pnpm install
-
-# Run tests
-pnpm test
-
-# Run the linter
-pnpm run lint
-
-# Automatically fix lint errors
-pnpm run lint:fix
+./scripts/uninstall.sh
 ```
 
-### 📜 Code of Conduct
-
-Please follow our community guidelines and maintain respectful, constructive communication.
-
-## 💼 Enterprise & Production Use
-
-### 🏢 Enterprise Features
-
-- **Team Collaboration**: Multi-user workflows with role-based access.
-- **Custom Branding**: White-label your documentation with your brand's identity.
-- **API Integration**: Use REST APIs for automated documentation pipelines.
-- **Analytics**: Track documentation usage and effectiveness.
+## 手动安装
 
-### 🔒 Security & Compliance
+如果脚本无法使用，可以手动安装：
 
-- **Private Cloud**: Deploy on your own infrastructure.
-- **SSO Integration**: Connect with your existing identity providers.
-- **Audit Logs**: Complete activity tracking and compliance reporting.
-- **Data Privacy**: Your code never leaves your environment in private deployments.
-
-### 📞 Support & Services
-
-- **Priority Support**: Get direct access to our engineering team.
-- **Custom Training**: We offer team onboarding and best practices workshops.
-- **Professional Services**: We provide custom integrations and deployment assistance.
-
-[Contact us](https://www.aigne.io/contact) for enterprise licensing and deployment options.
-
-## 📊 Community & Resources
-
-### 📚 Documentation & Tutorials
+```bash
+mkdir -p ~/.claude/skills
+cp -r doc-smith ~/.claude/skills/
+```
 
-- 📖 [Documentation](https://docsmith.aigne.io/docs/)
+## 开发和自定义
 
-### 💬 Community Support
+如果你想修改或扩展 doc-smith skill：
 
-- 🐦 [Twitter](https://twitter.com/arcblock_io) - For updates and announcements.
-- 🎮 [Community](https://community.arcblock.io/discussions/boards/aigne) - For real-time community chat.
+1. 编辑 `doc-smith/SKILL.md` 中的说明文档
+2. 修改 `doc-smith/references/` 中的参考文档
+3. 运行 `./scripts/install.sh -y` 重新安装
 
-### 🏆 Showcase
+## 注意事项
 
-See DocSmith in action with these real-world examples:
+- 确保 Claude Code 已正确安装
+- 确保 Git 已安装（用于 submodule 和版本管理）
+- Workspace 需要在空目录中初始化
+- 生成的文档在独立的 workspace 目录中，不会污染源仓库
 
-- [Docs Repository](https://docsmith.aigne.io/app) - Generated with DocSmith.
+## 迁移说明
 
-## 📄 License
+如果你之前使用过旧版本（`.aigne/doc-smith/` 目录结构），建议：
+1. 创建新的 workspace 目录
+2. 重新生成文档
+3. 旧版本数据可以手动迁移到新的 workspace 目录结构中
 
-This project is licensed under the **Elastic License 2.0**. See the [LICENSE](LICENSE) file for details.
+## 支持
 
-### What does this mean?
+如有问题或建议，请在项目中提出 issue。
 
-- ✅ **Free for most use cases**: Including personal projects, internal use, and most commercial applications.
-- ✅ **Open source**: The full source code is available for review and contributions.
-- ✅ **Commercial friendly**: Use it in your business applications and services.
-- ❌ **Restrictions**: You cannot offer DocSmith as a competing hosted service.
+## 许可
 
-[Learn more about the Elastic License 2.0](https://www.elastic.co/licensing/elastic-license)
+[根据你的需求添加许可信息]