update docs

Author: qdriven

CLAUDE.md

@@ -21,7 +21,7 @@ go test ./internal/git/... -v -run TestFunctionName
 
 ## Architecture
 
-Spark is a Go CLI tool (`module spark`, binary `spark`) for managing multiple Git repositories, AI agent configs, scripts, and task workflows. Built with **Cobra** (CLI), **Viper** (config), **PTerm** + **Bubble Tea** (TUI), tested with **Ginkgo/Gomega** (BDD).
+Spark is a Go CLI tool (`module spark`, binary `spark`) for managing multiple Git repositories, scripts, and task workflows. Built with **Cobra** (CLI), **Viper** (config), **PTerm** + **Bubble Tea** (TUI), tested with **Ginkgo/Gomega** (BDD).
 
 ### Code Structure
 
@@ -30,33 +30,32 @@ Spark is a Go CLI tool (`module spark`, binary `spark`) for managing multiple Gi
   - `cmd/git/` — Git repo management commands
   - `cmd/magic/` — System utility commands (DNS flush, mirror switching)
   - `cmd/script/` — Script management commands
-  - `cmd/agent.go`, `cmd/agent_profile.go`, `cmd/task.go` — Top-level commands in the root `cmd/` package
+  - `cmd/task.go` — Top-level task commands in the root `cmd/` package
 - **`internal/`** — Business logic, separated by domain:
-  - `agent/` — AI agent config management (Claude Code, Codex, Kimi, GLM) and profile templates
+  - `agent/` — AI agent config management module (currently command entry disabled)
   - `config/` — Configuration loading and management
   - `git/` — Core Git operations (find repos, update, remote management, URL conversion)
   - `github/` — GitHub API interactions (list org repos, parse org URLs)
   - `mono/` — Mono-repo creation and submodule management
   - `script/` — Script discovery (from config and `scripts/` dir) and execution
-  - `task/` — Task init/dispatch/sync, feature CRUD, and implementation via `kimi` CLI
+  - `task/` — Task init/dispatch/sync, issue CRUD, and implementation via `kimi` CLI
   - `tui/` — Shared terminal UI components (spinner, dialogs, selector)
 - **`docs/usage/`** — Usage documentation per command
 
 ### Command Hierarchy
 
 ```
 spark
-├── git [update|mono|gitcode|config|url|batch-clone|update-org-status]
+├── git [update|mono|gitcode|config|url|batch-clone|issues|update-org-status]
 │   └── mono [add|sync]
-├── agent [list|view|edit|reset] + agent profile [list|add|edit]
 ├── task [list|init|dispatch|sync|create|delete|impl]
 ├── script [list|run]
 └── magic [flush-dns|pip|go|node]     # Mirror source switching + DNS
 ```
 
 ### Key Patterns
 
-- **TUI mode**: `task`, `agent`, and other commands accept `--tui` flag for interactive mode with Bubble Tea selectors and PTerm spinners. CLI mode is the default.
+- **TUI mode**: `task` and other commands accept `--tui` flag for interactive mode with Bubble Tea selectors and PTerm spinners. CLI mode is the default.
 - **Config binding**: Flags are bound to Viper via `viper.BindPFlag()` in `init()` functions. Config keys use snake_case in YAML but camelCase in struct tags.
 - **Script sources**: Scripts can come from `~/.spark.yaml` (`spark.scripts` or top-level `scripts`) or from a `scripts/` directory. Config scripts take precedence.
 

README.md

@@ -35,7 +35,7 @@ main.go → cmd.Execute()
 │   ├── github/             GitHub API interactions
 │   ├── mono/               Mono-repo & submodule management
 │   ├── script/             Script discovery & execution
-│   ├── task/               Task dispatch/sync/feature CRUD
+│   ├── task/               Task dispatch/sync/issue CRUD
 │   └── tui/                Shared terminal UI components
 ├── docs/                   Documentation (docmd)
 └── scripts/                User-defined automation scripts
@@ -81,6 +81,7 @@ go test ./internal/git/... -v -run TestFunctionName
 | `spark git url [repo-path]` | Get remote URL of repository |
 | `spark git batch-clone <account> [--ssh] [--include] [--exclude] [-o <dir>]` | Clone all repos from GitHub org/user |
 | `spark git update-org-status <org> [--dry-run] [--update-dot-github] [--section <name>]` | Update org README with repo list |
+| `spark git issues [-r <owner/repo>] (-d <dir> \| -f <file>) [--dry-run] [-l <labels>]` | Create GitHub issues from markdown docs/tasks |
 
 ---
 
