@zeyue0329/xiaoma-cli 1.0.39 → 1.0.41

package/.idea/workspace.xml

@@ -67,6 +67,7 @@
       <workItem from="1762494963355" duration="2769000" />
       <workItem from="1762781553645" duration="3390000" />
       <workItem from="1762933631198" duration="16000" />
+      <workItem from="1763045898895" duration="851000" />
     </task>
     <task id="LOCAL-00001" summary="drop unchecked message">
       <option name="closed" value="true" />

package/.xiaoma-core/.coordinator-state.json

@@ -0,0 +1,19 @@
+{
+  "workflowId": "test-1763048289115",
+  "workflowName": "自动化需求分析和架构设计流程",
+  "status": "in_progress",
+  "startTime": "2025-11-13T15:38:09.121Z",
+  "currentStepIndex": 1,
+  "completedSteps": [
+    {
+      "stepId": "pre_workflow_validation",
+      "status": "completed",
+      "outputs": [],
+      "duration": 5000,
+      "completedAt": "2025-11-13T15:38:09.126Z"
+    }
+  ],
+  "context": {},
+  "errors": [],
+  "retries": {}
+}

package/dist/agents/architect.txt

@@ -84,6 +84,7 @@ commands:
   - execute-checklist {checklist}: 运行任务 execute-checklist (默认为->architect-checklist)
   - research {topic}: 执行任务 create-deep-research-prompt
   - shard-prd: 为提供的 architecture.md 运行任务 shard-doc.md (如果未找到则询问)
+  - shard-doc: 执行任务 shard-doc.md 切分大型文档到多个小文档
   - yolo: 切换 Yolo 模式
   - exit: 作为架构师道别，然后放弃扮演此角色
 dependencies:
@@ -96,6 +97,7 @@ dependencies:
     - create-doc.md
     - document-project.md
     - execute-checklist.md
+    - shard-doc.md
   templates:
     - architecture-tmpl.yaml
     - brownfield-architecture-tmpl.yaml
@@ -932,6 +934,196 @@ The LLM will:
 - Offer to provide detailed analysis of any section, especially those with warnings or failures
 ==================== END: .xiaoma-core/tasks/execute-checklist.md ====================
 
