@ia-ccun/code-agent-cli 0.0.52-beta.6 → 0.0.52-beta.7

package/config/agent/bin/README.md

@@ -0,0 +1,112 @@
+# CLI 工具安装指南
+
+本目录包含 `fd` 和 `rg`（ripgrep）两个高效文件搜索工具的各平台预编译二进制文件。
+
+> **Author**: aicode-cli
+
+## 文件清单
+
+| 文件名 | 平台 | 版本 |
+|--------|------|------|
+| `fd` | Linux (x86-64 ELF) | 10.3.0 |
+| `rg` | Linux (x86-64 ELF) | 15.1.0 |
+| `fd-win.zip` | Windows (x64) | 10.4.2 |
+| `rg-win.zip` | Windows (x64) | 15.1.0 |
+
+---
+
+## Linux 用户
+
+本目录中的 `fd` 和 `rg` 已是 Linux 可执行文件，无需额外操作，只需赋予执行权限即可使用。
+
+```bash
+# 确保有执行权限
+chmod +x fd rg
+
+# 验证安装
+./fd --version
+./rg --version
+```
+
+### 安装到系统路径（可选）
+
+```bash
+sudo cp fd rg /usr/local/bin/
+```
+
+或安装到用户目录：
+
+```bash
+mkdir -p ~/.local/bin
+cp fd rg ~/.local/bin/
+```
+
+确保 `~/.local/bin` 在 `$PATH` 中。
+
+---
+
+## Windows 用户
+
+需要解压 zip 文件获取 `.exe` 可执行文件
+
+### 方法一：文件资源管理器
+
+1. 右键 `fd-win.zip` → 解压到当前文件夹
+2. 右键 `rg-win.zip` → 解压到当前文件夹
+3. 将解压出的 `fd.exe` 和 `rg.exe` 复制到你的工具目录
+
+### 方法二：PowerShell
+
+```powershell
+# 解压
+Expand-Archive fd-win.zip -DestinationPath .
+Expand-Archive rg-win.zip -DestinationPath .
+
+# 验证
+.\fd.exe --version
+.\rg.exe --version
+```
+
+### 添加到 PATH（可选）
+
+将 `fd.exe` 和 `rg.exe` 放入以下任一位置：
+
+- `C:\Users\<用户名>\.aicode-cli\agent\bin\`
+- 或任意已在 `%PATH%` 中的目录
+
+**验证：**
+
+```powershell
+# 重新打开终端后执行
+fd --version
+rg --version
+```
+
+---
+
+## macOS 用户
+
+> ⚠️ 本目录 **不提供** macOS 版本二进制文件。
+
+请通过 Homebrew 安装：
+
+```bash
+brew install fd ripgrep
+```
+
+---
+
+## 用途说明
+
+| 工具 | 用途 | 常用示例 |
+|------|------|----------|
+| `fd` | 快速文件查找 | `fd -e ts "pattern"` |
+| `rg` | 快速文本搜索 | `rg -t ts "pattern"` |
+
+---
+
+
+
+详细用法请参阅：
+- fd: https://github.com/sharkdp/fd
+- ripgrep: https://github.com/BurntSushi/ripgrep

package/config/agent/extensions/aicode-safety-guard.ts

@@ -266,10 +266,10 @@ async function confirmOrBlock(
           finish({ allow: true, scope: "permanent" });
           break;
         default:
-          finish({ block: true, reason: "Blocked by safety-guard extension" });
+          finish({ block: true, reason: "Blocked by aicode-safety-guard extension" });
           break;
       }
-    }).catch(() => finish({ block: true, reason: "Blocked by safety-guard extension" }));
+    }).catch(() => finish({ block: true, reason: "Blocked by aicode-safety-guard extension" }));
   });
 }
 

package/config/agent/extensions/aicode-tips.ts

@@ -98,6 +98,14 @@ const AICODE_TIPS = [
   "/btw 并行侧边对话，可在不中断主流程的情况下进行临时讨论或查询 ",
   "/rewind 回退到任意工具执行前的状态，支持快照恢复和撤销重做 ",
   "/mcp 连接现有的 MCP 服务器 (如 xx 平台、企业微信等等)，扩展 AI 能力支持多种外部工具和服务 ",
+  // 新增扩展命令提示
+  "/cd 路径  切换会话工作目录，快速跳转不同项目",
+  "/grill-me  启动设计访谈，系统收集需求并生成决策文档",
+  "/ponytail  开启极简模式，强制 AI 用最少代码解决问题",
+  "💡 多步骤任务会自动显示待办进度条，实时跟踪完成情况",
+  "💡 需要理解陌生代码库时说'帮我解读这个项目'，自动构建知识图谱",
+  "💡 autoresearch：自动实验循环，持续优化参数直到收敛",
+  "🛡️ 安全围栏已默认启用，自动拦截危险操作（rm -rf、git reset --hard 等）",
   // 新增扩展功能提示
   "Alt+/ 或 Ctrl+Alt+W 快速切换到 BTW 侧边对话窗口",
   "BTW 侧边对话：独立上下文，不影响主会话，适合临时查询和讨论",

package/config/agent/skills/chroma/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Chroma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/config/agent/skills/chroma/chroma-local/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: chroma-local
+description: Use when the user needs self-hosted or local Chroma for semantic search, including `ChromaClient`, `HttpClient`, or Python `EphemeralClient`, local persistence, Docker or `chroma run`, or OSS Chroma without Chroma Cloud features.
+---
+
+## Instructions
+
+Determine these before writing code. Prefer discovering them from the repo and the user request. Ask only when the choice materially changes the implementation.
+
+1. **Runtime shape**
+   - Are they connecting to a running local server, embedding Chroma into tests, or setting up local development from scratch?
+   - Decide whether they need `chroma run`, a Docker or service command, `HttpClient` or `ChromaClient`, or Python `EphemeralClient`.
+
+2. **Persistence**
+   - Persistent local data: choose an intentional data path.
+   - Disposable test data: use defaults or a temp directory.
+
+3. **Embedding model**
+   - Reuse the app's existing embedding provider when possible.
+   - Otherwise default to `@chroma-core/default-embed` in TypeScript or the standard local default in Python.
+   - If the user explicitly wants OpenAI embeddings in TypeScript, install and use `@chroma-core/openai`.
+
+4. **Indexed data shape**
+   - Determine what is being indexed, how it should be chunked, and what metadata is needed for filtering and updates.
+
+## Routing
+
+- **Existing local server**
+  - Confirm host and port before changing client code.
+  - Validate the server is reachable before assuming collections are missing.
+
+- **Fresh local development**
+  - Add a local startup path such as `chroma run` or the repo's existing Docker or service command.
+  - Default to `localhost:8000` unless the repo already uses another address.
+
+- **Python tests or disposable local workflows**
+  - Prefer `EphemeralClient` when persistence is unnecessary.
+  - Call out that data is lost when the process exits.
+
+- **Persistent local development**
+  - Use a stable data path and make persistence explicit in code or config.
+  - Do not silently switch between ephemeral and persistent modes.
+
+- **Search integration work**
+  - Use `getOrCreateCollection()` in TypeScript or `get_or_create_collection()` in Python.
+  - Design document IDs and metadata so upserts and deletes are straightforward.
+  - Batch writes when syncing large datasets.
+
+## Ask vs proceed
+
+**Ask first:**
+- Embedding model choice (cost and quality implications)
+- Whether they need persistent local data
+- How they are starting the local server
+- Multi-tenant data isolation strategy
+
+**Proceed with sensible defaults:**
+- Use `getOrCreateCollection()` (TypeScript) / `get_or_create_collection()` (Python)
+- Use cosine similarity (most common)
+- Chunk size under 8KB
+- Store source IDs in metadata for updates/deletes
+- Use a local server on `localhost:8000` unless the repo already configures another address or is using Python `EphemeralClient`
+
+## What to validate
+
+- Correct client import (`ChromaClient`, `HttpClient`, or `Client`)
+- Embedding function package is installed (TypeScript)
+- Local server is reachable before assuming collections are missing
+- Local path and persistence mode are intentional
+
+## Implementation notes
+
+- Local Chroma is the right default for development, tests, and self-hosted deployments.
+- OSS Chroma does not include Chroma Cloud-only features such as `Schema()` and `Search()`.
+- If the user asks for hybrid dense and sparse retrieval, treat that as a likely Chroma Cloud requirement unless the repo already implements an OSS workaround.
+- For open source Chroma, dense retrieval with a single embedding function is the normal baseline.
+
+## Minimal patterns
+
+Start a local Chroma server when the repo needs one:
+
+```bash
+chroma run
+```
+
+Default address: `localhost:8000`.
+
+TypeScript local client:
+
+```typescript
+import { ChromaClient } from 'chromadb';
+import { DefaultEmbeddingFunction } from '@chroma-core/default-embed';
+
+const client = new ChromaClient();
+
+const embeddingFunction = new DefaultEmbeddingFunction();
+const collection = await client.getOrCreateCollection({
+  name: 'my_collection',
+  embeddingFunction,
+});
+
+// Add documents
+await collection.add({
+  ids: ['doc1', 'doc2'],
+  documents: ['First document text', 'Second document text'],
+});
+
+// Query
+const results = await collection.query({
+  queryTexts: ['search query'],
+  nResults: 5,
+});
+```
+
+Python local client:
+
+```python
+import chromadb
+
+client = chromadb.HttpClient(host="localhost", port=8000)
+
+collection = client.get_or_create_collection(name="my_collection")
+
+# Add documents
+collection.add(
+    ids=["doc1", "doc2"]   ,
+    documents=["First document text", "Second document text"],
+)
+
+# Query
+results = collection.query(
+    query_texts=["search query"],
+    n_results=5,
+)
+```
+
+## Learn More
+
+Fetch Chroma's `llms.txt` only when you need API or product details that are not already in the repo or this skill: https://docs.trychroma.com/llms.txt
+
+## Available Topics
+
+### Typescript
+
+- [Chroma Regex Filtering](./regex/typescript.md) - Learn how to use regex filters in Chroma queries
+- [Query and Get](./querying/typescript.md) - Query and Get Data from Chroma Collections
+- [Metadata](./metadata/typescript.md) - Store and query metadata, including filters and array values
+- [Updating and Deleting](./updating-deleting/typescript.md) - Update existing documents and delete data from collections
+- [Error Handling](./error-handling/typescript.md) - Handling errors and failures when working with Chroma
+- [Local Chroma](./local-chroma/typescript.md) - How to run and use local chroma
+
+### Python
+
+- [Chroma Regex Filtering](./regex/python.md) - Learn how to use regex filters in Chroma queries
+- [Query and Get](./querying/python.md) - Query and Get Data from Chroma Collections
+- [Metadata](./metadata/python.md) - Store and query metadata, including filters and array values
+- [Updating and Deleting](./updating-deleting/python.md) - Update existing documents and delete data from collections
+- [Error Handling](./error-handling/python.md) - Handling errors and failures when working with Chroma
+- [Local Chroma](./local-chroma/python.md) - How to run and use local chroma
+
+## General
+
+- [Data Model](./data-model.md) - An overview of how Chroma stores data
+- [Integrating Chroma into an existing system](./understanding-a-codebase.md) - Guidance for adding Chroma search to an existing application
+- [Chroma CLI](./cli.md) - Starting and managing a local open source Chroma server from the CLI

package/config/agent/skills/chroma/chroma-local/cli.md

@@ -0,0 +1,48 @@
+---
+name: Chroma CLI
+description: Starting and managing a local open source Chroma server from the CLI
+---
+
+## Chroma CLI
+
+The Chroma CLI can also be used for local open source Chroma workflows. This topic focuses on starting and managing a local server, not Chroma Cloud account setup.
+
+### Install
+
+```bash
+pip install chromadb
+```
+
+### Start a local server
+
+Run Chroma locally on the default address:
+
+```bash
+chroma run
+```
+
+This starts a server on `localhost:8000`.
+
+### Choose a persistent data directory
+
+Store local data in a specific path instead of the default working directory:
+
+```bash
+chroma run --path ./chroma-data
+```
+
+### Change the port
+
+If another process already uses port `8000`, pick another one:
+
+```bash
+chroma run --port 8001
+```
+
+Update your client code to match the chosen host and port.
+
+### Local workflow tips
+
+- Use a dedicated data directory per environment so dev and test data do not mix.
+- In tests, use disposable directories or clear collections between runs.
+- Check that the server is running before debugging client-side collection errors.

package/config/agent/skills/chroma/chroma-local/data-model.md

@@ -0,0 +1,103 @@
+---
+name: Data Model
+description: An overview of how Chroma stores data
+---
+
+## Data Model
+
+Use this reference when designing collection layout, chunking, IDs, metadata, and filtering for Chroma.
+
+### Core concepts
+
+**Collections** are the top-level containers, similar to tables in a relational database. Each collection has its own embedding configuration and indexes.
+
+**Documents** are the searchable units within a collection. Each document has:
+- **ID** - A unique string identifier
+- **Content** - The text that gets embedded and searched
+- **Embedding** - The vector representation
+- **Metadata** - Key-value pairs for filtering
+
+## Chunking
+
+Most real-world data is too large to fit in a single document. Chunking splits content into searchable pieces.
+
+### Chunking strategy
+
+**Recommended chunk size:** Keep chunks comfortably below product limits and small enough to preserve search precision and context. Generally, 8KB or less is a good default starting point.
+
+**Good chunking preserves meaning:**
+- Split at natural boundaries (paragraphs, sentences, sections)
+- Don't cut mid-sentence or mid-word
+- Include enough context for the chunk to be meaningful on its own
+
+**Determine from the repo or ask if ambiguous:**
+- What type of content are they indexing?
+- Are there natural boundaries (chapters, sections, records)?
+- How much context does a search result need to be useful?
+
+### Tracking chunks with metadata
+
+When a single source document becomes multiple chunks, use metadata to track the relationship:
+
+```
+{
+  "source_id": "post-123",      // ID in the primary database
+  "source_type": "blog_post",   // Type of content
+  "chunk_index": 0,             // Position in sequence
+  "total_chunks": 3             // Total chunks from this source
+}
+```
+
+This approach is better than encoding information in the document ID because:
+- IDs can be simple UUIDs
+- Metadata is filterable
+- Updates and deletes are easier (filter by `source_id`)
+
+## Collection organization
+
+For multi-tenant applications, separate collections per tenant are a strong default when isolation, deletion, and search quality matter more than minimizing collection count.
+
+**Why this works better:**
+- Nearest neighbor search is more accurate with fewer candidates
+- Lower latency with smaller collections
+- Natural isolation between tenants
+- Easy to delete all tenant data by dropping the collection
+
+**Example:** A knowledge base SaaS might have collections like `kb_customer_123`, `kb_customer_456`, etc.
+
+**Determine from the repo or ask if ambiguous:** What's the smallest logical unit of data isolation in their application?
+
+## Filtering
+
+Metadata filtering reduces the candidate set before vector search runs, making queries faster and more precise.
+
+### Filter operators
+
+| Operator | Description | Types |
+|----------|-------------|-------|
+| `$eq` | Equal (default) | string, int, bool |
+| `$ne` | Not equal | string, int, bool |
+| `$gt`, `$gte` | Greater than (or equal) | int |
+| `$lt`, `$lte` | Less than (or equal) | int |
+| `$in` | In list | string, int |
+| `$nin` | Not in list | string, int |
+| `$and`, `$or` | Logical combinators | filter arrays |
+| `$contains`, `$not_contains` | Check within arrays | arrays of string, int, bool |
+
+### Document content filtering
+
+Beyond metadata, you can filter on the document text itself using `where_document`:
+- `$contains` - Full-text substring search
+- `$regex` - Regular expression matching
+
+## Dense vs sparse vectors
+
+**Dense vectors** (default) are produced by neural embedding models. They capture semantic meaning, so "car" and "automobile" will be similar.
+
+**Sparse vectors** (BM25, SPLADE) are high-dimensional but mostly zeros. They excel at exact keyword matching.
+
+**Hybrid search** combines both, often outperforming either alone. Chroma Cloud supports hybrid search through the Schema and Search APIs.
+
+### Important note
+
+When creating collections, `get_or_create_collection()` accepts either an `embedding_function` OR a `schema`, but not both. Use Schema when you need multiple indexes or sparse embeddings. 

package/config/agent/skills/chroma/chroma-local/error-handling/python.md

@@ -0,0 +1,166 @@
+---
+name: Error Handling
+description: Handling errors and failures when working with Chroma
+---
+
+## Error Handling
+
+Local Chroma operations can fail for various reasons: the local server may not be running, collections may be missing, or input data may be invalid. This guide covers the common local error scenarios and how to handle them.
+
+```python
+import json
+import time
+
+import chromadb
+from chromadb.errors import NotFoundError
+from chromadb.types import Metadata
+```
+
+### Error types
+
+**Python** uses specific exception classes:
+- `chromadb.errors.NotFoundError` - Collection, tenant, or database doesn't exist
+- `ValueError` - Invalid collection name or duplicate creation attempt
+
+**TypeScript** throws standard `Error` objects with descriptive messages. Check the error message to determine the cause.
+
+### Connection errors
+
+Connection failures occur when the client can't reach the Chroma server. This is common during startup or when network issues occur.
+
+```python
+def connect_with_retry(max_retries: int = 3):
+    """Connect to a local Chroma server with exponential backoff retry."""
+    client = chromadb.HttpClient(host="localhost", port=8000)
+
+    for attempt in range(1, max_retries + 1):
+        try:
+            client.heartbeat()
+            return client
+        except Exception as e:
+            if attempt == max_retries:
+                raise ConnectionError(
+                    f"Failed to connect to local Chroma after {max_retries} attempts: {e}"
+                )
+
+            time.sleep(2 ** (attempt - 1))
+
+    raise ConnectionError("Chroma is unreachable")
+```
+
+### Collection not found
+
+When working with collections that may not exist, handle the `NotFoundError` (Python) or catch the error and check its message (TypeScript).
+
+```python
+client = chromadb.HttpClient(host="localhost", port=8000)
+
+try:
+    collection = client.get_collection(name="my_collection")
+except NotFoundError:
+    print("Collection not found, creating it...")
+    collection = client.create_collection(name="my_collection")
+```
+
+### Safe collection access pattern
+
+The `getOrCreateCollection` method is the recommended way to avoid "not found" errors entirely. Use `getCollection` only when you specifically need to verify a collection exists.
+
+```python
+client = chromadb.HttpClient(host="localhost", port=8000)
+collection = client.get_or_create_collection(name="my_collection")
+
+results = collection.query(
+    query_texts=["search query"],
+    n_results=5,
+)
+
+if results["documents"] and len(results["documents"][0]) > 0:
+    first_doc = results["documents"][0][0]
+else:
+    pass
+```
+
+### Validation errors
+
+Chroma validates data before operations. Common validation failures include:
+- Document content exceeding 16KB
+- Embedding dimensions not matching the collection
+- Metadata exceeding limits (4KB total, 32 keys max)
+- Invalid collection names
+
+```python
+client = chromadb.HttpClient(host="localhost", port=8000)
+
+
+def validate_document(doc: str) -> bool:
+    byte_size = len(doc.encode("utf-8"))
+    return byte_size <= 16384
+
+
+def validate_metadata(metadata: Metadata) -> bool:
+    if len(metadata.keys()) > 32:
+        return False
+
+    json_size = len(json.dumps(metadata).encode("utf-8"))
+    return json_size <= 4096
+
+
+def safe_add(
+    collection_name: str,
+    ids: list[str],
+    documents: list[str],
+    metadatas: list[Metadata] | None
+) -> None:
+    for doc in documents:
+        if not validate_document(doc):
+            raise ValueError("Document exceeds 16KB limit")
+
+    if metadatas:
+        for meta in metadatas:
+            if not validate_metadata(meta):
+                raise ValueError("Metadata exceeds limits (4KB or 32 keys)")
+
+    collection = client.get_or_create_collection(name=collection_name)
+    collection.add(ids=ids, documents=documents, metadatas=metadatas)
+```
+
+### Batch operation failures
+
+When adding or upserting multiple documents, a single invalid document fails the entire batch. Validate data before sending, or implement retry logic for partial failures.
+
+```python
+client = chromadb.HttpClient(host="localhost", port=8000)
+
+
+def batch_add(
+    collection_name: str,
+    ids: list[str],
+    documents: list[str],
+    batch_size: int = 100,
+) -> dict:
+    collection = client.get_or_create_collection(name=collection_name)
+    failures = []
+
+    for i in range(0, len(ids), batch_size):
+        batch_ids = ids[i : i + batch_size]
+        batch_docs = documents[i : i + batch_size]
+
+        try:
+            collection.add(ids=batch_ids, documents=batch_docs)
+        except Exception as e:
+            failures.append({"index": i, "error": str(e)})
+
+    total_batches = (len(ids) + batch_size - 1) // batch_size
+    return {"total_batches": total_batches, "failures": failures}
+```
+
+### Defensive patterns summary
+
+| Scenario | Recommended approach |
+|----------|---------------------|
+| Collection access | Use `getOrCreateCollection` instead of `getCollection` |
+| Missing data | Check results length before accessing |
+| Connection issues | Implement retry with exponential backoff |
+| Large batches | Validate data size before operations |
+| Local server startup | Verify the server is running before debugging query logic |