deepspider 0.2.12 → 0.3.1

package/.trellis/spec/backend/tool-guidelines.md

@@ -1,144 +0,0 @@
-# Tool Guidelines
-
-> LangChain 工具定义规范
-
----
-
-## Overview
-
-DeepSpider 使用 `@langchain/core/tools` 定义 Agent 工具。
-每个工具是一个独立的功能单元，通过 Zod schema 定义参数类型。
-
----
-
-## Tool Structure
-
-标准工具定义结构：
-
-```javascript
-import { z } from 'zod';
-import { tool } from '@langchain/core/tools';
-
-export const myTool = tool(
-  async ({ param1, param2 }) => {
-    // 工具逻辑
-    return JSON.stringify(result, null, 2);
-  },
-  {
-    name: 'tool_name',           // snake_case 命名
-    description: '工具描述',      // 简洁明确
-    schema: z.object({
-      param1: z.string().describe('参数描述'),
-      param2: z.number().optional().default(100),
-    }),
-  }
-);
-
-// 导出工具数组
-export const myTools = [myTool];
-```
-
-**示例**: `src/agent/tools/analyzer.js:14-38`
-
----
-
-## Schema Conventions
-
-使用 Zod 定义参数 schema：
-
-```javascript
-schema: z.object({
-  // 必填参数
-  code: z.string().describe('JS代码'),
-
-  // 可选参数带默认值
-  extractFunctions: z.boolean().optional().default(true),
-
-  // 枚举类型
-  mode: z.enum(['fast', 'deep']).optional().default('fast'),
-
-  // 数组类型
-  patterns: z.array(z.string()).optional(),
-})
-```
-
-**示例**: `src/agent/tools/analyzer.js:32-36`
-
----
-
-## Return Value Patterns
-
-工具返回值规范：
-
-```javascript
-// 返回 JSON 字符串（推荐）
-return JSON.stringify(result, null, 2);
-
-// 返回简单字符串
-return `分析完成: ${count} 个函数`;
-
-// 错误处理
-try {
-  // ...
-} catch (e) {
-  return JSON.stringify({ error: e.message });
-}
-```
-
----
-
-## Tool Organization
-
-工具文件组织：
-
-```javascript
-// src/agent/tools/analyzer.js
-
-// 1. 导入依赖
-import { z } from 'zod';
-import { tool } from '@langchain/core/tools';
-import { ASTAnalyzer } from '../../analyzer/ASTAnalyzer.js';
-
-// 2. 定义各个工具
-export const analyzeAst = tool(...);
-export const analyzeCallstack = tool(...);
-
-// 3. 导出工具数组
-export const analyzerTools = [analyzeAst, analyzeCallstack];
-```
-
-**示例**: `src/agent/tools/analyzer.js`
-
----
-
-## Common Mistakes
-
-### 1. 工具名称不规范
-
-```javascript
-// ❌ 错误：使用 camelCase
-name: 'analyzeAst'
-
-// ✅ 正确：使用 snake_case
-name: 'analyze_ast'
-```
-
-### 2. 缺少参数描述
-
-```javascript
-// ❌ 错误：无描述
-param1: z.string()
-
-// ✅ 正确：有描述
-param1: z.string().describe('JS代码')
-```
-
-### 3. 返回非字符串
-
-```javascript
-// ❌ 错误：返回对象
-return result;
-
-// ✅ 正确：返回 JSON 字符串
-return JSON.stringify(result, null, 2);
-```

package/.trellis/spec/backend/type-safety.md