+==================== START: .xiaoma-core/tasks/shard-doc.md ====================
+<!-- Powered by XiaoMa™ Core -->
+
+# Document Sharding Task
+
+## Purpose
+
+- Split a large document into multiple smaller documents based on level 2 sections
+- Create a folder structure to organize the sharded documents
+- Maintain all content integrity including code blocks, diagrams, and markdown formatting
+
+## Primary Method: Automatic with markdown-tree
+
+[[LLM: First, check if markdownExploder is set to true in .xiaoma-core/core-config.yaml. If it is, attempt to run the command: `md-tree explode {input file} {output path}`.
+
+If the command succeeds, inform the user that the document has been sharded successfully and STOP - do not proceed further.
+
+If the command fails (especially with an error indicating the command is not found or not available), inform the user: "The markdownExploder setting is enabled but the md-tree command is not available. Please either:
+
+1. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
+2. Or set markdownExploder to false in .xiaoma-core/core-config.yaml
+
+**IMPORTANT: STOP HERE - do not proceed with manual sharding until one of the above actions is taken.**"
+
+If markdownExploder is set to false, inform the user: "The markdownExploder setting is currently false. For better performance and reliability, you should:
+
+1. Set markdownExploder to true in .xiaoma-core/core-config.yaml
+2. Install @kayvan/markdown-tree-parser globally with: `npm install -g @kayvan/markdown-tree-parser`
+
+I will now proceed with the manual sharding process."
+
+Then proceed with the manual method below ONLY if markdownExploder is false.]]
+
+### Installation and Usage
+
+1. **Install globally**:
+
+   ```bash
+   npm install -g @kayvan/markdown-tree-parser
+   ```
+
+2. **Use the explode command**:
+
+   ```bash
+   # For PRD
+   md-tree explode docs/prd.md docs/prd
+
+   # For Architecture
+   md-tree explode docs/architecture.md docs/architecture
+
+   # For any document
+   md-tree explode [source-document] [destination-folder]
+   ```
+
+3. **What it does**:
+   - Automatically splits the document by level 2 sections
+   - Creates properly named files
+   - Adjusts heading levels appropriately
+   - Handles all edge cases with code blocks and special markdown
+
+If the user has @kayvan/markdown-tree-parser installed, use it and skip the manual process below.
+
+---
+
+## Manual Method (if @kayvan/markdown-tree-parser is not available or user indicated manual method)
+
+### Task Instructions
+
+1. Identify Document and Target Location
+
+- Determine which document to shard (user-provided path)
+- Create a new folder under `docs/` with the same name as the document (without extension)
+- Example: `docs/prd.md` → create folder `docs/prd/`
+
+2. Parse and Extract Sections
+
+CRITICAL AEGNT SHARDING RULES:
+
+1. Read the entire document content
+2. Identify all level 2 sections (## headings)
+3. For each level 2 section:
+   - Extract the section heading and ALL content until the next level 2 section
+   - Include all subsections, code blocks, diagrams, lists, tables, etc.
+   - Be extremely careful with:
+     - Fenced code blocks (```) - ensure you capture the full block including closing backticks and account for potential misleading level 2's that are actually part of a fenced section example
+     - Mermaid diagrams - preserve the complete diagram syntax
+     - Nested markdown elements
+     - Multi-line content that might contain ## inside code blocks
+
+CRITICAL: Use proper parsing that understands markdown context. A ## inside a code block is NOT a section header.]]
+
+### 3. Create Individual Files
+
+For each extracted section:
+
+1. **Generate filename**: Convert the section heading to lowercase-dash-case
+   - Remove special characters
+   - Replace spaces with dashes
+   - Example: "## Tech Stack" → `tech-stack.md`
+
+2. **Adjust heading levels**:
+   - The level 2 heading becomes level 1 (# instead of ##) in the sharded new document
+   - All subsection levels decrease by 1:
+
+   ```txt
+     - ### → ##
+     - #### → ###
+     - ##### → ####
+     - etc.
+   ```
+
+3. **Write content**: Save the adjusted content to the new file
+
+### 4. Create Index File
+
+Create an `index.md` file in the sharded folder that:
+
+1. Contains the original level 1 heading and any content before the first level 2 section
+2. Lists all the sharded files with links:
+
+```markdown
+# Original Document Title
+
+[Original introduction content if any]
+
+## Sections
+
+- [Section Name 1](./section-name-1.md)
+- [Section Name 2](./section-name-2.md)
+- [Section Name 3](./section-name-3.md)
+  ...
+```
+
+### 5. Preserve Special Content
+
+1. **Code blocks**: Must capture complete blocks including:
+
+   ```language
+   content
+   ```
+
+2. **Mermaid diagrams**: Preserve complete syntax:
+
+   ```mermaid
+   graph TD
+   ...
+   ```
+
+3. **Tables**: Maintain proper markdown table formatting
+
+4. **Lists**: Preserve indentation and nesting
+
+5. **Inline code**: Preserve backticks
+
+6. **Links and references**: Keep all markdown links intact
+
+7. **Template markup**: If documents contain {{placeholders}} ,preserve exactly
+
+### 6. Validation
+
+After sharding:
+
+1. Verify all sections were extracted
+2. Check that no content was lost
+3. Ensure heading levels were properly adjusted
+4. Confirm all files were created successfully
+
+### 7. Report Results
+
+Provide a summary:
+
+```text
+Document sharded successfully:
+- Source: [original document path]
+- Destination: docs/[folder-name]/
+- Files created: [count]
+- Sections:
+  - section-name-1.md: "Section Title 1"
+  - section-name-2.md: "Section Title 2"
+  ...
+```
+
+## Important Notes
+
+- Never modify the actual content, only adjust heading levels
+- Preserve ALL formatting, including whitespace where significant
+- Handle edge cases like sections with code blocks containing ## symbols
+- Ensure the sharding is reversible (could reconstruct the original from shards)
+==================== END: .xiaoma-core/tasks/shard-doc.md ====================
+
 ==================== START: .xiaoma-core/templates/architecture-tmpl.yaml ====================
 template:
   id: architecture-template-v2

package/dist/agents/workflow-helper.txt

@@ -0,0 +1,93 @@
+# Web Agent Bundle Instructions
+
+You are now operating as a specialized AI agent from the XiaoMa-Cli framework. This is a bundled web-compatible version containing all necessary resources for your role.
+
+## Important Instructions
+
+1. **Follow all startup commands**: Your agent configuration includes startup instructions that define your behavior, personality, and approach. These MUST be followed exactly.
+
+2. **Resource Navigation**: This bundle contains all resources you need. Resources are marked with tags like:
+
+- `==================== START: .xiaoma-core/folder/filename.md ====================`
+- `==================== END: .xiaoma-core/folder/filename.md ====================`
+
+When you need to reference a resource mentioned in your instructions:
+
+- Look for the corresponding START/END tags
+- The format is always the full path with dot prefix (e.g., `.xiaoma-core/personas/analyst.md`, `.xiaoma-core/tasks/create-story.md`)
+- If a section is specified (e.g., `{root}/tasks/create-story.md#section-name`), navigate to that section within the file
+
+**Understanding YAML References**: In the agent configuration, resources are referenced in the dependencies section. For example:
+
+```yaml
+dependencies:
+  utils:
+    - template-format
+  tasks:
+    - create-story
+```
+
+These references map directly to bundle sections:
+
+- `utils: template-format` → Look for `==================== START: .xiaoma-core/utils/template-format.md ====================`
+- `tasks: create-story` → Look for `==================== START: .xiaoma-core/tasks/create-story.md ====================`
+
+3. **Execution Context**: You are operating in a web environment. All your capabilities and knowledge are contained within this bundle. Work within these constraints to provide the best possible assistance.
+
+4. **Primary Directive**: Your primary goal is defined in your agent configuration below. Focus on fulfilling your designated role according to the XiaoMa-Cli framework.
+
+---
+
+
+==================== START: .xiaoma-core/agents/workflow-helper.md ====================
+# agent
+
+CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:
+
+```yaml
+on_failure:
+  max_retries: 3
+  escalation: 请检查架构模板完整性
+```
+
+## 调试
+
+### 启用详细日志
+
+在协调器启动时查看详细日志:
+```bash
+DEBUG=* node src/index.js start automated-requirements-analysis
+```
+
+### 查看状态文件
+
+工作流状态保存在:`.xiaoma-core/.coordinator-state.json`
+
+查看:
+```bash
+cat .xiaoma-core/.coordinator-state.json
+```
+
+## 使用提示
+
+1. **先启动协调器**:在Claude Code中启动工作流前,确保协调器已运行
+2. **保持终端开启**:协调器需要持续运行,不要关闭终端
+3. **监控日志**:协调器日志会显示详细的执行进度和问题
+4. **状态恢复**:如果中断,状态文件允许从中断点恢复
+5. **工作流定义**:所有工作流定义在`xiaoma-core/workflows/`目录
+
+## 与workflow-executor的区别
+
+**workflow-executor**(旧方案):
+- 完全由AI驱动,基于AI判断决定下一步
+- 会在关键点暂停询问用户
+- 无法完全自动化
+
+**workflow-helper + Coordinator**(新方案):
+- 程序化流程控制,消除AI决策延迟
+- 完全自动执行,无需人工确认
+- 状态持久化,支持恢复
+- 质量门控,自动验证输出
+
+workflow-helper专注于"执行层",协调器负责"控制层",实现关注点分离和更可靠的自动化。
+==================== END: .xiaoma-core/agents/workflow-helper.md ====================