@zeyue0329/xiaoma-cli 1.0.49 → 1.6.4

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

@@ -0,0 +1,134 @@
+---
+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

@@ -0,0 +1,144 @@
+---
+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

@@ -0,0 +1,105 @@
+---
+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

@@ -0,0 +1,181 @@
+---
+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**：工作流。一系列有序的任务或步骤，用于完成特定的业务流程或开发流程。