deepspider 0.1.0

package/.cursor/commands/trellis-update-spec.md

@@ -0,0 +1,213 @@
+# Update Spec - Capture Knowledge into Specifications
+
+When you learn something valuable (from debugging, implementing, or discussion), use this command to update the relevant spec documents.
+
+**Timing**: After completing a task, fixing a bug, or discovering a new pattern
+
+---
+
+## When to Update Specs
+
+| Trigger | Example | Target Spec |
+|---------|---------|-------------|
+| **Fixed a bug** | Found a subtle issue with error handling | `backend/error-handling.md` |
+| **Discovered a pattern** | Found a better way to structure code | Relevant guidelines file |
+| **Hit a gotcha** | Learned that X must be done before Y | Relevant spec + "Common Mistakes" section |
+| **Established a convention** | Team agreed on naming pattern | `quality-guidelines.md` |
+| **Cross-layer insight** | Understood how data flows between layers | `guides/cross-layer-thinking-guide.md` |
+
+---
+
+## Spec Structure Overview
+
+```
+.trellis/spec/
+├── backend/           # Backend development standards
+│   ├── index.md       # Overview and links
+│   └── *.md           # Topic-specific guidelines
+├── frontend/          # Frontend development standards
+│   ├── index.md       # Overview and links
+│   └── *.md           # Topic-specific guidelines
+└── guides/            # Thinking guides
+    ├── index.md       # Guide index
+    └── *.md           # Topic-specific guides
+```
+
+---
+
+## Update Process
+
+### Step 1: Identify What You Learned
+
+Answer these questions:
+
+1. **What did you learn?** (Be specific)
+2. **Why is it important?** (What problem does it prevent?)
+3. **Where does it belong?** (Which spec file?)
+
+### Step 2: Classify the Update Type
+
+| Type | Description | Action |
+|------|-------------|--------|
+| **New Pattern** | A reusable approach discovered | Add to "Patterns" section |
+| **Forbidden Pattern** | Something that causes problems | Add to "Anti-patterns" or "Don't" section |
+| **Common Mistake** | Easy-to-make error | Add to "Common Mistakes" section |
+| **Convention** | Agreed-upon standard | Add to relevant section |
+| **Gotcha** | Non-obvious behavior | Add warning callout |
+
+### Step 3: Read the Target Spec
+
+Before editing, read the current spec to:
+- Understand existing structure
+- Avoid duplicating content
+- Find the right section for your update
+
+```bash
+cat .trellis/spec/<category>/<file>.md
+```
+
+### Step 4: Make the Update
+
+Follow these principles:
+
+1. **Be Specific**: Include concrete examples, not just abstract rules
+2. **Explain Why**: State the problem this prevents
+3. **Show Code**: Add code snippets for patterns
+4. **Keep it Short**: One concept per section
+
+### Step 5: Update the Index (if needed)
+
+If you added a new section or the spec status changed, update the category's `index.md`.
+
+---
+
+## Update Templates
+
+### Adding a New Pattern
+
+```markdown
+### Pattern Name
+
+**Problem**: What problem does this solve?
+
+**Solution**: Brief description of the approach.
+
+**Example**:
+\`\`\`
+// Good
+code example
+
+// Bad
+code example
+\`\`\`
+
+**Why**: Explanation of why this works better.
+```
+
+### Adding a Forbidden Pattern
+
+```markdown
+### Don't: Pattern Name
+
+**Problem**:
+\`\`\`
+// Don't do this
+bad code example
+\`\`\`
+
+**Why it's bad**: Explanation of the issue.
+
+**Instead**:
+\`\`\`
+// Do this instead
+good code example
+\`\`\`
+```
+
+### Adding a Common Mistake
+
+```markdown
+### Common Mistake: Description
+
+**Symptom**: What goes wrong
+
+**Cause**: Why this happens
+
+**Fix**: How to correct it
+
+**Prevention**: How to avoid it in the future
+```
+
+### Adding a Gotcha
+
+```markdown
+> **Warning**: Brief description of the non-obvious behavior.
+>
+> Details about when this happens and how to handle it.
+```
+
+---
+
+## Interactive Mode
+
+If you're unsure what to update, answer these prompts:
+
+1. **What did you just finish?**
+   - [ ] Fixed a bug
+   - [ ] Implemented a feature
+   - [ ] Refactored code
+   - [ ] Had a discussion about approach
+
+2. **What surprised you or was non-obvious?**
+   - (Describe the insight)
+
+3. **Would this help someone else avoid the same problem?**
+   - Yes → Proceed to update spec
+   - No → Maybe not worth documenting
+
+4. **Which area does it relate to?**
+   - [ ] Backend code
+   - [ ] Frontend code
+   - [ ] Cross-layer data flow
+   - [ ] Code organization/reuse
+   - [ ] Quality/testing
+
+---
+
+## Quality Checklist
+
+Before finishing your spec update:
+
+- [ ] Is the content specific and actionable?
+- [ ] Did you include a code example?
+- [ ] Did you explain WHY, not just WHAT?
+- [ ] Is it in the right spec file?
+- [ ] Does it duplicate existing content?
+- [ ] Would a new team member understand it?
+
+---
+
+## Relationship to Other Commands
+
+```
+Development Flow:
+  Learn something → /trellis-update-spec → Knowledge captured
+       ↑                                  ↓
+  /trellis-break-loop ←──────────────────── Future sessions benefit
+  (deep bug analysis)
+```
+
+- `/trellis-break-loop` - Analyzes bugs deeply, often reveals spec updates needed
+- `/trellis-update-spec` - Actually makes the updates (this command)
+- `/trellis-finish-work` - Reminds you to check if specs need updates
+
+---
+
+## Core Philosophy
+
+> **Specs are living documents. Every debugging session, every "aha moment" is an opportunity to make the spec better.**
+
+The goal is **institutional memory**:
+- What one person learns, everyone benefits from
+- What AI learns in one session, persists to future sessions
+- Mistakes become documented guardrails