@@ -1,71 +0,0 @@
-# Type Safety
-
-> Zod 类型验证规范
-
----
-
-## Overview
-
-DeepSpider 是纯 JavaScript 项目，使用 Zod 进行运行时类型验证。
-主要用于 LangChain 工具的参数 schema 定义。
-
----
-
-## Zod Schema
-
-工具参数使用 Zod 定义：
-
-```javascript
-import { z } from 'zod';
-
-const schema = z.object({
-  code: z.string().describe('JS代码'),
-  mode: z.enum(['fast', 'deep']).default('fast'),
-});
-```
-
----
-
-## Validation
-
-常用 Zod 类型：
-
-| 类型 | 用法 |
-|------|------|
-| 字符串 | `z.string()` |
-| 数字 | `z.number()` |
-| 布尔 | `z.boolean()` |
-| 枚举 | `z.enum(['a', 'b'])` |
-| 数组 | `z.array(z.string())` |
-| 可选 | `.optional()` |
-| 默认值 | `.default(value)` |
-
----
-
-## Common Patterns
-
-参数描述模式：
-
-```javascript
-schema: z.object({
-  // 必填 + 描述
-  code: z.string().describe('JS代码'),
-
-  // 可选 + 默认值
-  deep: z.boolean().optional().default(false),
-})
-```
-
----
-
-## Forbidden Patterns
-
-### 1. 缺少 describe
-
-```javascript
-// ❌ 错误
-code: z.string()
-
-// ✅ 正确
-code: z.string().describe('JS代码')
-```

package/.trellis/spec/guides/code-reuse-thinking-guide.md

@@ -1,92 +0,0 @@
-# Code Reuse Thinking Guide
-
-> **Purpose**: Stop and think before creating new code - does it already exist?
-
----
-
-## The Problem
-
-**Duplicated code is the #1 source of inconsistency bugs.**
-
-When you copy-paste or rewrite existing logic:
-- Bug fixes don't propagate
-- Behavior diverges over time
-- Codebase becomes harder to understand
-
----
-
-## Before Writing New Code
-
-### Step 1: Search First
-
-```bash
-# Search for similar function names
-grep -r "functionName" .
-
-# Search for similar logic
-grep -r "keyword" .
-```
-
-### Step 2: Ask These Questions
-
-| Question | If Yes... |
-|----------|-----------|
-| Does a similar function exist? | Use or extend it |
-| Is this pattern used elsewhere? | Follow the existing pattern |
-| Could this be a shared utility? | Create it in the right place |
-| Am I copying code from another file? | **STOP** - extract to shared |
-
----
-
-## Common Duplication Patterns
-
-### Pattern 1: Copy-Paste Functions
-
-**Bad**: Copying a validation function to another file
-
-**Good**: Extract to shared utilities, import where needed
-
-### Pattern 2: Similar Components
-
-**Bad**: Creating a new component that's 80% similar to existing
-
-**Good**: Extend existing component with props/variants
-
-### Pattern 3: Repeated Constants
-
-**Bad**: Defining the same constant in multiple files
-
-**Good**: Single source of truth, import everywhere
-
----
-
-## When to Abstract
-
-**Abstract when**:
-- Same code appears 3+ times
-- Logic is complex enough to have bugs
-- Multiple people might need this
-
-**Don't abstract when**:
-- Only used once
-- Trivial one-liner
-- Abstraction would be more complex than duplication
-
----
-
-## After Batch Modifications
-
-When you've made similar changes to multiple files:
-
-1. **Review**: Did you catch all instances?
-2. **Search**: Run grep to find any missed
-3. **Consider**: Should this be abstracted?
-
----
-
-## Checklist Before Commit
-
-- [ ] Searched for existing similar code
-- [ ] No copy-pasted logic that should be shared
-- [ ] Constants defined in one place
-- [ ] Similar patterns follow same structure

package/.trellis/spec/guides/cross-layer-thinking-guide.md