@@ -108,10 +109,10 @@ Supported agents: `claude-code`, `codex`, `kimi`, `glm`
 | Command | Description |
 |---------|-------------|
 | `spark task init` | Initialize task directory structure |
-| `spark task list` | List all tasks and features |
-| `spark task create <name> [--content <text>]` | Create feature file |
-| `spark task delete <name> [--force]` | Delete feature file |
-| `spark task impl <name>` | Implement feature via kimi CLI |
+| `spark task list` | List all tasks and issues |
+| `spark task create <name> [--content <text>]` | Create issue file |
+| `spark task delete <name> [--force]` | Delete issue file |
+| `spark task impl <name>` | Implement issue via kimi CLI |
 | `spark task dispatch [name] [--dest <path>]` | Dispatch task to workspace |
 | `spark task sync [name] [--work-path <path>]` | Sync task back |
 

docs/README.md

@@ -35,7 +35,7 @@ main.go → cmd.Execute()
 │   ├── github/             GitHub API interactions
 │   ├── mono/               Mono-repo & submodule management
 │   ├── script/             Script discovery & execution
-│   ├── task/               Task dispatch/sync/feature CRUD
+│   ├── task/               Task dispatch/sync/issue CRUD
 │   └── tui/                Shared terminal UI components
 ├── docs/                   Documentation (docmd)
 └── scripts/                User-defined automation scripts
@@ -81,6 +81,7 @@ go test ./internal/git/... -v -run TestFunctionName
 | `spark git url [repo-path]` | Get remote URL of repository |
 | `spark git batch-clone <account> [--ssh] [--include] [--exclude] [-o <dir>]` | Clone all repos from GitHub org/user |
 | `spark git update-org-status <org> [--dry-run] [--update-dot-github] [--section <name>]` | Update org README with repo list |
+| `spark git issues [-r <owner/repo>] (-d <dir> \| -f <file>) [--dry-run] [-l <labels>]` | Create GitHub issues from markdown docs/tasks |
 
 ---
 
@@ -108,10 +109,10 @@ Supported agents: `claude-code`, `codex`, `kimi`, `glm`
 | Command | Description |
 |---------|-------------|
 | `spark task init` | Initialize task directory structure |
-| `spark task list` | List all tasks and features |
-| `spark task create <name> [--content <text>]` | Create feature file |
-| `spark task delete <name> [--force]` | Delete feature file |
-| `spark task impl <name>` | Implement feature via kimi CLI |
+| `spark task list` | List all tasks and issues |
+| `spark task create <name> [--content <text>]` | Create issue file |
+| `spark task delete <name> [--force]` | Delete issue file |
+| `spark task impl <name>` | Implement issue via kimi CLI |
 | `spark task dispatch [name] [--dest <path>]` | Dispatch task to workspace |
 | `spark task sync [name] [--work-path <path>]` | Sync task back |
 

docs/features/git.md

@@ -53,19 +53,22 @@ spark git batch-clone jackwener -o ./repos
 spark git update-org-status variableway --update-dot-github
 ```
 
-### 批量创建 Issue
+### Markdown 创建 Issue
 
-从文件夹中的 Markdown 文档批量创建 GitHub Issue。每个文档对应一个 Issue，标题自动提取自文档的首行标题。
+统一使用 `spark git issues` 命令创建 GitHub Issue，支持两种输入模式：
+
+- 目录模式：读取目录下所有 Markdown 文件，每个文件创建一个 Issue
+- 任务模式：读取单个任务文件，按 `# Task <id>` / `## Task <id>` 分段创建多个 Issue
 
 ```bash
-# 从文档创建 Issue
-spark git batch-issue variableway/spark-cli -d ./docs
+# 目录模式
+spark git issues -d ./docs -r variableway/spark-cli
 
-# 预览模式
-spark git batch-issue owner/repo -d ./issues --dry-run
+# 任务模式
+spark git issues -f tasks/features/task-bug-fix.md -r variableway/spark-cli
 
-# 添加标签
-spark git batch-issue owner/repo -d ./docs --label "documentation"
+# 自动识别当前仓库 + 预览
+spark git issues -f tasks/features/task-bug-fix.md --dry-run
 ```
 
 ## 使用参数
@@ -78,11 +81,16 @@ spark git batch-issue owner/repo -d ./docs --label "documentation"
 | `-o, --output` | 输出路径 |
 | `--ssh` | 使用 SSH 克隆（batch-clone） |
 | `--include` / `--exclude` | 包含/排除匹配模式（batch-clone） |
