@zeyue0329/xiaoma-cli 1.6.4 → 1.7.0

package/docs/zh-cn/how-to/established-projects.md

@@ -1,134 +0,0 @@
----
-title: "既有项目"
-description: 如何在现有代码库中使用 XiaoMa Method
-sidebar:
-  order: 6
----
-
-在现有项目和遗留代码库上工作时，有效使用 XiaoMa Method。
-
-本指南涵盖了使用 XiaoMa Method 接入现有项目的核心工作流程。
-
-:::note[前置条件]
-- 已安装 XiaoMa Method（`npx xiaoma-cli install`）
-- 一个你想要处理的现有代码库
-- 访问 AI 驱动的 IDE（Claude Code 或 Cursor）
-:::
-
-## 步骤 1：清理已完成的规划产物
-
-如果你通过 XiaoMa 流程完成了所有 PRD 史诗和用户故事，请清理这些文件。归档它们、删除它们，或者在需要时依赖版本历史。不要将这些文件保留在：
-
-- `docs/`
-- `_xiaoma-output/planning-artifacts/`
-- `_xiaoma-output/implementation-artifacts/`
-
-## 步骤 2：创建项目上下文
-
-:::tip[推荐用于既有项目]
-生成 `project-context.md` 以捕获你现有代码库的模式和约定。这确保 AI 智能体在实施变更时遵循你既定的实践。
-:::
-
-运行生成项目上下文工作流程：
-
-```bash
-/xiaoma-xmc-generate-project-context
-```
-
-这将扫描你的代码库以识别：
-- 技术栈和版本
-- 代码组织模式
-- 命名约定
-- 测试方法
-- 框架特定模式
-
-你可以查看和完善生成的文件，或者如果你更喜欢，可以在 `_xiaoma-output/project-context.md` 手动创建它。
-
-[了解更多关于项目上下文](../explanation/project-context.md)
-
-## 步骤 3：维护高质量项目文档
-
-你的 `docs/` 文件夹应包含简洁、组织良好的文档，准确代表你的项目：
-
-- 意图和业务理由
-- 业务规则
-- 架构
-- 任何其他相关的项目信息
-
-对于复杂项目，考虑使用 `document-project` 工作流程。它提供运行时变体，将扫描你的整个项目并记录其实际当前状态。
-
-## 步骤 3：获取帮助
-
-### XiaoMa-Help：你的起点
-
-**随时运行 `/xiaoma-help`，当你不确定下一步该做什么时。** 这个智能指南：
-
-- 检查你的项目以查看已经完成了什么
-- 根据你安装的模块显示选项
-- 理解自然语言查询
-
-```
-/xiaoma-help 我有一个现有的 Rails 应用，我应该从哪里开始？
-/xiaoma-help quick-flow 和完整方法有什么区别？
-/xiaoma-help 显示我有哪些可用的工作流程
-```
-
-XiaoMa-Help 还会在**每个工作流程结束时自动运行**，提供关于下一步该做什么的清晰指导。
-
-### 选择你的方法
-
-根据变更范围，你有两个主要选项：
-
-| 范围                          | 推荐方法                                                                                                          |
-| ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
-| **小型更新或添加** | 使用 `quick-flow-solo-dev` 创建技术规范并实施变更。完整的四阶段 XiaoMa Method 可能有些过度。 |
-| **重大变更或添加** | 从 XiaoMa Method 开始，根据需要应用或多或少的严谨性。                                                    |
-
-### 在创建 PRD 期间
-
-在创建简报或直接进入 PRD 时，确保智能体：
-
-- 查找并分析你现有的项目文档
-- 阅读关于你当前系统的适当上下文
-
-你可以明确地指导智能体，但目标是确保新功能与你的现有系统良好集成。
-
-### UX 考量
-
-UX 工作是可选的。决定不取决于你的项目是否有 UX，而取决于：
-
-- 你是否将处理 UX 变更
-- 是否需要重要的新 UX 设计或模式
-
-如果你的变更只是对你满意的现有屏幕进行简单更新，则不需要完整的 UX 流程。
-
-### 架构考量
-
-在进行架构工作时，确保架构师：
-
-- 使用适当的已记录文件
-- 扫描现有代码库
-
-在此处要密切注意，以防止重新发明轮子或做出与你现有架构不一致的决定。
-
-## 更多信息
-
-- **[快速修复](./quick-fixes.md)** - 错误修复和临时变更
-- **[既有项目 FAQ](../explanation/established-projects-faq.md)** - 关于在既有项目上工作的常见问题
-
----
-## 术语说明
-
-- **XiaoMa Method**：XiaoMa 方法。一种结构化的软件开发方法论，用于指导从分析到实施的完整流程。
-- **PRD**：产品需求文档（Product Requirements Document）。描述产品功能、需求和目标的文档。
-- **epic**：史诗。大型功能或用户故事的集合，通常需要较长时间完成。
-- **story**：用户故事。描述用户需求的简短陈述，通常遵循"作为...我想要...以便于..."的格式。
-- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
-- **IDE**：集成开发环境（Integrated Development Environment）。提供代码编辑、调试、构建等功能的软件工具。
-- **UX**：用户体验（User Experience）。用户在使用产品或服务过程中的整体感受和交互体验。
-- **tech-spec**：技术规范（Technical Specification）。描述技术实现细节、架构设计和开发标准的文档。
-- **quick-flow**：快速流程。XiaoMa Method 中的一种简化工作流程，适用于小型变更或快速迭代。
-- **legacy codebase**：遗留代码库。指历史遗留的、可能缺乏文档或使用过时技术的代码集合。
-- **project context**：项目上下文。描述项目技术栈、约定、模式等背景信息的文档。
-- **artifact**：产物。在开发过程中生成的文档、代码或其他输出物。
-- **runtime variant**：运行时变体。在程序运行时可选择或切换的不同实现方式或配置。