@@ -1,94 +0,0 @@
-# Cross-Layer Thinking Guide
-
-> **Purpose**: Think through data flow across layers before implementing.
-
----
-
-## The Problem
-
-**Most bugs happen at layer boundaries**, not within layers.
-
-Common cross-layer bugs:
-- API returns format A, frontend expects format B
-- Database stores X, service transforms to Y, but loses data
-- Multiple layers implement the same logic differently
-
----
-
-## Before Implementing Cross-Layer Features
-
-### Step 1: Map the Data Flow
-
-Draw out how data moves:
-
-```
-Source → Transform → Store → Retrieve → Transform → Display
-```
-
-For each arrow, ask:
-- What format is the data in?
-- What could go wrong?
-- Who is responsible for validation?
-
-### Step 2: Identify Boundaries
-
-| Boundary | Common Issues |
-|----------|---------------|
-| API ↔ Service | Type mismatches, missing fields |
-| Service ↔ Database | Format conversions, null handling |
-| Backend ↔ Frontend | Serialization, date formats |
-| Component ↔ Component | Props shape changes |
-
-### Step 3: Define Contracts
-
-For each boundary:
-- What is the exact input format?
-- What is the exact output format?
-- What errors can occur?
-
----
-
-## Common Cross-Layer Mistakes
-
-### Mistake 1: Implicit Format Assumptions
-
-**Bad**: Assuming date format without checking
-
-**Good**: Explicit format conversion at boundaries
-
-### Mistake 2: Scattered Validation
-
-**Bad**: Validating the same thing in multiple layers
-
-**Good**: Validate once at the entry point
-
-### Mistake 3: Leaky Abstractions
-
-**Bad**: Component knows about database schema
-
-**Good**: Each layer only knows its neighbors
-
----
-
-## Checklist for Cross-Layer Features
-
-Before implementation:
-- [ ] Mapped the complete data flow
-- [ ] Identified all layer boundaries
-- [ ] Defined format at each boundary
-- [ ] Decided where validation happens
-
-After implementation:
-- [ ] Tested with edge cases (null, empty, invalid)
-- [ ] Verified error handling at each boundary
-- [ ] Checked data survives round-trip
-
----
-
-## When to Create Flow Documentation
-
-Create detailed flow docs when:
-- Feature spans 3+ layers
-- Multiple teams are involved
-- Data format is complex
-- Feature has caused bugs before

package/.trellis/spec/guides/index.md

@@ -1,79 +0,0 @@
-# Thinking Guides
-
-> **Purpose**: Expand your thinking to catch things you might not have considered.
-
----
-
-## Why Thinking Guides?
-
-**Most bugs and tech debt come from "didn't think of that"**, not from lack of skill:
-
-- Didn't think about what happens at layer boundaries → cross-layer bugs
-- Didn't think about code patterns repeating → duplicated code everywhere
-- Didn't think about edge cases → runtime errors
-- Didn't think about future maintainers → unreadable code
-
-These guides help you **ask the right questions before coding**.
-
----
-
-## Available Guides
-
-| Guide | Purpose | When to Use |
-|-------|---------|-------------|
-| [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md) | Identify patterns and reduce duplication | When you notice repeated patterns |
-| [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md) | Think through data flow across layers | Features spanning multiple layers |
-
----
-
-## Quick Reference: Thinking Triggers
-
-### When to Think About Cross-Layer Issues
-
-- [ ] Feature touches 3+ layers (API, Service, Component, Database)
-- [ ] Data format changes between layers
-- [ ] Multiple consumers need the same data
-- [ ] You're not sure where to put some logic
-
-→ Read [Cross-Layer Thinking Guide](./cross-layer-thinking-guide.md)
-
-### When to Think About Code Reuse
-
-- [ ] You're writing similar code to something that exists
-- [ ] You see the same pattern repeated 3+ times
-- [ ] You're adding a new field to multiple places
-- [ ] **You're modifying any constant or config**
-- [ ] **You're creating a new utility/helper function** ← Search first!
-
-→ Read [Code Reuse Thinking Guide](./code-reuse-thinking-guide.md)
-
----
-
-## Pre-Modification Rule (CRITICAL)
-
-> **Before changing ANY value, ALWAYS search first!**
-
-```bash
-# Search for the value you're about to change
-grep -r "value_to_change" .
-```
-
-This single habit prevents most "forgot to update X" bugs.
-
----
-
-## How to Use This Directory
-
-1. **Before coding**: Skim the relevant thinking guide
-2. **During coding**: If something feels repetitive or complex, check the guides
-3. **After bugs**: Add new insights to the relevant guide (learn from mistakes)
-
----
-
-## Contributing
-
-Found a new "didn't think of that" moment? Add it to the relevant guide.
-
----
-
-**Core Principle**: 30 minutes of thinking saves 3 hours of debugging.

