Skip to content

Commit eaaadcd

Browse files
author
catlog22
committed
feat: 添加执行ID和子命令功能,增强CLI工具的输出选项和文档生成
1 parent ece4afc commit eaaadcd

6 files changed

Lines changed: 514 additions & 37 deletions

File tree

.ccw/workflows/cli-tools-usage.md

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -321,6 +321,12 @@ ccw cli -p "..." --tool gemini --mode analysis --rule analysis-review-architectu
321321
- Description: Additional directories (comma-separated, quote if paths contain spaces)
322322
- Default: none
323323

324+
- **`--id <id>`**
325+
- Description: Execution ID (recommended, auto-generated if omitted)
326+
- Default: Auto-generated in format `{prefix}-{HHmmss}-{rand4}` (e.g., `gem-143022-x7k2`)
327+
- Prefix mapping: gemini→gem, qwen→qwn, codex→cdx, claude→cld, opencode→opc
328+
- Note: ID is always output to stderr as `[CCW_EXEC_ID=<id>]` for programmatic capture
329+
324330
- **`--resume [id]`**
325331
- Description: Resume previous session
326332
- Default: -
@@ -385,6 +391,65 @@ ASSISTANT RESPONSE: [Previous output]
385391
[Your new prompt]
386392
```
387393

394+
### Subcommands
395+
396+
#### `show` — List All Executions
397+
398+
```bash
399+
ccw cli show # Active + recent completed executions
400+
ccw cli show --all # Include full history
401+
```
402+
403+
Displays a unified table of running and recent executions with: ID, Tool, Mode, Status, Duration, Prompt Preview.
404+
405+
#### `watch <id>` — Stream Execution Output
406+
407+
```bash
408+
ccw cli watch <id> # Stream until completion (output to stderr)
409+
ccw cli watch <id> --timeout 120 # Auto-exit after 120 seconds
410+
```
411+
412+
Behavior:
413+
- Output written to **stderr** (does not pollute stdout)
414+
- Exit code: 0 = success, 1 = error, 2 = timeout
415+
- Callers can `ccw cli watch <id> 2>/dev/null` to silently wait
416+
417+
#### `output <id>` — Get Execution Output
418+
419+
```bash
420+
ccw cli output <id> # Final result only (default)
421+
ccw cli output <id> --verbose # Full metadata + raw output
422+
ccw cli output <id> --raw # Raw stdout (for piping)
423+
```
424+
425+
Default returns `finalOutput > parsedOutput > stdout` — agent's final response text only.
426+
`--verbose` shows full metadata (ID, turn, status, project) plus raw stdout/stderr.
427+
428+
#### ID Workflow Example
429+
430+
```bash
431+
# Execute with auto-generated ID
432+
ccw cli -p "analyze code" --tool gemini --mode analysis
433+
# stderr outputs: [CCW_EXEC_ID=gem-143022-x7k2]
434+
435+
# Execute with custom ID
436+
ccw cli -p "implement feature" --tool gemini --mode write --id my-task-1
437+
# stderr outputs: [CCW_EXEC_ID=my-task-1]
438+
439+
# Check status
440+
ccw cli show
441+
442+
# Watch running execution
443+
ccw cli watch gem-143022-x7k2
444+
445+
# Get final result
446+
ccw cli output gem-143022-x7k2
447+
448+
# Capture ID programmatically
449+
EXEC_ID=$(ccw cli -p "test" --tool gemini --mode analysis 2>&1 | grep -oP 'CCW_EXEC_ID=\K[^\]]+')
450+
ccw cli output $EXEC_ID
451+
```
452+
388453
### Command Examples
389454

390455
#### Task-Type Specific Templates

.claude/commands/ddd/plan.md

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -153,6 +153,27 @@ If DeepWiki is available (`deepwiki_feature_to_symbol_index` exists in doc-index
153153

154154
**Graceful degradation**: If DeepWiki unavailable → log warning → skip symbol injection → continue flow.
155155

156+
### Phase 1.8: Persist Doc Context Package
157+
158+
After building doc_context (including symbol_docs from Phase 1.7), persist it as a reusable context package:
159+
160+
1. Bundle doc_context into JSON structure:
161+
```json
162+
{
163+
"affected_features": ["feat-auth"],
164+
"affected_requirements": ["REQ-001", "REQ-002"],
165+
"affected_components": ["tech-auth-service"],
166+
"architecture_constraints": ["ADR-001"],
167+
"index_path": ".workflow/.doc-index/doc-index.json",
168+
"symbol_docs": [...]
169+
}
170+
```
171+
172+
2. Write to session folder: `{sessionFolder}/.process/doc-context-package.json`
173+
3. Store relative path for task.json population: `../.process/doc-context-package.json`
174+
175+
**Error handling**: If write fails → log warning → continue without context package (backward compatible).
176+
156177
---
157178

158179
## Phase 2: Doc-Index-Guided Exploration (NEW)
@@ -318,6 +339,93 @@ Agent(subagent_type="cli-lite-planning-agent", prompt="
318339
")
319340
```
320341

