mirror of
https://github.com/instructkr/claw-code.git
synced 2026-10-27 00:00:00 +08:00
docs: add GJC tool semantics analysis for Batch 1 (read/edit/search/find)
This commit is contained in:
clawdbot committed
1 parent
7e6981fbe7
commit
1e55fb11bc
1 file changed
+337
@@ -0,0 +1,337 @@
|
||||
# GJC Tool Semantics Alignment: Phase 1 (read/edit/search/find)
|
||||
|
||||
**Status**: Implementation plan
|
||||
**Issue**: #3323
|
||||
**Scope**: Slice 2.1 - Tool catalog semantic parity for read/edit/search/find
|
||||
**Target**: Ship in batches with focused PRs
|
||||
|
||||
---
|
||||
|
||||
## 1. EXECUTIVE SUMMARY
|
||||
|
||||
This document details the semantic gaps between claw-code's current tool implementations and GJC's (gajae-code) reference implementations for the highest-value tools: **read**, **edit**, **search**, and **find**.
|
||||
|
||||
### Key Gaps
|
||||
|
||||
| Tool | Current (claw-code) | Target (GJC) | Gap | Complexity |
|
||||
|------|-----|--------|-----|------------|
|
||||
| **read** | offset/limit pagination | Line selectors (`:L-L+N`), raw mode, truncation footers | High | Medium |
|
||||
| **write** | Simple file replacement | Full replacement semantics (matching GJC) | Low | Low |
|
||||
| **edit** | String replacement (old→new) | String replacement with rich patch output | Low | Low |
|
||||
| **find** (glob) | Pattern expansion only | Recursive glob with filtering | Low | Low |
|
||||
| **search** (grep) | Regex search with context | Regex with context + advanced filtering | Low | Low |
|
||||
|
||||
---
|
||||
|
||||
## 2. GJC TOOL SEMANTICS REFERENCE
|
||||
|
||||
### 2.1 READ Tool
|
||||
|
||||
**Source**: `gajae-code/packages/coding-agent/src/tools/read.ts` (3,500+ LOC)
|
||||
|
||||
#### Input Schema
|
||||
```typescript
|
||||
{
|
||||
path: string; // File path (relative or absolute)
|
||||
offset?: number; // Line offset (for pagination)
|
||||
limit?: number; // Lines to read (for pagination)
|
||||
// GJC extensions (missing in claw-code):
|
||||
selector?: string; // Line range syntax:
|
||||
// ":50" = line 50 onward
|
||||
// ":50-200" = lines 50-200 inclusive
|
||||
// ":50+150" = 150 lines starting at line 50
|
||||
// ":raw" = full file verbatim
|
||||
// ":conflicts" = git merge conflicts only
|
||||
truncationDirection?: "head" | "tail" | "both"; // Which end to keep
|
||||
maxSummaryBytes?: number; // Summary budget (default 50KB)
|
||||
maxSummaryLines?: number; // Summary budget (default 20K lines)
|
||||
}
|
||||
```
|
||||
|
||||
#### Output Structure
|
||||
```json
|
||||
{
|
||||
"file": {
|
||||
"path": "src/main.rs",
|
||||
"content": "...",
|
||||
"totalLines": 500,
|
||||
"totalBytes": 12345,
|
||||
"truncatedBy": "lines" | "bytes" | "middle" | null,
|
||||
"displayMode": "summarized" | "raw" | "receipt"
|
||||
},
|
||||
"truncationFooter": "[Showing lines 1-50 of 500; re-read ...]"
|
||||
}
|
||||
```
|
||||
|
||||
#### Key Behaviors
|
||||
|
||||
1. **Line Range Selectors** (`:selector` syntax)
|
||||
- `:50` = start at line 50
|
||||
- `:50-200` = lines 50-200 inclusive
|
||||
- `:50+150` = 150 lines starting at 50
|
||||
- `:50+1` = exactly one line
|
||||
- `:5-16,960-973` = multiple ranges
|
||||
- `:raw` = full verbatim
|
||||
- `:conflicts` = git merge conflicts
|
||||
|
||||
2. **Truncation Modes**
|
||||
- Default: 50KB bytes limit, 20K lines limit
|
||||
- Direction: `head` (keep start), `tail` (keep end), `both` (keep both ends)
|
||||
- Footer includes recovery hint (e.g., "`re-read path:1-9999` for verbatim")
|
||||
|
||||
3. **Structural Summarization**
|
||||
- Code: collapse function bodies to `..` or `…` (merged brace pairs)
|
||||
- Prose: preserve full lines, truncate at word boundaries
|
||||
- Special files: documents (PDF, DOCX, XLSX) converted via markit
|
||||
|
||||
4. **Archive Support**
|
||||
- `.tar`, `.tar.gz`, `.tgz`, `.zip`: member read with `archive.ext:path/inside`
|
||||
- SQLite: `.sqlite:table` or `.sqlite:table:key` queries
|
||||
- Line ranges apply to archive members
|
||||
|
||||
5. **Output Formatting**
|
||||
- Anchored output: Line prefixes with source line numbers and hash anchors
|
||||
- Optional hash lines: Marks structural boundaries (`# pragma`, function start, etc.)
|
||||
- Prose column cap: Long lines wrapped/truncated at column limit
|
||||
|
||||
### 2.2 EDIT Tool
|
||||
|
||||
**Source**: `gajae-code/packages/coding-agent/src/tools/edit.ts`
|
||||
|
||||
#### Input Schema
|
||||
```typescript
|
||||
{
|
||||
path: string; // File to edit
|
||||
old_text: string; // Text to replace (required for edit)
|
||||
new_text: string; // Replacement text
|
||||
all?: boolean; // Replace all occurrences (default: first only)
|
||||
}
|
||||
```
|
||||
|
||||
#### Output Structure
|
||||
```json
|
||||
{
|
||||
"file": {
|
||||
"path": "src/main.rs",
|
||||
"editCount": 1,
|
||||
"beforeSize": 12345,
|
||||
"afterSize": 12400
|
||||
},
|
||||
"patch": [
|
||||
{
|
||||
"type": "replace",
|
||||
"lineStart": 50,
|
||||
"lineEnd": 55,
|
||||
"before": "old content",
|
||||
"after": "new content",
|
||||
"context": {"before": 3, "after": 3}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Key Behaviors
|
||||
|
||||
1. **Exact Match Required**: `old_text` must match exactly (no fuzzy matching)
|
||||
2. **Smallest Replacement**: Use smallest unique old_text that identifies the change
|
||||
3. **All-or-Nothing**: Either all occurrences replaced or none (no partial)
|
||||
4. **Patch Metadata**: Line numbers, context, before/after preserved
|
||||
|
||||
### 2.3 SEARCH Tool
|
||||
|
||||
**Source**: `gajae-code/packages/coding-agent/src/tools/search.ts`
|
||||
|
||||
#### Input Schema
|
||||
```typescript
|
||||
{
|
||||
pattern: string; // Regex pattern
|
||||
paths?: string[]; // Files/dirs to search
|
||||
context?: number; // Context lines before/after (default: 2)
|
||||
i?: boolean; // Case-insensitive
|
||||
glob_exclude?: string[]; // Patterns to skip
|
||||
file_type?: string; // Filter by extension
|
||||
limit?: number; // Max results
|
||||
truncation?: "head" | "tail" | "both";
|
||||
}
|
||||
```
|
||||
|
||||
#### Output Structure
|
||||
```json
|
||||
{
|
||||
"matches": [
|
||||
{
|
||||
"file": "src/main.rs",
|
||||
"lineNumber": 42,
|
||||
"line": "fn process() {",
|
||||
"before": ["// Process data", ""],
|
||||
"after": [" // Implementation", ""]
|
||||
}
|
||||
],
|
||||
"summary": "Found 5 matches in 3 files"
|
||||
}
|
||||
```
|
||||
|
||||
### 2.4 FIND Tool
|
||||
|
||||
**Source**: `gajae-code/packages/coding-agent/src/tools/find.ts`
|
||||
|
||||
#### Input Schema
|
||||
```typescript
|
||||
{
|
||||
paths: string[]; // Glob patterns
|
||||
timeout?: number; // Timeout in seconds (default: 5)
|
||||
gitignore?: boolean; // Respect .gitignore (default: true)
|
||||
hidden?: boolean; // Include hidden files (default: true)
|
||||
limit?: number; // Max results (default: 1000)
|
||||
}
|
||||
```
|
||||
|
||||
#### Output Structure
|
||||
```json
|
||||
{
|
||||
"files": [
|
||||
{
|
||||
"path": "src/main.rs",
|
||||
"modified": "2026-10-13T12:34:56Z",
|
||||
"size": 12345
|
||||
}
|
||||
],
|
||||
"summary": "Found 42 files matching pattern",
|
||||
"truncated": false
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. CURRENT CLAW-CODE IMPLEMENTATION GAPS
|
||||
|
||||
### 3.1 READ Tool Gaps
|
||||
|
||||
**File**: `rust/crates/runtime/src/file_ops.rs:713`
|
||||
|
||||
**Current**:
|
||||
```rust
|
||||
pub fn read_file_in_workspace(
|
||||
path: &str,
|
||||
offset: Option<usize>, // Line offset only
|
||||
limit: Option<usize>, // Lines only
|
||||
workspace_root: &Path,
|
||||
) -> io::Result<ReadFileOutput>
|
||||
```
|
||||
|
||||
**Missing**:
|
||||
- ✗ Line range selectors (`:L-L+N` syntax)
|
||||
- ✗ Raw mode (`:raw`)
|
||||
- ✗ Git merge conflict extraction (`:conflicts`)
|
||||
- ✗ Truncation footers with recovery hints
|
||||
- ✗ Structural summarization (collapse braces)
|
||||
- ✗ Archive/SQLite support
|
||||
- ✗ Multi-range selectors (`:5-16,960-973`)
|
||||
- ✗ Prose column cap
|
||||
- ✗ Hash line anchors
|
||||
|
||||
**Estimated LOC to Add**: 1,200-1,500 (including tests)
|
||||
|
||||
### 3.2 EDIT Tool Gaps
|
||||
|
||||
**File**: `rust/crates/runtime/src/file_ops.rs:760`
|
||||
|
||||
**Current**: Basic string replacement works
|
||||
**Missing**:
|
||||
- ✗ Rich patch metadata (line numbers, context lines)
|
||||
|
||||
**Estimated LOC to Add**: 200-300
|
||||
|
||||
### 3.3 SEARCH Tool Gaps
|
||||
|
||||
**File**: `rust/crates/tools/src/lib.rs` (grep search)
|
||||
|
||||
**Current**: Basic regex with context
|
||||
**Missing**:
|
||||
- ✗ Advanced filtering (file type, glob exclude)
|
||||
- ✗ Structured output format
|
||||
|
||||
**Estimated LOC to Add**: 300-400
|
||||
|
||||
### 3.4 FIND Tool Gaps
|
||||
|
||||
**File**: `rust/crates/tools/src/lib.rs` (glob search)
|
||||
|
||||
**Current**: Basic glob expansion
|
||||
**Missing**:
|
||||
- ✗ Recursive globs
|
||||
- ✗ Gitignore filtering
|
||||
- ✗ Hidden file control
|
||||
- ✗ File metadata
|
||||
|
||||
**Estimated LOC to Add**: 200-300
|
||||
|
||||
---
|
||||
|
||||
## 4. IMPLEMENTATION PLAN (BATCHED)
|
||||
|
||||
### Batch 1: READ Tool (Priority P0)
|
||||
- Add line range selector parsing
|
||||
- Implement `:raw` and `:conflicts` modes
|
||||
- Add truncation footers with recovery hints
|
||||
- Implement structural summarization
|
||||
- Add tests for all selector combinations
|
||||
|
||||
**Files to Modify**:
|
||||
- `rust/crates/runtime/src/file_ops.rs` (read_file_in_workspace)
|
||||
- `rust/crates/tools/src/lib.rs` (ReadFileInput struct)
|
||||
- Tests in both
|
||||
|
||||
**Size Estimate**: 1,200 LOC
|
||||
**Complexity**: Medium (string parsing, output formatting)
|
||||
|
||||
### Batch 2: EDIT Tool (Priority P1)
|
||||
- Add patch metadata to output
|
||||
- Ensure exact match semantics
|
||||
- Add comprehensive tests
|
||||
|
||||
**Files to Modify**:
|
||||
- `rust/crates/runtime/src/file_ops.rs` (edit_file_in_workspace)
|
||||
- Tests
|
||||
|
||||
**Size Estimate**: 200 LOC
|
||||
**Complexity**: Low
|
||||
|
||||
### Batch 3: SEARCH/FIND Tools (Priority P1)
|
||||
- Enhance grep/find with GJC-compatible filtering
|
||||
- Add structured output format
|
||||
- Add metadata (file type, modified time)
|
||||
|
||||
**Files to Modify**:
|
||||
- `rust/crates/tools/src/lib.rs` (glob_search, grep_search)
|
||||
- `rust/crates/runtime/src/file_ops.rs`
|
||||
|
||||
**Size Estimate**: 500 LOC
|
||||
**Complexity**: Low-Medium
|
||||
|
||||
---
|
||||
|
||||
## 5. VERIFICATION STRATEGY
|
||||
|
||||
Each batch will include:
|
||||
1. **Semantic Tests**: Verify tool inputs/outputs match GJC reference
|
||||
2. **Edge Case Tests**: Line ranges, truncation, archives, etc.
|
||||
3. **Integration Tests**: End-to-end with claw CLI
|
||||
4. **Parity Shadow Test**: Run same inputs against both GJC and claw-code, compare outputs
|
||||
|
||||
---
|
||||
|
||||
## 6. ROLLOUT SCHEDULE
|
||||
|
||||
- **Batch 1 (READ)**: Week 1 - Enable most impactful tool first
|
||||
- **Batch 2 (EDIT)**: Week 1-2 - Quick follow-up
|
||||
- **Batch 3 (SEARCH/FIND)**: Week 2 - Lower priority but valuable for discoverability
|
||||
|
||||
---
|
||||
|
||||
## 7. REFERENCES
|
||||
|
||||
- GJC Read Tool: `/home/bellman/Workspace/gajae-code/packages/coding-agent/src/tools/read.ts`
|
||||
- claw-code file_ops: `rust/crates/runtime/src/file_ops.rs`
|
||||
- claw-code tools: `rust/crates/tools/src/lib.rs`
|
||||
- Gap Matrix: `docs/gjc-compat/gap-matrix.md`
|
||||
Reference in new issue
Block a user