package/.trellis/tasks/archive/02-02-evolving-skills/prd.md

@@ -1,61 +0,0 @@
-# Self-Evolving Skills System
-
-## 目标
-
-实现 Skills 自我进化机制，让 Agent 在分析过程中积累的经验能够持久化，系统越用越好用。
-
-## 核心设计
-
-### 目录结构
-
-```
-src/agent/skills/<skill-name>/
-├── SKILL.md      # 静态：基础知识（git管理）
-└── evolved.md    # 动态：运行时积累
-```
-
-### evolved.md 格式
-
-```markdown
----
-total: 15
-last_merged: 2026-01-15
----
-
-## 核心经验
-
-### 经验标题
-**场景**: 具体案例
-**经验**: 一句话总结
-
-## 近期发现
-
-### [2026-02-02] 发现标题
-**场景**: 具体案例
-**经验**: 一句话总结
-```
-
-### 加载策略
-
-- 静态 SKILL.md：全量加载
-- 动态 evolved.md：核心经验 + 最近 10 条
-
-### 阈值提示
-
-- 动态经验达到 20 条时提示合并
-- 合并通过命令触发：`/evolve:merge <skill-name>`
-
-## 实现清单
-
-1. [ ] 创建 `evolved.md` 模板文件
-2. [ ] 实现 `createEvolvingSkillsMiddleware` 中间件
-3. [ ] 实现 `evolve_skill` 工具
-4. [ ] 创建 `/evolve:merge` 命令
-5. [ ] 更新各 subagent 使用新中间件
-6. [ ] 更新 systemPrompt 指导 Agent 何时进化
-
-## 技术要点
-
-- 中间件在 Agent 启动时合并静态+动态
-- evolve_skill 工具追加内容到 evolved.md
-- 合并命令将核心经验迁移到 SKILL.md

package/.trellis/tasks/archive/02-02-evolving-skills/task.json

@@ -1,29 +0,0 @@
-{
-  "id": "evolving-skills",
-  "name": "evolving-skills",
-  "title": "Self-Evolving Skills System",
-  "description": "",
-  "status": "planning",
-  "dev_type": null,
-  "scope": null,
-  "priority": "P2",
-  "creator": "pony",
-  "assignee": "pony",
-  "createdAt": "2026-02-02",
-  "completedAt": null,
-  "branch": null,
-  "base_branch": null,
-  "worktree_path": null,
-  "current_phase": 0,
-  "next_action": [
-    {"phase": 1, "action": "implement"},
-    {"phase": 2, "action": "check"},
-    {"phase": 3, "action": "finish"},
-    {"phase": 4, "action": "create-pr"}
-  ],
-  "commit": null,
-  "pr_url": null,
-  "subtasks": [],
-  "relatedFiles": [],
-  "notes": ""
-}

package/.trellis/tasks/archive/2026-02/00-bootstrap-guidelines/prd.md