342+
### 4.3.1 Populate Task Artifacts (TASK-002)
343+
344+
After task generation, enrich each TASK-*.json with artifacts[] field:
345+
346+
1. Load doc-index.json from `.workflow/.doc-index/doc-index.json`
347+
2. For each task, extract feature_ids from task.doc_context
348+
3. Filter doc-index features/requirements matching task scope:
349+
- Match by feature_ids in task.doc_context.feature_ids
350+
- Include linked requirements via requirementIds
351+
- Include linked components via componentIds
352+
4. Populate task.artifacts[] with filtered references:
353+
354+
```json
355+
{
356+
"artifacts": [
357+
{
358+
"type": "feature_spec",
359+
"source": "doc-index",
360+
"path": ".workflow/.doc-index/feature-maps/auth.md",
361+
"feature_id": "feat-auth",
362+
"usage": "Reference for authentication requirements"
363+
},
364+
{
365+
"type": "requirement",
366+
"source": "doc-index",
367+
"path": ".workflow/.doc-index/doc-index.json#requirements[0]",
368+
"feature_id": "feat-auth",
369+
"requirement_id": "REQ-001",
370+
"usage": "Acceptance criteria source"
371+
},
372+
{
373+
"type": "component_doc",
374+
"source": "doc-index",
375+
"path": ".workflow/.doc-index/tech-registry/auth-service.md",
376+
"component_id": "tech-auth-service",
377+
"usage": "Implementation reference"
378+
}
379+
]
380+
}
381+
```
382+
383+
**Loading pattern** (following brainstorm pattern from action-planning-agent.md:200-214):
384+
- Load doc-index.json once for catalog
385+
- Filter by task-relevant feature IDs (1-3 per task)
386+
- Only include artifacts directly referenced in task scope
387+
- Use relative paths from task file location
388+
389+
### 4.3.2 Populate Context Package Path (TASK-001)
390+
391+
Set context_package_path field in each TASK-*.json:
392+
393+
```json
394+
{
395+
"context_package_path": "../.process/doc-context-package.json"
396+
}
397+
```
398+
399+
Relative path from `.task/TASK-*.json` to `.process/doc-context-package.json`.
400+
401+
### 4.3.3 Add Navigation Links Block (TASK-003)
402+
403+
Add links{} navigation block to each TASK-*.json for improved discoverability:
404+
405+
```json
406+
{
407+
"links": {
408+
"plan": "../plan.json",
409+
"doc_index": "../../.doc-index/doc-index.json",
410+
"feature_maps": [
411+
"../../.doc-index/feature-maps/auth.md"
412+
],
413+
"related_tasks": [
414+
"TASK-002.json",
415+
"TASK-003.json"
416+
]
417+
}
418+
}
419+
```
420+
421+
**Path computation**:
422+
- `plan`: Relative path from `.task/TASK-*.json` to `plan.json` (sibling of .task/)
423+
- `doc_index`: Relative path to `.workflow/.doc-index/doc-index.json`
424+
- `feature_maps`: Paths to feature-map docs from task.doc_context.feature_docs
425+
- `related_tasks`: Task IDs from task.depends_on or tasks sharing same feature_ids
426+
427+
**Backward compatibility**: links{} is optional field (task-schema allows additionalProperties).
428+
321429
### 4.4 Output Schema: plan.json
322430

323431
Follows `plan-overview-base-schema` with ddd-specific `doc_context` extension:

0 commit comments

Comments
 (0)