+| `-r, --repo` | 目标仓库（未指定时自动从当前仓库解析） |
+| `-d, --dir` | 文档目录（目录模式） |
+| `-f, --file` | 任务文件（任务模式） |
+| `-l, --labels` | Issue 标签（逗号分隔） |
+| `--dry-run` | 仅预览，不创建 Issue |
 
 ## 依赖
 
 - `git` 命令行工具
-- `gh` CLI（batch-clone、update-org-status 需要 GitHub API 访问）
+- `gh` CLI（issues、batch-clone、update-org-status 需要 GitHub API 访问）
 
 ## 相关文档
 

docs/features/task.md

@@ -8,26 +8,26 @@
 
 ### 任务初始化
 
-在项目中创建标准的任务目录结构（`tasks/features/`）。
+在项目中创建标准的任务目录结构（`tasks/issues/`）。
 
 ```bash
 spark task init
 ```
 
 ### 特性文件管理
 
-创建、列出、删除特性描述文件。特性文件是 Markdown 格式的任务描述。
+创建、列出、删除 issue 描述文件。issue 文件是 Markdown 格式的任务描述。
 
 ```bash
-spark task create my-feature                     # 创建
+spark task create my-feature                     # 创建 issue
 spark task create my-feature --content "描述"    # 带内容创建
 spark task list                                  # 列出
 spark task delete my-feature                     # 删除
 ```
 
 ### AI 实现
 
-通过 `kimi` CLI 自动实现特性描述中的任务。
+通过 `kimi` CLI 自动实现 issue 描述中的任务。
 
 ```bash
 spark task impl my-feature
@@ -51,7 +51,7 @@ spark task sync my-feature
 ```
 create → impl → dispatch → (开发) → sync
   ↑                                      ↓