@@ -1,86 +0,0 @@
-# Bootstrap: Fill Project Development Guidelines
-
-## Purpose
-
-Welcome to Trellis! This is your first task.
-
-AI agents use `.trellis/spec/` to understand YOUR project's coding conventions.
-**Empty templates = AI writes generic code that doesn't match your project style.**
-
-Filling these guidelines is a one-time setup that pays off for every future AI session.
-
----
-
-## Your Task
-
-Fill in the guideline files based on your **existing codebase**.
-
-### Frontend Guidelines
-
-| File | What to Document |
-|------|------------------|
-| `.trellis/spec/frontend/directory-structure.md` | Component/page/hook organization |
-| `.trellis/spec/frontend/component-guidelines.md` | Component patterns, props conventions |
-| `.trellis/spec/frontend/hook-guidelines.md` | Custom hook naming, patterns |
-| `.trellis/spec/frontend/state-management.md` | State library, patterns, what goes where |
-| `.trellis/spec/frontend/type-safety.md` | TypeScript conventions, type organization |
-| `.trellis/spec/frontend/quality-guidelines.md` | Linting, testing, accessibility |
-
-### Thinking Guides (Optional)
-
-The `.trellis/spec/guides/` directory contains thinking guides that are already
-filled with general best practices. You can customize them for your project if needed.
-
----
-
-## How to Fill Guidelines
-
-### Principle: Document Reality, Not Ideals
-
-Write what your codebase **actually does**, not what you wish it did.
-AI needs to match existing patterns, not introduce new ones.
-
-### Steps
-
-1. **Look at existing code** - Find 2-3 examples of each pattern
-2. **Document the pattern** - Describe what you see
-3. **Include file paths** - Reference real files as examples
-4. **List anti-patterns** - What does your team avoid?
-
----
-
-## Tips for Using AI
-
-Ask AI to help analyze your codebase:
-
-- "Look at my codebase and document the patterns you see"
-- "Analyze my code structure and summarize the conventions"
-- "Find error handling patterns and document them"
-
-The AI will read your code and help you document it.
-
----
-
-## Completion Checklist
-
-- [ ] Guidelines filled for your project type
-- [ ] At least 2-3 real code examples in each guideline
-- [ ] Anti-patterns documented
-
-When done:
-
-```bash
-./.trellis/scripts/task.sh finish
-./.trellis/scripts/task.sh archive 00-bootstrap-guidelines
-```
-
----
-
-## Why This Matters
-
-After completing this task:
-
-1. AI will write code that matches your project style
-2. Relevant `/trellis:before-*-dev` commands will inject real context
-3. `/trellis:check-*` commands will validate against your actual standards
-4. Future developers (human or AI) will onboard faster

package/.trellis/tasks/archive/2026-02/00-bootstrap-guidelines/task.json

@@ -1,27 +0,0 @@
-{
-  "id": "00-bootstrap-guidelines",
-  "name": "Bootstrap Guidelines",
-  "description": "Fill in project development guidelines for AI agents",
-  "status": "completed",
-  "dev_type": "docs",
-  "priority": "P1",
-  "creator": "pony",
-  "assignee": "pony",
-  "createdAt": "2026-01-30",
-  "completedAt": "2026-02-02",
-  "commit": null,
-  "subtasks": [
-    {
-      "name": "Fill frontend guidelines",
-      "status": "pending"
-    },
-    {
-      "name": "Add code examples",
-      "status": "pending"
-    }
-  ],
-  "relatedFiles": [
-    ".trellis/spec/frontend/"
-  ],
-  "notes": "First-time setup task created by trellis init (frontend project)"
-}

package/.trellis/tasks/archive/2026-02/02-02-skills-system/check.jsonl

@@ -1,3 +0,0 @@
-{"file": ".claude/commands/trellis/finish-work.md", "reason": "Finish work checklist"}
-{"file": ".trellis/spec/shared/index.md", "reason": "Shared coding standards"}
-{"file": ".claude/commands/trellis/check-backend.md", "reason": "Backend check spec"}

package/.trellis/tasks/archive/2026-02/02-02-skills-system/debug.jsonl

@@ -1,2 +0,0 @@
-{"file": ".trellis/spec/shared/index.md", "reason": "Shared coding standards"}
-{"file": ".claude/commands/trellis/check-backend.md", "reason": "Backend check spec"}

package/.trellis/tasks/archive/2026-02/02-02-skills-system/implement.jsonl

@@ -1,5 +0,0 @@
-{"file": ".trellis/workflow.md", "reason": "Project workflow and conventions"}
-{"file": ".trellis/spec/shared/index.md", "reason": "Shared coding standards"}
-{"file": ".trellis/spec/backend/index.md", "reason": "Backend development guide"}
-{"file": ".trellis/spec/backend/api-module.md", "reason": "API module conventions"}
-{"file": ".trellis/spec/backend/quality.md", "reason": "Code quality requirements"}