package/.env.example

@@ -0,0 +1,11 @@
+# DeepSpider 配置
+
+# LLM API 配置（兼容 OpenAI 格式的任意供应商）
+LLM_API_KEY=your_api_key_here
+LLM_BASE_URL=https://api.openai.com/v1
+LLM_MODEL=gpt-4o
+
+# LangSmith 追踪配置（可选）
+LANGSMITH_TRACING=true
+LANGSMITH_API_KEY=your_langsmith_api_key_here
+LANGSMITH_PROJECT=deepspider

package/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "deepspider": {
+      "command": "node",
+      "args": ["src/mcp/server.js"]
+    }
+  }
+}

package/.trellis/.template-hashes.json

@@ -0,0 +1,65 @@
+{
+  ".trellis/scripts/add-session.sh": "5e8e4ebf9e85684c130e636b67c6def49bab4aa6e4e303d591173b1797e82c37",
+  ".trellis/scripts/common/developer.sh": "fac965c73fa93cb9656f1fdda71dc525ac53309fc702f306f68a4914fc0d5788",
+  ".trellis/scripts/common/git-context.sh": "c0fb34d6f71b6e22b2938a4143fa3053b4ecc5fbaa144281c4cd2fce2a9837f0",
+  ".trellis/scripts/common/paths.sh": "c2b38f795668071e40b4fb817f1f710d61db76b38d09e1f47d71573d4ee7475a",
+  ".trellis/scripts/common/phase.sh": "08ab369480d3a3c226de8ecf084dc34c297c27950ebcb2aa2bc8df1cec686288",
+  ".trellis/scripts/common/registry.sh": "2bf06ca0b100aa960e14590fb2c41c5aa1c40f156a406429757da038e92ead65",
+  ".trellis/scripts/common/task-queue.sh": "fbc168ee801a5986e8bd5ec6cfceb7384c2d93a9985f9c37f35c238b8d633ea9",
+  ".trellis/scripts/common/task-utils.sh": "8ad2ee44df470183f536319f88b446dc603e3fddcdd1b71396960d8dd52045ea",
+  ".trellis/scripts/common/worktree.sh": "7a420eecab9dfe361bea1b0a5cb9ce4b42b984fbffb570a75e2d9ac59f4b569d",
+  ".trellis/scripts/create-bootstrap.sh": "388905f88cf89035005eff84ae3828fdd4936707481ba702c08c6a206117b205",
+  ".trellis/scripts/get-context.sh": "e42bcf4b167b1d322b069d795110e4947cab4073e495be285ed7a9b8c1a3d728",
+  ".trellis/scripts/get-developer.sh": "82f62484fceef79954bb8aa77588789c476b7187bf0ff48d355d50108425dc67",
+  ".trellis/scripts/init-developer.sh": "34bbd2db4198196ec3297116ff0d8455b2af32ec6a297c978bdf8cb5abffa2f8",
+  ".trellis/scripts/multi-agent/cleanup.sh": "205993cc945ed2224ec45fa51e55f18624a6a7743fcfd44090308b1099bcb87b",
+  ".trellis/scripts/multi-agent/create-pr.sh": "0818c371031eed810e404997c10713ab685ca5eb4b5815f9a646ad1e5862e96c",
+  ".trellis/scripts/multi-agent/plan.sh": "a2349c913314561349b92e506962b9ef9c716f61ee310a18b2fc53cde3ddf04d",
+  ".trellis/scripts/multi-agent/start.sh": "feca8869f5eb305a9d1609672ce121e24cfd3ac8d000018857ca917f14dc98a0",
+  ".trellis/scripts/multi-agent/status.sh": "00a422b73d4dc8e05afdd3a310fd4c36266201550ad23383151be8efa808af7b",
+  ".trellis/scripts/task.sh": "806ec3b6ebb7d046016d907ccd6546c534653291b791d02b755d901f6d930bb2",
+  ".trellis/spec/guides/code-reuse-thinking-guide.md": "e768d4937198ccfacfb927a27e6ee731766a7dd2de0d770a3d7293ea6e3f19d5",
+  ".trellis/spec/guides/cross-layer-thinking-guide.md": "b89b09d8356f9985a838613d425e15e97bd4b5b9e8640cfe0c941d97fb152ef6",
+  ".trellis/spec/guides/index.md": "c41ea8dd33dc9ae01b376f2bf66c6b2f80e699d84a895ca87d55c7a44368d2d5",
+  ".trellis/workflow.md": "3eb1408d68456fc3dd799899997245d1c096e705db6164fe26479dbdff275114",
+  ".trellis/worktree.yaml": "c57de79e40d5f748f099625ed4a17d5f0afbf25cac598aced0b3c964e7b7c226",
+  ".claude/agents/check.md": "7c7400e7ea8bf3f3f879bfa028fd5b4d41673e0150d44c52292161ba33612812",
+  ".claude/agents/debug.md": "94be0b1cfbae4c64caee4775ef504f43acfcd4a80427a26d6f680ceaddcbee24",
+  ".claude/agents/dispatch.md": "1f26bf7dc26f739ea50ce7a662b1b8df65a18d6289584383ca6c3f1ba5559a72",
+  ".claude/agents/implement.md": "026b2193f4de057dbe1e5e0559b8a2c2ebb6c7bcdcd24e810287c35819a33db3",
+  ".claude/agents/plan.md": "077cc6f9d40563b9e4814308578c2596806e7a0dee1e7fbd9ddc5e98c2287b10",
+  ".claude/agents/research.md": "086ae23120151b3591089a4de20fd54e6ae2b89038f5903ee9a52269cd7ded6a",
+  ".claude/commands/trellis/before-backend-dev.md": "7e35444de2a5779ef39944f17f566ea21d2ed7f4994246f4cfe6ebf9a11dd3e3",
+  ".claude/commands/trellis/before-frontend-dev.md": "a6225f9d123dbd4a7aec822652030cae50be3f5b308297015e04d42b23a27b2a",
+  ".claude/commands/trellis/break-loop.md": "24d07ac0ac1873cb7adf5228c597e58a58125d80fc1e8d2eb5d6948c43761566",
+  ".claude/commands/trellis/check-backend.md": "4e81a28d681ea770f780df55a212fd504ce21ee49b44ba16023b74b5c243cef3",
+  ".claude/commands/trellis/check-cross-layer.md": "b9ab24515ead84330d6634f6ad912ca3547db3a36139d62c5688161824097d60",
+  ".claude/commands/trellis/check-frontend.md": "5e8e3b682032ba0dd6bb843dd4826fff0159f78a7084964ccb119c6cf98b3d91",
+  ".claude/commands/trellis/create-command.md": "c2825c7941b4ef4a3f3365c4c807ff138096a39aece3d051776f3c11a4e4857d",
+  ".claude/commands/trellis/finish-work.md": "6a29961bd1ee55b79bfb44bce637275e4646317a3ac4a6cc77ba28c19d18ff80",
+  ".claude/commands/trellis/integrate-skill.md": "d141fd8b045c6ef27b1716c0135143879736a6cb232c56b72b4e42fd4d7effb4",
+  ".claude/commands/trellis/onboard.md": "02d219d8cde3785f79270febf5d03039e8b8052dc95341f9a6b582fb5c433ee0",
+  ".claude/commands/trellis/parallel.md": "e97ebff92fbe8959ea522530cbef1840e637c62813cf57516edeceecd84eb25e",
+  ".claude/commands/trellis/record-session.md": "bbb8140082f51128ed5b20eaead97ff084c10eafd52b5763acc879cde77a9351",
+  ".claude/commands/trellis/start.md": "3b00f04b7ccf16df0ddb87b9f3ca179ebcf45e79fdd7fbf4add1f6896a522216",
+  ".claude/commands/trellis/update-spec.md": "c8e259d66fa7223c9ab99fede83de3e5c39fb16d956ca9a3ab1f749fb1956390",
+  ".claude/hooks/inject-subagent-context.py": "3cc16fd8c6c8eb232e33538080ee7c00ee3b613df454a87da86d1856e48f2c2c",
+  ".claude/hooks/ralph-loop.py": "fd2b8cb40cbaa6428e7d1a9a89189c9481e2279165ee5b7fa5d1dd1d42b02662",
+  ".claude/hooks/session-start.py": "67b5fc4ab01b74d0352e12af5f99eada48996a88fb188216cc741e94b619894a",
+  ".claude/settings.json": "f03439ad594adb545fdeeb7cf564726d35972d37c73e5c632f6c64a4d1fed7c9",
+  ".claude/settings.local.json": "f2a6ec4081ab0412a25b049a822fb9b94f6260d36fed87a5d64bdd680cf9a577",
+  ".claude/skills/deepagents-guide/SKILL.md": "6f4e0ac61f18cfba2338f06190094c7234641b092d447e384d503d2046871f6b",
+  ".cursor/commands/trellis-before-backend-dev.md": "7e35444de2a5779ef39944f17f566ea21d2ed7f4994246f4cfe6ebf9a11dd3e3",
+  ".cursor/commands/trellis-before-frontend-dev.md": "a6225f9d123dbd4a7aec822652030cae50be3f5b308297015e04d42b23a27b2a",
+  ".cursor/commands/trellis-break-loop.md": "24d07ac0ac1873cb7adf5228c597e58a58125d80fc1e8d2eb5d6948c43761566",
+  ".cursor/commands/trellis-check-backend.md": "4e81a28d681ea770f780df55a212fd504ce21ee49b44ba16023b74b5c243cef3",
+  ".cursor/commands/trellis-check-cross-layer.md": "a79fe38f29f84a4524a70987e9fecfca569430df476082bff9dde31596ca3951",
+  ".cursor/commands/trellis-check-frontend.md": "5e8e3b682032ba0dd6bb843dd4826fff0159f78a7084964ccb119c6cf98b3d91",
+  ".cursor/commands/trellis-create-command.md": "9a9283add72832e0e015de770531edf37cf3720e4a72782c1cea6e9941603490",
+  ".cursor/commands/trellis-finish-work.md": "a91678f24c494775486e1462c7aeea611fde386b6dbd6fecd0d75a5fbe965de6",
+  ".cursor/commands/trellis-integrate-skill.md": "b200ce1087679bcedf508aeeb085c82549ab1232d8f01d95ff276aa5d1a24548",
+  ".cursor/commands/trellis-onboard.md": "d0bf3049e8be3a3c374587525eb574eef8ac47efe22bfa7b5daead7b9f07a778",
+  ".cursor/commands/trellis-record-session.md": "bbb8140082f51128ed5b20eaead97ff084c10eafd52b5763acc879cde77a9351",
+  ".cursor/commands/trellis-start.md": "91653b5216c58617a98d8c332937fd99534083a10cd22d6a782f7fe4053f5a15",
+  ".cursor/commands/trellis-update-spec.md": "008df54aa9b43d94dbc5107452628cac6cf18fb93bf801f8944f4a89904d066a"
+}

