Enhance search functionality and indexing pipeline

- Updated `cmd_search` to include line numbers and content in search results. - Modified `IndexingPipeline` to handle start and end line numbers for chunks. - Enhanced `FTSEngine` to support storing line metadata in the database. - Improved `SearchPipeline` to return line numbers and full content in search results. - Added unit tests for bridge, FTS delete operations, metadata store, and watcher functionality. - Introduced a `.gitignore` file to exclude specific directories.
2026-03-18 18:48:48 +08:00 · 2026-03-17 14:55:27 +08:00
parent bfe5426b7e
commit 0f02b75be1
25 changed files with 2014 additions and 1482 deletions
--- a/.claude/skills/prompt-generator/SKILL.md
+++ b/.claude/skills/prompt-generator/SKILL.md
@@ -1,19 +1,20 @@
 ---
 name: prompt-generator
-description: Generate or convert Claude Code prompt files — command orchestrators, agent role definitions, or style conversion of existing files. Follows GSD-style content separation with built-in quality gates. Triggers on "create command", "new command", "create agent", "new agent", "convert command", "convert agent", "prompt generator".
+description: Generate or convert Claude Code prompt files — command orchestrators, skill files, agent role definitions, or style conversion of existing files. Follows GSD-style content separation with built-in quality gates. Triggers on "create command", "new command", "create skill", "new skill", "create agent", "new agent", "convert command", "convert skill", "convert agent", "prompt generator", "优化".
 allowed-tools: Read, Write, Edit, Bash, Glob, AskUserQuestion
 ---

 <purpose>
-Generate or convert Claude Code prompt files with concrete, domain-specific content. Three modes:
+Generate or convert Claude Code prompt files with concrete, domain-specific content. Four modes:

 - **Create command** — new orchestration workflow at `.claude/commands/` or `~/.claude/commands/`
+- **Create skill** — new skill file at `.claude/skills/*/SKILL.md` (progressive loading, no @ refs)
 - **Create agent** — new role + expertise file at `.claude/agents/`
- **Convert** — restyle existing command/agent to GSD conventions with zero content loss
+- **Convert** — restyle existing command/skill/agent to GSD conventions with zero content loss

-Content separation principle (from GSD): commands own orchestration flow; agents own domain knowledge.
+Content separation principle (from GSD): commands/skills own orchestration flow; agents own domain knowledge. Skills are a variant of commands but loaded progressively inline — they CANNOT use `@` file references.

-Invoked when user requests "create command", "new command", "create agent", "new agent", "convert command", "convert agent", or "prompt generator".
+Invoked when user requests "create command", "new command", "create skill", "new skill", "create agent", "new agent", "convert command", "convert skill", "convert agent", "prompt generator", or "优化".
 </purpose>

 <required_reading>
@@ -33,11 +34,17 @@ Parse `$ARGUMENTS` to determine what to generate.
 | Signal | Type |
 |--------|------|
 | "command", "workflow", "orchestrator" in args | `command` |
+| "skill", "SKILL.md" in args, or path contains `.claude/skills/` | `skill` |
 | "agent", "role", "worker" in args | `agent` |
-| "convert", "restyle", "refactor" + file path in args | `convert` |
+| "convert", "restyle", "refactor", "optimize", "优化" + file path in args | `convert` |
 | Ambiguous or missing | Ask user |

-**Convert mode detection:** If args contain a file path (`.md` extension) + conversion keywords, enter convert mode. Extract `$SOURCE_PATH` from args.
+**Convert mode detection:** If args contain a file path (`.md` extension) + conversion keywords, enter convert mode. Extract `$SOURCE_PATH` from args. Auto-detect source type from path:
+- `.claude/commands/` → command
+- `.claude/skills/*/SKILL.md` → skill
+- `.claude/agents/` → agent
+
+**Skill vs Command distinction:** Skills (`.claude/skills/*/SKILL.md`) are loaded **progressively inline** into the conversation context. They CANNOT use `@` file references — only `Read()` tool calls within process steps. See `@specs/command-design-spec.md` → "Skill Variant" section.

 If ambiguous:

@@ -47,13 +54,14 @@ AskUserQuestion(
  question: "What type of prompt file do you want to generate?",
  options: [
    { label: "Command", description: "New orchestration workflow — process steps, user interaction, agent spawning" },
+    { label: "Skill", description: "New skill file — progressive loading, no @ refs, inline Read() for external files" },
    { label: "Agent", description: "New role definition — identity, domain expertise, behavioral rules" },
-    { label: "Convert", description: "Restyle existing command/agent to GSD conventions (zero content loss)" }
+    { label: "Convert", description: "Restyle existing command/agent/skill to GSD conventions (zero content loss)" }
  ]
 )
 ```

-Store as `$ARTIFACT_TYPE` (`command` | `agent` | `convert`).
+Store as `$ARTIFACT_TYPE` (`command` | `skill` | `agent` | `convert`).

 ## 2. Validate Parameters

@@ -101,6 +109,12 @@ Else:
  $TARGET_PATH = {base}/{$NAME}.md
 ```

+**Skill:**
+
+```
+$TARGET_PATH = .claude/skills/{$NAME}/SKILL.md
+```
+
 **Agent:**

 ```
@@ -179,6 +193,31 @@ Generate a complete command file with:
 - Shell blocks use heredoc for multi-line, quote all variables
 - Include `<auto_mode>` section if command supports `--auto` flag

+### 5a-skill. Skill Generation (variant of command)
+
+Follow `@specs/command-design-spec.md` → "Skill Variant" section.
+
+Skills are command-like orchestrators but loaded **progressively inline** — they CANNOT use `@` file references.
+
+Generate a complete skill file with:
+
+1. **`<purpose>`** — 2-3 sentences: what + when + what it produces
+2. **NO `<required_reading>`** — skills cannot use `@` refs. External files loaded via `Read()` within process steps.
+3. **`<process>`** — numbered steps (GSD workflow style):
+   - Step 1: Initialize / parse arguments / set workflow preferences
+   - Steps 2-N: Domain-specific orchestration logic with inline `Read("phases/...")` for phase files
+   - Each step: validation, agent spawning via `Agent()`, error handling
+   - Final step: completion status or handoff to next skill via `Skill()`
+4. **`<success_criteria>`** — checkbox list of verifiable conditions
+
+**Skill-specific writing rules:**
+- **NO `<required_reading>` tag** — `@` syntax not supported in skills
+- **NO `@path` references** anywhere in the file — use `Read("path")` within `<process>` steps
+- Phase files loaded on-demand: `Read("phases/01-xxx.md")` within the step that needs it
+- Frontmatter uses `allowed-tools:` (not `argument-hint:`)
+- `<offer_next>` is optional — skills often chain via `Skill()` calls
+- `<auto_mode>` can be inline within `<process>` step 1 or as standalone section
+
 ### 5b. Agent Generation

 Follow `@specs/agent-design-spec.md` and `@templates/agent-md.md`.
@@ -225,11 +264,20 @@ $INVENTORY = {

 | Signal | Type |
 |--------|------|
+| Path in `.claude/skills/*/SKILL.md` | skill |
+| `allowed-tools:` in frontmatter + path in `.claude/skills/` | skill |
 | Contains `<process>`, `<step>`, numbered `## N.` steps | command |
 | Contains `<role>`, `tools:` in frontmatter, domain sections | agent |
-| Flat markdown with `## Implementation`, `## Phase N` | command (unstructured) |
+| Flat markdown with `## Implementation`, `## Phase N` + in skills dir | skill (unstructured) |
+| Flat markdown with `## Implementation`, `## Phase N` + in commands dir | command (unstructured) |
 | Flat prose with role description, no process steps | agent (unstructured) |

+**Skill-specific conversion rules:**
+- **NO `<required_reading>`** — skills cannot use `@` file references (progressive loading)
+- **NO `@path` references** anywhere — replace with `Read("path")` within `<process>` steps
+- If source has `@specs/...` or `@phases/...` refs, convert to `Read("specs/...")` / `Read("phases/...")`
+- Follow `@specs/conversion-spec.md` → "Skill Conversion Rules" section
+
 **Step 5c.3: Build conversion map.**

 Map every source section to its target location. Follow `@specs/conversion-spec.md` transformation rules.
@@ -293,6 +341,20 @@ Set `$TARGET_PATH = $SOURCE_PATH` (in-place conversion) unless user specifies ou
 | `<success_criteria>` | 4+ checkbox items, all verifiable |
 | Content separation | No domain expertise embedded — only orchestration |

+### 6b-skill. Skill-Specific Checks
+
+| Check | Pass Condition |
+|-------|---------------|
+| `<purpose>` | 2-3 sentences, no placeholders |
+| **NO `<required_reading>`** | Must NOT contain `<required_reading>` tag |
+| **NO `@` file references** | Zero `@specs/`, `@phases/`, `@./` patterns in prose |
+| `<process>` with numbered steps | At least 3 `## N.` headers |
+| Step 1 is initialization | Parses args, sets workflow preferences |
+| Phase file loading | Uses `Read("phases/...")` within process steps (if has phases) |
+| `<success_criteria>` | 4+ checkbox items, all verifiable |
+| Frontmatter `allowed-tools` | Present and lists required tools |
+| Content separation | No domain expertise embedded — only orchestration |
+
 ### 6c. Agent-Specific Checks

 | Check | Pass Condition |
--- a/.claude/skills/prompt-generator/specs/command-design-spec.md
+++ b/.claude/skills/prompt-generator/specs/command-design-spec.md
@@ -36,6 +36,7 @@ allowed-tools: Tool1, Tool2  # Optional: restricted tool set
 .claude/commands/deploy.md           # Top-level command
 .claude/commands/issue/create.md     # Grouped command
 ~/.claude/commands/global-status.md  # User-level command
+.claude/skills/my-skill/SKILL.md     # Skill file (see Skill Variant below)
 ```

 ## Content Structure
@@ -45,12 +46,60 @@ Commands use XML semantic tags with process steps inside `<process>`:
 | Tag | Required | Purpose |
 |-----|----------|---------|
 | `<purpose>` | Yes | What + when + what it produces (2-3 sentences) |
-| `<required_reading>` | Yes | @ file references loaded before execution |
+| `<required_reading>` | Commands only | @ file references loaded before execution |
 | `<process>` | Yes | Steps — numbered or named (see Step Styles below) |
 | `<auto_mode>` | Optional | Behavior when `--auto` flag present |
 | `<offer_next>` | Recommended | Formatted completion status + next actions |
 | `<success_criteria>` | Yes | Checkbox list of verifiable conditions |

+## Skill Variant
+
+Skills (`.claude/skills/*/SKILL.md`) follow command structure with critical differences due to **progressive loading** — skills are loaded inline into the conversation context, NOT via file resolution.
+
+### Key Differences: Skill vs Command
+
+| Aspect | Command | Skill |
+|--------|---------|-------|
+| Location | `.claude/commands/` | `.claude/skills/*/SKILL.md` |
+| Loading | Slash-command invocation, `@` refs resolved | Progressive inline loading into conversation |
+| `<required_reading>` | Yes — `@path` refs auto-resolved | **NO** — `@` refs do NOT work in skills |
+| External file access | `@` references | `Read()` tool calls within `<process>` steps |
+| Phase files | N/A | `Read("phases/01-xxx.md")` within process steps |
+| Frontmatter | `name`, `description`, `argument-hint` | `name`, `description`, `allowed-tools` |
+
+### Skill-Specific Rules
+
+1. **NO `<required_reading>` tag** — Skills cannot use `@` file references. All external context must be loaded via `Read()` tool calls within `<process>` steps.
+
+2. **Progressive phase loading** — For multi-phase skills with phase files in `phases/` subdirectory, use inline `Read()`:
+   ```javascript
+   // Within process step: Load phase doc on-demand
+   Read("phases/01-session-discovery.md")
+   // Execute phase logic...
+   ```
+
+3. **Self-contained content** — All instructions, rules, and logic must be directly in the SKILL.md or loaded via `Read()` at runtime. No implicit file dependencies.
+
+4. **Frontmatter uses `allowed-tools:`** instead of `argument-hint:`:
+   ```yaml
+   ---
+   name: my-skill
+   description: What this skill does
+   allowed-tools: Agent, Read, Write, Bash, Glob, Grep
+   ---
+   ```
+
+### Skill Content Structure
+
+| Tag | Required | Purpose |
+|-----|----------|---------|
+| `<purpose>` | Yes | What + when + what it produces (2-3 sentences) |
+| `<process>` | Yes | Steps with inline `Read()` for external files |
+| `<auto_mode>` | Optional | Behavior when `-y`/`--yes` flag present |
+| `<success_criteria>` | Yes | Checkbox list of verifiable conditions |
+
+**Note**: `<offer_next>` is less common in skills since skills often chain to other skills via `Skill()` calls.
+
 ## Step Styles

 GSD uses two step styles. Choose based on command nature:
--- a/.claude/skills/prompt-generator/specs/conversion-spec.md
+++ b/.claude/skills/prompt-generator/specs/conversion-spec.md
@@ -36,6 +36,62 @@ Conversion Summary:
  New sections added: {list of TODO sections}
 ```

+## Artifact Type Detection
+
+Before applying conversion rules, determine the source type:
+
+| Source Location | Type |
+|----------------|------|
+| `.claude/commands/**/*.md` | command |
+| `.claude/skills/*/SKILL.md` | skill |
+| `.claude/agents/*.md` | agent |
+
+**Skill detection signals**: `allowed-tools:` in frontmatter, located in `.claude/skills/` directory, progressive phase loading pattern (`Read("phases/...")`)
+
+## Skill Conversion Rules
+
+### Critical: No @ References
+
+Skills are loaded **progressively inline** into the conversation context. They CANNOT use `@` file references — these only work in commands.
+
+### Source Pattern → Target Pattern (Skill)
+
+| Source Style | Target Style |
+|-------------|-------------|
+| `# Title` + flat markdown overview | `<purpose>` (2-3 sentences) |
+| `## Implementation` / `## Execution Flow` / `## Phase Summary` | `<process>` with numbered `## N.` steps |
+| Phase file references as prose | `Read("phases/...")` calls within process steps |
+| `## Success Criteria` / `## Coordinator Checklist` | `<success_criteria>` with checkbox list |
+| `## Auto Mode` / `## Auto Mode Defaults` | `<auto_mode>` section |
+| `## Error Handling` | Preserve as-is within `<process>` or as standalone section |
+| Code blocks, tables, ASCII diagrams | **Preserve exactly** |
+
+### What NOT to Add (Skill-Specific)
+
+| Element | Why NOT |
+|---------|---------|
+| `<required_reading>` | Skills cannot use `@` refs — progressive loading |
+| `@specs/...` or `@phases/...` | `@` syntax not supported in skills |
+| `<offer_next>` | Skills chain via `Skill()` calls, not offer menus |
+
+### What to ADD (Skill-Specific)
+
+| Missing Element | Add |
+|----------------|-----|
+| `<purpose>` | Extract from overview/description |
+| `<process>` wrapper | Wrap implementation steps |
+| `<success_criteria>` | Generate from coordinator checklist or existing content |
+| `<auto_mode>` | If auto mode behavior exists, wrap in tag |
+
+### Frontmatter Conversion (Skill)
+
+| Source Field | Target Field | Transformation |
+|-------------|-------------|----------------|
+| `name` | `name` | Keep as-is |
+| `description` | `description` | Keep as-is |
+| `allowed-tools` | `allowed-tools` | Keep as-is |
+| Missing `allowed-tools` | `allowed-tools` | Infer from content |
+
 ## Command Conversion Rules

 ### Source Pattern → Target Pattern