package/docs/zh-cn/how-to/get-answers-about-xiaoma.md

@@ -1,144 +0,0 @@
----
-title: "如何获取关于 XiaoMa 的答案"
-description: 使用 LLM 快速回答您自己的 XiaoMa 问题
-sidebar:
-  order: 4
----
-
-## 从这里开始：XiaoMa-Help
-
-**获取关于 XiaoMa 答案的最快方式是 `/xiaoma-help`。** 这个智能指南可以回答超过 80% 的问题，并且直接在您的 IDE 中可用，方便您工作时使用。
-
-XiaoMa-Help 不仅仅是一个查询工具——它：
-- **检查您的项目**以查看已完成的内容
-- **理解自然语言**——用简单的英语提问
-- **根据您安装的模块变化**——显示相关选项
-- **在工作流后自动运行**——告诉您接下来该做什么
-- **推荐第一个必需任务**——无需猜测从哪里开始
-
-### 如何使用 XiaoMa-Help
-
-只需使用斜杠命令运行它：
-
-```
-/xiaoma-help
-```
-
-或者结合自然语言查询：
-
-```
-/xiaoma-help 我有一个 SaaS 想法并且知道所有功能。我应该从哪里开始？
-/xiaoma-help 我在 UX 设计方面有哪些选择？
-/xiaoma-help 我在 PRD 工作流上卡住了
-/xiaoma-help 向我展示到目前为止已完成的内容
-```
-
-XiaoMa-Help 会回应：
-- 针对您情况的建议
-- 第一个必需任务是什么
-- 流程的其余部分是什么样的
-
----
-
-## 何时使用本指南
-
-在以下情况下使用本节：
-- 您想了解 XiaoMa 的架构或内部机制
-- 您需要 XiaoMa-Help 提供范围之外的答案
-- 您在安装前研究 XiaoMa
-- 您想直接探索源代码
-
-## 步骤
-
-### 1. 选择您的来源
-
-| 来源               | 最适合用于                                  | 示例                     |
-| -------------------- | ----------------------------------------- | ---------------------------- |
-| **`_xiaoma` 文件夹**   | XiaoMa 如何工作——智能体、工作流、提示词 | "PM 智能体做什么？" |
-| **完整的 GitHub 仓库** | 历史、安装程序、架构          | "v6 中有什么变化？"        |
-| **`llms-full.txt`**  | 来自文档的快速概述                  | "解释 XiaoMa 的四个阶段" |
-
-`_xiaoma` 文件夹在您安装 XiaoMa 时创建。如果您还没有它，请改为克隆仓库。
-
-### 2. 将您的 AI 指向来源
-
-**如果您的 AI 可以读取文件（Claude Code、Cursor 等）：**
-
-- **已安装 XiaoMa：** 指向 `_xiaoma` 文件夹并直接提问
-- **想要更深入的上下文：** 克隆[完整仓库](https://github.com/xiaoma-code-org/XiaoMa-Cli)
-
-**如果您使用 ChatGPT 或 Claude.ai：**
-
-将 `llms-full.txt` 获取到您的会话中：
-
-```text
-https://xiaoma-code-org.github.io/XiaoMa-Cli/llms-full.txt
-```
-
-
-### 3. 提出您的问题
-
-:::note[示例]
-**问：** "告诉我用 XiaoMa 构建某物的最快方式"
-
-**答：** 使用快速流程：运行 `quick-spec` 编写技术规范，然后运行 `quick-dev` 实现它——跳过完整的规划阶段。
-:::
-
-## 您将获得什么
-
-关于 XiaoMa 的直接答案——智能体如何工作、工作流做什么、为什么事物以这种方式构建——无需等待其他人回应。
-
-## 提示
-
-- **验证令人惊讶的答案**——LLM 偶尔会出错。检查源文件或在 Discord 上询问。
-- **具体化**——"PRD 工作流的第 3 步做什么？"比"PRD 如何工作？"更好
-
-## 仍然卡住了？
-
-尝试了 LLM 方法但仍需要帮助？您现在有一个更好的问题可以问。
-
-| 频道                   | 用于                                     |
-| ------------------------- | ------------------------------------------- |
-| `#xiaoma-cli-help`       | 快速问题（实时聊天）            |
-| `help-requests` 论坛     | 详细问题（可搜索、持久） |
-| `#suggestions-feedback`   | 想法和功能请求                  |
-| `#report-bugs-and-issues` | 错误报告                                 |
-
-**Discord：** [discord.gg/gk8jAdXWmj](https://discord.gg/gk8jAdXWmj)
-
-**GitHub Issues：** [github.com/xiaoma-code-org/XiaoMa-Cli/issues](https://github.com/xiaoma-code-org/XiaoMa-Cli/issues)（用于明确的错误）
-
-*你！*
-        *卡住*
-              *在队列中——*
-                       *等待*
-                               *等待谁？*
-
-*来源*
-        *就在那里，*
-                *显而易见！*
-
-*指向*
-      *你的机器。*
-               *释放它。*
-
-*它读取。*
-         *它说话。*
-                 *尽管问——*
-
-*为什么要等*
-         *明天*
-                 *当你拥有*
-                         *今天？*
-
-*—Claude*
-
----
-## 术语说明
-
-- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
-- **LLM**：大语言模型。基于深度学习的自然语言处理模型，能够理解和生成人类语言。
-- **SaaS**：软件即服务。一种通过互联网提供软件应用的交付模式。
-- **UX**：用户体验。用户在使用产品或服务过程中建立的主观感受和评价。
-- **PRD**：产品需求文档。详细描述产品功能、特性和需求的正式文档。
-- **IDE**：集成开发环境。提供代码编辑、调试、构建等功能的软件开发工具。

package/docs/zh-cn/how-to/install-xiaoma.md

@@ -1,105 +0,0 @@
----
-title: "如何安装 XiaoMa"
-description: 在项目中安装 XiaoMa 的分步指南
-sidebar:
-  order: 1
----
-
-使用 `npx xiaoma-cli install` 命令在项目中设置 XiaoMa，并选择你需要的模块和 AI 工具。
-
-如果你想使用非交互式安装程序并在命令行中提供所有安装选项，请参阅[本指南](./non-interactive-installation.md)。
-
-## 何时使用
-
-- 使用 XiaoMa 启动新项目
-- 将 XiaoMa 添加到现有代码库
-- 更新现有的 XiaoMa 安装
-
-:::note[前置条件]
-- **Node.js** 20+（安装程序必需）
-- **Git**（推荐）
-- **AI 工具**（Claude Code、Cursor 或类似工具）
-:::
-
-## 步骤
-
-### 1. 运行安装程序
-
-```bash
-npx xiaoma-cli install
-```
-
-:::tip[最新版本]
-要从主分支安装最新版本（可能不稳定）：
-```bash
-npx github:xiaoma-code-org/XiaoMa-Cli install
-```
-:::
-
-### 2. 选择安装位置
-
-安装程序会询问在哪里安装 XiaoMa 文件：
-
-- 当前目录（如果你自己创建了目录并从该目录运行，推荐用于新项目）
-- 自定义路径
-
-### 3. 选择你的 AI 工具
-
-选择你使用的 AI 工具：
-
-- Claude Code
-- Cursor
-- 其他
-
-每个工具都有自己的命令集成方式。安装程序会创建微小的提示文件来激活工作流和智能体——它只是将它们放在工具期望找到的位置。
-
-### 4. 选择模块
-
-安装程序会显示可用的模块。选择你需要的模块——大多数用户只需要 **XiaoMa Method**（软件开发模块）。
-
-### 5. 按照提示操作
-
-安装程序会引导你完成剩余步骤——自定义内容、设置等。
-
-## 你将获得
-
-```text
-your-project/
-├── _xiaoma/
-│   ├── xmc/            # 你选择的模块
-│   │   └── config.yaml # 模块设置（如果你需要更改它们）
-│   ├── core/           # 必需的核心模块
-│   └── ...
-├── _xiaoma-output/       # 生成的工件
-├── .claude/            # Claude Code 命令（如果使用 Claude Code）
-└── .kiro/              # Kiro 引导文件（如果使用 Kiro）
-```
-
-## 验证安装
-
-运行 `/xiaoma-help` 来验证一切正常并查看下一步操作。
-
-**XiaoMa-Help 是你的智能向导**，它会：
-- 确认你的安装正常工作
-- 根据你安装的模块显示可用内容
-- 推荐你的第一步
-
-你也可以向它提问：
-```
-/xiaoma-help 我刚安装完成，应该先做什么？
-/xiaoma-help 对于 SaaS 项目我有哪些选项？
-```
-
-## 故障排除
-
-**安装程序抛出错误**——将输出复制粘贴到你的 AI 助手中，让它来解决问题。
-
-**安装程序工作正常但后续出现问题**——你的 AI 需要 XiaoMa 上下文才能提供帮助。请参阅[如何获取关于 XiaoMa 的答案](./get-answers-about-xiaoma.md)了解如何将你的 AI 指向正确的来源。
-
----
-## 术语说明
-
-- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
-- **workflow**：工作流。指一系列有序的任务或步骤，用于完成特定目标。
-- **module**：模块。指软件系统中可独立开发、测试和维护的功能单元。
-- **artifact**：工件。指在软件开发过程中生成的任何输出，如文档、代码、配置文件等。

package/docs/zh-cn/how-to/non-interactive-installation.md

@@ -1,181 +0,0 @@
----
-title: "非交互式安装"
-description: 使用命令行标志安装 XiaoMa，适用于 CI/CD 流水线和自动化部署
-sidebar:
-  order: 2
----
-
-使用命令行标志以非交互方式安装 XiaoMa。这适用于：
-
-## 使用场景
-
-- 自动化部署和 CI/CD 流水线
-- 脚本化安装
-- 跨多个项目的批量安装
-- 使用已知配置的快速安装
-
-:::note[前置条件]
-需要 [Node.js](https://nodejs.org) v20+ 和 `npx`（随 npm 附带）。
-:::
-
-## 可用标志
-
-### 安装选项
-
-| 标志 | 描述 | 示例 |
-|------|-------------|---------|
-| `--directory <path>` | 安装目录 | `--directory ~/projects/myapp` |
-| `--modules <modules>` | 逗号分隔的模块 ID | `--modules xmc,bmb` |
-| `--tools <tools>` | 逗号分隔的工具/IDE ID（使用 `none` 跳过） | `--tools claude-code,cursor` 或 `--tools none` |
-| `--custom-content <paths>` | 逗号分隔的自定义模块路径 | `--custom-content ~/my-module,~/another-module` |
-| `--action <type>` | 对现有安装的操作：`install`（默认）、`update`、`quick-update` 或 `compile-agents` | `--action quick-update` |
-
-### 核心配置
-
-| 标志 | 描述 | 默认值 |
-|------|-------------|---------|
-| `--user-name <name>` | 智能体使用的名称 | 系统用户名 |
-| `--communication-language <lang>` | 智能体通信语言 | 英语 |
-| `--document-output-language <lang>` | 文档输出语言 | 英语 |
-| `--output-folder <path>` | 输出文件夹路径 | _xiaoma-output |
-
-### 其他选项
-
-| 标志 | 描述 |
-|------|-------------|
-| `-y, --yes` | 接受所有默认值并跳过提示 |
-| `-d, --debug` | 启用清单生成的调试输出 |
-
-## 模块 ID
-
-`--modules` 标志可用的模块 ID：
-
-- `xmc` — XiaoMa Method Core
-- `bmb` — XiaoMa Builder
-
-查看 [XiaoMa 注册表](https://github.com/xiaoma-code-org) 获取可用的外部模块。
-
-## 工具/IDE ID
-
-`--tools` 标志可用的工具 ID：
-
-**推荐：** `claude-code`、`cursor`
-
-运行一次 `npx xiaoma-cli install` 交互式安装以查看完整的当前支持工具列表，或查看 [平台代码配置](https://github.com/xiaoma-code-org/XiaoMa-Cli/blob/main/tools/cli/installers/lib/ide/platform-codes.yaml)。
-
-## 安装模式
-
-| 模式 | 描述 | 示例 |
-|------|-------------|---------|
-| 完全非交互式 | 提供所有标志以跳过所有提示 | `npx xiaoma-cli install --directory . --modules xmc --tools claude-code --yes` |
-| 半交互式 | 提供部分标志；XiaoMa 提示其余部分 | `npx xiaoma-cli install --directory . --modules xmc` |
-| 仅使用默认值 | 使用 `-y` 接受所有默认值 | `npx xiaoma-cli install --yes` |
-| 不包含工具 | 跳过工具/IDE 配置 | `npx xiaoma-cli install --modules xmc --tools none` |
-
-## 示例
-
-### CI/CD 流水线安装
-
-```bash
-#!/bin/bash
-# install-xiaoma.sh
-
-npx xiaoma-cli install \
-  --directory "${GITHUB_WORKSPACE}" \
-  --modules xmc \
-  --tools claude-code \
-  --user-name "CI Bot" \
-  --communication-language English \
-  --document-output-language English \
-  --output-folder _xiaoma-output \
-  --yes
-```
-
-### 更新现有安装
-
-```bash
-npx xiaoma-cli install \
-  --directory ~/projects/myapp \
-  --action update \
-  --modules xmc,bmb,custom-module
-```
-
-### 快速更新（保留设置）
-
-```bash
-npx xiaoma-cli install \
-  --directory ~/projects/myapp \
-  --action quick-update
-```
-
-### 使用自定义内容安装
-
-```bash
-npx xiaoma-cli install \
-  --directory ~/projects/myapp \
-  --modules xmc \
-  --custom-content ~/my-custom-module,~/another-module \
-  --tools claude-code
-```
-
-## 安装结果
-
-- 项目中完全配置的 `_xiaoma/` 目录
-- 为所选模块和工具编译的智能体和工作流
-- 用于生成产物的 `_xiaoma-output/` 文件夹
-
-## 验证和错误处理
-
-XiaoMa 会验证所有提供的标志：
-
-- **目录** — 必须是具有写入权限的有效路径
-- **模块** — 对无效的模块 ID 发出警告（但不会失败）
-- **工具** — 对无效的工具 ID 发出警告（但不会失败）
-- **自定义内容** — 每个路径必须包含有效的 `module.yaml` 文件
-- **操作** — 必须是以下之一：`install`、`update`、`quick-update`、`compile-agents`
-
-无效值将：
-1. 显示错误并退出（对于目录等关键选项）
-2. 显示警告并跳过（对于自定义内容等可选项目）
-3. 回退到交互式提示（对于缺失的必需值）
-
-:::tip[最佳实践]
-- 为 `--directory` 使用绝对路径以避免歧义
-- 在 CI/CD 流水线中使用前先在本地测试标志
-- 结合 `-y` 实现真正的无人值守安装
-- 如果在安装过程中遇到问题，使用 `--debug`
-:::
-
-## 故障排除
-
-### 安装失败，提示"Invalid directory"
-
-- 目录路径必须存在（或其父目录必须存在）
-- 您需要写入权限
-- 路径必须是绝对路径或相对于当前目录的正确相对路径
-
-### 未找到模块
-
-- 验证模块 ID 是否正确
-- 外部模块必须在注册表中可用
-
-### 自定义内容路径无效
-
-确保每个自定义内容路径：
-- 指向一个目录
-- 在根目录中包含 `module.yaml` 文件
-- 在 `module.yaml` 中有 `code` 字段
-
-:::note[仍然卡住了？]
-使用 `--debug` 运行以获取详细输出，尝试交互模式以隔离问题，或在 <https://github.com/xiaoma-code-org/XiaoMa-Cli/issues> 报告。
-:::
-
----
-## 术语说明
-
-- **CI/CD**：持续集成/持续部署。一种自动化软件开发流程的实践，用于频繁集成代码更改并自动部署到生产环境。
-- **agent**：智能体。在人工智能与编程文档中，指具备自主决策或执行能力的单元。
-- **module**：模块。软件系统中可独立开发、测试和维护的功能单元。
-- **IDE**：集成开发环境。提供代码编辑、调试、构建等功能的软件开发工具。
-- **npx**：Node Package eXecute。npm 包执行器，用于直接执行 npm 包而无需全局安装。
-- **workflow**：工作流。一系列有序的任务或步骤，用于完成特定的业务流程或开发流程。