package/.trellis/.version

@@ -0,0 +1 @@
+0.2.11

package/.trellis/scripts/add-session.sh

@@ -0,0 +1,384 @@
+#!/bin/bash
+# Add a new session to journal file and update index.md
+#
+# Usage:
+#   ./.trellis/scripts/add-session.sh --title "Title" --commit "hash" --summary "Summary"
+#   echo "content" | ./.trellis/scripts/add-session.sh --title "Title" --commit "hash"
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common/paths.sh"
+source "$SCRIPT_DIR/common/developer.sh"
+
+MAX_LINES=2000
+TODAY=$(date +%Y-%m-%d)
+
+# Ensure developer is initialized
+ensure_developer
+
+DEVELOPER=$(get_developer)
+REPO_ROOT=$(get_repo_root)
+DEV_DIR="$REPO_ROOT/$DIR_WORKFLOW/$DIR_WORKSPACE/$DEVELOPER"
+INDEX_FILE="$DEV_DIR/index.md"
+
+# =============================================================================
+# Helper Functions
+# =============================================================================
+
+get_latest_journal_info() {
+  local latest_file=""
+  local latest_num=-1  # Start at -1 so journal-0.md can be detected (0 > -1)
+
+  for f in "$DEV_DIR"/${FILE_JOURNAL_PREFIX}*.md; do
+    if [[ -f "$f" ]]; then
+      local num=$(basename "$f" | sed "s/${FILE_JOURNAL_PREFIX}\([0-9]*\)\.md/\1/")
+      if [[ "$num" -gt "$latest_num" ]]; then
+        latest_num=$num
+        latest_file="$f"
+      fi
+    fi
+  done
+
+  if [[ -n "$latest_file" ]]; then
+    local lines=$(wc -l < "$latest_file" | tr -d ' ')
+    echo "$latest_file:$latest_num:$lines"
+  else
+    echo ":0:0"
+  fi
+}
+
+get_current_session() {
+  local line=$(grep "Total Sessions" "$INDEX_FILE" 2>/dev/null | head -1)
+  echo "$line" | sed 's/.*: //' | tr -d ' '
+}
+
+count_journal_files() {
+  local result=""
+  local journal_info=$(get_latest_journal_info)
+  local active_num=$(echo "$journal_info" | cut -d: -f2)
+  local active_file="${FILE_JOURNAL_PREFIX}$active_num.md"
+
+  for f in $(ls -v "$DEV_DIR"/${FILE_JOURNAL_PREFIX}*.md 2>/dev/null | sort -t- -k2 -n -r); do
+    if [[ -f "$f" ]]; then
+      local filename=$(basename "$f")
+      local lines=$(wc -l < "$f" | tr -d ' ')
+
+      local status="Archived"
+      if [[ "$filename" == "$active_file" ]]; then
+        status="Active"
+      fi
+
+      result="${result}| \`$filename\` | ~$lines | $status |
+"
+    fi
+  done
+  echo "$result" | sed '/^$/d'
+}
+
+create_new_journal_file() {
+  local num=$1
+  local prev_num=$((num - 1))
+  local new_file="$DEV_DIR/${FILE_JOURNAL_PREFIX}$num.md"
+
+  cat > "$new_file" << EOF
+# Journal - $DEVELOPER (Part $num)
+
+> Continuation from \`${FILE_JOURNAL_PREFIX}$prev_num.md\` (archived at ~$MAX_LINES lines)
+> Started: $TODAY
+
+---
+
+EOF
+  echo "$new_file"
+}
+
+generate_session_content() {
+  local session_num=$1
+  local title=$2
+  local commit=$3
+  local summary=$4
+  local extra_content=$5
+
+  local commit_table=""
+  if [[ -n "$commit" && "$commit" != "-" ]]; then
+    commit_table="| Hash | Message |
+|------|---------|"
+    IFS=',' read -ra COMMITS <<< "$commit"
+    for c in "${COMMITS[@]}"; do
+      c=$(echo "$c" | tr -d ' ')
+      commit_table="$commit_table
+| \`$c\` | (see git log) |"
+    done
+  else
+    commit_table="(No commits - planning session)"
+  fi
+
+  cat << EOF
+
+## Session $session_num: $title
+
+**Date**: $TODAY
+**Task**: $title
+
+### Summary
+
+$summary
+
+### Main Changes
+
+$extra_content
+
+### Git Commits
+
+$commit_table
+
+### Testing
+
+- [OK] (Add test results)
+
+### Status
+
+[OK] **Completed**
+
+### Next Steps
+
+- None - task complete
+EOF
+}
+
+# =============================================================================
+# Update Index.md
+# =============================================================================
+
+update_index() {
+  local title="$1"
+  local commit="$2"
+  local new_session="$3"
+  local active_file="$4"
+
+  # Format commit for display
+  local commit_display="-"
+  if [[ -n "$commit" && "$commit" != "-" ]]; then
+    commit_display=$(echo "$commit" | sed 's/,/, /g' | sed 's/\([a-f0-9]\{7,\}\)/`\1`/g')
+  fi
+
+  local files_table=$(count_journal_files)
+
+  echo "Updating index.md for session $new_session..."
+  echo "  Title: $title"
+  echo "  Commit: $commit_display"
+  echo "  Active File: $active_file"
+  echo ""
+
+  if ! grep -q "@@@auto:current-status" "$INDEX_FILE"; then
+    echo "Error: Markers not found in index.md. Please ensure markers exist." >&2
+    exit 1
+  fi
+
+  local tmp_file=$(mktemp)
+
+  local in_current_status=false
+  local in_active_documents=false
+  local in_session_history=false
+  local header_written=false
+
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    if [[ "$line" == *"@@@auto:current-status"* ]]; then
+      echo "$line" >> "$tmp_file"
+      in_current_status=true
+      echo "- **Active File**: \`$active_file\`" >> "$tmp_file"
+      echo "- **Total Sessions**: $new_session" >> "$tmp_file"
+      echo "- **Last Active**: $TODAY" >> "$tmp_file"
+      continue
+    fi
+
+    if [[ "$line" == *"@@@/auto:current-status"* ]]; then
+      in_current_status=false
+      echo "$line" >> "$tmp_file"
+      continue
+    fi
+
+    if [[ "$line" == *"@@@auto:active-documents"* ]]; then
+      echo "$line" >> "$tmp_file"
+      in_active_documents=true
+      echo "| File | Lines | Status |" >> "$tmp_file"
+      echo "|------|-------|--------|" >> "$tmp_file"
+      echo "$files_table" >> "$tmp_file"
+      continue
+    fi
+
+    if [[ "$line" == *"@@@/auto:active-documents"* ]]; then
+      in_active_documents=false
+      echo "$line" >> "$tmp_file"
+      continue
+    fi
+
+    if [[ "$line" == *"@@@auto:session-history"* ]]; then
+      echo "$line" >> "$tmp_file"
+      in_session_history=true
+      header_written=false
+      continue
+    fi
+
+    if [[ "$line" == *"@@@/auto:session-history"* ]]; then
+      in_session_history=false
+      echo "$line" >> "$tmp_file"
+      continue
+    fi
+
+    if $in_current_status; then
+      continue
+    fi
+
+    if $in_active_documents; then
+      continue
+    fi
+
+    if $in_session_history; then
+      echo "$line" >> "$tmp_file"
+      if [[ "$line" == "|---"* ]] && ! $header_written; then
+        echo "| $new_session | $TODAY | $title | $commit_display |" >> "$tmp_file"
+        header_written=true
+      fi
+      continue
+    fi
+
+    echo "$line" >> "$tmp_file"
+  done < "$INDEX_FILE"
+
+  mv "$tmp_file" "$INDEX_FILE"
+
+  echo "[OK] Updated index.md successfully!"
+}
+
+# =============================================================================
+# Main Function
+# =============================================================================
+
+add_session() {
+  local title=""
+  local commit="-"
+  local summary="(Add summary)"
+  local content_file=""
+  local extra_content="(Add details)"
+
+  while [[ $# -gt 0 ]]; do
+    case $1 in
+      --title)
+        title="$2"
+        shift 2
+        ;;
+      --commit)
+        commit="$2"
+        shift 2
+        ;;
+      --summary)
+        summary="$2"
+        shift 2
+        ;;
+      --content-file)
+        content_file="$2"
+        shift 2
+        ;;
+      *)
+        shift
+        ;;
+    esac
+  done
+
+  if [[ -z "$title" ]]; then
+    echo "Error: --title is required" >&2
+    echo "Usage: $0 --title \"Session Title\" [--commit \"hash1,hash2\"] [--summary \"Brief summary\"]" >&2
+    exit 1
+  fi
+
+  if [[ -n "$content_file" && -f "$content_file" ]]; then
+    extra_content=$(cat "$content_file")
+  elif [[ ! -t 0 ]]; then
+    extra_content=$(cat)
+  fi
+
+  local journal_info=$(get_latest_journal_info)
+  local current_file=$(echo "$journal_info" | cut -d: -f1)
+  local current_num=$(echo "$journal_info" | cut -d: -f2)
+  local current_lines=$(echo "$journal_info" | cut -d: -f3)
+  local current_session=$(get_current_session)
+  local new_session=$((current_session + 1))
+
+  local session_content=$(generate_session_content "$new_session" "$title" "$commit" "$summary" "$extra_content")
+  local content_lines=$(echo "$session_content" | wc -l | tr -d ' ')
+
+  echo "========================================" >&2
+  echo "ADD SESSION" >&2
+  echo "========================================" >&2
+  echo "" >&2
+  echo "Session: $new_session" >&2
+  echo "Title: $title" >&2
+  echo "Commit: $commit" >&2
+  echo "" >&2
+  echo "Current journal file: ${FILE_JOURNAL_PREFIX}$current_num.md" >&2
+  echo "Current lines: $current_lines" >&2
+  echo "New content lines: $content_lines" >&2
+  echo "Total after append: $((current_lines + content_lines))" >&2
+  echo "" >&2
+
+  local target_file="$current_file"
+  local target_num=$current_num
+
+  if [[ $((current_lines + content_lines)) -gt $MAX_LINES ]]; then
+    target_num=$((current_num + 1))
+    echo "[!] Exceeds $MAX_LINES lines, creating ${FILE_JOURNAL_PREFIX}$target_num.md" >&2
+    target_file=$(create_new_journal_file "$target_num")
+    echo "Created: $target_file" >&2
+  fi
+
+  echo "$session_content" >> "$target_file"
+  echo "[OK] Appended session to $(basename "$target_file")" >&2
+
+  echo "" >&2
+
+  # Update index.md directly
+  local active_file="${FILE_JOURNAL_PREFIX}$target_num.md"
+  update_index "$title" "$commit" "$new_session" "$active_file"
+
+  echo "" >&2
+  echo "========================================" >&2
+  echo "[OK] Session $new_session added successfully!" >&2
+  echo "========================================" >&2
+  echo "" >&2
+  echo "Files updated:" >&2
+  echo "  - $(basename "$target_file")" >&2
+  echo "  - index.md" >&2
+}
+
+show_help() {
+  echo "Usage: $0 --title \"Title\" [options]"
+  echo ""
+  echo "Add a new session to journal file and update index.md automatically."
+  echo ""
+  echo "Options:"
+  echo "  --title TEXT       Session title (required)"
+  echo "  --commit HASHES    Comma-separated commit hashes (optional)"
+  echo "  --summary TEXT     Brief summary of the session (optional)"
+  echo "  --content-file     Path to file with detailed content (optional)"
+  echo ""
+  echo "You can also pipe content via stdin:"
+  echo "  echo \"Details\" | $0 --title \"Title\" --commit \"abc123\""
+  echo ""
+  echo "Examples:"
+  echo "  $0 --title \"Fix login bug\" --commit \"abc1234\" --summary \"Fixed auth issue\""
+}
+
+# =============================================================================
+# Main Entry
+# =============================================================================
+
+case "${1:-}" in
+  --help|-h|help)
+    show_help
+    ;;
+  *)
+    add_session "$@"
+    ;;
+esac