-  └────── tasks/features/*.md ←─────────┘
+  └────── tasks/issues/*.md ←───────────┘
 ```
 
 ## 使用参数

docs/index.md

@@ -40,7 +40,7 @@ main.go → cmd.Execute()
 │   ├── github/             GitHub API interactions
 │   ├── mono/               Mono-repo & submodule management
 │   ├── script/             Script discovery & execution
-│   ├── task/               Task dispatch/sync/feature CRUD
+│   ├── task/               Task dispatch/sync/issue CRUD
 │   └── tui/                Shared terminal UI components
 ├── docs/                   Documentation (docmd)
 └── scripts/                User-defined automation scripts
@@ -86,6 +86,7 @@ go test ./internal/git/... -v -run TestFunctionName
 | `spark git url [repo-path]` | Get remote URL of repository |
 | `spark git batch-clone <account> [--ssh] [--include] [--exclude] [-o <dir>]` | Clone all repos from GitHub org/user |
 | `spark git update-org-status <org> [--dry-run] [--update-dot-github] [--section <name>]` | Update org README with repo list |
+| `spark git issues [-r <owner/repo>] (-d <dir> \| -f <file>) [--dry-run] [-l <labels>]` | Create GitHub issues from markdown docs/tasks |
 
 ---
 
@@ -113,10 +114,10 @@ Supported agents: `claude-code`, `codex`, `kimi`, `glm`
 | Command | Description |
 |---------|-------------|
 | `spark task init` | Initialize task directory structure |
-| `spark task list` | List all tasks and features |
-| `spark task create <name> [--content <text>]` | Create feature file |
-| `spark task delete <name> [--force]` | Delete feature file |
-| `spark task impl <name>` | Implement feature via kimi CLI |
+| `spark task list` | List all tasks and issues |
+| `spark task create <name> [--content <text>]` | Create issue file |
+| `spark task delete <name> [--force]` | Delete issue file |
+| `spark task impl <name>` | Implement issue via kimi CLI |
 | `spark task dispatch [name] [--dest <path>]` | Dispatch task to workspace |
 | `spark task sync [name] [--work-path <path>]` | Sync task back |
 

docs/quick-start/getting-started.md

@@ -54,7 +54,7 @@ spark agent use my-profile                    # 应用到当前项目
 
 ```bash
 spark task init                               # 初始化任务目录
-spark task create my-feature                  # 创建特性文件
+spark task create my-feature                  # 创建 issue 文件
 spark task dispatch my-feature                # 分发到工作目录
 spark task sync my-feature                    # 同步回任务目录
 ```

docs/spec/task.md

@@ -19,7 +19,7 @@ spark task [--task-dir <dir>] [--owner <owner>] [--work-dir <dir>] [--tui]
 
 ## spark task init
 
-初始化任务目录结构，创建 `tasks/features/` 等目录。
+初始化任务目录结构，创建 `tasks/issues/` 等目录，并生成 `tasks/example-issue.md`。
 
 ```
 spark task init
@@ -47,7 +47,7 @@ spark task list [--task-dir <dir>]
 
 ## spark task create
 
-在 `tasks/features/` 下创建新的特性文件。文件名中的空格自动转为 `-`。
+在 `tasks/issues/` 下创建新的 issue 文件。文件名中的空格和下划线自动转为 `-`。
 
 ```
 spark task create <feature-name> [--content <text>]
@@ -59,13 +59,13 @@ spark task create <feature-name> [--content <text>]
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `feature-name` | string | 是 | 特性名称（作为文件名） |
+| `feature-name` | string | 是 | issue 名称（作为文件名） |
 
 ---
 
 ## spark task delete
 
-删除特性文件。
+删除 issue 文件。
 
 ```
 spark task delete <feature-name> [--force]
@@ -77,21 +77,21 @@ spark task delete <feature-name> [--force]
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `feature-name` | string | 是 | 特性名称 |
+| `feature-name` | string | 是 | issue 名称 |
 
 ---
 
 ## spark task impl
 
-使用 `kimi` CLI 实现特性。
+使用 `kimi` CLI 实现 issue。
 
 ```
 spark task impl <feature-name>
 ```
 
 | 参数 | 类型 | 必填 | 说明 |
 |------|------|------|------|
-| `feature-name` | string | 是 | 特性名称 |
+| `feature-name` | string | 是 | issue 名称 |
 
 无标志（除父命令 `--tui`）。
 

docs/usage/git.md

@@ -14,7 +14,7 @@ spark git config [--username --email]         # 配置 Git 用户
 spark git url [repo-path]                     # 查看远程 URL
 spark git batch-clone <account> [-o <dir>]    # 克隆用户/组织所有仓库
 spark git update-org-status <org> [--dry-run] # 更新组织 README
-spark git batch-issue <repo> [-d <docs-dir>]    # 从文档批量创建 Issue
+spark git issues [-r <owner/repo>] (-d <dir> | -f <file>) # 从文档/任务创建 Issue
 ```
 
 ---
@@ -171,24 +171,32 @@ spark git update-org-status variableway --section "My Projects"
 
 ---
 
-## spark git batch-issue
+## spark git issues
 
-从文件夹中的 Markdown 文档批量创建 GitHub Issue。每个文档对应一个 Issue。
+从 Markdown 文档创建 GitHub Issue，支持两种模式：
+
+- 目录模式：`-d` 指定目录，目录下每个 `.md` 文件创建一个 Issue
+- 任务模式：`-f` 指定单文件，按 `# Task <id>` 或 `## Task <id>` 分段创建多个 Issue
+
+仓库参数可通过 `-r` 显式指定；未指定时自动从当前仓库 `origin` 解析 `owner/repo`。
 
 | 标志 | 简写 | 默认值 | 说明 |
 |------|------|--------|------|
-| `--docs` | `-d` | `.` | 包含 Markdown 文档的目录 |
-| `--dry-run` | | `false` | 预览不创建 |
-| `--label` | `-l` | | 为所有 Issue 添加标签（逗号分隔） |
-
-**标题规则**：
-- 优先使用文档中的第一个 `# 标题`
-- 无标题时使用文件名（去掉 `.md` 后缀）
+| `--repo` | `-r` | 自动检测 | 目标仓库（`owner/repo`） |
+| `--dir` | `-d` | | Markdown 目录（目录模式） |
+| `--file` | `-f` | | 任务文件（任务模式） |
+| `--labels` | `-l` | | 为所有 Issue 添加标签（逗号分隔） |
+| `--dry-run` | | `false` | 预览，不创建 Issue |
 
 ```bash
-spark git batch-issue variableway/spark-cli -d ./docs
-spark git batch-issue owner/repo -d ./issues --dry-run
-spark git batch-issue owner/repo -d ./docs --label "documentation,enhancement"
+# 目录模式：每个 Markdown 文件创建一个 Issue
+spark git issues -d ./docs -r variableway/spark-cli
+
+# 任务模式：从任务文件按 Task 段落创建 Issue
+spark git issues -f tasks/features/task-bug-fix.md -r variableway/spark-cli
+
+# 自动从当前仓库解析 owner/repo
+spark git issues -f tasks/features/task-bug-fix.md --dry-run
 ```
 
 ## 相关命令