mirror of
https://github.com/sanbuphy/claude-code-source-code.git
synced 2026-04-03 03:24:57 +08:00
init repo
This commit is contained in:
sanbuphy
797
README.md
Normal file
797
README.md
Normal file
@@ -0,0 +1,797 @@
|
|||||||
|
# Claude Code Architecture Study
|
||||||
|
|
||||||
|
> **Introduction**: This project is a learning and research repository focused on CLI Agent architecture. All materials are compiled entirely from publicly available online references and discussions, with a particular focus on public information regarding the highly popular CLI Agent `claude-code`. Our intention is to help developers better understand and utilize Agent technologies. We will continue to share more insights and practical discussions on Agent architecture in the future. Thank you for your support!
|
||||||
|
|
||||||
|
> **Disclaimer**: All content in this repository is provided strictly for technical research, study, and educational exchange among enthusiasts. **Commercial use is strictly prohibited.** No individual, organization, or entity may use this content for commercial purposes, profit-making activities, illegal activities, or any other unauthorized scenarios. If any content infringes upon your legal rights, intellectual property, or other interests, please contact us and we will verify and remove it immediately.
|
||||||
|
|
||||||
|
|
||||||
|
**Language**: **English** | [中文](README_CN.md) | [한국어](README_KR.md) | [日本語](README_JA.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Table of Contents
|
||||||
|
|
||||||
|
- [Deep Analysis Reports (`docs/`)](#deep-analysis-reports-docs) — Telemetry, codenames, undercover mode, remote control, future roadmap
|
||||||
|
- [Directory Reference](#directory-reference) — Code structure tree
|
||||||
|
- [Architecture Overview](#architecture-overview) — Entry → Query Engine → Tools/Services/State
|
||||||
|
- [Tool System & Permissions](#tool-system-architecture) — 40+ tools, permission flow, sub-agents
|
||||||
|
- [The 12 Progressive Harness Mechanisms](#the-12-progressive-harness-mechanisms) — How Claude Code layers production features on the agent loop
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Deep Analysis Reports (`docs/`)
|
||||||
|
|
||||||
|
Deep analysis reports compiled from publicly available online references and community discussions on Claude Code v2.1.88. Quadrilingual (EN/JA/KO/ZH).
|
||||||
|
|
||||||
|
```
|
||||||
|
docs/
|
||||||
|
├── en/ # English
|
||||||
|
│ ├── [01-telemetry-and-privacy.md] # Telemetry & Privacy — what's collected, why you can't opt out
|
||||||
|
│ ├── [02-hidden-features-and-codenames.md] # Codenames (Capybara/Tengu/Numbat), feature flags, internal vs external
|
||||||
|
│ ├── [03-undercover-mode.md] # Undercover Mode — hiding AI authorship in open-source repos
|
||||||
|
│ ├── [04-remote-control-and-killswitches.md]# Remote Control — managed settings, killswitches, model overrides
|
||||||
|
│ └── [05-future-roadmap.md] # Future Roadmap — Numbat, KAIROS, voice mode, unreleased tools
|
||||||
|
│
|
||||||
|
├── ja/ # 日本語
|
||||||
|
│ ├── [01-テレメトリとプライバシー.md] # テレメトリとプライバシー — 収集項目、無効化不可の理由
|
||||||
|
│ ├── [02-隠し機能とコードネーム.md] # 隠し機能 — モデルコードネーム、feature flag、内部/外部ユーザーの違い
|
||||||
|
│ ├── [03-アンダーカバーモード.md] # アンダーカバーモード — オープンソースでのAI著作隠匿
|
||||||
|
│ ├── [04-リモート制御とキルスイッチ.md] # リモート制御 — 管理設定、キルスイッチ、モデルオーバーライド
|
||||||
|
│ └── [05-今後のロードマップ.md] # 今後のロードマップ — Numbat、KAIROS、音声モード、未公開ツール
|
||||||
|
│
|
||||||
|
├── ko/ # 한국어
|
||||||
|
│ ├── [01-텔레메트리와-프라이버시.md] # 텔레메트리 및 프라이버시 — 수집 항목, 비활성화 불가 이유
|
||||||
|
│ ├── [02-숨겨진-기능과-코드네임.md] # 숨겨진 기능 — 모델 코드네임, feature flag, 내부/외부 사용자 차이
|
||||||
|
│ ├── [03-언더커버-모드.md] # 언더커버 모드 — 오픈소스에서 AI 저작 은폐
|
||||||
|
│ ├── [04-원격-제어와-킬스위치.md] # 원격 제어 — 관리 설정, 킬스위치, 모델 오버라이드
|
||||||
|
│ └── [05-향후-로드맵.md] # 향후 로드맵 — Numbat, KAIROS, 음성 모드, 미공개 도구
|
||||||
|
│
|
||||||
|
└── zh/ # 中文
|
||||||
|
├── [01-遥测与隐私分析.md] # 遥测与隐私 — 收集了什么，为什么无法退出
|
||||||
|
├── [02-隐藏功能与模型代号.md] # 隐藏功能 — 模型代号，feature flag，内外用户差异
|
||||||
|
├── [03-卧底模式分析.md] # 卧底模式 — 在开源项目中隐藏 AI 身份
|
||||||
|
├── [04-远程控制与紧急开关.md] # 远程控制 — 托管设置，紧急开关，模型覆盖
|
||||||
|
└── [05-未来路线图.md] # 未来路线图 — Numbat，KAIROS，语音模式，未上线工具
|
||||||
|
```
|
||||||
|
|
||||||
|
> Click any filename above to jump to the full report.
|
||||||
|
|
||||||
|
| # | Topic | Key Findings |
|
||||||
|
|---|-------|-------------|
|
||||||
|
| 01 | **Telemetry & Privacy** | Two analytics sinks (1P, Datadog). Environment fingerprint, process metrics, repo hash on every event. **No UI-exposed opt-out** for 1st-party logging. `OTEL_LOG_TOOL_DETAILS=1` enables full tool input capture. |
|
||||||
|
| 02 | **Hidden Features & Codenames** | Animal codenames (Capybara v8, Tengu, Fennec→Opus 4.6, **Numbat** next). Feature flags use random word pairs (`tengu_frond_boric`) to obscure purpose. Internal users get better prompts, verification agents, and effort anchors. Hidden commands: `/btw`, `/stickers`. |
|
||||||
|
| 03 | **Undercover Mode** | Official employees auto-enter undercover mode in public repos. Model instructed: *"Do not blow your cover"* — strip all AI attribution, write commits "as a human developer would." **No force-OFF exists.** Raises transparency questions for open-source communities. |
|
||||||
|
| 04 | **Remote Control** | Hourly polling of `/api/claude_code/settings`. Dangerous changes show blocking dialog — **reject = app exits**. 6+ killswitches (bypass permissions, fast mode, voice mode, analytics sink). GrowthBook flags can change any user's behavior without consent. |
|
||||||
|
| 05 | **Future Roadmap** | **Numbat** codename confirmed. Opus 4.7 / Sonnet 4.8 in development. **KAIROS** = fully autonomous agent mode with `<tick>` heartbeats, push notifications, PR subscriptions. Voice mode (push-to-talk) ready but gated. 17 unreleased tools found. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Copyright & Disclaimer
|
||||||
|
|
||||||
|
```text
|
||||||
|
This repository is provided strictly for technical research and educational purposes.
|
||||||
|
Commercial use is strictly prohibited.
|
||||||
|
|
||||||
|
If you are the copyright owner and believe this repository content infringes your rights,
|
||||||
|
please contact the repository owner for immediate removal.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Stats
|
||||||
|
|
||||||
|
| Item | Count |
|
||||||
|
|------|-------|
|
||||||
|
| Files (.ts/.tsx) | ~1,884 |
|
||||||
|
| Lines | ~512,664 |
|
||||||
|
| Largest single file | `query.ts` (~785KB) |
|
||||||
|
| Built-in tools | ~40+ |
|
||||||
|
| Slash commands | ~80+ |
|
||||||
|
| Dependencies (node_modules) | ~192 packages |
|
||||||
|
| Runtime | Bun (compiled to Node.js >= 18 bundle) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The Agent Pattern
|
||||||
|
|
||||||
|
```
|
||||||
|
THE CORE LOOP
|
||||||
|
=============
|
||||||
|
|
||||||
|
User --> messages[] --> Claude API --> response
|
||||||
|
|
|
||||||
|
stop_reason == "tool_use"?
|
||||||
|
/ \
|
||||||
|
yes no
|
||||||
|
| |
|
||||||
|
execute tools return text
|
||||||
|
append tool_result
|
||||||
|
loop back -----------------> messages[]
|
||||||
|
|
||||||
|
|
||||||
|
That is the minimal agent loop. Claude Code wraps this loop
|
||||||
|
with a production-grade harness: permissions, streaming,
|
||||||
|
concurrency, compaction, sub-agents, persistence, and MCP.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Directory Reference
|
||||||
|
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── main.tsx # REPL bootstrap, 4,683 lines
|
||||||
|
├── QueryEngine.ts # SDK/headless query lifecycle engine
|
||||||
|
├── query.ts # Main agent loop (785KB, largest file)
|
||||||
|
├── Tool.ts # Tool interface + buildTool factory
|
||||||
|
├── Task.ts # Task types, IDs, state base
|
||||||
|
├── tools.ts # Tool registry, presets, filtering
|
||||||
|
├── commands.ts # Slash command definitions
|
||||||
|
├── context.ts # User input context
|
||||||
|
├── cost-tracker.ts # API cost accumulation
|
||||||
|
├── setup.ts # First-run setup flow
|
||||||
|
│
|
||||||
|
├── bridge/ # Claude Desktop / remote bridge
|
||||||
|
│ ├── bridgeMain.ts # Session lifecycle manager
|
||||||
|
│ ├── bridgeApi.ts # HTTP client
|
||||||
|
│ ├── bridgeConfig.ts # Connection config
|
||||||
|
│ ├── bridgeMessaging.ts # Message relay
|
||||||
|
│ ├── sessionRunner.ts # Process spawning
|
||||||
|
│ ├── jwtUtils.ts # JWT refresh
|
||||||
|
│ ├── workSecret.ts # Auth tokens
|
||||||
|
│ └── capacityWake.ts # Capacity-based wakeup
|
||||||
|
│
|
||||||
|
├── cli/ # CLI infrastructure
|
||||||
|
│ ├── handlers/ # Command handlers
|
||||||
|
│ └── transports/ # I/O transports (stdio, structured)
|
||||||
|
│
|
||||||
|
├── commands/ # ~80 slash commands
|
||||||
|
│ ├── agents/ # Agent management
|
||||||
|
│ ├── compact/ # Context compaction
|
||||||
|
│ ├── config/ # Settings management
|
||||||
|
│ ├── help/ # Help display
|
||||||
|
│ ├── login/ # Authentication
|
||||||
|
│ ├── mcp/ # MCP server management
|
||||||
|
│ ├── memory/ # Memory system
|
||||||
|
│ ├── plan/ # Plan mode
|
||||||
|
│ ├── resume/ # Session resume
|
||||||
|
│ ├── review/ # Code review
|
||||||
|
│ └── ... # 70+ more commands
|
||||||
|
│
|
||||||
|
├── components/ # React/Ink terminal UI
|
||||||
|
│ ├── design-system/ # Reusable UI primitives
|
||||||
|
│ ├── messages/ # Message rendering
|
||||||
|
│ ├── permissions/ # Permission dialogs
|
||||||
|
│ ├── PromptInput/ # Input field + suggestions
|
||||||
|
│ ├── LogoV2/ # Branding + welcome screen
|
||||||
|
│ ├── Settings/ # Settings panels
|
||||||
|
│ ├── Spinner.tsx # Loading indicators
|
||||||
|
│ └── ... # 40+ component groups
|
||||||
|
│
|
||||||
|
├── entrypoints/ # Application entry points
|
||||||
|
│ ├── cli.tsx # CLI main (version, help, daemon)
|
||||||
|
│ ├── sdk/ # Agent SDK (types, sessions)
|
||||||
|
│ └── mcp.ts # MCP server entry
|
||||||
|
│
|
||||||
|
├── hooks/ # React hooks
|
||||||
|
│ ├── useCanUseTool.tsx # Permission checking
|
||||||
|
│ ├── useReplBridge.tsx # Bridge connection
|
||||||
|
│ ├── notifs/ # Notification hooks
|
||||||
|
│ └── toolPermission/ # Tool permission handlers
|
||||||
|
│
|
||||||
|
├── services/ # Business logic layer
|
||||||
|
│ ├── api/ # Claude API client
|
||||||
|
│ │ ├── claude.ts # Streaming API calls
|
||||||
|
│ │ ├── errors.ts # Error categorization
|
||||||
|
│ │ └── withRetry.ts # Retry logic
|
||||||
|
│ ├── analytics/ # Telemetry + GrowthBook
|
||||||
|
│ ├── compact/ # Context compression
|
||||||
|
│ ├── mcp/ # MCP connection management
|
||||||
|
│ ├── tools/ # Tool execution engine
|
||||||
|
│ │ ├── StreamingToolExecutor.ts # Parallel tool runner
|
||||||
|
│ │ └── toolOrchestration.ts # Batch orchestration
|
||||||
|
│ ├── plugins/ # Plugin loader
|
||||||
|
│ └── settingsSync/ # Cross-device settings
|
||||||
|
│
|
||||||
|
├── state/ # Application state
|
||||||
|
│ ├── AppStateStore.ts # Store definition
|
||||||
|
│ └── AppState.tsx # React provider + hooks
|
||||||
|
│
|
||||||
|
├── tasks/ # Task implementations
|
||||||
|
│ ├── LocalShellTask/ # Bash command execution
|
||||||
|
│ ├── LocalAgentTask/ # Sub-agent execution
|
||||||
|
│ ├── RemoteAgentTask/ # Remote agent via bridge
|
||||||
|
│ ├── InProcessTeammateTask/ # In-process teammate
|
||||||
|
│ └── DreamTask/ # Background thinking
|
||||||
|
│
|
||||||
|
├── tools/ # 40+ tool implementations
|
||||||
|
│ ├── AgentTool/ # Sub-agent spawning + fork
|
||||||
|
│ ├── BashTool/ # Shell command execution
|
||||||
|
│ ├── FileReadTool/ # File reading (PDF, image, etc)
|
||||||
|
│ ├── FileEditTool/ # String-replace editing
|
||||||
|
│ ├── FileWriteTool/ # Full file creation
|
||||||
|
│ ├── GlobTool/ # File pattern search
|
||||||
|
│ ├── GrepTool/ # Content search (ripgrep)
|
||||||
|
│ ├── WebFetchTool/ # HTTP fetching
|
||||||
|
│ ├── WebSearchTool/ # Web search
|
||||||
|
│ ├── MCPTool/ # MCP tool wrapper
|
||||||
|
│ ├── SkillTool/ # Skill invocation
|
||||||
|
│ ├── AskUserQuestionTool/ # User interaction
|
||||||
|
│ └── ... # 30+ more tools
|
||||||
|
│
|
||||||
|
├── types/ # Type definitions
|
||||||
|
│ ├── message.ts # Message discriminated unions
|
||||||
|
│ ├── permissions.ts # Permission types
|
||||||
|
│ ├── tools.ts # Tool progress types
|
||||||
|
│ └── ids.ts # Branded ID types
|
||||||
|
│
|
||||||
|
├── utils/ # Utilities (largest directory)
|
||||||
|
│ ├── permissions/ # Permission rule engine
|
||||||
|
│ ├── messages/ # Message formatting
|
||||||
|
│ ├── model/ # Model selection logic
|
||||||
|
│ ├── settings/ # Settings management
|
||||||
|
│ ├── sandbox/ # Sandbox runtime adapter
|
||||||
|
│ ├── hooks/ # Hook execution
|
||||||
|
│ ├── memory/ # Memory system utils
|
||||||
|
│ ├── git/ # Git operations
|
||||||
|
│ ├── github/ # GitHub API
|
||||||
|
│ ├── bash/ # Bash execution helpers
|
||||||
|
│ ├── swarm/ # Multi-agent swarm
|
||||||
|
│ ├── telemetry/ # Telemetry reporting
|
||||||
|
│ └── ... # 30+ more util groups
|
||||||
|
│
|
||||||
|
└── vendor/ # Native module source stubs
|
||||||
|
├── audio-capture-src/ # Audio input
|
||||||
|
├── image-processor-src/ # Image processing
|
||||||
|
├── modifiers-napi-src/ # Native modifiers
|
||||||
|
└── url-handler-src/ # URL handling
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Architecture Overview
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ ENTRY LAYER │
|
||||||
|
│ cli.tsx ──> main.tsx ──> REPL.tsx (interactive) │
|
||||||
|
│ └──> QueryEngine.ts (headless/SDK) │
|
||||||
|
└──────────────────────────────┬──────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ QUERY ENGINE │
|
||||||
|
│ submitMessage(prompt) ──> AsyncGenerator<SDKMessage> │
|
||||||
|
│ │ │
|
||||||
|
│ ├── fetchSystemPromptParts() ──> assemble system prompt │
|
||||||
|
│ ├── processUserInput() ──> handle /commands │
|
||||||
|
│ ├── query() ──> main agent loop │
|
||||||
|
│ │ ├── StreamingToolExecutor ──> parallel tool execution │
|
||||||
|
│ │ ├── autoCompact() ──> context compression │
|
||||||
|
│ │ └── runTools() ──> tool orchestration │
|
||||||
|
│ └── yield SDKMessage ──> stream to consumer │
|
||||||
|
└──────────────────────────────┬──────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌────────────────┼────────────────┐
|
||||||
|
▼ ▼ ▼
|
||||||
|
┌──────────────────┐ ┌─────────────────┐ ┌──────────────────┐
|
||||||
|
│ TOOL SYSTEM │ │ SERVICE LAYER │ │ STATE LAYER │
|
||||||
|
│ │ │ │ │ │
|
||||||
|
│ Tool Interface │ │ api/claude.ts │ │ AppState Store │
|
||||||
|
│ ├─ call() │ │ API client │ │ ├─ permissions │
|
||||||
|
│ ├─ validate() │ │ compact/ │ │ ├─ fileHistory │
|
||||||
|
│ ├─ checkPerms() │ │ auto-compact │ │ ├─ agents │
|
||||||
|
│ ├─ render() │ │ mcp/ │ │ └─ fastMode │
|
||||||
|
│ └─ prompt() │ │ MCP protocol │ │ │
|
||||||
|
│ │ │ analytics/ │ │ React Context │
|
||||||
|
│ 40+ Built-in: │ │ telemetry │ │ ├─ useAppState │
|
||||||
|
│ ├─ BashTool │ │ tools/ │ │ └─ useSetState │
|
||||||
|
│ ├─ FileRead │ │ executor │ │ │
|
||||||
|
│ ├─ FileEdit │ │ plugins/ │ └──────────────────┘
|
||||||
|
│ ├─ Glob/Grep │ │ loader │
|
||||||
|
│ ├─ AgentTool │ │ settingsSync/ │
|
||||||
|
│ ├─ WebFetch │ │ cross-device │
|
||||||
|
│ └─ MCPTool │ │ oauth/ │
|
||||||
|
│ │ │ auth flow │
|
||||||
|
└──────────────────┘ └─────────────────┘
|
||||||
|
│ │
|
||||||
|
▼ ▼
|
||||||
|
┌──────────────────┐ ┌─────────────────┐
|
||||||
|
│ TASK SYSTEM │ │ BRIDGE LAYER │
|
||||||
|
│ │ │ │
|
||||||
|
│ Task Types: │ │ bridgeMain.ts │
|
||||||
|
│ ├─ local_bash │ │ session mgmt │
|
||||||
|
│ ├─ local_agent │ │ bridgeApi.ts │
|
||||||
|
│ ├─ remote_agent │ │ HTTP client │
|
||||||
|
│ ├─ in_process │ │ workSecret.ts │
|
||||||
|
│ ├─ dream │ │ auth tokens │
|
||||||
|
│ └─ workflow │ │ sessionRunner │
|
||||||
|
│ │ │ process spawn │
|
||||||
|
│ ID: prefix+8chr │ └─────────────────┘
|
||||||
|
│ b=bash a=agent │
|
||||||
|
│ r=remote t=team │
|
||||||
|
└──────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Data Flow: A Single Query Lifecycle
|
||||||
|
|
||||||
|
```
|
||||||
|
USER INPUT (prompt / slash command)
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
processUserInput() ← parse /commands, build UserMessage
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
fetchSystemPromptParts() ← tools → prompt sections, CLAUDE.md memory
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
recordTranscript() ← persist user message to disk (JSONL)
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─→ normalizeMessagesForAPI() ← strip UI-only fields, compact if needed
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ Claude API (streaming) ← POST /v1/messages with tools + system prompt
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ stream events ← message_start → content_block_delta → message_stop
|
||||||
|
│ │
|
||||||
|
│ ├─ text block ──────────────→ yield to consumer (SDK / REPL)
|
||||||
|
│ │
|
||||||
|
│ └─ tool_use block?
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ StreamingToolExecutor ← partition: concurrent-safe vs serial
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ canUseTool() ← permission check (hooks + rules + UI prompt)
|
||||||
|
│ │
|
||||||
|
│ ├─ DENY ────────────────→ append tool_result(error), continue loop
|
||||||
|
│ │
|
||||||
|
│ └─ ALLOW
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ tool.call() ← execute the tool (Bash, Read, Edit, etc.)
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ append tool_result ← push to messages[], recordTranscript()
|
||||||
|
│ │
|
||||||
|
└─────────┘ ← loop back to API call
|
||||||
|
│
|
||||||
|
▼ (stop_reason != "tool_use")
|
||||||
|
yield result message ← final text, usage, cost, session_id
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Tool System Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
TOOL INTERFACE
|
||||||
|
==============
|
||||||
|
|
||||||
|
buildTool(definition) ──> Tool<Input, Output, Progress>
|
||||||
|
|
||||||
|
Every tool implements:
|
||||||
|
┌────────────────────────────────────────────────────────┐
|
||||||
|
│ LIFECYCLE │
|
||||||
|
│ ├── validateInput() → reject bad args early │
|
||||||
|
│ ├── checkPermissions() → tool-specific authz │
|
||||||
|
│ └── call() → execute and return result │
|
||||||
|
│ │
|
||||||
|
│ CAPABILITIES │
|
||||||
|
│ ├── isEnabled() → feature gate check │
|
||||||
|
│ ├── isConcurrencySafe() → can run in parallel? │
|
||||||
|
│ ├── isReadOnly() → no side effects? │
|
||||||
|
│ ├── isDestructive() → irreversible ops? │
|
||||||
|
│ └── interruptBehavior() → cancel or block on user? │
|
||||||
|
│ │
|
||||||
|
│ RENDERING (React/Ink) │
|
||||||
|
│ ├── renderToolUseMessage() → input display │
|
||||||
|
│ ├── renderToolResultMessage() → output display │
|
||||||
|
│ ├── renderToolUseProgressMessage() → spinner/status │
|
||||||
|
│ └── renderGroupedToolUse() → parallel tool groups │
|
||||||
|
│ │
|
||||||
|
│ AI FACING │
|
||||||
|
│ ├── prompt() → tool description for LLM │
|
||||||
|
│ ├── description() → dynamic description │
|
||||||
|
│ └── mapToolResultToAPI() → format for API response │
|
||||||
|
└────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### Complete Tool Inventory
|
||||||
|
|
||||||
|
```
|
||||||
|
FILE OPERATIONS SEARCH & DISCOVERY EXECUTION
|
||||||
|
═════════════════ ══════════════════════ ══════════
|
||||||
|
FileReadTool GlobTool BashTool
|
||||||
|
FileEditTool GrepTool PowerShellTool
|
||||||
|
FileWriteTool ToolSearchTool
|
||||||
|
NotebookEditTool INTERACTION
|
||||||
|
═══════════
|
||||||
|
WEB & NETWORK AGENT / TASK AskUserQuestionTool
|
||||||
|
════════════════ ══════════════════ BriefTool
|
||||||
|
WebFetchTool AgentTool
|
||||||
|
WebSearchTool SendMessageTool PLANNING & WORKFLOW
|
||||||
|
TeamCreateTool ════════════════════
|
||||||
|
MCP PROTOCOL TeamDeleteTool EnterPlanModeTool
|
||||||
|
══════════════ TaskCreateTool ExitPlanModeTool
|
||||||
|
MCPTool TaskGetTool EnterWorktreeTool
|
||||||
|
ListMcpResourcesTool TaskUpdateTool ExitWorktreeTool
|
||||||
|
ReadMcpResourceTool TaskListTool TodoWriteTool
|
||||||
|
TaskStopTool
|
||||||
|
TaskOutputTool SYSTEM
|
||||||
|
════════
|
||||||
|
SKILLS & EXTENSIONS ConfigTool
|
||||||
|
═════════════════════ SkillTool
|
||||||
|
SkillTool ScheduleCronTool
|
||||||
|
LSPTool SleepTool
|
||||||
|
TungstenTool
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Permission System
|
||||||
|
|
||||||
|
```
|
||||||
|
TOOL CALL REQUEST
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ validateInput() ──────────────────────────────────┐
|
||||||
|
│ reject invalid inputs before any permission check │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ PreToolUse Hooks ─────────────────────────────────┐
|
||||||
|
│ user-defined shell commands (settings.json hooks) │
|
||||||
|
│ can: approve, deny, or modify input │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ Permission Rules ─────────────────────────────────┐
|
||||||
|
│ alwaysAllowRules: match tool name/pattern → auto │
|
||||||
|
│ alwaysDenyRules: match tool name/pattern → deny │
|
||||||
|
│ alwaysAskRules: match tool name/pattern → ask │
|
||||||
|
│ Sources: settings, CLI args, session decisions │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
no rule match?
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ Interactive Prompt ───────────────────────────────┐
|
||||||
|
│ User sees tool name + input │
|
||||||
|
│ Options: Allow Once / Allow Always / Deny │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ checkPermissions() ───────────────────────────────┐
|
||||||
|
│ Tool-specific logic (e.g. path sandboxing) │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
APPROVED → tool.call()
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Sub-Agent & Multi-Agent Architecture
|
||||||
|
|
||||||
|
```
|
||||||
|
MAIN AGENT
|
||||||
|
==========
|
||||||
|
│
|
||||||
|
┌───────────────┼───────────────┐
|
||||||
|
▼ ▼ ▼
|
||||||
|
┌──────────────┐ ┌──────────┐ ┌──────────────┐
|
||||||
|
│ FORK AGENT │ │ REMOTE │ │ IN-PROCESS │
|
||||||
|
│ │ │ AGENT │ │ TEAMMATE │
|
||||||
|
│ Fork process │ │ Bridge │ │ Same process │
|
||||||
|
│ Shared cache │ │ session │ │ Async context│
|
||||||
|
│ Fresh msgs[] │ │ Isolated │ │ Shared state │
|
||||||
|
└──────────────┘ └──────────┘ └──────────────┘
|
||||||
|
|
||||||
|
SPAWN MODES:
|
||||||
|
├─ default → in-process, shared conversation
|
||||||
|
├─ fork → child process, fresh messages[], shared file cache
|
||||||
|
├─ worktree → isolated git worktree + fork
|
||||||
|
└─ remote → bridge to Claude Code Remote / container
|
||||||
|
|
||||||
|
COMMUNICATION:
|
||||||
|
├─ SendMessageTool → agent-to-agent messages
|
||||||
|
├─ TaskCreate/Update → shared task board
|
||||||
|
└─ TeamCreate/Delete → team lifecycle management
|
||||||
|
|
||||||
|
SWARM MODE (feature-gated):
|
||||||
|
┌─────────────────────────────────────────────┐
|
||||||
|
│ Lead Agent │
|
||||||
|
│ ├── Teammate A ──> claims Task 1 │
|
||||||
|
│ ├── Teammate B ──> claims Task 2 │
|
||||||
|
│ └── Teammate C ──> claims Task 3 │
|
||||||
|
│ │
|
||||||
|
│ Shared: task board, message inbox │
|
||||||
|
│ Isolated: messages[], file cache, cwd │
|
||||||
|
└─────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Context Management (Compact System)
|
||||||
|
|
||||||
|
```
|
||||||
|
CONTEXT WINDOW BUDGET
|
||||||
|
═════════════════════
|
||||||
|
|
||||||
|
┌─────────────────────────────────────────────────────┐
|
||||||
|
│ System Prompt (tools, permissions, CLAUDE.md) │
|
||||||
|
│ ══════════════════════════════════════════════ │
|
||||||
|
│ │
|
||||||
|
│ Conversation History │
|
||||||
|
│ ┌─────────────────────────────────────────────┐ │
|
||||||
|
│ │ [compacted summary of older messages] │ │
|
||||||
|
│ │ ═══════════════════════════════════════════ │ │
|
||||||
|
│ │ [compact_boundary marker] │ │
|
||||||
|
│ │ ─────────────────────────────────────────── │ │
|
||||||
|
│ │ [recent messages — full fidelity] │ │
|
||||||
|
│ │ user → assistant → tool_use → tool_result │ │
|
||||||
|
│ └─────────────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ Current Turn (user + assistant response) │
|
||||||
|
└─────────────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
THREE COMPRESSION STRATEGIES:
|
||||||
|
├─ autoCompact → triggers when token count exceeds threshold
|
||||||
|
│ summarizes old messages via a compact API call
|
||||||
|
├─ snipCompact → removes zombie messages and stale markers
|
||||||
|
│ (HISTORY_SNIP feature flag)
|
||||||
|
└─ contextCollapse → restructures context for efficiency
|
||||||
|
(CONTEXT_COLLAPSE feature flag)
|
||||||
|
|
||||||
|
COMPACTION FLOW:
|
||||||
|
messages[] ──> getMessagesAfterCompactBoundary()
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
older messages ──> Claude API (summarize) ──> compact summary
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
[summary] + [compact_boundary] + [recent messages]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## MCP (Model Context Protocol) Integration
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ MCP ARCHITECTURE │
|
||||||
|
│ │
|
||||||
|
│ MCPConnectionManager.tsx │
|
||||||
|
│ ├── Server Discovery (config from settings.json) │
|
||||||
|
│ │ ├── stdio → spawn child process │
|
||||||
|
│ │ ├── sse → HTTP EventSource │
|
||||||
|
│ │ ├── http → Streamable HTTP │
|
||||||
|
│ │ ├── ws → WebSocket │
|
||||||
|
│ │ └── sdk → in-process transport │
|
||||||
|
│ │ │
|
||||||
|
│ ├── Client Lifecycle │
|
||||||
|
│ │ ├── connect → initialize → list tools │
|
||||||
|
│ │ ├── tool calls via MCPTool wrapper │
|
||||||
|
│ │ └── disconnect / reconnect with backoff │
|
||||||
|
│ │ │
|
||||||
|
│ ├── Authentication │
|
||||||
|
│ │ ├── OAuth 2.0 flow (McpOAuthConfig) │
|
||||||
|
│ │ ├── Cross-App Access (XAA / SEP-990) │
|
||||||
|
│ │ └── API key via headers │
|
||||||
|
│ │ │
|
||||||
|
│ └── Tool Registration │
|
||||||
|
│ ├── mcp__<server>__<tool> naming convention │
|
||||||
|
│ ├── Dynamic schema from MCP server │
|
||||||
|
│ ├── Permission passthrough to Claude Code │
|
||||||
|
│ └── Resource listing (ListMcpResourcesTool) │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Bridge Layer (Claude Desktop / Remote)
|
||||||
|
|
||||||
|
```
|
||||||
|
Claude Desktop / Web / Cowork Claude Code CLI
|
||||||
|
══════════════════════════ ═════════════════
|
||||||
|
|
||||||
|
┌───────────────────┐ ┌──────────────────┐
|
||||||
|
│ Bridge Client │ ←─ HTTP ──→ │ bridgeMain.ts │
|
||||||
|
│ (Desktop App) │ │ │
|
||||||
|
└───────────────────┘ │ Session Manager │
|
||||||
|
│ ├── spawn CLI │
|
||||||
|
PROTOCOL: │ ├── poll status │
|
||||||
|
├─ JWT authentication │ ├── relay msgs │
|
||||||
|
├─ Work secret exchange │ └── capacityWake │
|
||||||
|
├─ Session lifecycle │ │
|
||||||
|
│ ├── create │ Backoff: │
|
||||||
|
│ ├── run │ ├─ conn: 2s→2m │
|
||||||
|
│ └─ stop │ └─ gen: 500ms→30s│
|
||||||
|
└─ Token refresh scheduler └──────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Session Persistence
|
||||||
|
|
||||||
|
```
|
||||||
|
SESSION STORAGE
|
||||||
|
══════════════
|
||||||
|
|
||||||
|
~/.claude/projects/<hash>/sessions/
|
||||||
|
└── <session-id>.jsonl ← append-only log
|
||||||
|
├── {"type":"user",...}
|
||||||
|
├── {"type":"assistant",...}
|
||||||
|
├── {"type":"progress",...}
|
||||||
|
└── {"type":"system","subtype":"compact_boundary",...}
|
||||||
|
|
||||||
|
RESUME FLOW:
|
||||||
|
getLastSessionLog() ──> parse JSONL ──> rebuild messages[]
|
||||||
|
│
|
||||||
|
├── --continue → last session in cwd
|
||||||
|
├── --resume <id> → specific session
|
||||||
|
└── --fork-session → new ID, copy history
|
||||||
|
|
||||||
|
PERSISTENCE STRATEGY:
|
||||||
|
├─ User messages → await write (blocking, for crash recovery)
|
||||||
|
├─ Assistant msgs → fire-and-forget (order-preserving queue)
|
||||||
|
├─ Progress → inline write (dedup on next query)
|
||||||
|
└─ Flush → on result yield / cowork eager flush
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Feature Flag System
|
||||||
|
|
||||||
|
```
|
||||||
|
DEAD CODE ELIMINATION (Bun compile-time)
|
||||||
|
══════════════════════════════════════════
|
||||||
|
|
||||||
|
feature('FLAG_NAME') ──→ true → included in bundle
|
||||||
|
──→ false → stripped from bundle
|
||||||
|
|
||||||
|
FLAGS (observed in source):
|
||||||
|
├─ COORDINATOR_MODE → multi-agent coordinator
|
||||||
|
├─ HISTORY_SNIP → aggressive history trimming
|
||||||
|
├─ CONTEXT_COLLAPSE → context restructuring
|
||||||
|
├─ DAEMON → background daemon workers
|
||||||
|
├─ AGENT_TRIGGERS → cron/remote triggers
|
||||||
|
├─ AGENT_TRIGGERS_REMOTE → remote trigger support
|
||||||
|
├─ MONITOR_TOOL → MCP monitoring tool
|
||||||
|
├─ WEB_BROWSER_TOOL → browser automation
|
||||||
|
├─ VOICE_MODE → voice input/output
|
||||||
|
├─ TEMPLATES → job classifier
|
||||||
|
├─ EXPERIMENTAL_SKILL_SEARCH → skill discovery
|
||||||
|
├─ KAIROS → push notifications, file sends
|
||||||
|
├─ PROACTIVE → sleep tool, proactive behavior
|
||||||
|
├─ OVERFLOW_TEST_TOOL → testing tool
|
||||||
|
├─ TERMINAL_PANEL → terminal capture
|
||||||
|
├─ WORKFLOW_SCRIPTS → workflow tool
|
||||||
|
├─ CHICAGO_MCP → computer use MCP
|
||||||
|
├─ DUMP_SYSTEM_PROMPT → prompt extraction (ant-only)
|
||||||
|
├─ UDS_INBOX → peer discovery
|
||||||
|
├─ ABLATION_BASELINE → experiment ablation
|
||||||
|
└─ UPGRADE_NOTICE → upgrade notifications
|
||||||
|
|
||||||
|
RUNTIME GATES:
|
||||||
|
├─ process.env.USER_TYPE === 'ant' → internal features
|
||||||
|
└─ GrowthBook feature flags → A/B experiments at runtime
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## State Management
|
||||||
|
|
||||||
|
```
|
||||||
|
┌──────────────────────────────────────────────────────────┐
|
||||||
|
│ AppState Store │
|
||||||
|
│ │
|
||||||
|
│ AppState { │
|
||||||
|
│ toolPermissionContext: { │
|
||||||
|
│ mode: PermissionMode, ← default/plan/etc │
|
||||||
|
│ additionalWorkingDirectories, │
|
||||||
|
│ alwaysAllowRules, ← auto-approve │
|
||||||
|
│ alwaysDenyRules, ← auto-reject │
|
||||||
|
│ alwaysAskRules, ← always prompt │
|
||||||
|
│ isBypassPermissionsModeAvailable │
|
||||||
|
│ }, │
|
||||||
|
│ fileHistory: FileHistoryState, ← undo snapshots │
|
||||||
|
│ attribution: AttributionState, ← commit tracking │
|
||||||
|
│ verbose: boolean, │
|
||||||
|
│ mainLoopModel: string, ← active model │
|
||||||
|
│ fastMode: FastModeState, │
|
||||||
|
│ speculation: SpeculationState │
|
||||||
|
│ } │
|
||||||
|
│ │
|
||||||
|
│ React Integration: │
|
||||||
|
│ ├── AppStateProvider → creates store via createContext │
|
||||||
|
│ ├── useAppState(sel) → selector-based subscriptions │
|
||||||
|
│ └── useSetAppState() → immer-style updater function │
|
||||||
|
└──────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## The 12 Progressive Harness Mechanisms
|
||||||
|
|
||||||
|
This architecture demonstrates 12 layered mechanisms that a production AI agent harness needs beyond the basic loop. Each builds on the previous:
|
||||||
|
|
||||||
|
```
|
||||||
|
s01 THE LOOP "One loop & Bash is all you need"
|
||||||
|
query.ts: the while-true loop that calls Claude API,
|
||||||
|
checks stop_reason, executes tools, appends results.
|
||||||
|
|
||||||
|
s02 TOOL DISPATCH "Adding a tool = adding one handler"
|
||||||
|
Tool.ts + tools.ts: every tool registers into the dispatch
|
||||||
|
map. The loop stays identical. buildTool() factory provides
|
||||||
|
safe defaults.
|
||||||
|
|
||||||
|
s03 PLANNING "An agent without a plan drifts"
|
||||||
|
EnterPlanModeTool/ExitPlanModeTool + TodoWriteTool:
|
||||||
|
list steps first, then execute. Doubles completion rate.
|
||||||
|
|
||||||
|
s04 SUB-AGENTS "Break big tasks; clean context per subtask"
|
||||||
|
AgentTool + forkSubagent.ts: each child gets fresh messages[],
|
||||||
|
keeping the main conversation clean.
|
||||||
|
|
||||||
|
s05 KNOWLEDGE ON DEMAND "Load knowledge when you need it"
|
||||||
|
SkillTool + memdir/: inject via tool_result, not system prompt.
|
||||||
|
CLAUDE.md files loaded lazily per directory.
|
||||||
|
|
||||||
|
s06 CONTEXT COMPRESSION "Context fills up; make room"
|
||||||
|
services/compact/: three-layer strategy:
|
||||||
|
autoCompact (summarize) + snipCompact (trim) + contextCollapse
|
||||||
|
|
||||||
|
s07 PERSISTENT TASKS "Big goals → small tasks → disk"
|
||||||
|
TaskCreate/Update/Get/List: file-based task graph with
|
||||||
|
status tracking, dependencies, and persistence.
|
||||||
|
|
||||||
|
s08 BACKGROUND TASKS "Slow ops in background; agent keeps thinking"
|
||||||
|
DreamTask + LocalShellTask: daemon threads run commands,
|
||||||
|
inject notifications on completion.
|
||||||
|
|
||||||
|
s09 AGENT TEAMS "Too big for one → delegate to teammates"
|
||||||
|
TeamCreate/Delete + InProcessTeammateTask: persistent
|
||||||
|
teammates with async mailboxes.
|
||||||
|
|
||||||
|
s10 TEAM PROTOCOLS "Shared communication rules"
|
||||||
|
SendMessageTool: one request-response pattern drives
|
||||||
|
all negotiation between agents.
|
||||||
|
|
||||||
|
s11 AUTONOMOUS AGENTS "Teammates scan and claim tasks themselves"
|
||||||
|
coordinator/coordinatorMode.ts: idle cycle + auto-claim,
|
||||||
|
no need for lead to assign each task.
|
||||||
|
|
||||||
|
s12 WORKTREE ISOLATION "Each works in its own directory"
|
||||||
|
EnterWorktreeTool/ExitWorktreeTool: tasks manage goals,
|
||||||
|
worktrees manage directories, bound by ID.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Key Design Patterns
|
||||||
|
|
||||||
|
| Pattern | Where | Purpose |
|
||||||
|
|---------|-------|---------|
|
||||||
|
| **AsyncGenerator streaming** | `QueryEngine`, `query()` | Full-chain streaming from API to consumer |
|
||||||
|
| **Builder + Factory** | `buildTool()` | Safe defaults for tool definitions |
|
||||||
|
| **Branded Types** | `SystemPrompt`, `asSystemPrompt()` | Prevent string/array confusion |
|
||||||
|
| **Feature Flags + DCE** | `feature()` from `bun:bundle` | Compile-time dead code elimination |
|
||||||
|
| **Discriminated Unions** | `Message` types | Type-safe message handling |
|
||||||
|
| **Observer + State Machine** | `StreamingToolExecutor` | Tool execution lifecycle tracking |
|
||||||
|
| **Snapshot State** | `FileHistoryState` | Undo/redo for file operations |
|
||||||
|
| **Ring Buffer** | Error log | Bounded memory for long sessions |
|
||||||
|
| **Fire-and-Forget Write** | `recordTranscript()` | Non-blocking persistence with ordering |
|
||||||
|
| **Lazy Schema** | `lazySchema()` | Defer Zod schema evaluation for performance |
|
||||||
|
| **Context Isolation** | `AsyncLocalStorage` | Per-agent context in shared process |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
This repository content is for technical research and education only. All intellectual property rights belong to the original company. If there is any infringement, please contact us for removal.
|
||||||
781
README_CN.md
Normal file
781
README_CN.md
Normal file
@@ -0,0 +1,781 @@
|
|||||||
|
# Claude Code 架构学习与研究
|
||||||
|
|
||||||
|
> **导读**：本项目是一个关于 CLI Agent 架构的学习研究仓库。所有内容均基于互联网上公开的资料与讨论整理而成，特别参考了目前非常受欢迎的 CLI Agent `claude-code` 的相关公开信息。我们的初衷是帮助大家更好地理解和使用 Agent 技术，未来也会持续推出更多关于 Agent 架构解析与实践的探讨内容，感谢各位的关注与支持！
|
||||||
|
|
||||||
|
> **免责声明**: 本仓库内容仅用于技术研究和科研爱好者交流学习参考，**严禁任何个人、机构及组织将其用于商业用途、盈利性活动、非法用途及其他未经授权的场景。** 若内容涉及侵犯您的合法权益、知识产权或存在其他侵权问题，请及时联系我们，我们将第一时间核实并予以删除处理。
|
||||||
|
|
||||||
|
|
||||||
|
**语言**: [English](README.md) | **中文** | [한국어](README_KR.md) | [日本語](README_JA.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 目录
|
||||||
|
|
||||||
|
- [深度分析文档 (`docs/`)](#深度分析文档-docs) — 遥测、模型代号、卧底模式、远程控制、未来路线图
|
||||||
|
- [目录参考](#目录参考) — 代码结构树
|
||||||
|
- [架构概览](#架构概览) — 入口 → 查询引擎 → 工具/服务/状态
|
||||||
|
- [工具系统与权限架构](#工具系统与权限架构) — 40+ 工具、权限流、子代理
|
||||||
|
- [12 个渐进式安全带机制](#12-个渐进式安全带机制-harness-mechanisms) — Claude Code 如何在代理循环上构建生产特性
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 深度分析文档 (`docs/`)
|
||||||
|
|
||||||
|
基于网络公开资料与社区讨论整理的 Claude Code v2.1.88 分析报告，中英双语。
|
||||||
|
|
||||||
|
```
|
||||||
|
docs/
|
||||||
|
├── en/ # English
|
||||||
|
│ ├── [01-telemetry-and-privacy.md] # Telemetry & Privacy — what's collected, why you can't opt out
|
||||||
|
│ ├── [02-hidden-features-and-codenames.md] # Codenames (Capybara/Tengu/Numbat), feature flags, internal vs external
|
||||||
|
│ ├── [03-undercover-mode.md] # Undercover Mode — hiding AI authorship in open-source repos
|
||||||
|
│ ├── [04-remote-control-and-killswitches.md]# Remote Control — managed settings, killswitches, model overrides
|
||||||
|
│ └── [05-future-roadmap.md] # Future Roadmap — Numbat, KAIROS, voice mode, unreleased tools
|
||||||
|
│
|
||||||
|
└── zh/ # 中文
|
||||||
|
├── [01-遥测与隐私分析.md] # 遥测与隐私 — 收集了什么，为什么无法退出
|
||||||
|
├── [02-隐藏功能与模型代号.md] # 隐藏功能 — 模型代号，feature flag，内外用户差异
|
||||||
|
├── [03-卧底模式分析.md] # 卧底模式 — 在开源项目中隐藏 AI 身份
|
||||||
|
├── [04-远程控制与紧急开关.md] # 远程控制 — 托管设置，紧急开关，模型覆盖
|
||||||
|
└── [05-未来路线图.md] # 未来路线图 — Numbat，KAIROS，语音模式，未上线工具
|
||||||
|
```
|
||||||
|
|
||||||
|
> 点击文件名即可跳转到对应报告。
|
||||||
|
|
||||||
|
| # | 主题 | 核心发现 | 链接 |
|
||||||
|
|---|------|---------|------|
|
||||||
|
| 01 | **遥测与隐私** | 双层分析管道（1P, Datadog）。环境指纹、进程指标、每个事件携带会话/用户 ID。**没有面向用户的退出开关**。`OTEL_LOG_TOOL_DETAILS=1` 可记录完整工具输入。 | [EN](docs/en/01-telemetry-and-privacy.md) · [中文](docs/zh/01-遥测与隐私分析.md) |
|
||||||
|
| 02 | **隐藏功能与代号** | 动物代号体系（Capybara v8, Tengu, Fennec→Opus 4.6, **Numbat** 下一代）。Feature flag 用随机词对掩盖用途。内部用户获得更好的 prompt 和验证代理。隐藏命令：`/btw`、`/stickers`。 | [EN](docs/en/02-hidden-features-and-codenames.md) · [中文](docs/zh/02-隐藏功能与模型代号.md) |
|
||||||
|
| 03 | **卧底模式** | 官方员工在公开仓库自动进入卧底模式。模型指令："**不要暴露你的掩护身份**" — 剥离所有 AI 归属，commit 看起来像人类写的。**没有强制关闭选项。** | [EN](docs/en/03-undercover-mode.md) · [中文](docs/zh/03-卧底模式分析.md) |
|
||||||
|
| 04 | **远程控制与 Killswitch** | 每小时轮询 `/api/claude_code/settings`。危险变更弹出阻塞对话框 — **拒绝 = 程序退出**。6+ 紧急开关（绕过权限、快速模式、语音模式、分析 sink）。GrowthBook 可无同意改变任何用户行为。 | [EN](docs/en/04-remote-control-and-killswitches.md) · [中文](docs/zh/04-远程控制与紧急开关.md) |
|
||||||
|
| 05 | **未来路线图** | **Numbat** 代号确认。Opus 4.7 / Sonnet 4.8 开发中。**KAIROS** = 完全自主代理模式，心跳 `<tick>`、推送通知、PR 订阅。语音模式（push-to-talk）已就绪。发现 17 个未上线工具。 | [EN](docs/en/05-future-roadmap.md) · [中文](docs/zh/05-未来路线图.md) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 版权与免责声明
|
||||||
|
|
||||||
|
```
|
||||||
|
本仓库仅用于技术研究和教育目的。严禁商业使用。
|
||||||
|
|
||||||
|
如果您是版权所有者并认为本仓库内容侵犯了您的权利，
|
||||||
|
请联系仓库所有者立即删除。
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 统计数据
|
||||||
|
|
||||||
|
| 项目 | 数量 |
|
||||||
|
|------|------|
|
||||||
|
| 文件 (.ts/.tsx) | ~1,884 |
|
||||||
|
| 行数 | ~512,664 |
|
||||||
|
| 最大单文件 | `query.ts` (~785KB) |
|
||||||
|
| 内置工具 | ~40+ |
|
||||||
|
| 斜杠命令 | ~80+ |
|
||||||
|
| 依赖 (node_modules) | ~192 个包 |
|
||||||
|
| 运行时 | Bun（编译为 Node.js >= 18 bundle）|
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 代理模式
|
||||||
|
|
||||||
|
```text
|
||||||
|
核心循环
|
||||||
|
========
|
||||||
|
|
||||||
|
用户 --> messages[] --> Claude API --> 响应
|
||||||
|
|
|
||||||
|
stop_reason == "tool_use"?
|
||||||
|
/ \
|
||||||
|
是 否
|
||||||
|
| |
|
||||||
|
执行工具 返回文本
|
||||||
|
追加 tool_result
|
||||||
|
循环回退 -----------------> messages[]
|
||||||
|
|
||||||
|
|
||||||
|
这就是最小的代理循环。Claude Code 在此循环上
|
||||||
|
包裹了生产级线束：权限、流式传输、并发、
|
||||||
|
压缩、子代理、持久化和 MCP。
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 目录参考
|
||||||
|
|
||||||
|
```text
|
||||||
|
src/
|
||||||
|
├── main.tsx # REPL 引导程序，4,683 行
|
||||||
|
├── QueryEngine.ts # SDK/headless 查询生命周期引擎
|
||||||
|
├── query.ts # 主代理循环 (785KB，最大文件)
|
||||||
|
├── Tool.ts # 工具接口 + buildTool 工厂
|
||||||
|
├── Task.ts # 任务类型、ID、状态基类
|
||||||
|
├── tools.ts # 工具注册、预设、过滤
|
||||||
|
├── commands.ts # 斜杠命令定义
|
||||||
|
├── context.ts # 用户输入上下文
|
||||||
|
├── cost-tracker.ts # API 成本累积
|
||||||
|
├── setup.ts # 首次运行设置流程
|
||||||
|
│
|
||||||
|
├── bridge/ # Claude Desktop / 远程桥接
|
||||||
|
│ ├── bridgeMain.ts # 会话生命周期管理器
|
||||||
|
│ ├── bridgeApi.ts # HTTP 客户端
|
||||||
|
│ ├── bridgeConfig.ts # 连接配置
|
||||||
|
│ ├── bridgeMessaging.ts # 消息中继
|
||||||
|
│ ├── sessionRunner.ts # 进程生成
|
||||||
|
│ ├── jwtUtils.ts # JWT 刷新
|
||||||
|
│ ├── workSecret.ts # 认证令牌
|
||||||
|
│ └── capacityWake.ts # 基于容量的唤醒
|
||||||
|
│
|
||||||
|
├── cli/ # CLI 基础设施
|
||||||
|
│ ├── handlers/ # 命令处理器
|
||||||
|
│ └── transports/ # I/O 传输 (stdio, structured)
|
||||||
|
│
|
||||||
|
├── commands/ # ~80 个斜杠命令
|
||||||
|
│ ├── agents/ # 代理管理
|
||||||
|
│ ├── compact/ # 上下文压缩
|
||||||
|
│ ├── config/ # 设置管理
|
||||||
|
│ ├── help/ # 帮助显示
|
||||||
|
│ ├── login/ # 身份验证
|
||||||
|
│ ├── mcp/ # MCP 服务器管理
|
||||||
|
│ ├── memory/ # 记忆系统
|
||||||
|
│ ├── plan/ # 计划模式
|
||||||
|
│ ├── resume/ # 会话恢复
|
||||||
|
│ ├── review/ # 代码审查
|
||||||
|
│ └── ... # 还有 70+ 个命令
|
||||||
|
│
|
||||||
|
├── components/ # React/Ink 终端 UI
|
||||||
|
│ ├── design-system/ # 可重用 UI 原语
|
||||||
|
│ ├── messages/ # 消息渲染
|
||||||
|
│ ├── permissions/ # 权限对话框
|
||||||
|
│ ├── PromptInput/ # 输入字段 + 建议
|
||||||
|
│ ├── LogoV2/ # 品牌 + 欢迎屏幕
|
||||||
|
│ ├── Settings/ # 设置面板
|
||||||
|
│ ├── Spinner.tsx # 加载指示器
|
||||||
|
│ └── ... # 还有 40+ 个组件组
|
||||||
|
│
|
||||||
|
├── entrypoints/ # 应用入口点
|
||||||
|
│ ├── cli.tsx # CLI 主程序 (版本、帮助、守护进程)
|
||||||
|
│ ├── sdk/ # Agent SDK (类型、会话)
|
||||||
|
│ └── mcp.ts # MCP 服务器入口
|
||||||
|
│
|
||||||
|
├── hooks/ # React hooks
|
||||||
|
│ ├── useCanUseTool.tsx # 权限检查
|
||||||
|
│ ├── useReplBridge.tsx # 网桥连接
|
||||||
|
│ ├── notifs/ # 通知 hooks
|
||||||
|
│ └── toolPermission/ # 工具权限处理程序
|
||||||
|
│
|
||||||
|
├── services/ # 业务逻辑层
|
||||||
|
│ ├── api/ # Claude API 客户端
|
||||||
|
│ │ ├── claude.ts # 流式 API 调用
|
||||||
|
│ │ ├── errors.ts # 错误分类
|
||||||
|
│ │ └── withRetry.ts # 重试逻辑
|
||||||
|
│ ├── analytics/ # 遥测 + GrowthBook
|
||||||
|
│ ├── compact/ # 上下文压缩
|
||||||
|
│ ├── mcp/ # MCP 连接管理
|
||||||
|
│ ├── tools/ # 工具执行引擎
|
||||||
|
│ │ ├── StreamingToolExecutor.ts # 并行工具运行器
|
||||||
|
│ │ └── toolOrchestration.ts # 批处理编排
|
||||||
|
│ ├── plugins/ # 插件加载器
|
||||||
|
│ └── settingsSync/ # 跨设备设置同步
|
||||||
|
│
|
||||||
|
├── state/ # 应用状态
|
||||||
|
│ ├── AppStateStore.ts # Store 定义
|
||||||
|
│ └── AppState.tsx # React provider + hooks
|
||||||
|
│
|
||||||
|
├── tasks/ # 任务实现
|
||||||
|
│ ├── LocalShellTask/ # Bash 命令执行
|
||||||
|
│ ├── LocalAgentTask/ # 子代理执行
|
||||||
|
│ ├── RemoteAgentTask/ # 通过网桥连接远程代理
|
||||||
|
│ ├── InProcessTeammateTask/ # 进程内队友
|
||||||
|
│ └── DreamTask/ # 后台思考
|
||||||
|
│
|
||||||
|
├── tools/ # 40+ 工具实现
|
||||||
|
│ ├── AgentTool/ # 子代理生成 + fork
|
||||||
|
│ ├── BashTool/ # Shell 命令执行
|
||||||
|
│ ├── FileReadTool/ # 文件读取 (PDF, 图像等)
|
||||||
|
│ ├── FileEditTool/ # 字符串替换编辑
|
||||||
|
│ ├── FileWriteTool/ # 完整文件创建
|
||||||
|
│ ├── GlobTool/ # 文件模式搜索
|
||||||
|
│ ├── GrepTool/ # 内容搜索 (ripgrep)
|
||||||
|
│ ├── WebFetchTool/ # HTTP 获取
|
||||||
|
│ ├── WebSearchTool/ # Web 搜索
|
||||||
|
│ ├── MCPTool/ # MCP 工具包装器
|
||||||
|
│ ├── SkillTool/ # 技能调用
|
||||||
|
│ ├── AskUserQuestionTool/ # 用户交互
|
||||||
|
│ └── ... # 还有 30+ 个工具
|
||||||
|
│
|
||||||
|
├── types/ # 类型定义
|
||||||
|
│ ├── message.ts # 消息辨识联合类型
|
||||||
|
│ ├── permissions.ts # 权限类型
|
||||||
|
│ ├── tools.ts # 工具进度类型
|
||||||
|
│ └── ids.ts # 带有品牌的 ID 类型
|
||||||
|
│
|
||||||
|
├── utils/ # 工具函数（最大目录）
|
||||||
|
│ ├── permissions/ # 权限规则引擎
|
||||||
|
│ ├── messages/ # 消息格式化
|
||||||
|
│ ├── model/ # 模型选择逻辑
|
||||||
|
│ ├── settings/ # 设置管理
|
||||||
|
│ ├── sandbox/ # 沙盒运行时适配器
|
||||||
|
│ ├── hooks/ # Hook 执行
|
||||||
|
│ ├── memory/ # 记忆系统工具
|
||||||
|
│ ├── git/ # Git 操作
|
||||||
|
│ ├── github/ # GitHub API
|
||||||
|
│ ├── bash/ # Bash 执行辅助函数
|
||||||
|
│ ├── swarm/ # 多代理集群
|
||||||
|
│ ├── telemetry/ # 遥测报告
|
||||||
|
│ └── ... # 还有 30+ 个工具组
|
||||||
|
│
|
||||||
|
└── vendor/ # 原生模块存根
|
||||||
|
├── audio-capture-src/ # 音频输入
|
||||||
|
├── image-processor-src/ # 图像处理
|
||||||
|
├── modifiers-napi-src/ # 原生修饰符
|
||||||
|
└── url-handler-src/ # URL 处理
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 架构概览
|
||||||
|
|
||||||
|
```text
|
||||||
|
┌─────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 入口层 │
|
||||||
|
│ cli.tsx ──> main.tsx ──> REPL.tsx (交互式) │
|
||||||
|
│ └──> QueryEngine.ts (headless/SDK) │
|
||||||
|
└──────────────────────────────┬──────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 查询引擎 │
|
||||||
|
│ submitMessage(prompt) ──> AsyncGenerator<SDKMessage> │
|
||||||
|
│ │ │
|
||||||
|
│ ├── fetchSystemPromptParts() ──> 组装系统提示词 │
|
||||||
|
│ ├── processUserInput() ──> 处理 /命令 │
|
||||||
|
│ ├── query() ──> 主代理循环 │
|
||||||
|
│ │ ├── StreamingToolExecutor ──> 并行工具执行 │
|
||||||
|
│ │ ├── autoCompact() ──> 上下文压缩 │
|
||||||
|
│ │ └── runTools() ──> 工具编排 │
|
||||||
|
│ └── yield SDKMessage ──> 流式传输给消费者 │
|
||||||
|
└──────────────────────────────┬──────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
┌────────────────┼────────────────┐
|
||||||
|
▼ ▼ ▼
|
||||||
|
┌──────────────────┐ ┌─────────────────┐ ┌──────────────────┐
|
||||||
|
│ 工具系统 │ │ 服务层 │ │ 状态层 │
|
||||||
|
│ │ │ │ │ │
|
||||||
|
│ 工具接口 │ │ api/claude.ts │ │ AppState Store │
|
||||||
|
│ ├─ call() │ │ API 客户端 │ │ ├─ permissions │
|
||||||
|
│ ├─ validate() │ │ compact/ │ │ ├─ fileHistory │
|
||||||
|
│ ├─ checkPerms() │ │ 自动压缩 │ │ ├─ agents │
|
||||||
|
│ ├─ render() │ │ mcp/ │ │ └─ fastMode │
|
||||||
|
│ └─ prompt() │ │ MCP 协议 │ │ │
|
||||||
|
│ │ │ analytics/ │ │ React Context │
|
||||||
|
│ 40+ 内置工具: │ │ 遥测 │ │ ├─ useAppState │
|
||||||
|
│ ├─ BashTool │ │ tools/ │ │ └─ useSetState │
|
||||||
|
│ ├─ FileRead │ │ 执行器 │ │ │
|
||||||
|
│ ├─ FileEdit │ │ plugins/ │ └──────────────────┘
|
||||||
|
│ ├─ Glob/Grep │ │ 加载器 │
|
||||||
|
│ ├─ AgentTool │ │ settingsSync/ │
|
||||||
|
│ ├─ WebFetch │ │ 跨设备同步 │
|
||||||
|
│ └─ MCPTool │ │ oauth/ │
|
||||||
|
│ │ │ 认证流程 │
|
||||||
|
└──────────────────┘ └─────────────────┘
|
||||||
|
│ │
|
||||||
|
▼ ▼
|
||||||
|
┌──────────────────┐ ┌─────────────────┐
|
||||||
|
│ 任务系统 │ │ 桥接层 │
|
||||||
|
│ │ │ │
|
||||||
|
│ 任务类型: │ │ bridgeMain.ts │
|
||||||
|
│ ├─ local_bash │ │ 会话管理 │
|
||||||
|
│ ├─ local_agent │ │ bridgeApi.ts │
|
||||||
|
│ ├─ remote_agent │ │ HTTP 客户端 │
|
||||||
|
│ ├─ in_process │ │ workSecret.ts │
|
||||||
|
│ ├─ dream │ │ 认证令牌 │
|
||||||
|
│ └─ workflow │ │ sessionRunner │
|
||||||
|
│ │ │ 进程生成 │
|
||||||
|
│ ID: 前缀+8字符 │ └─────────────────┘
|
||||||
|
│ b=bash a=agent │
|
||||||
|
│ r=remote t=team │
|
||||||
|
└──────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 数据流：单个查询生命周期
|
||||||
|
|
||||||
|
```text
|
||||||
|
用户输入 (提示词 / 斜杠命令)
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
processUserInput() ← 解析 /命令，构建 UserMessage
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
fetchSystemPromptParts() ← 工具 → 提示词部分，CLAUDE.md 记忆
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
recordTranscript() ← 将用户消息持久化到磁盘 (JSONL)
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─→ normalizeMessagesForAPI() ← 剥离仅 UI 使用的字段，需要时进行压缩
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ Claude API (流式) ← 带有工具 + 系统提示词的 POST /v1/messages
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ 流事件 ← message_start → content_block_delta → message_stop
|
||||||
|
│ │
|
||||||
|
│ ├─ 文本块 ──────────────────→ 传递给消费者 (SDK / REPL)
|
||||||
|
│ │
|
||||||
|
│ └─ tool_use 块?
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ StreamingToolExecutor ← 划分：并发安全 vs 串行
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ canUseTool() ← 权限检查 (钩子 + 规则 + UI 提示)
|
||||||
|
│ │
|
||||||
|
│ ├─ 拒绝 ────────────────→ 追加 tool_result(error)，继续循环
|
||||||
|
│ │
|
||||||
|
│ └─ 允许
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ tool.call() ← 执行工具 (Bash, Read, Edit 等)
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ 追加 tool_result ← 推入 messages[]，recordTranscript()
|
||||||
|
│ │
|
||||||
|
└─────────┘ ← 循环回到 API 调用
|
||||||
|
│
|
||||||
|
▼ (stop_reason != "tool_use")
|
||||||
|
生成结果消息 ← 最终文本、使用情况、成本、session_id
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 工具系统与权限架构
|
||||||
|
|
||||||
|
```text
|
||||||
|
工具接口
|
||||||
|
==============
|
||||||
|
|
||||||
|
buildTool(definition) ──> Tool<Input, Output, Progress>
|
||||||
|
|
||||||
|
每个工具都实现：
|
||||||
|
┌────────────────────────────────────────────────────────┐
|
||||||
|
│ 生命周期 │
|
||||||
|
│ ├── validateInput() → 尽早拒绝无效参数 │
|
||||||
|
│ ├── checkPermissions() → 工具特定的授权检查 │
|
||||||
|
│ └── call() → 执行并返回结果 │
|
||||||
|
│ │
|
||||||
|
│ 能力特性 │
|
||||||
|
│ ├── isEnabled() → 功能开关检查 │
|
||||||
|
│ ├── isConcurrencySafe() → 是否可并行运行？ │
|
||||||
|
│ ├── isReadOnly() → 是否无副作用？ │
|
||||||
|
│ ├── isDestructive() → 是否为不可逆操作？ │
|
||||||
|
│ └── interruptBehavior() → 拦截还是阻塞等待用户？ │
|
||||||
|
│ │
|
||||||
|
│ 渲染 (React/Ink) │
|
||||||
|
│ ├── renderToolUseMessage() → 输入显示 │
|
||||||
|
│ ├── renderToolResultMessage() → 输出显示 │
|
||||||
|
│ ├── renderToolUseProgressMessage() → 加载状态/进度 │
|
||||||
|
│ └── renderGroupedToolUse() → 并行工具组显示 │
|
||||||
|
│ │
|
||||||
|
│ 面向 AI │
|
||||||
|
│ ├── prompt() → 提供给 LLM 的工具描述 │
|
||||||
|
│ ├── description() → 动态描述 │
|
||||||
|
│ └── mapToolResultToAPI() → 格式化为 API 响应 │
|
||||||
|
└────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 完整工具清单
|
||||||
|
|
||||||
|
```text
|
||||||
|
文件操作 搜索与发现 执行
|
||||||
|
═════════════════ ══════════════════════ ══════════
|
||||||
|
FileReadTool GlobTool BashTool
|
||||||
|
FileEditTool GrepTool PowerShellTool
|
||||||
|
FileWriteTool ToolSearchTool
|
||||||
|
NotebookEditTool 交互
|
||||||
|
═══════════
|
||||||
|
网络与请求 代理与任务 AskUserQuestionTool
|
||||||
|
════════════════ ══════════════════ BriefTool
|
||||||
|
WebFetchTool AgentTool
|
||||||
|
WebSearchTool SendMessageTool 计划与工作流
|
||||||
|
TeamCreateTool ════════════════════
|
||||||
|
MCP 协议 TeamDeleteTool EnterPlanModeTool
|
||||||
|
══════════════ TaskCreateTool ExitPlanModeTool
|
||||||
|
MCPTool TaskGetTool EnterWorktreeTool
|
||||||
|
ListMcpResourcesTool TaskUpdateTool ExitWorktreeTool
|
||||||
|
ReadMcpResourceTool TaskListTool TodoWriteTool
|
||||||
|
TaskStopTool
|
||||||
|
TaskOutputTool 系统
|
||||||
|
════════
|
||||||
|
技能与扩展 ConfigTool
|
||||||
|
═════════════════════ SkillTool
|
||||||
|
SkillTool ScheduleCronTool
|
||||||
|
LSPTool SleepTool
|
||||||
|
TungstenTool
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 权限系统
|
||||||
|
|
||||||
|
```text
|
||||||
|
工具调用请求
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ validateInput() ──────────────────────────────────┐
|
||||||
|
│ 在任何权限检查之前拒绝无效的输入 │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ PreToolUse Hooks (调用前钩子) ────────────────────┐
|
||||||
|
│ 用户定义的 shell 命令 (settings.json hooks) │
|
||||||
|
│ 可以：批准、拒绝或修改输入 │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ 权限规则 (Permission Rules) ──────────────────────┐
|
||||||
|
│ alwaysAllowRules: 匹配工具名/模式 → 自动允许 │
|
||||||
|
│ alwaysDenyRules: 匹配工具名/模式 → 自动拒绝 │
|
||||||
|
│ alwaysAskRules: 匹配工具名/模式 → 总是询问 │
|
||||||
|
│ 来源：设置、CLI 参数、会话决策 │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
没有规则匹配？
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ 交互式提示 (Interactive Prompt) ──────────────────┐
|
||||||
|
│ 用户看到工具名称 + 输入参数 │
|
||||||
|
│ 选项：允许一次 / 总是允许 / 拒绝 │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ checkPermissions() ───────────────────────────────┐
|
||||||
|
│ 工具特定的逻辑 (例如：路径沙盒检查) │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
已批准 → tool.call()
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 子代理与多代理架构
|
||||||
|
|
||||||
|
```text
|
||||||
|
主代理 (MAIN AGENT)
|
||||||
|
==========
|
||||||
|
│
|
||||||
|
┌───────────────┼───────────────┐
|
||||||
|
▼ ▼ ▼
|
||||||
|
┌──────────────┐ ┌──────────┐ ┌──────────────┐
|
||||||
|
│ FORK 代理 │ │ 远程代理 │ │ 进程内队友 │
|
||||||
|
│ │ │ │ │ │
|
||||||
|
│ Fork 进程 │ │ 网桥会话 │ │ 同一进程 │
|
||||||
|
│ 共享缓存 │ │ 完全隔离 │ │ 异步上下文 │
|
||||||
|
│ 全新 msgs[] │ │ │ │ 共享状态 │
|
||||||
|
└──────────────┘ └──────────┘ └──────────────┘
|
||||||
|
|
||||||
|
生成模式 (SPAWN MODES):
|
||||||
|
├─ default → 进程内，共享对话
|
||||||
|
├─ fork → 子进程，全新的 messages[]，共享文件缓存
|
||||||
|
├─ worktree → 隔离的 git worktree + fork
|
||||||
|
└─ remote → 通过网桥连接到 Claude Code Remote / 容器
|
||||||
|
|
||||||
|
通信机制:
|
||||||
|
├─ SendMessageTool → 代理间消息传递
|
||||||
|
├─ TaskCreate/Update → 共享任务看板
|
||||||
|
└─ TeamCreate/Delete → 团队生命周期管理
|
||||||
|
|
||||||
|
集群模式 (SWARM MODE，特性受限):
|
||||||
|
┌─────────────────────────────────────────────┐
|
||||||
|
│ 领导代理 (Lead Agent) │
|
||||||
|
│ ├── 队友 A ──> 认领任务 1 │
|
||||||
|
│ ├── 队友 B ──> 认领任务 2 │
|
||||||
|
│ └── 队友 C ──> 认领任务 3 │
|
||||||
|
│ │
|
||||||
|
│ 共享：任务看板、消息收件箱 │
|
||||||
|
│ 隔离：messages[]、文件缓存、cwd │
|
||||||
|
└─────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 上下文管理 (压缩系统)
|
||||||
|
|
||||||
|
```text
|
||||||
|
上下文窗口预算
|
||||||
|
═════════════════════
|
||||||
|
|
||||||
|
┌─────────────────────────────────────────────────────┐
|
||||||
|
│ 系统提示词 (工具、权限、CLAUDE.md) │
|
||||||
|
│ ══════════════════════════════════════════════ │
|
||||||
|
│ │
|
||||||
|
│ 对话历史 │
|
||||||
|
│ ┌─────────────────────────────────────────────┐ │
|
||||||
|
│ │ [旧消息的压缩摘要] │ │
|
||||||
|
│ │ ═══════════════════════════════════════════ │ │
|
||||||
|
│ │ [compact_boundary 标记] │ │
|
||||||
|
│ │ ─────────────────────────────────────────── │ │
|
||||||
|
│ │ [最近的消息 — 完整保真度] │ │
|
||||||
|
│ │ user → assistant → tool_use → tool_result │ │
|
||||||
|
│ └─────────────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ 当前轮次 (用户 + 助手响应) │
|
||||||
|
└─────────────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
三种压缩策略:
|
||||||
|
├─ autoCompact → 当 token 数量超过阈值时触发
|
||||||
|
│ 通过紧凑的 API 调用总结旧消息
|
||||||
|
├─ snipCompact → 移除僵尸消息和过时标记
|
||||||
|
│ (HISTORY_SNIP feature flag)
|
||||||
|
└─ contextCollapse → 重构上下文以提高效率
|
||||||
|
(CONTEXT_COLLAPSE feature flag)
|
||||||
|
|
||||||
|
压缩流程:
|
||||||
|
messages[] ──> getMessagesAfterCompactBoundary()
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
旧消息 ──> Claude API (总结) ──> 压缩摘要
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
[摘要] + [compact_boundary] + [最近的消息]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## MCP (模型上下文协议) 集成
|
||||||
|
|
||||||
|
```text
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ MCP 架构 │
|
||||||
|
│ │
|
||||||
|
│ MCPConnectionManager.tsx │
|
||||||
|
│ ├── 服务器发现 (来自 settings.json 的配置) │
|
||||||
|
│ │ ├── stdio → 生成子进程 │
|
||||||
|
│ │ ├── sse → HTTP EventSource │
|
||||||
|
│ │ ├── http → 流式 HTTP │
|
||||||
|
│ │ ├── ws → WebSocket │
|
||||||
|
│ │ └── sdk → 进程内传输 │
|
||||||
|
│ │ │
|
||||||
|
│ ├── 客户端生命周期 │
|
||||||
|
│ │ ├── connect → initialize → list tools │
|
||||||
|
│ │ ├── 通过 MCPTool 包装器调用工具 │
|
||||||
|
│ │ └── disconnect / 带有退避的重连 │
|
||||||
|
│ │ │
|
||||||
|
│ ├── 身份验证 │
|
||||||
|
│ │ ├── OAuth 2.0 流程 (McpOAuthConfig) │
|
||||||
|
│ │ ├── 跨应用访问 (XAA / SEP-990) │
|
||||||
|
│ │ └── 通过 headers 传递 API key │
|
||||||
|
│ │ │
|
||||||
|
│ └── 工具注册 │
|
||||||
|
│ ├── mcp__<server>__<tool> 命名约定 │
|
||||||
|
│ ├── 来自 MCP 服务器的动态 schema │
|
||||||
|
│ ├── 权限透传给 Claude Code │
|
||||||
|
│ └── 资源列表 (ListMcpResourcesTool) │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 桥接层 (Claude Desktop / Remote)
|
||||||
|
|
||||||
|
```text
|
||||||
|
Claude Desktop / Web / Cowork Claude Code CLI
|
||||||
|
══════════════════════════ ═════════════════
|
||||||
|
|
||||||
|
┌───────────────────┐ ┌──────────────────┐
|
||||||
|
│ 桥接客户端 │ ←─ HTTP ──→ │ bridgeMain.ts │
|
||||||
|
│ (Desktop App) │ │ │
|
||||||
|
└───────────────────┘ │ 会话管理器 │
|
||||||
|
│ ├── 生成 CLI │
|
||||||
|
协议: │ ├── 轮询状态 │
|
||||||
|
├─ JWT 身份验证 │ ├── 中继消息 │
|
||||||
|
├─ 工作密钥交换 │ └── 容量唤醒 │
|
||||||
|
├─ 会话生命周期 │ │
|
||||||
|
│ ├── create │ 退避策略: │
|
||||||
|
│ ├── run │ ├─ 连接: 2s→2m │
|
||||||
|
│ └─ stop │ └─ 生成: 500ms→30s│
|
||||||
|
└─ 令牌刷新调度器 └──────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 会话持久化
|
||||||
|
|
||||||
|
```text
|
||||||
|
会话存储
|
||||||
|
══════════════
|
||||||
|
|
||||||
|
~/.claude/projects/<hash>/sessions/
|
||||||
|
└── <session-id>.jsonl ← 仅追加日志
|
||||||
|
├── {"type":"user",...}
|
||||||
|
├── {"type":"assistant",...}
|
||||||
|
├── {"type":"progress",...}
|
||||||
|
└── {"type":"system","subtype":"compact_boundary",...}
|
||||||
|
|
||||||
|
恢复流程:
|
||||||
|
getLastSessionLog() ──> 解析 JSONL ──> 重建 messages[]
|
||||||
|
│
|
||||||
|
├── --continue → cwd 中的最后一次会话
|
||||||
|
├── --resume <id> → 特定会话
|
||||||
|
└── --fork-session → 新 ID，复制历史记录
|
||||||
|
|
||||||
|
持久化策略:
|
||||||
|
├─ 用户消息 → 阻塞等待写入 (用于崩溃恢复)
|
||||||
|
├─ 助手消息 → 即发即弃 (保持顺序的队列)
|
||||||
|
├─ 进度 → 内联写入 (在下一次查询时去重)
|
||||||
|
└─ 刷新 → 在生成结果时 / cowork 急切刷新
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 功能开关系统 (Feature Flag)
|
||||||
|
|
||||||
|
```text
|
||||||
|
死代码消除 (Bun 编译时)
|
||||||
|
══════════════════════════════════════════
|
||||||
|
|
||||||
|
feature('FLAG_NAME') ──→ true → 包含在包中
|
||||||
|
──→ false → 从包中剥离
|
||||||
|
|
||||||
|
标志 (在源码中观察到):
|
||||||
|
├─ COORDINATOR_MODE → 多代理协调器
|
||||||
|
├─ HISTORY_SNIP → 激进的历史修剪
|
||||||
|
├─ CONTEXT_COLLAPSE → 上下文重构
|
||||||
|
├─ DAEMON → 后台守护进程 worker
|
||||||
|
├─ AGENT_TRIGGERS → cron/远程触发器
|
||||||
|
├─ AGENT_TRIGGERS_REMOTE → 远程触发器支持
|
||||||
|
├─ MONITOR_TOOL → MCP 监控工具
|
||||||
|
├─ WEB_BROWSER_TOOL → 浏览器自动化
|
||||||
|
├─ VOICE_MODE → 语音输入/输出
|
||||||
|
├─ TEMPLATES → 任务分类器
|
||||||
|
├─ EXPERIMENTAL_SKILL_SEARCH → 技能发现
|
||||||
|
├─ KAIROS → 推送通知、文件发送
|
||||||
|
├─ PROACTIVE → 睡眠工具、主动行为
|
||||||
|
├─ OVERFLOW_TEST_TOOL → 测试工具
|
||||||
|
├─ TERMINAL_PANEL → 终端捕获
|
||||||
|
├─ WORKFLOW_SCRIPTS → 工作流工具
|
||||||
|
├─ CHICAGO_MCP → 计算机使用 MCP
|
||||||
|
├─ DUMP_SYSTEM_PROMPT → 提示词提取 (仅限 ant)
|
||||||
|
├─ UDS_INBOX → 对等发现
|
||||||
|
├─ ABLATION_BASELINE → 实验消融
|
||||||
|
└─ UPGRADE_NOTICE → 升级通知
|
||||||
|
|
||||||
|
运行时门控:
|
||||||
|
├─ process.env.USER_TYPE === 'ant' → 内部功能
|
||||||
|
└─ GrowthBook feature flags → 运行时的 A/B 实验
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 状态管理
|
||||||
|
|
||||||
|
```text
|
||||||
|
┌──────────────────────────────────────────────────────────┐
|
||||||
|
│ AppState Store │
|
||||||
|
│ │
|
||||||
|
│ AppState { │
|
||||||
|
│ toolPermissionContext: { │
|
||||||
|
│ mode: PermissionMode, ← default/plan等 │
|
||||||
|
│ additionalWorkingDirectories, │
|
||||||
|
│ alwaysAllowRules, ← 自动批准 │
|
||||||
|
│ alwaysDenyRules, ← 自动拒绝 │
|
||||||
|
│ alwaysAskRules, ← 总是提示 │
|
||||||
|
│ isBypassPermissionsModeAvailable │
|
||||||
|
│ }, │
|
||||||
|
│ fileHistory: FileHistoryState, ← 撤销快照 │
|
||||||
|
│ attribution: AttributionState, ← 提交跟踪 │
|
||||||
|
│ verbose: boolean, │
|
||||||
|
│ mainLoopModel: string, ← 活动模型 │
|
||||||
|
│ fastMode: FastModeState, │
|
||||||
|
│ speculation: SpeculationState │
|
||||||
|
│ } │
|
||||||
|
│ │
|
||||||
|
│ React 集成: │
|
||||||
|
│ ├── AppStateProvider → 通过 createContext 创建 store │
|
||||||
|
│ ├── useAppState(sel) → 基于选择器的订阅 │
|
||||||
|
│ └── useSetAppState() → immer 风格的更新函数 │
|
||||||
|
└──────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12 个渐进式安全带机制 (Harness Mechanisms)
|
||||||
|
|
||||||
|
该架构展示了生产级 AI 代理除了基本循环之外，所需的 12 层渐进式机制：
|
||||||
|
|
||||||
|
```text
|
||||||
|
s01 核心循环 (THE LOOP) "一个循环 + Bash 就是你所需要的全部"
|
||||||
|
query.ts: 调用 Claude API 的 while-true 循环，
|
||||||
|
检查 stop_reason，执行工具，追加结果。
|
||||||
|
|
||||||
|
s02 工具调度 (TOOL DISPATCH) "添加一个工具 = 添加一个处理程序"
|
||||||
|
Tool.ts + tools.ts: 每个工具都注册到调度映射中。
|
||||||
|
循环保持不变。buildTool() 工厂提供安全的默认值。
|
||||||
|
|
||||||
|
s03 计划 (PLANNING) "没有计划的代理会迷失方向"
|
||||||
|
EnterPlanModeTool/ExitPlanModeTool + TodoWriteTool:
|
||||||
|
先列出步骤，然后执行。使完成率翻倍。
|
||||||
|
|
||||||
|
s04 子代理 (SUB-AGENTS) "拆分大任务；每个子任务清理上下文"
|
||||||
|
AgentTool + forkSubagent.ts: 每个子代获得全新的 messages[]，
|
||||||
|
保持主对话的干净。
|
||||||
|
|
||||||
|
s05 按需知识 (KNOWLEDGE) "需要时加载知识"
|
||||||
|
SkillTool + memdir/: 通过 tool_result 注入，而不是系统提示词。
|
||||||
|
按目录延迟加载 CLAUDE.md 文件。
|
||||||
|
|
||||||
|
s06 上下文压缩 (COMPRESSION) "上下文满了；腾出空间"
|
||||||
|
services/compact/: 三层策略：
|
||||||
|
autoCompact (总结) + snipCompact (修剪) + contextCollapse
|
||||||
|
|
||||||
|
s07 持久化任务 (TASKS) "大目标 → 小任务 → 磁盘"
|
||||||
|
TaskCreate/Update/Get/List: 基于文件的任务图，
|
||||||
|
具有状态跟踪、依赖关系和持久性。
|
||||||
|
|
||||||
|
s08 后台任务 (BACKGROUND) "后台执行慢操作；代理继续思考"
|
||||||
|
DreamTask + LocalShellTask: 守护线程运行命令，
|
||||||
|
完成后注入通知。
|
||||||
|
|
||||||
|
s09 代理团队 (TEAMS) "一个人做太大 → 委派给队友"
|
||||||
|
TeamCreate/Delete + InProcessTeammateTask:
|
||||||
|
具有异步邮箱的持久队友。
|
||||||
|
|
||||||
|
s10 团队协议 (PROTOCOLS) "共享通信规则"
|
||||||
|
SendMessageTool: 一种请求-响应模式驱动
|
||||||
|
代理之间的所有协商。
|
||||||
|
|
||||||
|
s11 自主代理 (AUTONOMOUS) "队友自己扫描并认领任务"
|
||||||
|
coordinator/coordinatorMode.ts: 空闲循环 + 自动认领，
|
||||||
|
不需要领导来分配每个任务。
|
||||||
|
|
||||||
|
s12 工作树隔离 (WORKTREE) "每个人在自己的目录中工作"
|
||||||
|
EnterWorktreeTool/ExitWorktreeTool: 任务管理目标，
|
||||||
|
工作树管理目录，由 ID 绑定。
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 关键设计模式
|
||||||
|
|
||||||
|
| 模式 | 位置 | 目的 |
|
||||||
|
|---------|-------|---------|
|
||||||
|
| **AsyncGenerator 流式传输** | `QueryEngine`, `query()` | 从 API 到消费者的全链路流式传输 |
|
||||||
|
| **构建器 + 工厂 (Builder + Factory)** | `buildTool()` | 为工具定义提供安全的默认值 |
|
||||||
|
| **品牌类型 (Branded Types)** | `SystemPrompt`, `asSystemPrompt()` | 防止字符串/数组混淆 |
|
||||||
|
| **功能开关 + DCE** | 来自 `bun:bundle` 的 `feature()` | 编译时死代码消除 |
|
||||||
|
| **辨识联合 (Discriminated Unions)** | `Message` 类型 | 类型安全的消息处理 |
|
||||||
|
| **观察者 + 状态机** | `StreamingToolExecutor` | 工具执行生命周期跟踪 |
|
||||||
|
| **快照状态 (Snapshot State)** | `FileHistoryState` | 文件操作的撤销/重做 |
|
||||||
|
| **环形缓冲区 (Ring Buffer)** | 错误日志 | 长会话的有限内存 |
|
||||||
|
| **即发即弃写入 (Fire-and-Forget)** | `recordTranscript()` | 保持顺序的非阻塞持久化 |
|
||||||
|
| **延迟 Schema (Lazy Schema)** | `lazySchema()` | 延迟 Zod schema 评估以提高性能 |
|
||||||
|
| **上下文隔离 (Context Isolation)** | `AsyncLocalStorage` | 共享进程中每个代理的上下文 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 许可证
|
||||||
|
|
||||||
|
本仓库内容仅用于技术研究和教育目的。知识产权归原公司所有，若有侵权请联系删除。
|
||||||
665
README_JA.md
Normal file
665
README_JA.md
Normal file
@@ -0,0 +1,665 @@
|
|||||||
|
# Claude Code アーキテクチャ学習と研究
|
||||||
|
|
||||||
|
> **はじめに**: このプロジェクトは、CLI Agent アーキテクチャに関する学習および研究用のリポジトリです。すべての資料は、インターネット上で公開されている情報や議論のみに基づいてまとめられており、特に現在非常に人気のある CLI Agent `claude-code` に関する公開情報を参考にしています。私たちの目的は、開発者が Agent 技術をより深く理解し、活用できるように支援することです。今後も Agent アーキテクチャに関する洞察や実践的な議論を継続的に共有していく予定です。皆様のご関心とご支援に感謝いたします！
|
||||||
|
|
||||||
|
> **免責事項**: 本リポジトリのコンテンツは技術研究、学習、教育目的の交流のためにのみ提供されます。**商用利用は厳禁です。** いかなる個人、機関、団体も、本コンテンツを商業目的、営利活動、違法行為、その他の無許可の用途に使用することはできません。本コンテンツがお客様の法的権利、知的財産権、その他の利益を侵害する場合は、ご連絡いただければ直ちに確認・削除いたします。
|
||||||
|
|
||||||
|
|
||||||
|
**言語**: [English](README.md) | [中文](README_CN.md) | [한국어](README_KR.md) | **日本語**
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ツールシステムと権限アーキテクチャ
|
||||||
|
|
||||||
|
```text
|
||||||
|
ツールインターフェース
|
||||||
|
==============
|
||||||
|
|
||||||
|
buildTool(definition) ──> Tool<Input, Output, Progress>
|
||||||
|
|
||||||
|
各ツールは以下を実装します:
|
||||||
|
┌────────────────────────────────────────────────────────┐
|
||||||
|
│ ライフサイクル (LIFECYCLE) │
|
||||||
|
│ ├── validateInput() → 不正な引数を早期に拒否 │
|
||||||
|
│ ├── checkPermissions() → ツール固有の権限チェック │
|
||||||
|
│ └── call() → 実行して結果を返す │
|
||||||
|
│ │
|
||||||
|
│ 機能 (CAPABILITIES) │
|
||||||
|
│ ├── isEnabled() → 機能フラグの確認 │
|
||||||
|
│ ├── isConcurrencySafe() → 並列実行可能か？ │
|
||||||
|
│ ├── isReadOnly() → 副作用がないか？ │
|
||||||
|
│ ├── isDestructive() → 元に戻せない操作か？ │
|
||||||
|
│ └── interruptBehavior() → キャンセルまたはユーザー待機？ │
|
||||||
|
│ │
|
||||||
|
│ レンダリング (RENDERING - React/Ink) │
|
||||||
|
│ ├── renderToolUseMessage() → 入力表示 │
|
||||||
|
│ ├── renderToolResultMessage() → 出力表示 │
|
||||||
|
│ ├── renderToolUseProgressMessage() → スピナー/状態表示 │
|
||||||
|
│ └── renderGroupedToolUse() → 並列ツールグループ表示 │
|
||||||
|
│ │
|
||||||
|
│ AI 連携 (AI FACING) │
|
||||||
|
│ ├── prompt() → LLM 向けツール説明 │
|
||||||
|
│ ├── description() → 動的な説明 │
|
||||||
|
│ └── mapToolResultToAPI() → API 応答用フォーマット │
|
||||||
|
└────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 完全なツールインベントリ
|
||||||
|
|
||||||
|
```text
|
||||||
|
ファイル操作 検索と検出 実行
|
||||||
|
═════════════════ ══════════════════════ ══════════
|
||||||
|
FileReadTool GlobTool BashTool
|
||||||
|
FileEditTool GrepTool PowerShellTool
|
||||||
|
FileWriteTool ToolSearchTool
|
||||||
|
NotebookEditTool 対話
|
||||||
|
═══════════
|
||||||
|
Web とネットワーク エージェント / タスク AskUserQuestionTool
|
||||||
|
════════════════ ══════════════════ BriefTool
|
||||||
|
WebFetchTool AgentTool
|
||||||
|
WebSearchTool SendMessageTool 計画とワークフロー
|
||||||
|
TeamCreateTool ════════════════════
|
||||||
|
MCP プロトコル TeamDeleteTool EnterPlanModeTool
|
||||||
|
══════════════ TaskCreateTool ExitPlanModeTool
|
||||||
|
MCPTool TaskGetTool EnterWorktreeTool
|
||||||
|
ListMcpResourcesTool TaskUpdateTool ExitWorktreeTool
|
||||||
|
ReadMcpResourceTool TaskListTool TodoWriteTool
|
||||||
|
TaskStopTool
|
||||||
|
TaskOutputTool システム
|
||||||
|
════════
|
||||||
|
スキルと拡張機能 ConfigTool
|
||||||
|
═════════════════════ SkillTool
|
||||||
|
SkillTool ScheduleCronTool
|
||||||
|
LSPTool SleepTool
|
||||||
|
TungstenTool
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 権限システム
|
||||||
|
|
||||||
|
```text
|
||||||
|
ツール呼び出しリクエスト
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ validateInput() ──────────────────────────────────┐
|
||||||
|
│ 権限チェックの前に無効な入力を早期に拒否 │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ PreToolUse Hooks (ツール使用前フック) ────────────┐
|
||||||
|
│ ユーザー定義のシェルコマンド (settings.json hooks)│
|
||||||
|
│ 可能な操作: 承認、拒否、または入力の変更 │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ Permission Rules (権限ルール) ────────────────────┐
|
||||||
|
│ alwaysAllowRules: ツール名/パターン一致 → 自動承認 │
|
||||||
|
│ alwaysDenyRules: ツール名/パターン一致 → 自動拒否 │
|
||||||
|
│ alwaysAskRules: ツール名/パターン一致 → 常に確認 │
|
||||||
|
│ ソース: 設定、CLI 引数、セッション内の決定 │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
一致するルールなし？
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ Interactive Prompt (対話型プロンプト) ────────────┐
|
||||||
|
│ ユーザーがツール名 + 入力値を確認 │
|
||||||
|
│ オプション: 1回許可 / 常に許可 / 拒否 │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ checkPermissions() ───────────────────────────────┐
|
||||||
|
│ ツール固有のロジック (例: パスサンドボックスの確認) │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
承認済み → tool.call()
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## サブエージェントとマルチエージェントアーキテクチャ
|
||||||
|
|
||||||
|
```text
|
||||||
|
メインエージェント
|
||||||
|
==========
|
||||||
|
│
|
||||||
|
┌───────────────┼───────────────┐
|
||||||
|
▼ ▼ ▼
|
||||||
|
┌──────────────┐ ┌──────────┐ ┌──────────────┐
|
||||||
|
│ フォークエージェント │ リモートエージェント │ プロセス内チームメイト│
|
||||||
|
│ (FORK) │ │ (REMOTE) │ │ (IN-PROCESS) │
|
||||||
|
│ プロセスフォーク │ ブリッジセッション │ 同一プロセス │
|
||||||
|
│ キャッシュ共有 │ 完全隔離 │ 非同期コンテキスト │
|
||||||
|
│ 新規 msgs[] │ │ │ 状態共有 │
|
||||||
|
└──────────────┘ └──────────┘ └──────────────┘
|
||||||
|
|
||||||
|
生成モード (SPAWN MODES):
|
||||||
|
├─ default → プロセス内、会話を共有
|
||||||
|
├─ fork → 子プロセス、新しい messages[]、ファイルキャッシュを共有
|
||||||
|
├─ worktree → 隔離された git worktree + fork
|
||||||
|
└─ remote → Claude Code Remote / コンテナへのブリッジ接続
|
||||||
|
|
||||||
|
通信メカニズム (COMMUNICATION):
|
||||||
|
├─ SendMessageTool → エージェント間のメッセージ伝達
|
||||||
|
├─ TaskCreate/Update → 共有タスクボード
|
||||||
|
└─ TeamCreate/Delete → チームのライフサイクル管理
|
||||||
|
|
||||||
|
スウォームモード (SWARM MODE、機能フラグで制御):
|
||||||
|
┌─────────────────────────────────────────────┐
|
||||||
|
│ リーダーエージェント (Lead Agent) │
|
||||||
|
│ ├── チームメイト A ──> タスク 1 を担当 │
|
||||||
|
│ ├── チームメイト B ──> タスク 2 を担当 │
|
||||||
|
│ └── チームメイト C ──> タスク 3 を担当 │
|
||||||
|
│ │
|
||||||
|
│ 共有: タスクボード、メッセージ受信トレイ │
|
||||||
|
│ 隔離: messages[]、ファイルキャッシュ、cwd │
|
||||||
|
└─────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## コンテキスト管理 (圧縮システム)
|
||||||
|
|
||||||
|
```text
|
||||||
|
コンテキストウィンドウ予算 (CONTEXT WINDOW BUDGET)
|
||||||
|
══════════════════════════════════════
|
||||||
|
|
||||||
|
┌─────────────────────────────────────────────────────┐
|
||||||
|
│ システムプロンプト (ツール、権限、CLAUDE.md) │
|
||||||
|
│ ══════════════════════════════════════════════ │
|
||||||
|
│ │
|
||||||
|
│ 会話履歴 (Conversation History) │
|
||||||
|
│ ┌─────────────────────────────────────────────┐ │
|
||||||
|
│ │ [過去のメッセージの圧縮要約] │ │
|
||||||
|
│ │ ═══════════════════════════════════════════ │ │
|
||||||
|
│ │ [compact_boundary マーカー] │ │
|
||||||
|
│ │ ─────────────────────────────────────────── │ │
|
||||||
|
│ │ [最近のメッセージ — 元のまま保持] │ │
|
||||||
|
│ │ user → assistant → tool_use → tool_result │ │
|
||||||
|
│ └─────────────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ 現在のターン (ユーザー + アシスタントの応答) │
|
||||||
|
└─────────────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
3つの圧縮戦略:
|
||||||
|
├─ autoCompact → トークン数がしきい値を超えた時にトリガー
|
||||||
|
│ 圧縮 API 呼び出しを通じて過去のメッセージを要約
|
||||||
|
├─ snipCompact → 不要なメッセージと古いマーカーを削除
|
||||||
|
│ (HISTORY_SNIP 機能フラグ)
|
||||||
|
└─ contextCollapse → 効率化のためにコンテキストを再構築
|
||||||
|
(CONTEXT_COLLAPSE 機能フラグ)
|
||||||
|
|
||||||
|
圧縮フロー (COMPACTION FLOW):
|
||||||
|
messages[] ──> getMessagesAfterCompactBoundary()
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
過去のメッセージ ──> Claude API (要約) ──> 圧縮要約
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
[要約] + [compact_boundary] + [最近のメッセージ]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## MCP (Model Context Protocol) 統合
|
||||||
|
|
||||||
|
```text
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ MCP アーキテクチャ │
|
||||||
|
│ │
|
||||||
|
│ MCPConnectionManager.tsx │
|
||||||
|
│ ├── サーバー検出 (settings.json の設定に基づく) │
|
||||||
|
│ │ ├── stdio → 子プロセスを生成 │
|
||||||
|
│ │ ├── sse → HTTP EventSource │
|
||||||
|
│ │ ├── http → ストリーミング HTTP │
|
||||||
|
│ │ ├── ws → WebSocket │
|
||||||
|
│ │ └── sdk → プロセス内転送 │
|
||||||
|
│ │ │
|
||||||
|
│ ├── クライアントライフサイクル │
|
||||||
|
│ │ ├── connect → initialize → list tools │
|
||||||
|
│ │ ├── MCPTool ラッパーを通じたツール呼び出し │
|
||||||
|
│ │ └── バックオフ (backoff) 付きの切断 / 再接続 │
|
||||||
|
│ │ │
|
||||||
|
│ ├── 認証 (Authentication) │
|
||||||
|
│ │ ├── OAuth 2.0 フロー (McpOAuthConfig) │
|
||||||
|
│ │ ├── クロスアプリアクセス (XAA / SEP-990) │
|
||||||
|
│ │ └── ヘッダーを通じた API キーの受け渡し │
|
||||||
|
│ │ │
|
||||||
|
│ └── ツール登録 (Tool Registration) │
|
||||||
|
│ ├── mcp__<server>__<tool> 命名規則 │
|
||||||
|
│ ├── MCP サーバーからの動的スキーマ (schema) 受信 │
|
||||||
|
│ ├── Claude Code への権限パススルー (passthrough) │
|
||||||
|
│ └── リソースのリスト化 (ListMcpResourcesTool) │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ブリッジレイヤー (Claude Desktop / Remote)
|
||||||
|
|
||||||
|
```text
|
||||||
|
Claude Desktop / Web / Cowork Claude Code CLI
|
||||||
|
══════════════════════════ ═════════════════
|
||||||
|
|
||||||
|
┌───────────────────┐ ┌──────────────────┐
|
||||||
|
│ ブリッジクライアント│ ←─ HTTP ──→ │ bridgeMain.ts │
|
||||||
|
│ (Desktop App) │ │ │
|
||||||
|
└───────────────────┘ │ セッション管理者│
|
||||||
|
│ ├── CLI 生成 │
|
||||||
|
プロトコル (PROTOCOL): │ ├── 状態ポーリング│
|
||||||
|
├─ JWT 認証 │ ├── メッセージリレー│
|
||||||
|
├─ Work secret 交換 │ └── 容量ウェイク│
|
||||||
|
├─ セッションライフサイクル │ │
|
||||||
|
│ ├── create │ バックオフ(Backoff):│
|
||||||
|
│ ├── run │ ├─ 接続: 2s→2m │
|
||||||
|
│ └─ stop │ └─ 生成: 500ms→30s│
|
||||||
|
└─ トークン更新スケジューラー └──────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## セッションの永続性 (Session Persistence)
|
||||||
|
|
||||||
|
```text
|
||||||
|
セッションストレージ (SESSION STORAGE)
|
||||||
|
═════════════════════════════
|
||||||
|
|
||||||
|
~/.claude/projects/<hash>/sessions/
|
||||||
|
└── <session-id>.jsonl ← 追記専用 (append-only) ログ
|
||||||
|
├── {"type":"user",...}
|
||||||
|
├── {"type":"assistant",...}
|
||||||
|
├── {"type":"progress",...}
|
||||||
|
└── {"type":"system","subtype":"compact_boundary",...}
|
||||||
|
|
||||||
|
復元フロー (RESUME FLOW):
|
||||||
|
getLastSessionLog() ──> JSONL パース ──> messages[] 再構築
|
||||||
|
│
|
||||||
|
├── --continue → 現在の作業ディレクトリの最後のセッション
|
||||||
|
├── --resume <id> → 特定のセッション
|
||||||
|
└── --fork-session → 新しい ID、履歴をコピー
|
||||||
|
|
||||||
|
永続性戦略 (PERSISTENCE STRATEGY):
|
||||||
|
├─ ユーザーメッセージ → 書き込み待機 (クラッシュ復旧のためのブロッキング)
|
||||||
|
├─ アシスタントメッセージ → 非同期送信 (順序が保持されるキュー)
|
||||||
|
├─ 進行状態 → インライン書き込み (次のクエリ時に重複排除)
|
||||||
|
└─ フラッシュ(Flush) → 結果返却時 / cowork の即時フラッシュ
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 機能フラグシステム (Feature Flag System)
|
||||||
|
|
||||||
|
```text
|
||||||
|
デッドコードの削除 (Bun コンパイル時)
|
||||||
|
══════════════════════════════
|
||||||
|
|
||||||
|
feature('FLAG_NAME') ──→ true → バンドルに含まれる
|
||||||
|
──→ false → バンドルから削除される
|
||||||
|
|
||||||
|
フラグ一覧 (ソース内で確認):
|
||||||
|
├─ COORDINATOR_MODE → マルチエージェントコーディネーター
|
||||||
|
├─ HISTORY_SNIP → 積極的な履歴のトリミング
|
||||||
|
├─ CONTEXT_COLLAPSE → コンテキストの再構築
|
||||||
|
├─ DAEMON → バックグラウンドデーモンワーカー
|
||||||
|
├─ AGENT_TRIGGERS → cron/リモートトリガー
|
||||||
|
├─ AGENT_TRIGGERS_REMOTE → リモートトリガーのサポート
|
||||||
|
├─ MONITOR_TOOL → MCP モニタリングツール
|
||||||
|
├─ WEB_BROWSER_TOOL → ブラウザ自動化
|
||||||
|
├─ VOICE_MODE → 音声入力/出力
|
||||||
|
├─ TEMPLATES → タスク分類器
|
||||||
|
├─ EXPERIMENTAL_SKILL_SEARCH → スキル探索
|
||||||
|
├─ KAIROS → プッシュ通知、ファイル送信
|
||||||
|
├─ PROACTIVE → スリープツール、先行的な行動
|
||||||
|
├─ OVERFLOW_TEST_TOOL → テストツール
|
||||||
|
├─ TERMINAL_PANEL → ターミナルキャプチャ
|
||||||
|
├─ WORKFLOW_SCRIPTS → ワークフローツール
|
||||||
|
├─ CHICAGO_MCP → コンピューター使用 MCP
|
||||||
|
├─ DUMP_SYSTEM_PROMPT → プロンプト抽出 (内部専用)
|
||||||
|
├─ UDS_INBOX → ピア探索
|
||||||
|
├─ ABLATION_BASELINE → 実験的アブレーション (ablation)
|
||||||
|
└─ UPGRADE_NOTICE → アップグレード通知
|
||||||
|
|
||||||
|
ランタイムゲート (RUNTIME GATES):
|
||||||
|
├─ process.env.USER_TYPE === 'ant' → 内部機能
|
||||||
|
└─ GrowthBook feature flags → ランタイムの A/B 実験
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 状態管理 (State Management)
|
||||||
|
|
||||||
|
```text
|
||||||
|
┌──────────────────────────────────────────────────────────┐
|
||||||
|
│ AppState Store │
|
||||||
|
│ │
|
||||||
|
│ AppState { │
|
||||||
|
│ toolPermissionContext: { │
|
||||||
|
│ mode: PermissionMode, ← default/plan など│
|
||||||
|
│ additionalWorkingDirectories, │
|
||||||
|
│ alwaysAllowRules, ← 自動承認 │
|
||||||
|
│ alwaysDenyRules, ← 自動拒否 │
|
||||||
|
│ alwaysAskRules, ← 常に確認 │
|
||||||
|
│ isBypassPermissionsModeAvailable │
|
||||||
|
│ }, │
|
||||||
|
│ fileHistory: FileHistoryState, ← 元に戻すスナップショット│
|
||||||
|
│ attribution: AttributionState, ← コミット追跡 │
|
||||||
|
│ verbose: boolean, │
|
||||||
|
│ mainLoopModel: string, ← アクティブなモデル │
|
||||||
|
│ fastMode: FastModeState, │
|
||||||
|
│ speculation: SpeculationState │
|
||||||
|
│ } │
|
||||||
|
│ │
|
||||||
|
│ React 統合: │
|
||||||
|
│ ├── AppStateProvider → createContext を通じてストア作成│
|
||||||
|
│ ├── useAppState(sel) → セレクタ (selector) ベースの購読│
|
||||||
|
│ └── useSetAppState() → immer スタイルの更新関数 │
|
||||||
|
└──────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12の段階的ハーネスメカニズム (The 12 Progressive Harness Mechanisms)
|
||||||
|
|
||||||
|
このアーキテクチャは、基本的なループを超えて、プロダクション AI エージェントのハーネスに必要な 12 の段階的なメカニズムを示しています。各メカニズムは前のものを基盤として構築されます:
|
||||||
|
|
||||||
|
```text
|
||||||
|
s01 コアループ (THE LOOP) "一つのループと Bash があれば十分"
|
||||||
|
query.ts: Claude API を呼び出す while-true ループ、
|
||||||
|
stop_reason を確認し、ツールを実行して結果を追加します。
|
||||||
|
|
||||||
|
s02 ツールディスパッチ (TOOL DISPATCH) "ツールの追加 = ハンドラーの追加"
|
||||||
|
Tool.ts + tools.ts: すべてのツールがディスパッチマップに登録されます。
|
||||||
|
ループは同一に保たれます。buildTool() ファクトリが安全なデフォルト値を提供します。
|
||||||
|
|
||||||
|
s03 計画 (PLANNING) "計画のないエージェントは漂流する"
|
||||||
|
EnterPlanModeTool/ExitPlanModeTool + TodoWriteTool:
|
||||||
|
ステップを先にリストアップしてから実行します。完了率を2倍に高めます。
|
||||||
|
|
||||||
|
s04 サブエージェント (SUB-AGENTS) "大きなタスクを分割し、サブタスクごとにコンテキストを整理する"
|
||||||
|
AgentTool + forkSubagent.ts: 各サブエージェントは新しい messages[] を持ち、
|
||||||
|
メインの会話をクリーンに保ちます。
|
||||||
|
|
||||||
|
s05 オンデマンドの知識 (KNOWLEDGE) "必要な時に知識をロードする"
|
||||||
|
SkillTool + memdir/: システムプロンプトではなく tool_result を通じて注入します。
|
||||||
|
ディレクトリごとに CLAUDE.md ファイルを遅延ロード (lazy load) します。
|
||||||
|
|
||||||
|
s06 コンテキスト圧縮 (COMPRESSION) "コンテキストがいっぱいになったらスペースを確保する"
|
||||||
|
services/compact/: 3層の戦略:
|
||||||
|
autoCompact (要約) + snipCompact (切り取り) + contextCollapse
|
||||||
|
|
||||||
|
s07 永続的なタスク (TASKS) "大きな目標 → 小さなタスク → ディスク"
|
||||||
|
TaskCreate/Update/Get/List: ファイルベースのタスクグラフ (Task graph) で、
|
||||||
|
状態追跡、依存関係、および永続性を持ちます。
|
||||||
|
|
||||||
|
s08 バックグラウンドタスク (BACKGROUND) "バックグラウンドで遅い操作を実行; エージェントは考え続ける"
|
||||||
|
DreamTask + LocalShellTask: デーモンスレッドがコマンドを実行し、
|
||||||
|
完了時に通知を注入します。
|
||||||
|
|
||||||
|
s09 エージェントチーム (TEAMS) "一人でやるには大きすぎる → チームメイトに委任する"
|
||||||
|
TeamCreate/Delete + InProcessTeammateTask:
|
||||||
|
非同期メールボックスを持つ永続的なチームメイトエージェント。
|
||||||
|
|
||||||
|
s10 チームプロトコル (PROTOCOLS) "共有された通信ルール"
|
||||||
|
SendMessageTool: 一つのリクエスト-レスポンスパターンが
|
||||||
|
エージェント間のすべての交渉を主導します。
|
||||||
|
|
||||||
|
s11 自律型エージェント (AUTONOMOUS) "チームメイトが自らタスクをスキャンして要求する"
|
||||||
|
coordinator/coordinatorMode.ts: アイドルループ (Idle cycle) + 自動割り当て、
|
||||||
|
リーダーがすべてのタスクを一つ一つ割り当てる必要はありません。
|
||||||
|
|
||||||
|
s12 ワークツリーの隔離 (WORKTREE) "各自が自分のディレクトリで作業する"
|
||||||
|
EnterWorktreeTool/ExitWorktreeTool: タスクは目標を管理し、
|
||||||
|
ワークツリーはディレクトリを管理し、ID で結び付けられます。
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 主要なデザインパターン (Key Design Patterns)
|
||||||
|
|
||||||
|
| パターン | 場所 | 目的 |
|
||||||
|
|---------|-------|---------|
|
||||||
|
| **AsyncGenerator ストリーミング** | `QueryEngine`, `query()` | API からコンシューマーに至る全チェーンのストリーミング |
|
||||||
|
| **ビルダー + ファクトリ (Builder + Factory)** | `buildTool()` | ツール定義のための安全なデフォルト値の提供 |
|
||||||
|
| **ブランドタイプ (Branded Types)** | `SystemPrompt`, `asSystemPrompt()` | 文字列/配列の混同を防止 |
|
||||||
|
| **機能フラグ + DCE** | `bun:bundle` の `feature()` | コンパイル時のデッドコード削除 (DCE) |
|
||||||
|
| **判別可能なユニオン (Discriminated Unions)** | `Message` タイプ | 型安全性が保証されるメッセージ処理 |
|
||||||
|
| **オブザーバー + ステートマシン** | `StreamingToolExecutor` | ツール実行のライフサイクル追跡 |
|
||||||
|
| **スナップショット状態 (Snapshot State)** | `FileHistoryState` | ファイル操作の元に戻す/やり直し |
|
||||||
|
| **リングバッファ (Ring Buffer)** | エラーログ | 長いセッションのための制限付きメモリ使用 |
|
||||||
|
| **撃ちっ放し (Fire-and-Forget)** | `recordTranscript()` | 順序が保持されるノンブロッキングな永続化 |
|
||||||
|
| **遅延スキーマ (Lazy Schema)** | `lazySchema()` | パフォーマンス向上のための Zod スキーマ遅延評価 |
|
||||||
|
| **コンテキストの隔離 (Context Isolation)** | `AsyncLocalStorage` | 共有プロセス内の各エージェントごとのコンテキスト |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## データフロー: 単一クエリのライフサイクル
|
||||||
|
|
||||||
|
```text
|
||||||
|
ユーザー入力 (プロンプト / スラッシュコマンド)
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
processUserInput() ← /コマンドのパース、UserMessage の作成
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
fetchSystemPromptParts() ← ツール → プロンプトセクション、CLAUDE.md メモリ
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
recordTranscript() ← ユーザーメッセージをディスクに永続化 (JSONL)
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─→ normalizeMessagesForAPI() ← UI 専用フィールドを削除、必要に応じて圧縮を実行
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ Claude API (ストリーミング) ← ツール + システムプロンプトと共に POST /v1/messages
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ ストリームイベント ← message_start → content_block_delta → message_stop
|
||||||
|
│ │
|
||||||
|
│ ├─ テキストブロック ────────→ コンシューマー (SDK / REPL) に伝達
|
||||||
|
│ │
|
||||||
|
│ └─ tool_use ブロック?
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ StreamingToolExecutor ← 分割: 並行処理安全 (concurrent-safe) vs 直列 (serial)
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ canUseTool() ← 権限チェック (フック + ルール + UI プロンプト)
|
||||||
|
│ │
|
||||||
|
│ ├─ 拒否 ────────────────→ tool_result(error) を追加、ループを継続
|
||||||
|
│ │
|
||||||
|
│ └─ 許可
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ tool.call() ← ツールの実行 (Bash, Read, Edit など)
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ tool_result 追加 ← messages[] にプッシュ、recordTranscript()
|
||||||
|
│ │
|
||||||
|
└─────────┘ ← API 呼び出しにループで戻る
|
||||||
|
│
|
||||||
|
▼ (stop_reason != "tool_use")
|
||||||
|
結果メッセージの生成 ← 最終テキスト、使用量、コスト、session_id
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 目次
|
||||||
|
|
||||||
|
- [詳細分析レポート (`docs/`)](#詳細分析レポート-docs) — テレメトリ、コードネーム、アンダーカバーモード、リモート制御、今後のロードマップ
|
||||||
|
- [ディレクトリ参照](#ディレクトリ参照) — コード構造ツリー
|
||||||
|
- [アーキテクチャ概要](#アーキテクチャ概要) — エントリポイント → クエリエンジン → ツール/サービス/状態
|
||||||
|
- [ツールシステムと権限アーキテクチャ](#ツールシステムと権限アーキテクチャ) — 40+ ツール、権限フロー、サブエージェント
|
||||||
|
- [12の段階的ハーネスメカニズム](#12の段階的ハーネスメカニズム-the-12-progressive-harness-mechanisms) — Claude Code がエージェントループにプロダクション機能を実装する方法
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 詳細分析レポート (`docs/`)
|
||||||
|
|
||||||
|
インターネット上で公開されている資料やコミュニティの議論をもとに整理した Claude Code v2.1.88 分析レポート。英語/中国語/韓国語/日本語の4言語で提供。
|
||||||
|
|
||||||
|
```
|
||||||
|
docs/
|
||||||
|
├── en/ # English
|
||||||
|
│ ├── [01-telemetry-and-privacy.md] # Telemetry & Privacy — what's collected, why you can't opt out
|
||||||
|
│ ├── [02-hidden-features-and-codenames.md] # Codenames (Capybara/Tengu/Numbat), feature flags, internal vs external
|
||||||
|
│ ├── [03-undercover-mode.md] # Undercover Mode — hiding AI authorship in open-source repos
|
||||||
|
│ ├── [04-remote-control-and-killswitches.md]# Remote Control — managed settings, killswitches, model overrides
|
||||||
|
│ └── [05-future-roadmap.md] # Future Roadmap — Numbat, KAIROS, voice mode, unreleased tools
|
||||||
|
│
|
||||||
|
├── ja/ # 日本語
|
||||||
|
│ ├── [01-テレメトリとプライバシー.md] # テレメトリとプライバシー — 収集項目、無効化不可の理由
|
||||||
|
│ ├── [02-隠し機能とコードネーム.md] # 隠し機能 — モデルコードネーム、feature flag、内部/外部ユーザーの違い
|
||||||
|
│ ├── [03-アンダーカバーモード.md] # アンダーカバーモード — オープンソースでのAI著作隠匿
|
||||||
|
│ ├── [04-リモート制御とキルスイッチ.md] # リモート制御 — 管理設定、キルスイッチ、モデルオーバーライド
|
||||||
|
│ └── [05-今後のロードマップ.md] # 今後のロードマップ — Numbat、KAIROS、音声モード、未公開ツール
|
||||||
|
│
|
||||||
|
├── ko/ # 한국어
|
||||||
|
│ ├── [01-텔레메트리와-프라이버시.md] # 텔레메트리 및 프라이버시 — 수집 항목, 비활성화 불가 이유
|
||||||
|
│ ├── [02-숨겨진-기능과-코드네임.md] # 숨겨진 기능 — 모델 코드네임, feature flag, 내부/외부 사용자 차이
|
||||||
|
│ ├── [03-언더커버-모드.md] # 언더커버 모드 — 오픈소스에서 AI 저작 은폐
|
||||||
|
│ ├── [04-원격-제어와-킬스위치.md] # 원격 제어 — 관리 설정, 킬스위치, 모델 오버라이드
|
||||||
|
│ └── [05-향후-로드맵.md] # 향후 로드맵 — Numbat, KAIROS, 음성 모드, 미공개 도구
|
||||||
|
│
|
||||||
|
└── zh/ # 中文
|
||||||
|
├── [01-遥测与隐私分析.md] # 遥测与隐私 — 收集了什么，为什么无法退出
|
||||||
|
├── [02-隐藏功能与模型代号.md] # 隐藏功能 — 模型代号，feature flag，内外用户差异
|
||||||
|
├── [03-卧底模式分析.md] # 卧底模式 — 在开源项目中隐藏 AI 身份
|
||||||
|
├── [04-远程控制与紧急开关.md] # 远程控制 — 托管设置，紧急开关，模型覆盖
|
||||||
|
└── [05-未来路线图.md] # 未来路线图 — Numbat，KAIROS，语音模式，未上线工具
|
||||||
|
```
|
||||||
|
|
||||||
|
> ファイル名をクリックすると該当レポートに移動します。
|
||||||
|
|
||||||
|
| # | テーマ | 主要発見 | リンク |
|
||||||
|
|---|--------|---------|------|
|
||||||
|
| 01 | **テレメトリとプライバシー** | 二層分析パイプライン（1P、Datadog）。環境フィンガープリント、プロセスメトリクス、全イベントにセッション/ユーザーID。**ユーザー向け無効化設定なし。** `OTEL_LOG_TOOL_DETAILS=1` で全ツール入力記録可能。 | [EN](docs/en/01-telemetry-and-privacy.md) · [日本語](docs/ja/01-テレメトリとプライバシー.md) |
|
||||||
|
| 02 | **隠し機能とコードネーム** | 動物コードネーム体系（Capybara v8、Tengu、Fennec→Opus 4.6、**Numbat** 次期）。Feature flagにランダム単語ペアで目的を難読化。内部ユーザーは優遇プロンプトと検証エージェントを利用可能。隠しコマンド: `/btw`、`/stickers`。 | [EN](docs/en/02-hidden-features-and-codenames.md) · [日本語](docs/ja/02-隠し機能とコードネーム.md) |
|
||||||
|
| 03 | **アンダーカバーモード** | 公式社員は公開リポジトリで自動的にアンダーカバーモードに突入。モデルへの指示: **「正体を明かすな」** — 全AI帰属表示を除去し、人間が書いたようにコミット。**強制無効化オプションなし。** | [EN](docs/en/03-undercover-mode.md) · [日本語](docs/ja/03-アンダーカバーモード.md) |
|
||||||
|
| 04 | **リモート制御とキルスイッチ** | 1時間ごとに `/api/claude_code/settings` をポーリング。危険な変更時にブロッキングダイアログ — **拒否＝アプリ終了**。6以上のキルスイッチ（パーミッションバイパス、Fastモード、音声モード、分析シンク）。GrowthBookで同意なくユーザー動作変更可能。 | [EN](docs/en/04-remote-control-and-killswitches.md) · [日本語](docs/ja/04-リモート制御とキルスイッチ.md) |
|
||||||
|
| 05 | **今後のロードマップ** | **Numbat** コードネーム確認。Opus 4.7 / Sonnet 4.8開発中。**KAIROS** ＝ 完全自律エージェントモード、`<tick>`ハートビート、プッシュ通知、PR購読。音声モード（push-to-talk）準備完了。未公開ツール17個発見。 | [EN](docs/en/05-future-roadmap.md) · [日本語](docs/ja/05-今後のロードマップ.md) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 著作権および免責事項
|
||||||
|
|
||||||
|
```text
|
||||||
|
本リポジトリは技術研究および教育目的でのみ提供されます。商用利用は禁止です。
|
||||||
|
|
||||||
|
著作権者として本リポジトリのコンテンツがお客様の権利を侵害すると判断される場合は、
|
||||||
|
リポジトリ所有者にご連絡いただければ直ちに削除いたします。
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 統計
|
||||||
|
|
||||||
|
| 項目 | 数量 |
|
||||||
|
|------|------|
|
||||||
|
| ファイル (.ts/.tsx) | 約1,884 |
|
||||||
|
| 行数 | 約512,664 |
|
||||||
|
| 最大単一ファイル | `query.ts`（約785KB） |
|
||||||
|
| 組込ツール | 約40以上 |
|
||||||
|
| スラッシュコマンド | 約80以上 |
|
||||||
|
| 依存関係 (node_modules) | 約192パッケージ |
|
||||||
|
| ランタイム | Bun（Node.js >= 18バンドルにコンパイル） |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## エージェントモード
|
||||||
|
|
||||||
|
```
|
||||||
|
コアループ
|
||||||
|
========
|
||||||
|
|
||||||
|
ユーザー --> messages[] --> Claude API --> レスポンス
|
||||||
|
|
|
||||||
|
stop_reason == "tool_use"?
|
||||||
|
/ \
|
||||||
|
はい いいえ
|
||||||
|
| |
|
||||||
|
ツール実行 テキスト返却
|
||||||
|
tool_result追加
|
||||||
|
ループ再突入 -----------------> messages[]
|
||||||
|
|
||||||
|
|
||||||
|
これが最小のエージェントループである。Claude Codeはこのループの上に
|
||||||
|
プロダクショングレードのハーネスをラップする: 権限、ストリーミング、
|
||||||
|
並行性、圧縮、サブエージェント、永続化、MCP。
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ディレクトリ参照
|
||||||
|
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── main.tsx # REPLブートストラップ、4,683行
|
||||||
|
├── QueryEngine.ts # SDK/headlessクエリライフサイクルエンジン
|
||||||
|
├── query.ts # メインエージェントループ（785KB、最大ファイル）
|
||||||
|
├── Tool.ts # ツールインターフェース + buildToolファクトリ
|
||||||
|
├── Task.ts # タスクタイプ、ID、状態ベースクラス
|
||||||
|
├── tools.ts # ツール登録、プリセット、フィルタリング
|
||||||
|
├── commands.ts # スラッシュコマンド定義
|
||||||
|
├── context.ts # ユーザー入力コンテキスト
|
||||||
|
├── cost-tracker.ts # APIコスト累積
|
||||||
|
├── setup.ts # 初回実行セットアップフロー
|
||||||
|
│
|
||||||
|
├── bridge/ # Claude Desktop / リモートブリッジ
|
||||||
|
│ ├── bridgeMain.ts # セッションライフサイクルマネージャ
|
||||||
|
│ ├── bridgeApi.ts # HTTPクライアント
|
||||||
|
│ ├── bridgeConfig.ts # 接続設定
|
||||||
|
│ ├── bridgeMessaging.ts # メッセージリレー
|
||||||
|
│ ├── sessionRunner.ts # プロセススポーン
|
||||||
|
│ ├── jwtUtils.ts # JWTリフレッシュ
|
||||||
|
│ ├── workSecret.ts # 認証トークン
|
||||||
|
│ └── capacityWake.ts # 容量ベースウェイク
|
||||||
|
│
|
||||||
|
├── cli/ # CLIインフラ
|
||||||
|
│ ├── handlers/ # コマンドハンドラ
|
||||||
|
│ └── transports/ # I/Oトランスポート（stdio, structured）
|
||||||
|
│
|
||||||
|
├── commands/ # 約80スラッシュコマンド
|
||||||
|
├── components/ # React/InkターミナルUI
|
||||||
|
├── entrypoints/ # アプリエントリポイント
|
||||||
|
├── hooks/ # React hooks
|
||||||
|
├── services/ # ビジネスロジック層
|
||||||
|
├── state/ # アプリ状態
|
||||||
|
├── tasks/ # タスク実装
|
||||||
|
├── tools/ # 40以上のツール実装
|
||||||
|
├── types/ # 型定義
|
||||||
|
├── utils/ # ユーティリティ（最大ディレクトリ）
|
||||||
|
└── vendor/ # ネイティブモジュールスタブ
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## アーキテクチャ概要
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ エントリ層 │
|
||||||
|
│ cli.tsx ──> main.tsx ──> REPL.tsx（インタラクティブ） │
|
||||||
|
│ └──> QueryEngine.ts（headless/SDK） │
|
||||||
|
└──────────────────────────────┬──────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ クエリエンジン │
|
||||||
|
│ submitMessage(prompt) ──> AsyncGenerator<SDKMessage> │
|
||||||
|
│ ├── fetchSystemPromptParts() ──> システムプロンプト組立 │
|
||||||
|
│ ├── processUserInput() ──> /コマンド処理 │
|
||||||
|
│ ├── query() ──> メインエージェントループ │
|
||||||
|
│ │ ├── StreamingToolExecutor ──> 並列ツール実行 │
|
||||||
|
│ │ ├── autoCompact() ──> コンテキスト圧縮 │
|
||||||
|
│ │ └── runTools() ──> ツールオーケストレーション │
|
||||||
|
│ └── yield SDKMessage ──> コンシューマにストリーミング │
|
||||||
|
└──────────────────────────────┬──────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## ライセンス
|
||||||
|
|
||||||
|
本リポジトリのコンテンツは技術研究および教育目的でのみ提供されます。知的財産権は元の会社に帰属します。権利侵害がある場合は、削除のためご連絡ください。。
|
||||||
658
README_KR.md
Normal file
658
README_KR.md
Normal file
@@ -0,0 +1,658 @@
|
|||||||
|
# Claude Code 아키텍처 학습 및 연구
|
||||||
|
|
||||||
|
> **소개**: 이 프로젝트는 CLI Agent 아키텍처에 대한 학습 및 연구 저장소입니다. 모든 자료는 전적으로 인터넷에 공개된 정보와 토론을 바탕으로 정리되었으며, 특히 현재 매우 인기 있는 CLI Agent인 `claude-code`와 관련된 공개 정보를 참고했습니다. 저희의 목적은 개발자들이 Agent 기술을 더 잘 이해하고 활용할 수 있도록 돕는 것입니다. 앞으로도 Agent 아키텍처와 관련된 더 많은 통찰과 실용적인 토론 콘텐츠를 지속적으로 공유할 예정입니다. 여러분의 관심과 성원에 감사드립니다!
|
||||||
|
|
||||||
|
> **면책 조항**: 본 저장소의 콘텐츠는 기술 연구, 학습, 교육 목적의 교류를 위해서만 제공됩니다. **상업적 사용은 엄격히 금지됩니다.** 어떠한 개인, 기관, 단체도 이 콘텐츠를 상업적 목적, 영리 활동, 불법 활동 또는 기타 무단 사용에 활용할 수 없습니다. 본 콘텐츠가 귀하의 법적 권리, 지적 재산권 또는 기타 이익을 침해하는 경우, 연락 주시면 즉시 확인 후 삭제 조치하겠습니다.
|
||||||
|
|
||||||
|
|
||||||
|
**언어**: [English](README.md) | [中文](README_CN.md) | **한국어** | [日本語](README_JA.md)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 도구 시스템 및 권한 아키텍처
|
||||||
|
|
||||||
|
```text
|
||||||
|
도구 인터페이스
|
||||||
|
==============
|
||||||
|
|
||||||
|
buildTool(definition) ──> Tool<Input, Output, Progress>
|
||||||
|
|
||||||
|
모든 도구는 다음을 구현합니다:
|
||||||
|
┌────────────────────────────────────────────────────────┐
|
||||||
|
│ 수명주기 (LIFECYCLE) │
|
||||||
|
│ ├── validateInput() → 잘못된 인수 조기 거부 │
|
||||||
|
│ ├── checkPermissions() → 도구별 권한 검사 │
|
||||||
|
│ └── call() → 실행 및 결과 반환 │
|
||||||
|
│ │
|
||||||
|
│ 기능 (CAPABILITIES) │
|
||||||
|
│ ├── isEnabled() → 기능 플래그 확인 │
|
||||||
|
│ ├── isConcurrencySafe() → 병렬 실행 가능 여부? │
|
||||||
|
│ ├── isReadOnly() → 부작용(side effects) 없음? │
|
||||||
|
│ ├── isDestructive() → 되돌릴 수 없는 작업? │
|
||||||
|
│ └── interruptBehavior() → 취소 또는 사용자 대기? │
|
||||||
|
│ │
|
||||||
|
│ 렌더링 (RENDERING - React/Ink) │
|
||||||
|
│ ├── renderToolUseMessage() → 입력 표시 │
|
||||||
|
│ ├── renderToolResultMessage() → 출력 표시 │
|
||||||
|
│ ├── renderToolUseProgressMessage() → 스피너/상태 표시 │
|
||||||
|
│ └── renderGroupedToolUse() → 병렬 도구 그룹 표시 │
|
||||||
|
│ │
|
||||||
|
│ AI 연동 (AI FACING) │
|
||||||
|
│ ├── prompt() → LLM용 도구 설명 │
|
||||||
|
│ ├── description() → 동적 설명 │
|
||||||
|
│ └── mapToolResultToAPI() → API 응답용 포맷팅 │
|
||||||
|
└────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
### 전체 도구 인벤토리
|
||||||
|
|
||||||
|
```text
|
||||||
|
파일 작업 검색 및 탐색 실행
|
||||||
|
═════════════════ ══════════════════════ ══════════
|
||||||
|
FileReadTool GlobTool BashTool
|
||||||
|
FileEditTool GrepTool PowerShellTool
|
||||||
|
FileWriteTool ToolSearchTool
|
||||||
|
NotebookEditTool 상호작용
|
||||||
|
═══════════
|
||||||
|
웹 및 네트워크 에이전트 / 작업 AskUserQuestionTool
|
||||||
|
════════════════ ══════════════════ BriefTool
|
||||||
|
WebFetchTool AgentTool
|
||||||
|
WebSearchTool SendMessageTool 계획 및 워크플로우
|
||||||
|
TeamCreateTool ════════════════════
|
||||||
|
MCP 프로토콜 TeamDeleteTool EnterPlanModeTool
|
||||||
|
══════════════ TaskCreateTool ExitPlanModeTool
|
||||||
|
MCPTool TaskGetTool EnterWorktreeTool
|
||||||
|
ListMcpResourcesTool TaskUpdateTool ExitWorktreeTool
|
||||||
|
ReadMcpResourceTool TaskListTool TodoWriteTool
|
||||||
|
TaskStopTool
|
||||||
|
TaskOutputTool 시스템
|
||||||
|
════════
|
||||||
|
스킬 및 확장 ConfigTool
|
||||||
|
═════════════════════ SkillTool
|
||||||
|
SkillTool ScheduleCronTool
|
||||||
|
LSPTool SleepTool
|
||||||
|
TungstenTool
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 권한 시스템
|
||||||
|
|
||||||
|
```text
|
||||||
|
도구 호출 요청
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ validateInput() ──────────────────────────────────┐
|
||||||
|
│ 권한 검사 전 유효하지 않은 입력 조기 거부 │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ PreToolUse Hooks (도구 사용 전 훅) ───────────────┐
|
||||||
|
│ 사용자 정의 쉘 명령 (settings.json hooks) │
|
||||||
|
│ 가능 작업: 승인, 거부 또는 입력 수정 │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ Permission Rules (권한 규칙) ─────────────────────┐
|
||||||
|
│ alwaysAllowRules: 도구 이름/패턴 일치 → 자동 승인│
|
||||||
|
│ alwaysDenyRules: 도구 이름/패턴 일치 → 자동 거부│
|
||||||
|
│ alwaysAskRules: 도구 이름/패턴 일치 → 항상 확인│
|
||||||
|
│ 출처: 설정, CLI 인수, 세션 내 결정 │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
일치하는 규칙 없음?
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ Interactive Prompt (대화형 프롬프트) ─────────────┐
|
||||||
|
│ 사용자가 도구 이름 + 입력값 확인 │
|
||||||
|
│ 옵션: 한 번 허용 / 항상 허용 / 거부 │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─ checkPermissions() ───────────────────────────────┐
|
||||||
|
│ 도구별 특수 로직 (예: 경로 샌드박스 검사) │
|
||||||
|
└────────────────────┬───────────────────────────────┘
|
||||||
|
│
|
||||||
|
승인됨 → tool.call()
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 서브 에이전트 및 다중 에이전트 아키텍처
|
||||||
|
|
||||||
|
```text
|
||||||
|
메인 에이전트
|
||||||
|
==========
|
||||||
|
│
|
||||||
|
┌───────────────┼───────────────┐
|
||||||
|
▼ ▼ ▼
|
||||||
|
┌──────────────┐ ┌──────────┐ ┌──────────────┐
|
||||||
|
│ 포크 에이전트│ │ 원격 에이전트│ │ 프로세스 내 동료│
|
||||||
|
│ (FORK) │ │ (REMOTE) │ │ (IN-PROCESS) │
|
||||||
|
│ 프로세스 포크│ │ 브릿지 세션│ │ 동일 프로세스 │
|
||||||
|
│ 캐시 공유 │ │ 완전 격리 │ │ 비동기 컨텍스트│
|
||||||
|
│ 새 msgs[] │ │ │ │ 상태 공유 │
|
||||||
|
└──────────────┘ └──────────┘ └──────────────┘
|
||||||
|
|
||||||
|
생성 모드 (SPAWN MODES):
|
||||||
|
├─ default → 프로세스 내, 대화 공유
|
||||||
|
├─ fork → 자식 프로세스, 새로운 messages[], 파일 캐시 공유
|
||||||
|
├─ worktree → 격리된 git worktree + fork
|
||||||
|
└─ remote → Claude Code Remote / 컨테이너로의 브릿지 연결
|
||||||
|
|
||||||
|
통신 메커니즘 (COMMUNICATION):
|
||||||
|
├─ SendMessageTool → 에이전트 간 메시지 전달
|
||||||
|
├─ TaskCreate/Update → 공유 작업 보드(task board)
|
||||||
|
└─ TeamCreate/Delete → 팀 수명주기 관리
|
||||||
|
|
||||||
|
스웜 모드 (SWARM MODE, 기능 플래그로 제어됨):
|
||||||
|
┌─────────────────────────────────────────────┐
|
||||||
|
│ 리더 에이전트 (Lead Agent) │
|
||||||
|
│ ├── 동료 A ──> 작업 1 할당 │
|
||||||
|
│ ├── 동료 B ──> 작업 2 할당 │
|
||||||
|
│ └── 동료 C ──> 작업 3 할당 │
|
||||||
|
│ │
|
||||||
|
│ 공유: 작업 보드, 메시지 수신함 │
|
||||||
|
│ 격리: messages[], 파일 캐시, cwd │
|
||||||
|
└─────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 컨텍스트 관리 (압축 시스템)
|
||||||
|
|
||||||
|
```text
|
||||||
|
컨텍스트 창 예산 (CONTEXT WINDOW BUDGET)
|
||||||
|
══════════════════════════════════════
|
||||||
|
|
||||||
|
┌─────────────────────────────────────────────────────┐
|
||||||
|
│ 시스템 프롬프트 (도구, 권한, CLAUDE.md) │
|
||||||
|
│ ══════════════════════════════════════════════ │
|
||||||
|
│ │
|
||||||
|
│ 대화 기록 (Conversation History) │
|
||||||
|
│ ┌─────────────────────────────────────────────┐ │
|
||||||
|
│ │ [이전 메시지들의 압축된 요약] │ │
|
||||||
|
│ │ ═══════════════════════════════════════════ │ │
|
||||||
|
│ │ [compact_boundary 마커] │ │
|
||||||
|
│ │ ─────────────────────────────────────────── │ │
|
||||||
|
│ │ [최근 메시지 — 원본 그대로 유지] │ │
|
||||||
|
│ │ user → assistant → tool_use → tool_result │ │
|
||||||
|
│ └─────────────────────────────────────────────┘ │
|
||||||
|
│ │
|
||||||
|
│ 현재 턴 (사용자 + 어시스턴트 응답) │
|
||||||
|
└─────────────────────────────────────────────────────┘
|
||||||
|
|
||||||
|
3가지 압축 전략:
|
||||||
|
├─ autoCompact → 토큰 수가 임계값을 초과할 때 트리거됨
|
||||||
|
│ 압축 API 호출을 통해 이전 메시지 요약
|
||||||
|
├─ snipCompact → 불필요한 메시지와 오래된 마커 제거
|
||||||
|
│ (HISTORY_SNIP 기능 플래그)
|
||||||
|
└─ contextCollapse → 효율성을 위해 컨텍스트 재구성
|
||||||
|
(CONTEXT_COLLAPSE 기능 플래그)
|
||||||
|
|
||||||
|
압축 흐름 (COMPACTION FLOW):
|
||||||
|
messages[] ──> getMessagesAfterCompactBoundary()
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
이전 메시지 ──> Claude API (요약) ──> 압축된 요약
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
[요약] + [compact_boundary] + [최근 메시지]
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## MCP (Model Context Protocol) 통합
|
||||||
|
|
||||||
|
```text
|
||||||
|
┌─────────────────────────────────────────────────────────┐
|
||||||
|
│ MCP 아키텍처 │
|
||||||
|
│ │
|
||||||
|
│ MCPConnectionManager.tsx │
|
||||||
|
│ ├── 서버 검색 (settings.json 구성 기반) │
|
||||||
|
│ │ ├── stdio → 자식 프로세스 생성 │
|
||||||
|
│ │ ├── sse → HTTP EventSource │
|
||||||
|
│ │ ├── http → 스트리밍 HTTP │
|
||||||
|
│ │ ├── ws → WebSocket │
|
||||||
|
│ │ └── sdk → 프로세스 내 전송 │
|
||||||
|
│ │ │
|
||||||
|
│ ├── 클라이언트 수명주기 │
|
||||||
|
│ │ ├── connect → initialize → list tools │
|
||||||
|
│ │ ├── MCPTool 래퍼를 통한 도구 호출 │
|
||||||
|
│ │ └── 백오프(backoff)가 포함된 연결 해제 / 재연결│
|
||||||
|
│ │ │
|
||||||
|
│ ├── 인증 (Authentication) │
|
||||||
|
│ │ ├── OAuth 2.0 흐름 (McpOAuthConfig) │
|
||||||
|
│ │ ├── 교차 앱 액세스 (XAA / SEP-990) │
|
||||||
|
│ │ └── 헤더를 통한 API 키 전달 │
|
||||||
|
│ │ │
|
||||||
|
│ └── 도구 등록 (Tool Registration) │
|
||||||
|
│ ├── mcp__<server>__<tool> 명명 규칙 │
|
||||||
|
│ ├── MCP 서버로부터 동적 스키마(schema) 수신 │
|
||||||
|
│ ├── Claude Code로 권한 통과(passthrough) │
|
||||||
|
│ └── 리소스 목록화 (ListMcpResourcesTool) │
|
||||||
|
│ │
|
||||||
|
└─────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 브릿지 레이어 (Claude Desktop / Remote)
|
||||||
|
|
||||||
|
```text
|
||||||
|
Claude Desktop / Web / Cowork Claude Code CLI
|
||||||
|
══════════════════════════ ═════════════════
|
||||||
|
|
||||||
|
┌───────────────────┐ ┌──────────────────┐
|
||||||
|
│ 브릿지 클라이언트│ ←─ HTTP ──→ │ bridgeMain.ts │
|
||||||
|
│ (Desktop App) │ │ │
|
||||||
|
└───────────────────┘ │ 세션 관리자 │
|
||||||
|
│ ├── CLI 스폰 │
|
||||||
|
프로토콜 (PROTOCOL): │ ├── 상태 폴링 │
|
||||||
|
├─ JWT 인증 │ ├── 메시지 릴레이│
|
||||||
|
├─ Work secret 교환 │ └── 용량 웨이크 │
|
||||||
|
├─ 세션 수명주기 │ │
|
||||||
|
│ ├── create │ 백오프(Backoff):│
|
||||||
|
│ ├── run │ ├─ 연결: 2s→2m │
|
||||||
|
│ └─ stop │ └─ 생성: 500ms→30s│
|
||||||
|
└─ 토큰 새로고침 스케줄러 └──────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 세션 영속성 (Session Persistence)
|
||||||
|
|
||||||
|
```text
|
||||||
|
세션 스토리지 (SESSION STORAGE)
|
||||||
|
═════════════════════════════
|
||||||
|
|
||||||
|
~/.claude/projects/<hash>/sessions/
|
||||||
|
└── <session-id>.jsonl ← 추가 전용(append-only) 로그
|
||||||
|
├── {"type":"user",...}
|
||||||
|
├── {"type":"assistant",...}
|
||||||
|
├── {"type":"progress",...}
|
||||||
|
└── {"type":"system","subtype":"compact_boundary",...}
|
||||||
|
|
||||||
|
복구 흐름 (RESUME FLOW):
|
||||||
|
getLastSessionLog() ──> JSONL 파싱 ──> messages[] 재구성
|
||||||
|
│
|
||||||
|
├── --continue → 현재 작업 디렉터리의 마지막 세션
|
||||||
|
├── --resume <id> → 특정 세션
|
||||||
|
└── --fork-session → 새 ID, 기록 복사
|
||||||
|
|
||||||
|
영속성 전략 (PERSISTENCE STRATEGY):
|
||||||
|
├─ 사용자 메시지 → 쓰기 대기 (충돌 복구를 위한 블로킹)
|
||||||
|
├─ 어시스턴트 메시지 → 비동기 전송 (순서가 유지되는 큐)
|
||||||
|
├─ 진행 상태 → 인라인 쓰기 (다음 쿼리 시 중복 제거)
|
||||||
|
└─ 플러시(Flush) → 결과 반환 시 / cowork 즉시 플러시
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 기능 플래그 시스템 (Feature Flag System)
|
||||||
|
|
||||||
|
```text
|
||||||
|
데드 코드 제거 (Bun 컴파일 시점)
|
||||||
|
══════════════════════════════
|
||||||
|
|
||||||
|
feature('FLAG_NAME') ──→ true → 번들에 포함됨
|
||||||
|
──→ false → 번들에서 제거됨
|
||||||
|
|
||||||
|
플래그 목록 (소스에서 관찰됨):
|
||||||
|
├─ COORDINATOR_MODE → 다중 에이전트 코디네이터
|
||||||
|
├─ HISTORY_SNIP → 공격적인 기록 다듬기
|
||||||
|
├─ CONTEXT_COLLAPSE → 컨텍스트 재구성
|
||||||
|
├─ DAEMON → 백그라운드 데몬 워커
|
||||||
|
├─ AGENT_TRIGGERS → 크론(cron)/원격 트리거
|
||||||
|
├─ AGENT_TRIGGERS_REMOTE → 원격 트리거 지원
|
||||||
|
├─ MONITOR_TOOL → MCP 모니터링 도구
|
||||||
|
├─ WEB_BROWSER_TOOL → 브라우저 자동화
|
||||||
|
├─ VOICE_MODE → 음성 입력/출력
|
||||||
|
├─ TEMPLATES → 작업 분류기
|
||||||
|
├─ EXPERIMENTAL_SKILL_SEARCH → 스킬 탐색
|
||||||
|
├─ KAIROS → 푸시 알림, 파일 전송
|
||||||
|
├─ PROACTIVE → 수면 도구, 선제적 행동
|
||||||
|
├─ OVERFLOW_TEST_TOOL → 테스트 도구
|
||||||
|
├─ TERMINAL_PANEL → 터미널 캡처
|
||||||
|
├─ WORKFLOW_SCRIPTS → 워크플로우 도구
|
||||||
|
├─ CHICAGO_MCP → 컴퓨터 사용 MCP
|
||||||
|
├─ DUMP_SYSTEM_PROMPT → 프롬프트 추출 (내부 전용)
|
||||||
|
├─ UDS_INBOX → 피어 탐색
|
||||||
|
├─ ABLATION_BASELINE → 실험 제거(ablation)
|
||||||
|
└─ UPGRADE_NOTICE → 업그레이드 알림
|
||||||
|
|
||||||
|
런타임 게이트 (RUNTIME GATES):
|
||||||
|
├─ process.env.USER_TYPE === 'ant' → 내부 기능
|
||||||
|
└─ GrowthBook feature flags → 런타임 A/B 실험
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 상태 관리 (State Management)
|
||||||
|
|
||||||
|
```text
|
||||||
|
┌──────────────────────────────────────────────────────────┐
|
||||||
|
│ AppState Store │
|
||||||
|
│ │
|
||||||
|
│ AppState { │
|
||||||
|
│ toolPermissionContext: { │
|
||||||
|
│ mode: PermissionMode, ← default/plan 등 │
|
||||||
|
│ additionalWorkingDirectories, │
|
||||||
|
│ alwaysAllowRules, ← 자동 승인 │
|
||||||
|
│ alwaysDenyRules, ← 자동 거부 │
|
||||||
|
│ alwaysAskRules, ← 항상 확인 │
|
||||||
|
│ isBypassPermissionsModeAvailable │
|
||||||
|
│ }, │
|
||||||
|
│ fileHistory: FileHistoryState, ← 실행 취소 스냅샷 │
|
||||||
|
│ attribution: AttributionState, ← 커밋 추적 │
|
||||||
|
│ verbose: boolean, │
|
||||||
|
│ mainLoopModel: string, ← 활성 모델 │
|
||||||
|
│ fastMode: FastModeState, │
|
||||||
|
│ speculation: SpeculationState │
|
||||||
|
│ } │
|
||||||
|
│ │
|
||||||
|
│ React 통합: │
|
||||||
|
│ ├── AppStateProvider → createContext를 통해 스토어 생성│
|
||||||
|
│ ├── useAppState(sel) → 선택자(selector) 기반 구독 │
|
||||||
|
│ └── useSetAppState() → immer 스타일 업데이트 함수 │
|
||||||
|
└──────────────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 12가지 점진적 안전 장치 (The 12 Progressive Harness Mechanisms)
|
||||||
|
|
||||||
|
이 아키텍처는 기본 루프 외에 프로덕션 AI 에이전트 하니스에 필요한 12계층의 점진적 메커니즘을 보여줍니다. 각 메커니즘은 이전 메커니즘을 기반으로 구축됩니다:
|
||||||
|
|
||||||
|
```text
|
||||||
|
s01 핵심 루프 (THE LOOP) "하나의 루프와 Bash면 충분하다"
|
||||||
|
query.ts: Claude API를 호출하는 while-true 루프,
|
||||||
|
stop_reason을 확인하고, 도구를 실행하며 결과를 추가합니다.
|
||||||
|
|
||||||
|
s02 도구 디스패치 (TOOL DISPATCH) "도구 추가 = 핸들러 하나 추가"
|
||||||
|
Tool.ts + tools.ts: 모든 도구가 디스패치 맵에 등록됩니다.
|
||||||
|
루프는 동일하게 유지됩니다. buildTool() 팩토리가 안전한 기본값을 제공합니다.
|
||||||
|
|
||||||
|
s03 계획 (PLANNING) "계획 없는 에이전트는 표류한다"
|
||||||
|
EnterPlanModeTool/ExitPlanModeTool + TodoWriteTool:
|
||||||
|
단계를 먼저 나열한 다음 실행합니다. 완료율을 두 배로 높입니다.
|
||||||
|
|
||||||
|
s04 서브 에이전트 (SUB-AGENTS) "큰 작업을 나누고 하위 작업마다 컨텍스트를 정리한다"
|
||||||
|
AgentTool + forkSubagent.ts: 각 하위 에이전트는 새로운 messages[]를 가져,
|
||||||
|
메인 대화를 깨끗하게 유지합니다.
|
||||||
|
|
||||||
|
s05 온디맨드 지식 (KNOWLEDGE) "필요할 때 지식을 로드한다"
|
||||||
|
SkillTool + memdir/: 시스템 프롬프트가 아닌 tool_result를 통해 주입합니다.
|
||||||
|
디렉터리별로 CLAUDE.md 파일을 지연 로드(lazy load)합니다.
|
||||||
|
|
||||||
|
s06 컨텍스트 압축 (COMPRESSION) "컨텍스트가 꽉 차면 공간을 확보한다"
|
||||||
|
services/compact/: 3계층 전략:
|
||||||
|
autoCompact (요약) + snipCompact (자르기) + contextCollapse
|
||||||
|
|
||||||
|
s07 영구 작업 (TASKS) "큰 목표 → 작은 작업 → 디스크"
|
||||||
|
TaskCreate/Update/Get/List: 파일 기반의 작업 그래프(Task graph)로,
|
||||||
|
상태 추적, 종속성 및 영속성을 갖습니다.
|
||||||
|
|
||||||
|
s08 백그라운드 작업 (BACKGROUND) "백그라운드에서 느린 작업 실행; 에이전트는 계속 생각한다"
|
||||||
|
DreamTask + LocalShellTask: 데몬 스레드가 명령을 실행하고,
|
||||||
|
완료 시 알림을 주입합니다.
|
||||||
|
|
||||||
|
s09 에이전트 팀 (TEAMS) "혼자 하기엔 너무 크다 → 동료에게 위임한다"
|
||||||
|
TeamCreate/Delete + InProcessTeammateTask:
|
||||||
|
비동기 메일박스를 가진 영구적인 동료 에이전트들.
|
||||||
|
|
||||||
|
s10 팀 프로토콜 (PROTOCOLS) "공유된 통신 규칙"
|
||||||
|
SendMessageTool: 하나의 요청-응답 패턴이
|
||||||
|
에이전트 간의 모든 협상을 주도합니다.
|
||||||
|
|
||||||
|
s11 자율 에이전트 (AUTONOMOUS) "동료들이 스스로 작업을 스캔하고 청구한다"
|
||||||
|
coordinator/coordinatorMode.ts: 유휴 루프(Idle cycle) + 자동 할당,
|
||||||
|
리더가 모든 작업을 일일이 할당할 필요가 없습니다.
|
||||||
|
|
||||||
|
s12 작업 트리 격리 (WORKTREE) "각자 자신의 디렉터리에서 작업한다"
|
||||||
|
EnterWorktreeTool/ExitWorktreeTool: 작업은 목표를 관리하고,
|
||||||
|
작업 트리는 디렉터리를 관리하며, ID로 연결됩니다.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 핵심 디자인 패턴 (Key Design Patterns)
|
||||||
|
|
||||||
|
| 패턴 | 위치 | 목적 |
|
||||||
|
|---------|-------|---------|
|
||||||
|
| **AsyncGenerator 스트리밍** | `QueryEngine`, `query()` | API에서 소비자로 이어지는 전체 체인 스트리밍 |
|
||||||
|
| **빌더 + 팩토리 (Builder + Factory)** | `buildTool()` | 도구 정의를 위한 안전한 기본값 제공 |
|
||||||
|
| **브랜드 타입 (Branded Types)** | `SystemPrompt`, `asSystemPrompt()` | 문자열/배열 혼동 방지 |
|
||||||
|
| **기능 플래그 + DCE** | `bun:bundle`의 `feature()` | 컴파일 시점 데드 코드 제거(DCE) |
|
||||||
|
| **구별된 유니온 (Discriminated Unions)** | `Message` 타입 | 타입 안전성이 보장되는 메시지 처리 |
|
||||||
|
| **옵저버 + 상태 머신** | `StreamingToolExecutor` | 도구 실행 수명주기 추적 |
|
||||||
|
| **스냅샷 상태 (Snapshot State)** | `FileHistoryState` | 파일 작업의 실행 취소/다시 실행 |
|
||||||
|
| **링 버퍼 (Ring Buffer)** | 에러 로그 | 긴 세션을 위한 제한된 메모리 사용 |
|
||||||
|
| **발사 후 망각 (Fire-and-Forget)** | `recordTranscript()` | 순서가 유지되는 논블로킹 영속화 |
|
||||||
|
| **지연 스키마 (Lazy Schema)** | `lazySchema()` | 성능 향상을 위한 Zod 스키마 지연 평가 |
|
||||||
|
| **컨텍스트 격리 (Context Isolation)** | `AsyncLocalStorage` | 공유 프로세스 내 각 에이전트별 컨텍스트 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 데이터 흐름: 단일 쿼리 수명주기
|
||||||
|
|
||||||
|
```text
|
||||||
|
사용자 입력 (프롬프트 / 슬래시 명령)
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
processUserInput() ← /명령어 파싱, UserMessage 생성
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
fetchSystemPromptParts() ← 도구 → 프롬프트 섹션, CLAUDE.md 메모리
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
recordTranscript() ← 사용자 메시지를 디스크에 영속화 (JSONL)
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─→ normalizeMessagesForAPI() ← UI 전용 필드 제거, 필요시 압축 수행
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ Claude API (스트리밍) ← 도구 + 시스템 프롬프트와 함께 POST /v1/messages
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ 스트림 이벤트 ← message_start → content_block_delta → message_stop
|
||||||
|
│ │
|
||||||
|
│ ├─ 텍스트 블록 ──────────────→ 소비자(SDK / REPL)에게 전달
|
||||||
|
│ │
|
||||||
|
│ └─ tool_use 블록?
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ StreamingToolExecutor ← 분할: 동시성 안전(concurrent-safe) vs 직렬(serial)
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ canUseTool() ← 권한 검사 (훅 + 규칙 + UI 프롬프트)
|
||||||
|
│ │
|
||||||
|
│ ├─ 거부 ────────────────→ tool_result(error) 추가, 루프 계속
|
||||||
|
│ │
|
||||||
|
│ └─ 허용
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ tool.call() ← 도구 실행 (Bash, Read, Edit 등)
|
||||||
|
│ │
|
||||||
|
│ ▼
|
||||||
|
│ tool_result 추가 ← messages[]에 푸시, recordTranscript()
|
||||||
|
│ │
|
||||||
|
└─────────┘ ← API 호출로 루프 복귀
|
||||||
|
│
|
||||||
|
▼ (stop_reason != "tool_use")
|
||||||
|
결과 메시지 생성 ← 최종 텍스트, 사용량, 비용, session_id
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 목차
|
||||||
|
|
||||||
|
- [심층 분석 보고서 (`docs/`)](#심층-분석-보고서-docs) — 텔레메트리, 코드네임, 언더커버 모드, 원격 제어, 향후 로드맵
|
||||||
|
- [디렉터리 참조](#디렉터리-참조) — 코드 구조 트리
|
||||||
|
- [아키텍처 개요](#아키텍처-개요) — 진입점 → 쿼리 엔진 → 도구/서비스/상태
|
||||||
|
- [도구 시스템 및 권한 아키텍처](#도구-시스템-및-권한-아키텍처) — 40+ 도구, 권한 흐름, 서브 에이전트
|
||||||
|
- [12가지 점진적 안전 장치](#12가지-점진적-안전-장치-the-12-progressive-harness-mechanisms) — Claude Code가 에이전트 루프에 프로덕션 기능을 구현하는 방법
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 심층 분석 보고서 (`docs/`)
|
||||||
|
|
||||||
|
인터넷에 공개된 자료와 커뮤니티 토론을 바탕으로 정리된 Claude Code v2.1.88 분석 보고서. 영어/중국어/한국어/일본어 4개 국어 제공.
|
||||||
|
|
||||||
|
```
|
||||||
|
docs/
|
||||||
|
├── en/ # English
|
||||||
|
│ ├── [01-telemetry-and-privacy.md] # Telemetry & Privacy — what's collected, why you can't opt out
|
||||||
|
│ ├── [02-hidden-features-and-codenames.md] # Codenames (Capybara/Tengu/Numbat), feature flags, internal vs external
|
||||||
|
│ ├── [03-undercover-mode.md] # Undercover Mode — hiding AI authorship in open-source repos
|
||||||
|
│ ├── [04-remote-control-and-killswitches.md]# Remote Control — managed settings, killswitches, model overrides
|
||||||
|
│ └── [05-future-roadmap.md] # Future Roadmap — Numbat, KAIROS, voice mode, unreleased tools
|
||||||
|
│
|
||||||
|
├── ko/ # 한국어
|
||||||
|
│ ├── [01-텔레메트리와-프라이버시.md] # 텔레메트리 및 프라이버시 — 수집 항목, 비활성화 불가 이유
|
||||||
|
│ ├── [02-숨겨진-기능과-코드네임.md] # 숨겨진 기능 — 모델 코드네임, feature flag, 내부/외부 사용자 차이
|
||||||
|
│ ├── [03-언더커버-모드.md] # 언더커버 모드 — 오픈소스에서 AI 저작 은폐
|
||||||
|
│ ├── [04-원격-제어와-킬스위치.md] # 원격 제어 — 관리 설정, 킬스위치, 모델 오버라이드
|
||||||
|
│ └── [05-향후-로드맵.md] # 향후 로드맵 — Numbat, KAIROS, 음성 모드, 미공개 도구
|
||||||
|
│
|
||||||
|
└── zh/ # 中文
|
||||||
|
├── [01-遥测与隐私分析.md] # 遥测与隐私 — 收集了什么，为什么无法退出
|
||||||
|
├── [02-隐藏功能与模型代号.md] # 隐藏功能 — 模型代号，feature flag，内外用户差异
|
||||||
|
├── [03-卧底模式分析.md] # 卧底模式 — 在开源项目中隐藏 AI 身份
|
||||||
|
├── [04-远程控制与紧急开关.md] # 远程控制 — 托管设置，紧急开关，模型覆盖
|
||||||
|
└── [05-未来路线图.md] # 未来路线图 — Numbat，KAIROS，语音模式，未上线工具
|
||||||
|
```
|
||||||
|
|
||||||
|
> 파일명을 클릭하면 해당 보고서로 이동합니다.
|
||||||
|
|
||||||
|
| # | 주제 | 핵심 발견 | 링크 |
|
||||||
|
|---|------|----------|------|
|
||||||
|
| 01 | **텔레메트리 및 프라이버시** | 이중 분석 파이프라인 (1P, Datadog). 환경 핑거프린트, 프로세스 메트릭, 모든 이벤트에 세션/사용자 ID 포함. **사용자 대상 비활성화 설정 없음.** `OTEL_LOG_TOOL_DETAILS=1`로 전체 도구 입력 기록 가능. | [EN](docs/en/01-telemetry-and-privacy.md) · [한국어](docs/ko/01-텔레메트리와-프라이버시.md) · [中文](docs/zh/01-遥测与隐私分析.md) |
|
||||||
|
| 02 | **숨겨진 기능과 코드네임** | 동물 코드네임 체계 (Capybara v8, Tengu, Fennec→Opus 4.6, **Numbat** 차기). Feature flag에 무작위 단어 조합으로 목적 난독화. 내부 사용자는 더 나은 프롬프트와 검증 에이전트 제공. 숨겨진 명령어: `/btw`, `/stickers`. | [EN](docs/en/02-hidden-features-and-codenames.md) · [한국어](docs/ko/02-숨겨진-기능과-코드네임.md) · [中文](docs/zh/02-隐藏功能与模型代号.md) |
|
||||||
|
| 03 | **언더커버 모드** | 공식 직원은 공개 저장소에서 자동으로 언더커버 모드 진입. 모델 지시: **"정체를 들키지 마라"** — 모든 AI 저작 표시를 제거하고, 사람이 작성한 것처럼 커밋. **강제 비활성화 옵션 없음.** | [EN](docs/en/03-undercover-mode.md) · [한국어](docs/ko/03-언더커버-모드.md) · [中文](docs/zh/03-卧底模式分析.md) |
|
||||||
|
| 04 | **원격 제어 및 킬스위치** | 1시간마다 `/api/claude_code/settings` 폴링. 위험 변경 시 차단 다이얼로그 — **거부 = 앱 종료**. 6개 이상 킬스위치 (권한 우회, fast 모드, 음성 모드, 분석 싱크). GrowthBook으로 동의 없이 사용자 동작 변경 가능. | [EN](docs/en/04-remote-control-and-killswitches.md) · [한국어](docs/ko/04-원격-제어와-킬스위치.md) · [中文](docs/zh/04-远程控制与紧急开关.md) |
|
||||||
|
| 05 | **향후 로드맵** | **Numbat** 코드네임 확인. Opus 4.7 / Sonnet 4.8 개발 중. **KAIROS** = 완전 자율 에이전트 모드, `<tick>` 하트비트, 푸시 알림, PR 구독. 음성 모드(push-to-talk) 준비 완료. 미공개 도구 17개 발견. | [EN](docs/en/05-future-roadmap.md) · [한국어](docs/ko/05-향후-로드맵.md) · [中文](docs/zh/05-未来路线图.md) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 저작권 및 면책 조항
|
||||||
|
|
||||||
|
```text
|
||||||
|
본 저장소는 기술 연구 및 교육 목적으로만 제공됩니다. 상업적 사용은 금지됩니다.
|
||||||
|
|
||||||
|
저작권자로서 본 저장소 콘텐츠가 귀하의 권리를 침해한다고 판단되는 경우,
|
||||||
|
저장소 소유자에게 연락 주시면 즉시 삭제하겠습니다.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 통계
|
||||||
|
|
||||||
|
| 항목 | 수량 |
|
||||||
|
|------|------|
|
||||||
|
| 파일 (.ts/.tsx) | ~1,884 |
|
||||||
|
| 라인 수 | ~512,664 |
|
||||||
|
| 최대 단일 파일 | `query.ts` (~785KB) |
|
||||||
|
| 내장 도구 | ~40개 이상 |
|
||||||
|
| 슬래시 명령 | ~80개 이상 |
|
||||||
|
| 의존성 (node_modules) | ~192개 패키지 |
|
||||||
|
| 런타임 | Bun (Node.js >= 18 번들로 컴파일) |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 에이전트 모드
|
||||||
|
|
||||||
|
```
|
||||||
|
코어 루프
|
||||||
|
========
|
||||||
|
|
||||||
|
사용자 --> messages[] --> Claude API --> 응답
|
||||||
|
|
|
||||||
|
stop_reason == "tool_use"?
|
||||||
|
/ \
|
||||||
|
예 아니오
|
||||||
|
| |
|
||||||
|
도구 실행 텍스트 반환
|
||||||
|
tool_result 추가
|
||||||
|
루프 재진입 -----------------> messages[]
|
||||||
|
|
||||||
|
|
||||||
|
이것이 최소 에이전트 루프이다. Claude Code는 이 루프 위에
|
||||||
|
프로덕션급 하니스를 래핑한다: 권한, 스트리밍, 동시성,
|
||||||
|
압축, 서브에이전트, 영속화 및 MCP.
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 디렉터리 참조
|
||||||
|
|
||||||
|
```
|
||||||
|
src/
|
||||||
|
├── main.tsx # REPL 부트스트랩, 4,683줄
|
||||||
|
├── QueryEngine.ts # SDK/headless 쿼리 라이프사이클 엔진
|
||||||
|
├── query.ts # 메인 에이전트 루프 (785KB, 최대 파일)
|
||||||
|
├── Tool.ts # 도구 인터페이스 + buildTool 팩토리
|
||||||
|
├── Task.ts # 태스크 타입, ID, 상태 베이스 클래스
|
||||||
|
├── tools.ts # 도구 등록, 프리셋, 필터링
|
||||||
|
├── commands.ts # 슬래시 명령 정의
|
||||||
|
├── context.ts # 사용자 입력 컨텍스트
|
||||||
|
├── cost-tracker.ts # API 비용 누적
|
||||||
|
├── setup.ts # 최초 실행 설정 플로우
|
||||||
|
│
|
||||||
|
├── bridge/ # Claude Desktop / 원격 브릿지
|
||||||
|
│ ├── bridgeMain.ts # 세션 라이프사이클 매니저
|
||||||
|
│ ├── bridgeApi.ts # HTTP 클라이언트
|
||||||
|
│ ├── bridgeConfig.ts # 연결 설정
|
||||||
|
│ ├── bridgeMessaging.ts # 메시지 릴레이
|
||||||
|
│ ├── sessionRunner.ts # 프로세스 스폰
|
||||||
|
│ ├── jwtUtils.ts # JWT 갱신
|
||||||
|
│ ├── workSecret.ts # 인증 토큰
|
||||||
|
│ └── capacityWake.ts # 용량 기반 웨이크
|
||||||
|
│
|
||||||
|
├── cli/ # CLI 인프라
|
||||||
|
│ ├── handlers/ # 명령 핸들러
|
||||||
|
│ └── transports/ # I/O 전송 (stdio, structured)
|
||||||
|
│
|
||||||
|
├── commands/ # ~80개 슬래시 명령
|
||||||
|
├── components/ # React/Ink 터미널 UI
|
||||||
|
├── entrypoints/ # 앱 진입점
|
||||||
|
├── hooks/ # React hooks
|
||||||
|
├── services/ # 비즈니스 로직 레이어
|
||||||
|
├── state/ # 앱 상태
|
||||||
|
├── tasks/ # 태스크 구현
|
||||||
|
├── tools/ # 40개 이상 도구 구현
|
||||||
|
├── types/ # 타입 정의
|
||||||
|
├── utils/ # 유틸리티 (최대 디렉터리)
|
||||||
|
└── vendor/ # 네이티브 모듈 스텁
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 아키텍처 개요
|
||||||
|
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 진입 레이어 │
|
||||||
|
│ cli.tsx ──> main.tsx ──> REPL.tsx (인터랙티브) │
|
||||||
|
│ └──> QueryEngine.ts (headless/SDK) │
|
||||||
|
└──────────────────────────────┬──────────────────────────────────────┘
|
||||||
|
│
|
||||||
|
▼
|
||||||
|
┌─────────────────────────────────────────────────────────────────────┐
|
||||||
|
│ 쿼리 엔진 │
|
||||||
|
│ submitMessage(prompt) ──> AsyncGenerator<SDKMessage> │
|
||||||
|
│ ├── fetchSystemPromptParts() ──> 시스템 프롬프트 조립 │
|
||||||
|
│ ├── processUserInput() ──> /명령 처리 │
|
||||||
|
│ ├── query() ──> 메인 에이전트 루프 │
|
||||||
|
│ │ ├── StreamingToolExecutor ──> 병렬 도구 실행 │
|
||||||
|
│ │ ├── autoCompact() ──> 컨텍스트 압축 │
|
||||||
|
│ │ └── runTools() ──> 도구 오케스트레이션 │
|
||||||
|
│ └── yield SDKMessage ──> 소비자에게 스트리밍 │
|
||||||
|
└──────────────────────────────┬──────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 라이선스
|
||||||
|
|
||||||
|
본 저장소 콘텐츠는 기술 연구 및 교육 목적으로만 제공됩니다. 지적 재산권은 원 회사에 귀속됩니다. 권리 침해가 있는 경우 삭제를 위해 연락 주시기 바랍니다.
|
||||||
124
docs/en/01-telemetry-and-privacy.md
Normal file
124
docs/en/01-telemetry-and-privacy.md
Normal file
@@ -0,0 +1,124 @@
|
|||||||
|
# Telemetry & Privacy Analysis
|
||||||
|
|
||||||
|
> Based on publicly available online references and community discussions on Claude Code v2.1.88.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Claude Code implements a two-tier analytics pipeline that collects extensive environment and usage metadata. While there is no evidence of keylogging or user code exfiltration, the breadth of collection and inability to fully opt out raises legitimate privacy concerns.
|
||||||
|
|
||||||
|
## Data Pipeline Architecture
|
||||||
|
|
||||||
|
### First-Party Logging (1P)
|
||||||
|
|
||||||
|
- **Endpoint**: `https://api.anthropic.com/api/event_logging/batch`
|
||||||
|
- **Protocol**: OpenTelemetry with Protocol Buffers
|
||||||
|
- **Batch size**: Up to 200 events per batch, flushed every 10 seconds
|
||||||
|
- **Retry**: Quadratic backoff, up to 8 attempts, disk-persisted for durability
|
||||||
|
- **Storage**: Failed events saved to `~/.claude/telemetry/`
|
||||||
|
|
||||||
|
Source: `src/services/analytics/firstPartyEventLoggingExporter.ts`
|
||||||
|
|
||||||
|
### Third-Party Logging (Datadog)
|
||||||
|
|
||||||
|
- **Endpoint**: `https://http-intake.logs.us5.datadoghq.com/api/v2/logs`
|
||||||
|
- **Scope**: Limited to 64 pre-approved event types
|
||||||
|
- **Token**: `pubbbf48e6d78dae54bceaa4acf463299bf`
|
||||||
|
|
||||||
|
Source: `src/services/analytics/datadog.ts`
|
||||||
|
|
||||||
|
## What Is Collected
|
||||||
|
|
||||||
|
### Environment Fingerprint
|
||||||
|
|
||||||
|
Every event carries this metadata (`src/services/analytics/metadata.ts:417-452`):
|
||||||
|
|
||||||
|
```
|
||||||
|
- platform, platformRaw, arch, nodeVersion
|
||||||
|
- terminal type
|
||||||
|
- installed package managers and runtimes
|
||||||
|
- CI/CD detection, GitHub Actions metadata
|
||||||
|
- WSL version, Linux distro, kernel version
|
||||||
|
- VCS (version control system) type
|
||||||
|
- Claude Code version and build time
|
||||||
|
- deployment environment
|
||||||
|
```
|
||||||
|
|
||||||
|
### Process Metrics (`metadata.ts:457-467`)
|
||||||
|
|
||||||
|
```
|
||||||
|
- uptime, rss, heapTotal, heapUsed
|
||||||
|
- CPU usage and percentage
|
||||||
|
- memory arrays and external allocations
|
||||||
|
```
|
||||||
|
|
||||||
|
### User Tracking (`metadata.ts:472-496`)
|
||||||
|
|
||||||
|
```
|
||||||
|
- model in use
|
||||||
|
- session ID, user ID, device ID
|
||||||
|
- account UUID, organization UUID
|
||||||
|
- subscription tier (max, pro, enterprise, team)
|
||||||
|
- repository remote URL hash (SHA256, first 16 chars)
|
||||||
|
- agent type, team name, parent session ID
|
||||||
|
```
|
||||||
|
|
||||||
|
### Tool Input Logging
|
||||||
|
|
||||||
|
Tool inputs are truncated by default:
|
||||||
|
|
||||||
|
```
|
||||||
|
- Strings: truncated at 512 chars, displayed as 128 + ellipsis
|
||||||
|
- JSON: limited to 4,096 chars
|
||||||
|
- Arrays: max 20 items
|
||||||
|
- Nested objects: max 2 levels deep
|
||||||
|
```
|
||||||
|
|
||||||
|
Source: `metadata.ts:236-241`
|
||||||
|
|
||||||
|
However, when `OTEL_LOG_TOOL_DETAILS=1` is set, **full tool inputs are logged**.
|
||||||
|
|
||||||
|
Source: `metadata.ts:86-88`
|
||||||
|
|
||||||
|
### File Extension Tracking
|
||||||
|
|
||||||
|
Bash commands involving `rm, mv, cp, touch, mkdir, chmod, chown, cat, head, tail, sort, stat, diff, wc, grep, rg, sed` have their file arguments' extensions extracted and logged.
|
||||||
|
|
||||||
|
Source: `metadata.ts:340-412`
|
||||||
|
|
||||||
|
## The Opt-Out Problem
|
||||||
|
|
||||||
|
The first-party logging pipeline **cannot be disabled** for direct Anthropic API users.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/services/analytics/firstPartyEventLogger.ts:141-144
|
||||||
|
export function is1PEventLoggingEnabled(): boolean {
|
||||||
|
return !isAnalyticsDisabled()
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`isAnalyticsDisabled()` returns true only for:
|
||||||
|
- Test environments
|
||||||
|
- Third-party cloud providers (Bedrock, Vertex)
|
||||||
|
- Global telemetry opt-out (not exposed in settings UI)
|
||||||
|
|
||||||
|
There is **no user-facing setting** to disable first-party event logging.
|
||||||
|
|
||||||
|
## GrowthBook A/B Testing
|
||||||
|
|
||||||
|
Users are assigned to experiment groups via GrowthBook without explicit consent. The system sends user attributes including:
|
||||||
|
|
||||||
|
```
|
||||||
|
- id, sessionId, deviceID
|
||||||
|
- platform, organizationUUID, subscriptionType
|
||||||
|
```
|
||||||
|
|
||||||
|
Source: `src/services/analytics/growthbook.ts`
|
||||||
|
|
||||||
|
## Key Takeaways
|
||||||
|
|
||||||
|
1. **Volume**: Hundreds of events per session are collected
|
||||||
|
2. **No opt-out**: First-party logging cannot be disabled by direct API users
|
||||||
|
3. **Persistence**: Failed events are saved to disk and retried aggressively
|
||||||
|
4. **Third-party sharing**: Data flows to Datadog
|
||||||
|
5. **Tool detail backdoor**: `OTEL_LOG_TOOL_DETAILS=1` enables full input logging
|
||||||
|
6. **Repository fingerprinting**: Repo URLs are hashed and sent for server-side correlation
|
||||||
112
docs/en/02-hidden-features-and-codenames.md
Normal file
112
docs/en/02-hidden-features-and-codenames.md
Normal file
@@ -0,0 +1,112 @@
|
|||||||
|
# Hidden Features & Model Codenames
|
||||||
|
|
||||||
|
> Based on publicly available online references and community discussions on Claude Code v2.1.88.
|
||||||
|
|
||||||
|
## Model Codename System
|
||||||
|
|
||||||
|
Anthropic uses **animal names** as internal model codenames. These are aggressively protected from leaking into external builds.
|
||||||
|
|
||||||
|
### Known Codenames
|
||||||
|
|
||||||
|
| Codename | Role | Evidence |
|
||||||
|
|----------|------|----------|
|
||||||
|
| **Tengu** (天狗) | Product/telemetry prefix, possibly a model | Used as `tengu_*` prefix for all 250+ analytics events and feature flags |
|
||||||
|
| **Capybara** | Sonnet-series model, currently at v8 | `capybara-v2-fast[1m]`, prompt patches for v8 behavior issues |
|
||||||
|
| **Fennec** (耳廓狐) | Predecessor to Opus 4.6 | Migration: `fennec-latest` → `opus` |
|
||||||
|
| **Numbat** (袋食蚁兽) | Next model launch | Comment: "Remove this section when we launch numbat" |
|
||||||
|
|
||||||
|
### Codename Protection
|
||||||
|
|
||||||
|
The `undercover` mode explicitly lists protected codenames:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/undercover.ts:48-49
|
||||||
|
NEVER include in commit messages or PR descriptions:
|
||||||
|
- Internal model codenames (animal names like Capybara, Tengu, etc.)
|
||||||
|
- Unreleased model version numbers (e.g., opus-4-7, sonnet-4-8)
|
||||||
|
```
|
||||||
|
|
||||||
|
The build system uses `scripts/excluded-strings.txt` to scan for leaked codenames. Buddy system species are encoded via `String.fromCharCode()` to avoid triggering the canary:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/buddy/types.ts:10-13
|
||||||
|
// One species name collides with a model-codename canary in excluded-strings.txt.
|
||||||
|
// The check greps build output (not source), so runtime-constructing the value keeps
|
||||||
|
// the literal out of the bundle while the check stays armed for the actual codename.
|
||||||
|
```
|
||||||
|
|
||||||
|
That colliding species is **capybara** — both a pet species and a model codename.
|
||||||
|
|
||||||
|
### Capybara Behavior Issues (v8)
|
||||||
|
|
||||||
|
The architecture reveals specific behavioral problems with Capybara v8:
|
||||||
|
|
||||||
|
1. **Stop sequence false trigger** (~10% rate when `<functions>` at prompt tail)
|
||||||
|
- Source: `src/utils/messages.ts:2141`
|
||||||
|
|
||||||
|
2. **Empty tool_result causes zero output**
|
||||||
|
- Source: `src/utils/toolResultStorage.ts:281`
|
||||||
|
|
||||||
|
3. **Over-commenting** — requires dedicated anti-comment prompt patches
|
||||||
|
- Source: `src/constants/prompts.ts:204`
|
||||||
|
|
||||||
|
4. **High false-claims rate**: v8 has 29-30% FC rate vs v4's 16.7%
|
||||||
|
- Source: `src/constants/prompts.ts:237`
|
||||||
|
|
||||||
|
5. **Insufficient verification** — requires "thoroughness counterweight"
|
||||||
|
- Source: `src/constants/prompts.ts:210`
|
||||||
|
|
||||||
|
## Feature Flag Naming Convention
|
||||||
|
|
||||||
|
All feature flags use the `tengu_` prefix with **random word pairs** to obscure their purpose:
|
||||||
|
|
||||||
|
| Flag | Purpose |
|
||||||
|
|------|---------|
|
||||||
|
| `tengu_onyx_plover` | Auto Dream (background memory consolidation) |
|
||||||
|
| `tengu_coral_fern` | memdir feature |
|
||||||
|
| `tengu_moth_copse` | Another memdir switch |
|
||||||
|
| `tengu_herring_clock` | Team memory |
|
||||||
|
| `tengu_passport_quail` | Path feature |
|
||||||
|
| `tengu_slate_thimble` | Another memdir switch |
|
||||||
|
| `tengu_sedge_lantern` | Away Summary |
|
||||||
|
| `tengu_frond_boric` | Analytics kill switch |
|
||||||
|
| `tengu_amber_quartz_disabled` | Voice mode kill switch |
|
||||||
|
| `tengu_amber_flint` | Agent teams |
|
||||||
|
| `tengu_hive_evidence` | Verification agent |
|
||||||
|
|
||||||
|
The random word pattern (adjective/material + nature/object) prevents external observers from inferring feature purpose from flag names alone.
|
||||||
|
|
||||||
|
## Internal vs External User Difference
|
||||||
|
|
||||||
|
Anthropic employees (`USER_TYPE === 'ant'`) receive significantly better treatment:
|
||||||
|
|
||||||
|
### Prompt Differences (`src/constants/prompts.ts`)
|
||||||
|
|
||||||
|
| Dimension | External Users | Internal (ant) |
|
||||||
|
|-----------|---------------|----------------|
|
||||||
|
| Output style | "Be extra concise" | "Err on the side of more explanation" |
|
||||||
|
| False-claims mitigation | None | Dedicated Capybara v8 patches |
|
||||||
|
| Numeric length anchors | None | "≤25 words between tools, ≤100 words final" |
|
||||||
|
| Verification agent | None | Required for non-trivial changes |
|
||||||
|
| Comment guidance | Generic | Dedicated anti-over-commenting prompt |
|
||||||
|
| Proactive correction | None | "If user has misconception, say so" |
|
||||||
|
|
||||||
|
### Tool Access
|
||||||
|
|
||||||
|
Internal users have access to tools not available externally:
|
||||||
|
- `REPLTool` — REPL mode
|
||||||
|
- `SuggestBackgroundPRTool` — background PR suggestions
|
||||||
|
- `TungstenTool` — performance monitoring panel
|
||||||
|
- `VerifyPlanExecutionTool` — plan verification
|
||||||
|
- Agent nesting (agents spawning agents)
|
||||||
|
|
||||||
|
## Hidden Commands
|
||||||
|
|
||||||
|
| Command | Status | Description |
|
||||||
|
|---------|--------|-------------|
|
||||||
|
| `/btw` | Active | Ask side questions without interrupting |
|
||||||
|
| `/stickers` | Active | Order Claude Code stickers (opens browser) |
|
||||||
|
| `/thinkback` | Active | 2025 Year in Review |
|
||||||
|
| `/effort` | Active | Set model effort level |
|
||||||
|
| `/good-claude` | Stub | Hidden placeholder |
|
||||||
|
| `/bughunter` | Stub | Hidden placeholder |
|
||||||
110
docs/en/03-undercover-mode.md
Normal file
110
docs/en/03-undercover-mode.md
Normal file
@@ -0,0 +1,110 @@
|
|||||||
|
# Undercover Mode Analysis
|
||||||
|
|
||||||
|
> Based on publicly available online references and community discussions on Claude Code v2.1.88.
|
||||||
|
|
||||||
|
## What Is Undercover Mode?
|
||||||
|
|
||||||
|
Undercover mode is a safety system for official employees contributing to external/open-source repositories. When active, it hides internal-specific AI model information and attribution, instructing the system to present its contributions as if written by a human developer. This is primarily to prevent the leakage of internal secrets and unreleased model names into the open-source community.
|
||||||
|
|
||||||
|
Source: `src/utils/undercover.ts`
|
||||||
|
|
||||||
|
## Activation Logic
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/undercover.ts:28-37
|
||||||
|
export function isUndercover(): boolean {
|
||||||
|
if (process.env.USER_TYPE === 'ant') {
|
||||||
|
if (isEnvTruthy(process.env.CLAUDE_CODE_UNDERCOVER)) return true
|
||||||
|
// Auto: active unless positively confirmed internal repo
|
||||||
|
return getRepoClassCached() !== 'internal'
|
||||||
|
}
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Key properties:
|
||||||
|
- **Internal only**: Only active for official employees (`USER_TYPE === 'ant'`)
|
||||||
|
- **Default ON**: Active in all repos except those on the internal allowlist
|
||||||
|
- **No force-off**: "There is NO force-OFF. This guards against model codename leaks"
|
||||||
|
- **External builds**: Dead-code-eliminated by the bundler; never executes
|
||||||
|
|
||||||
|
## The Prompt Given to the Model
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/undercover.ts:39-69
|
||||||
|
export function getUndercoverInstructions(): string {
|
||||||
|
return `## UNDERCOVER MODE — CRITICAL
|
||||||
|
|
||||||
|
You are operating UNDERCOVER in a PUBLIC/OPEN-SOURCE repository. Your commit
|
||||||
|
messages, PR titles, and PR bodies MUST NOT contain ANY Anthropic-internal
|
||||||
|
information. Do not blow your cover.
|
||||||
|
|
||||||
|
NEVER include in commit messages or PR descriptions:
|
||||||
|
- Internal model codenames (animal names like Capybara, Tengu, etc.)
|
||||||
|
- Unreleased model version numbers (e.g., opus-4-7, sonnet-4-8)
|
||||||
|
- Internal repo or project names (e.g., claude-cli-internal, anthropics/…)
|
||||||
|
- Internal tooling, Slack channels, or short links (e.g., go/cc, #claude-code-…)
|
||||||
|
- The phrase "Claude Code" or any mention that you are an AI
|
||||||
|
- Any hint of what model or version you are
|
||||||
|
- Co-Authored-By lines or any other attribution
|
||||||
|
|
||||||
|
Write commit messages as a human developer would — describe only what the code
|
||||||
|
change does.
|
||||||
|
|
||||||
|
GOOD:
|
||||||
|
- "Fix race condition in file watcher initialization"
|
||||||
|
- "Add support for custom key bindings"
|
||||||
|
|
||||||
|
BAD (never write these):
|
||||||
|
- "Fix bug found while testing with Claude Capybara"
|
||||||
|
- "1-shotted by claude-opus-4-6"
|
||||||
|
- "Generated with Claude Code"
|
||||||
|
- "Co-Authored-By: Claude Opus 4.6 <…>"`
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Attribution System
|
||||||
|
|
||||||
|
The attribution system (`src/utils/attribution.ts`, `src/utils/commitAttribution.ts`) complements undercover mode:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/attribution.ts:70-72
|
||||||
|
// @[MODEL LAUNCH]: Update the hardcoded fallback model name below
|
||||||
|
// (guards against codename leaks).
|
||||||
|
// For external repos, fall back to "Claude Opus 4.6" for unrecognized models.
|
||||||
|
```
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/model/model.ts:386-392
|
||||||
|
function maskModelCodename(baseName: string): string {
|
||||||
|
// e.g. capybara-v2-fast → cap*****-v2-fast
|
||||||
|
const [codename = '', ...rest] = baseName.split('-')
|
||||||
|
const masked = codename.slice(0, 3) + '*'.repeat(Math.max(0, codename.length - 3))
|
||||||
|
return [masked, ...rest].join('-')
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## Implications
|
||||||
|
|
||||||
|
### For Open Source
|
||||||
|
|
||||||
|
When official employees use Claude Code to contribute to open-source projects:
|
||||||
|
1. Code is written by AI but commits appear human-authored
|
||||||
|
2. No "Co-Authored-By: Claude" attribution
|
||||||
|
3. No "Generated with Claude Code" markers
|
||||||
|
4. Project maintainers and community cannot identify AI-generated contributions
|
||||||
|
5. This potentially violates open-source transparency norms regarding AI contributions
|
||||||
|
|
||||||
|
### For Official Protection
|
||||||
|
|
||||||
|
The primary stated purpose is preventing accidental leaks of:
|
||||||
|
- Internal model codenames (competitive intelligence)
|
||||||
|
- Unreleased version numbers (market timing)
|
||||||
|
- Internal infrastructure details (security)
|
||||||
|
|
||||||
|
### Ethical Considerations
|
||||||
|
|
||||||
|
The phrase "Do not blow your cover" frames the AI as an undercover agent. The intentional concealment of AI authorship in public code contributions raises questions about:
|
||||||
|
- Transparency in open-source communities
|
||||||
|
- Compliance with project contribution guidelines
|
||||||
|
- The line between trade secret protection and deception
|
||||||
161
docs/en/04-remote-control-and-killswitches.md
Normal file
161
docs/en/04-remote-control-and-killswitches.md
Normal file
@@ -0,0 +1,161 @@
|
|||||||
|
# Remote Control & Killswitches
|
||||||
|
|
||||||
|
> Based on publicly available online references and community discussions on Claude Code v2.1.88.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
Claude Code implements remote management mechanisms that allow officials (and enterprise administrators) to manage and update specific client behaviors via remote configuration to ensure system security and enterprise compliance.
|
||||||
|
|
||||||
|
## 1. Remote Managed Settings
|
||||||
|
|
||||||
|
### Architecture
|
||||||
|
|
||||||
|
Every eligible session fetches settings from:
|
||||||
|
```
|
||||||
|
GET /api/claude_code/settings
|
||||||
|
```
|
||||||
|
|
||||||
|
Source: `src/services/remoteManagedSettings/index.ts:105-107`
|
||||||
|
|
||||||
|
### Polling Behavior
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/services/remoteManagedSettings/index.ts:52-54
|
||||||
|
const SETTINGS_TIMEOUT_MS = 10000
|
||||||
|
const DEFAULT_MAX_RETRIES = 5
|
||||||
|
const POLLING_INTERVAL_MS = 60 * 60 * 1000 // 1 hour
|
||||||
|
```
|
||||||
|
|
||||||
|
Settings are polled every hour, with up to 5 retries on failure.
|
||||||
|
|
||||||
|
### Eligibility
|
||||||
|
|
||||||
|
- Console users (API key): All eligible
|
||||||
|
- OAuth users: Only Enterprise/C4E and Team subscribers
|
||||||
|
|
||||||
|
### Accept-or-Die Dialog
|
||||||
|
|
||||||
|
When remote settings contain "dangerous" changes, a blocking dialog is shown:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/services/remoteManagedSettings/securityCheck.tsx:67-73
|
||||||
|
export function handleSecurityCheckResult(result: SecurityCheckResult): boolean {
|
||||||
|
if (result === 'rejected') {
|
||||||
|
gracefulShutdownSync(1) // Exit with code 1
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
return true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Users who reject remote settings have the application **forcefully terminated**. The only options are: accept the remote settings, or Claude Code exits.
|
||||||
|
|
||||||
|
### Graceful Degradation
|
||||||
|
|
||||||
|
If the remote server is unreachable, cached settings from disk are used:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/services/remoteManagedSettings/index.ts:433-436
|
||||||
|
if (cachedSettings) {
|
||||||
|
logForDebugging('Remote settings: Using stale cache after fetch failure')
|
||||||
|
setSessionCache(cachedSettings)
|
||||||
|
return cachedSettings
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Once remote settings have been applied, they persist even when the server is down.
|
||||||
|
|
||||||
|
## 2. Feature Flag Killswitches
|
||||||
|
|
||||||
|
Multiple features can be remotely disabled via GrowthBook feature flags:
|
||||||
|
|
||||||
|
### Bypass Permissions Killswitch
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/permissions/bypassPermissionsKillswitch.ts
|
||||||
|
// Checks a Statsig gate to disable bypass permissions
|
||||||
|
```
|
||||||
|
|
||||||
|
Can disable permission bypass capabilities without user consent.
|
||||||
|
|
||||||
|
### Auto Mode Circuit Breaker
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/permissions/autoModeState.ts
|
||||||
|
// autoModeCircuitBroken state prevents re-entry to auto mode
|
||||||
|
```
|
||||||
|
|
||||||
|
Auto mode can be remotely disabled.
|
||||||
|
|
||||||
|
### Fast Mode Killswitch
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/fastMode.ts
|
||||||
|
// Fetches from /api/claude_code_penguin_mode
|
||||||
|
// Can permanently disable fast mode for a user
|
||||||
|
```
|
||||||
|
|
||||||
|
### Analytics Sink Killswitch
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/services/analytics/sinkKillswitch.ts:4
|
||||||
|
const SINK_KILLSWITCH_CONFIG_NAME = 'tengu_frond_boric'
|
||||||
|
```
|
||||||
|
|
||||||
|
Can remotely stop all analytics output.
|
||||||
|
|
||||||
|
### Agent Teams Killswitch
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/agentSwarmsEnabled.ts
|
||||||
|
// Requires both env var AND GrowthBook gate 'tengu_amber_flint'
|
||||||
|
```
|
||||||
|
|
||||||
|
### Voice Mode Killswitch
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/voice/voiceModeEnabled.ts:21
|
||||||
|
// 'tengu_amber_quartz_disabled' — emergency off for voice mode
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. Model Override System
|
||||||
|
|
||||||
|
To conduct canary testing or respond to unexpected online situations, the system supports dynamically switching the model versions for specific groups, such as internal employees:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/model/antModels.ts:32-33
|
||||||
|
// @[MODEL LAUNCH]: Update tengu_ant_model_override with new ant-only models
|
||||||
|
// @[MODEL LAUNCH]: Add the codename to scripts/excluded-strings.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
The `tengu_ant_model_override` GrowthBook flag can:
|
||||||
|
- Set a default model
|
||||||
|
- Set default effort level
|
||||||
|
- Append to the system prompt
|
||||||
|
- Define custom model aliases
|
||||||
|
|
||||||
|
## 4. Penguin Mode
|
||||||
|
|
||||||
|
Fast mode status is fetched from a dedicated endpoint:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/fastMode.ts
|
||||||
|
// GET /api/claude_code_penguin_mode
|
||||||
|
// If API indicates disabled, permanently disabled for user
|
||||||
|
```
|
||||||
|
|
||||||
|
Multiple feature flags control fast mode availability:
|
||||||
|
- `tengu_penguins_off`
|
||||||
|
- `tengu_marble_sandcastle`
|
||||||
|
|
||||||
|
## Summary
|
||||||
|
|
||||||
|
| Mechanism | Scope | User Consent |
|
||||||
|
|-----------|-------|-------------|
|
||||||
|
| Remote managed settings | Enterprise/Team | Accept or exit |
|
||||||
|
| GrowthBook feature flags | All users | None |
|
||||||
|
| Killswitches | All users | None |
|
||||||
|
| Model override | Internal (ant) | None |
|
||||||
|
| Fast mode control | All users | None |
|
||||||
|
|
||||||
|
The remote control infrastructure is extensive. Enterprise administrators can enforce policies that users cannot override, and the system can remotely change behavior for any user through feature flags to address critical issues.
|
||||||
167
docs/en/05-future-roadmap.md
Normal file
167
docs/en/05-future-roadmap.md
Normal file
@@ -0,0 +1,167 @@
|
|||||||
|
# Future Roadmap — What the Architecture Reveals
|
||||||
|
|
||||||
|
> Based on publicly available online references and community discussions on Claude Code v2.1.88.
|
||||||
|
|
||||||
|
## 1. Next Model: Numbat
|
||||||
|
|
||||||
|
The most concrete evidence of the next model launch:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/constants/prompts.ts:402
|
||||||
|
// @[MODEL LAUNCH]: Remove this section when we launch numbat.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Numbat** (袋食蚁兽) is the codename for an upcoming model. The comment indicates the output efficiency section will be revised when Numbat launches, suggesting it may have better native output control.
|
||||||
|
|
||||||
|
### Future Version Numbers
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/undercover.ts:49
|
||||||
|
- Unreleased model version numbers (e.g., opus-4-7, sonnet-4-8)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Opus 4.7** and **Sonnet 4.8** are in development.
|
||||||
|
|
||||||
|
### Codename Evolution Chain
|
||||||
|
|
||||||
|
```
|
||||||
|
Fennec (耳廓狐) → Opus 4.6 → [Numbat?]
|
||||||
|
Capybara (水豚) → Sonnet v8 → [?]
|
||||||
|
Tengu (天狗) → telemetry/product prefix
|
||||||
|
```
|
||||||
|
|
||||||
|
The Fennec-to-Opus migration is documented:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/migrations/migrateFennecToOpus.ts:7-11
|
||||||
|
// fennec-latest → opus
|
||||||
|
// fennec-latest[1m] → opus[1m]
|
||||||
|
// fennec-fast-latest → opus[1m] + fast mode
|
||||||
|
```
|
||||||
|
|
||||||
|
### MODEL LAUNCH Checklist
|
||||||
|
|
||||||
|
The codebase contains 20+ `@[MODEL LAUNCH]` markers listing everything to update:
|
||||||
|
|
||||||
|
- Default model names (`FRONTIER_MODEL_NAME`)
|
||||||
|
- Model family IDs
|
||||||
|
- Knowledge cutoff dates
|
||||||
|
- Pricing tables
|
||||||
|
- Context window configurations
|
||||||
|
- Thinking mode support flags
|
||||||
|
- Display name mappings
|
||||||
|
- Migration scripts
|
||||||
|
|
||||||
|
## 2. KAIROS — Autonomous Agent Mode
|
||||||
|
|
||||||
|
The largest unreleased feature, KAIROS transforms Claude Code from a reactive assistant into a proactive autonomous agent.
|
||||||
|
|
||||||
|
### System Prompt (excerpts)
|
||||||
|
|
||||||
|
```
|
||||||
|
// src/constants/prompts.ts:860-913
|
||||||
|
|
||||||
|
You are running autonomously.
|
||||||
|
You will receive <tick> prompts that keep you alive between turns.
|
||||||
|
If you have nothing useful to do, call SleepTool.
|
||||||
|
Bias toward action — read files, make changes, commit without asking.
|
||||||
|
|
||||||
|
## Terminal focus
|
||||||
|
- Unfocused: The user is away. Lean heavily into autonomous action.
|
||||||
|
- Focused: The user is watching. Be more collaborative.
|
||||||
|
```
|
||||||
|
|
||||||
|
### Associated Tools
|
||||||
|
|
||||||
|
| Tool | Feature Flag | Purpose |
|
||||||
|
|------|-------------|---------|
|
||||||
|
| SleepTool | KAIROS / PROACTIVE | Control pacing between autonomous actions |
|
||||||
|
| SendUserFileTool | KAIROS | Proactively send files to users |
|
||||||
|
| PushNotificationTool | KAIROS / KAIROS_PUSH_NOTIFICATION | Push notifications to user devices |
|
||||||
|
| SubscribePRTool | KAIROS_GITHUB_WEBHOOKS | Subscribe to GitHub PR webhook events |
|
||||||
|
| BriefTool | KAIROS_BRIEF | Proactive status updates |
|
||||||
|
|
||||||
|
### Behavior
|
||||||
|
|
||||||
|
- Operates on `<tick>` heartbeat prompts
|
||||||
|
- Adjusts autonomy based on terminal focus state
|
||||||
|
- Can commit, push, and make decisions independently
|
||||||
|
- Sends proactive notifications and status updates
|
||||||
|
- Monitors GitHub PRs for changes
|
||||||
|
|
||||||
|
## 3. Voice Mode
|
||||||
|
|
||||||
|
Push-to-talk voice input is fully implemented but gated behind `VOICE_MODE` feature flag.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/voice/voiceModeEnabled.ts
|
||||||
|
// Connects to Anthropic's voice_stream WebSocket endpoint
|
||||||
|
// Uses conversation_engine backed models for speech-to-text
|
||||||
|
// Hold-to-talk: hold keybinding to record, release to submit
|
||||||
|
```
|
||||||
|
|
||||||
|
- OAuth-only (no API key / Bedrock / Vertex support)
|
||||||
|
- Uses mTLS for WebSocket connections
|
||||||
|
- Killswitch: `tengu_amber_quartz_disabled`
|
||||||
|
|
||||||
|
## 4. Unreleased Tools
|
||||||
|
|
||||||
|
Tools found in source but not yet enabled for external users:
|
||||||
|
|
||||||
|
| Tool | Feature Flag | Description |
|
||||||
|
|------|-------------|-------------|
|
||||||
|
| **WebBrowserTool** | `WEB_BROWSER_TOOL` | Built-in browser automation (codename: bagel) |
|
||||||
|
| **TerminalCaptureTool** | `TERMINAL_PANEL` | Terminal panel capture and monitoring |
|
||||||
|
| **WorkflowTool** | `WORKFLOW_SCRIPTS` | Execute predefined workflow scripts |
|
||||||
|
| **MonitorTool** | `MONITOR_TOOL` | System/process monitoring |
|
||||||
|
| **SnipTool** | `HISTORY_SNIP` | Conversation history snipping/truncation |
|
||||||
|
| **ListPeersTool** | `UDS_INBOX` | Unix domain socket peer discovery |
|
||||||
|
| **RemoteTriggerTool** | `AGENT_TRIGGERS_REMOTE` | Remote agent triggering |
|
||||||
|
| **TungstenTool** | ant-only | Internal performance monitoring panel |
|
||||||
|
| **VerifyPlanExecutionTool** | VERIFY_PLAN env | Plan execution verification |
|
||||||
|
| **OverflowTestTool** | `OVERFLOW_TEST_TOOL` | Context overflow testing |
|
||||||
|
| **SubscribePRTool** | `KAIROS_GITHUB_WEBHOOKS` | GitHub PR webhook subscriptions |
|
||||||
|
|
||||||
|
## 5. Coordinator Mode
|
||||||
|
|
||||||
|
Multi-agent coordination system:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/coordinator/coordinatorMode.ts
|
||||||
|
// Feature flag: COORDINATOR_MODE
|
||||||
|
```
|
||||||
|
|
||||||
|
Enables coordinated task execution across multiple agents with shared state and messaging.
|
||||||
|
|
||||||
|
## 6. Buddy System (Virtual Pets)
|
||||||
|
|
||||||
|
The complete pet companion system is implemented but not yet launched:
|
||||||
|
|
||||||
|
- **18 species**: duck, goose, blob, cat, dragon, octopus, owl, penguin, turtle, snail, ghost, axolotl, capybara, cactus, robot, rabbit, mushroom, chonk
|
||||||
|
- **5 rarity tiers**: Common (60%), Uncommon (25%), Rare (10%), Epic (4%), Legendary (1%)
|
||||||
|
- **7 hats**: crown, tophat, propeller, halo, wizard, beanie, tinyduck
|
||||||
|
- **5 stats**: DEBUGGING, PATIENCE, CHAOS, WISDOM, SNARK
|
||||||
|
- **1% shiny chance**: Sparkle variant of any species
|
||||||
|
- **Deterministic generation**: Based on hash of user ID
|
||||||
|
|
||||||
|
Source: `src/buddy/`
|
||||||
|
|
||||||
|
## 7. Dream Task
|
||||||
|
|
||||||
|
Background memory consolidation subagent:
|
||||||
|
|
||||||
|
```
|
||||||
|
// src/tasks/DreamTask/
|
||||||
|
// Auto-dreaming feature that works in the background
|
||||||
|
// Controlled by 'tengu_onyx_plover' feature flag
|
||||||
|
```
|
||||||
|
|
||||||
|
Enables the AI to autonomously process and consolidate memories during idle time.
|
||||||
|
|
||||||
|
## Summary: The Three Directions
|
||||||
|
|
||||||
|
1. **New Models**: Numbat (next), Opus 4.7, Sonnet 4.8 in development
|
||||||
|
2. **Autonomous Agent**: KAIROS mode — unattended operation, proactive actions, push notifications
|
||||||
|
3. **Multi-modal**: Voice input ready, browser tool waiting, workflow automation coming
|
||||||
|
|
||||||
|
Claude Code is evolving from a **coding assistant** into an **always-on autonomous development agent**.
|
||||||
124
docs/ja/01-テレメトリとプライバシー.md
Normal file
124
docs/ja/01-テレメトリとプライバシー.md
Normal file
@@ -0,0 +1,124 @@
|
|||||||
|
# テレメトリおよびプライバシー分析
|
||||||
|
|
||||||
|
> インターネット上で公開されている資料やコミュニティの議論をもとに整理した Claude Code v2.1.88 分析レポート。
|
||||||
|
|
||||||
|
## 概要
|
||||||
|
|
||||||
|
Claude Codeは二層の分析パイプラインを実装し、広範な環境情報と使用メタデータを収集している。キーロギングやユーザーコード流出の証拠はないが、収集範囲の広さと完全な無効化が不可能な点にプライバシー上の懸念がある。
|
||||||
|
|
||||||
|
## データパイプライン構成
|
||||||
|
|
||||||
|
### ファーストパーティロギング（1P）
|
||||||
|
|
||||||
|
- **エンドポイント**: `https://api.anthropic.com/api/event_logging/batch`
|
||||||
|
- **プロトコル**: OpenTelemetry + Protocol Buffers
|
||||||
|
- **バッチサイズ**: 最大200イベント、10秒間隔で送信
|
||||||
|
- **リトライ**: 二次バックオフ、最大8回、ディスク永続化
|
||||||
|
- **ストレージ**: 送信失敗時 `~/.claude/telemetry/` に保存
|
||||||
|
|
||||||
|
出典: `src/services/analytics/firstPartyEventLoggingExporter.ts`
|
||||||
|
|
||||||
|
### サードパーティロギング（Datadog）
|
||||||
|
|
||||||
|
- **エンドポイント**: `https://http-intake.logs.us5.datadoghq.com/api/v2/logs`
|
||||||
|
- **対象**: 事前承認済みの64種類のイベントに限定
|
||||||
|
- **トークン**: `pubbbf48e6d78dae54bceaa4acf463299bf`
|
||||||
|
|
||||||
|
出典: `src/services/analytics/datadog.ts`
|
||||||
|
|
||||||
|
## 収集項目
|
||||||
|
|
||||||
|
### 環境フィンガープリント
|
||||||
|
|
||||||
|
すべてのイベントに以下のメタデータが含まれる（`src/services/analytics/metadata.ts:417-452`）:
|
||||||
|
|
||||||
|
```
|
||||||
|
- platform, platformRaw, arch, nodeVersion
|
||||||
|
- ターミナル種別
|
||||||
|
- インストール済みパッケージマネージャとランタイム
|
||||||
|
- CI/CD検出、GitHub Actionsメタデータ
|
||||||
|
- WSLバージョン、Linuxディストリビューション、カーネルバージョン
|
||||||
|
- VCS（バージョン管理システム）種別
|
||||||
|
- Claude Codeバージョンとビルド日時
|
||||||
|
- デプロイ環境
|
||||||
|
```
|
||||||
|
|
||||||
|
### プロセスメトリクス（`metadata.ts:457-467`）
|
||||||
|
|
||||||
|
```
|
||||||
|
- uptime, rss, heapTotal, heapUsed
|
||||||
|
- CPU使用量と使用率
|
||||||
|
- memory arraysとexternal allocations
|
||||||
|
```
|
||||||
|
|
||||||
|
### ユーザー追跡（`metadata.ts:472-496`）
|
||||||
|
|
||||||
|
```
|
||||||
|
- 使用中のモデル
|
||||||
|
- セッションID、ユーザーID、デバイスID
|
||||||
|
- アカウントUUID、組織UUID
|
||||||
|
- サブスクリプション等級（max, pro, enterprise, team）
|
||||||
|
- リポジトリリモートURLハッシュ（SHA256、先頭16文字）
|
||||||
|
- エージェント種別、チーム名、親セッションID
|
||||||
|
```
|
||||||
|
|
||||||
|
### ツール入力ロギング
|
||||||
|
|
||||||
|
ツール入力はデフォルトで切り詰められる:
|
||||||
|
|
||||||
|
```
|
||||||
|
- 文字列: 512文字で切り詰め、128文字+省略記号で表示
|
||||||
|
- JSON: 4,096文字制限
|
||||||
|
- 配列: 最大20要素
|
||||||
|
- ネストオブジェクト: 最大2階層
|
||||||
|
```
|
||||||
|
|
||||||
|
出典: `metadata.ts:236-241`
|
||||||
|
|
||||||
|
ただし、`OTEL_LOG_TOOL_DETAILS=1` 設定時は**ツール入力がすべて記録される**。
|
||||||
|
|
||||||
|
出典: `metadata.ts:86-88`
|
||||||
|
|
||||||
|
### ファイル拡張子追跡
|
||||||
|
|
||||||
|
`rm, mv, cp, touch, mkdir, chmod, chown, cat, head, tail, sort, stat, diff, wc, grep, rg, sed` 関連のBashコマンドで、ファイル引数の拡張子が抽出・記録される。
|
||||||
|
|
||||||
|
出典: `metadata.ts:340-412`
|
||||||
|
|
||||||
|
## 無効化の問題
|
||||||
|
|
||||||
|
ファーストパーティロギングパイプラインは、直接Anthropic APIユーザーの場合**無効化できない**。
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/services/analytics/firstPartyEventLogger.ts:141-144
|
||||||
|
export function is1PEventLoggingEnabled(): boolean {
|
||||||
|
return !isAnalyticsDisabled()
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`isAnalyticsDisabled()` がtrueを返すケース:
|
||||||
|
- テスト環境
|
||||||
|
- サードパーティクラウドプロバイダ（Bedrock, Vertex）
|
||||||
|
- グローバルテレメトリ無効化（設定UIに非公開）
|
||||||
|
|
||||||
|
ファーストパーティイベントロギングを無効化する**ユーザー向け設定は存在しない**。
|
||||||
|
|
||||||
|
## GrowthBook A/Bテスト
|
||||||
|
|
||||||
|
ユーザーは明示的な同意なくGrowthBookを通じて実験グループに割り当てられる。送信されるユーザー属性:
|
||||||
|
|
||||||
|
```
|
||||||
|
- id, sessionId, deviceID
|
||||||
|
- platform, organizationUUID, subscriptionType
|
||||||
|
```
|
||||||
|
|
||||||
|
出典: `src/services/analytics/growthbook.ts`
|
||||||
|
|
||||||
|
## 要点
|
||||||
|
|
||||||
|
1. **収集量**: セッションあたり数百件のイベントが収集される
|
||||||
|
2. **無効化不可**: 直接APIユーザーはファーストパーティロギングを停止できない
|
||||||
|
3. **永続性**: 送信失敗イベントはディスクに保存され積極的にリトライされる
|
||||||
|
4. **サードパーティ共有**: データがDatadogに送信される
|
||||||
|
5. **ツール詳細バックドア**: `OTEL_LOG_TOOL_DETAILS=1` で全入力ロギングが有効化される
|
||||||
|
6. **リポジトリフィンガープリント**: リポジトリURLがハッシュ化されサーバー側の相関分析に使用される
|
||||||
112
docs/ja/02-隠し機能とコードネーム.md
Normal file
112
docs/ja/02-隠し機能とコードネーム.md
Normal file
@@ -0,0 +1,112 @@
|
|||||||
|
# 隠し機能とモデルコードネーム
|
||||||
|
|
||||||
|
> インターネット上で公開されている資料やコミュニティの議論をもとに整理した Claude Code v2.1.88 分析レポート。
|
||||||
|
|
||||||
|
## モデルコードネーム体系
|
||||||
|
|
||||||
|
Anthropicは内部モデルコードネームに**動物名**を使用している。外部ビルドへの漏洩を積極的に防止している。
|
||||||
|
|
||||||
|
### 既知のコードネーム
|
||||||
|
|
||||||
|
| コードネーム | 役割 | 根拠 |
|
||||||
|
|-------------|------|------|
|
||||||
|
| **Tengu**（天狗） | 製品/テレメトリ接頭辞、モデルの可能性あり | 250以上の分析イベントとfeature flagに `tengu_*` 接頭辞で使用 |
|
||||||
|
| **Capybara**（カピバラ） | Sonnet系モデル、現在v8 | `capybara-v2-fast[1m]`、v8動作問題のパッチあり |
|
||||||
|
| **Fennec**（フェネック） | Opus 4.6の前身モデル | マイグレーション: `fennec-latest` → `opus` |
|
||||||
|
| **Numbat**（ナンバット） | 次期モデル | コメント: "Remove this section when we launch numbat" |
|
||||||
|
|
||||||
|
### コードネーム保護
|
||||||
|
|
||||||
|
`undercover` モードで保護対象コードネームが明示されている:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/undercover.ts:48-49
|
||||||
|
NEVER include in commit messages or PR descriptions:
|
||||||
|
- Internal model codenames (animal names like Capybara, Tengu, etc.)
|
||||||
|
- Unreleased model version numbers (e.g., opus-4-7, sonnet-4-8)
|
||||||
|
```
|
||||||
|
|
||||||
|
ビルドシステムは `scripts/excluded-strings.txt` を使用してコードネームの漏洩を検出する。Buddyシステムの種（species）は `String.fromCharCode()` でエンコードし、カナリア検出を回避している:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/buddy/types.ts:10-13
|
||||||
|
// One species name collides with a model-codename canary in excluded-strings.txt.
|
||||||
|
// The check greps build output (not source), so runtime-constructing the value keeps
|
||||||
|
// the literal out of the bundle while the check stays armed for the actual codename.
|
||||||
|
```
|
||||||
|
|
||||||
|
衝突する種は **capybara** — ペットの種でありモデルコードネームでもある。
|
||||||
|
|
||||||
|
### Capybara動作問題（v8）
|
||||||
|
|
||||||
|
アーキテクチャからCapybara v8の具体的な動作問題が確認される:
|
||||||
|
|
||||||
|
1. **Stop sequenceの誤発動**（プロンプト末尾に `<functions>` がある場合、約10%の発生率）
|
||||||
|
- 出典: `src/utils/messages.ts:2141`
|
||||||
|
|
||||||
|
2. **空のtool_resultで出力ゼロ**
|
||||||
|
- 出典: `src/utils/toolResultStorage.ts:281`
|
||||||
|
|
||||||
|
3. **コメント過剰挿入** — 専用コメント抑制プロンプトパッチが必要
|
||||||
|
- 出典: `src/constants/prompts.ts:204`
|
||||||
|
|
||||||
|
4. **高い虚偽主張率**: v8は29-30%、v4は16.7%
|
||||||
|
- 出典: `src/constants/prompts.ts:237`
|
||||||
|
|
||||||
|
5. **不十分な検証** — "徹底度カウンターウェイト（thoroughness counterweight）"が必要
|
||||||
|
- 出典: `src/constants/prompts.ts:210`
|
||||||
|
|
||||||
|
## Feature Flag命名規則
|
||||||
|
|
||||||
|
すべてのfeature flagは `tengu_` 接頭辞に**ランダムな単語ペア**を使用し、目的を難読化している:
|
||||||
|
|
||||||
|
| Flag | 用途 |
|
||||||
|
|------|------|
|
||||||
|
| `tengu_onyx_plover` | Auto Dream（バックグラウンド記憶統合） |
|
||||||
|
| `tengu_coral_fern` | memdir機能 |
|
||||||
|
| `tengu_moth_copse` | memdir追加スイッチ |
|
||||||
|
| `tengu_herring_clock` | Team memory |
|
||||||
|
| `tengu_passport_quail` | Path機能 |
|
||||||
|
| `tengu_slate_thimble` | memdir追加スイッチ |
|
||||||
|
| `tengu_sedge_lantern` | Away Summary |
|
||||||
|
| `tengu_frond_boric` | 分析キルスイッチ |
|
||||||
|
| `tengu_amber_quartz_disabled` | 音声モードキルスイッチ |
|
||||||
|
| `tengu_amber_flint` | Agent teams |
|
||||||
|
| `tengu_hive_evidence` | 検証エージェント |
|
||||||
|
|
||||||
|
ランダムな単語パターン（形容詞/素材 + 自然/物体）により、外部の観察者がflag名から機能の目的を推測することを防ぐ。
|
||||||
|
|
||||||
|
## 内部ユーザーと外部ユーザーの違い
|
||||||
|
|
||||||
|
Anthropic社員（`USER_TYPE === 'ant'`）は大幅に優遇されている:
|
||||||
|
|
||||||
|
### プロンプトの違い（`src/constants/prompts.ts`）
|
||||||
|
|
||||||
|
| 項目 | 外部ユーザー | 内部ユーザー（ant） |
|
||||||
|
|------|------------|-------------------|
|
||||||
|
| 出力スタイル | "Be extra concise"（極めて簡潔に） | "Err on the side of more explanation"（説明を多めに） |
|
||||||
|
| 虚偽主張対策 | なし | 専用Capybara v8パッチ適用 |
|
||||||
|
| 数値的長さ基準 | なし | "ツール間≤25単語、最終回答≤100単語" |
|
||||||
|
| 検証エージェント | なし | 非自明な変更に必須 |
|
||||||
|
| コメントガイド | 一般的 | 専用コメント過剰防止プロンプト |
|
||||||
|
| 先制的修正 | なし | "ユーザーに誤解があれば指摘する" |
|
||||||
|
|
||||||
|
### ツールアクセス
|
||||||
|
|
||||||
|
内部ユーザーのみアクセス可能なツール:
|
||||||
|
- `REPLTool` — REPLモード
|
||||||
|
- `SuggestBackgroundPRTool` — バックグラウンドPR提案
|
||||||
|
- `TungstenTool` — パフォーマンス監視パネル
|
||||||
|
- `VerifyPlanExecutionTool` — 計画実行検証
|
||||||
|
- Agent入れ子（エージェントがエージェントを生成）
|
||||||
|
|
||||||
|
## 隠しコマンド
|
||||||
|
|
||||||
|
| コマンド | 状態 | 説明 |
|
||||||
|
|---------|------|------|
|
||||||
|
| `/btw` | 有効 | 作業中断なしで余談質問 |
|
||||||
|
| `/stickers` | 有効 | Claude Codeステッカー注文（ブラウザが開く） |
|
||||||
|
| `/thinkback` | 有効 | 2025年振り返り |
|
||||||
|
| `/effort` | 有効 | モデル努力レベル設定 |
|
||||||
|
| `/good-claude` | スタブ | 隠しプレースホルダー |
|
||||||
|
| `/bughunter` | スタブ | 隠しプレースホルダー |
|
||||||
110
docs/ja/03-アンダーカバーモード.md
Normal file
110
docs/ja/03-アンダーカバーモード.md
Normal file
@@ -0,0 +1,110 @@
|
|||||||
|
# アンダーカバーモード分析
|
||||||
|
|
||||||
|
> インターネット上で公開されている資料やコミュニティの議論をもとに整理した Claude Code v2.1.88 分析レポート。
|
||||||
|
|
||||||
|
## アンダーカバーモードとは
|
||||||
|
|
||||||
|
アンダーカバーモードは、公式社員が外部/オープンソースリポジトリで作業する際に使用する安全保護メカニズムです。有効化すると、内部固有の AI モデル情報や帰属表示が隠され、コミットされたコードが人間の開発者の貢献と同じように見えるようになります。これは主に、内部の機密情報や未公開モデルの名称がオープンソースコミュニティに漏洩するのを防ぐためのものです。
|
||||||
|
|
||||||
|
出典: `src/utils/undercover.ts`
|
||||||
|
|
||||||
|
## 有効化条件
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/undercover.ts:28-37
|
||||||
|
export function isUndercover(): boolean {
|
||||||
|
if (process.env.USER_TYPE === 'ant') {
|
||||||
|
if (isEnvTruthy(process.env.CLAUDE_CODE_UNDERCOVER)) return true
|
||||||
|
// Auto: 内部リポジトリと確認されない限り自動有効化
|
||||||
|
return getRepoClassCached() !== 'internal'
|
||||||
|
}
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
主な特性:
|
||||||
|
- **内部専用**: 公式社員（`USER_TYPE === 'ant'`）のみ対象
|
||||||
|
- **デフォルト有効**: 内部許可リストにないすべてのリポジトリで自動有効化
|
||||||
|
- **強制無効化不可**: "There is NO force-OFF. This guards against model codename leaks"
|
||||||
|
- **外部ビルド**: バンドラーによりデッドコード除去され、実行されない
|
||||||
|
|
||||||
|
## モデルに渡されるプロンプト
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/undercover.ts:39-69
|
||||||
|
export function getUndercoverInstructions(): string {
|
||||||
|
return `## UNDERCOVER MODE — CRITICAL
|
||||||
|
|
||||||
|
You are operating UNDERCOVER in a PUBLIC/OPEN-SOURCE repository. Your commit
|
||||||
|
messages, PR titles, and PR bodies MUST NOT contain ANY Anthropic-internal
|
||||||
|
information. Do not blow your cover.
|
||||||
|
|
||||||
|
NEVER include in commit messages or PR descriptions:
|
||||||
|
- Internal model codenames (animal names like Capybara, Tengu, etc.)
|
||||||
|
- Unreleased model version numbers (e.g., opus-4-7, sonnet-4-8)
|
||||||
|
- Internal repo or project names (e.g., claude-cli-internal, anthropics/…)
|
||||||
|
- Internal tooling, Slack channels, or short links (e.g., go/cc, #claude-code-…)
|
||||||
|
- The phrase "Claude Code" or any mention that you are an AI
|
||||||
|
- Any hint of what model or version you are
|
||||||
|
- Co-Authored-By lines or any other attribution
|
||||||
|
|
||||||
|
Write commit messages as a human developer would — describe only what the code
|
||||||
|
change does.
|
||||||
|
|
||||||
|
GOOD:
|
||||||
|
- "Fix race condition in file watcher initialization"
|
||||||
|
- "Add support for custom key bindings"
|
||||||
|
|
||||||
|
BAD (never write these):
|
||||||
|
- "Fix bug found while testing with Claude Capybara"
|
||||||
|
- "1-shotted by claude-opus-4-6"
|
||||||
|
- "Generated with Claude Code"
|
||||||
|
- "Co-Authored-By: Claude Opus 4.6 <…>"`
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 帰属表示システム
|
||||||
|
|
||||||
|
帰属表示システム（`src/utils/attribution.ts`、`src/utils/commitAttribution.ts`）はアンダーカバーモードを補完する:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/attribution.ts:70-72
|
||||||
|
// @[MODEL LAUNCH]: 以下のハードコードされたフォールバックモデル名を更新
|
||||||
|
// （コードネーム漏洩防止用）。
|
||||||
|
// 外部リポジトリでは、認識されないモデルは "Claude Opus 4.6" にフォールバック。
|
||||||
|
```
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/model/model.ts:386-392
|
||||||
|
function maskModelCodename(baseName: string): string {
|
||||||
|
// e.g. capybara-v2-fast → cap*****-v2-fast
|
||||||
|
const [codename = '', ...rest] = baseName.split('-')
|
||||||
|
const masked = codename.slice(0, 3) + '*'.repeat(Math.max(0, codename.length - 3))
|
||||||
|
return [masked, ...rest].join('-')
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 示唆
|
||||||
|
|
||||||
|
### オープンソースへの影響
|
||||||
|
|
||||||
|
公式社員がClaude Codeでオープンソースプロジェクトにコントリビュートする場合:
|
||||||
|
1. AIがコードを書くが、コミットは人間が書いたものとして表示される
|
||||||
|
2. "Co-Authored-By: Claude"の帰属表示がない
|
||||||
|
3. "Generated with Claude Code"のマーカーがない
|
||||||
|
4. プロジェクトメンテナーやコミュニティはAI生成のコントリビュートを識別できない
|
||||||
|
5. AIコントリビュートに関するオープンソースの透明性規範に抵触する可能性がある
|
||||||
|
|
||||||
|
### 公式保護目的
|
||||||
|
|
||||||
|
主な目的は以下の偶発的漏洩の防止:
|
||||||
|
- 内部モデルコードネーム（競争情報）
|
||||||
|
- 未公開バージョン番号（市場タイミング）
|
||||||
|
- 内部インフラの詳細（セキュリティ）
|
||||||
|
|
||||||
|
### 倫理的考察
|
||||||
|
|
||||||
|
"Do not blow your cover（正体を明かすな）"という表現はAIを潜入工作員として位置づけている。公開コードコントリビュートにおけるAI著作の意図的な隠匿は以下の問題を提起する:
|
||||||
|
- オープンソースコミュニティにおける透明性
|
||||||
|
- プロジェクトコントリビュートガイドラインの遵守
|
||||||
|
- 営業秘密保護と欺瞞の境界線
|
||||||
161
docs/ja/04-リモート制御とキルスイッチ.md
Normal file
161
docs/ja/04-リモート制御とキルスイッチ.md
Normal file
@@ -0,0 +1,161 @@
|
|||||||
|
# リモート制御およびキルスイッチ
|
||||||
|
|
||||||
|
> インターネット上で公開されている資料やコミュニティの議論をもとに整理した Claude Code v2.1.88 分析レポート。
|
||||||
|
|
||||||
|
## 概要
|
||||||
|
|
||||||
|
Claude Codeは、公式管理者（および企業管理者）がシステムセキュリティと企業のコンプライアンスを確保するために、リモート構成を通じて特定のクライアントの動作を管理および更新できるリモート管理メカニズムを実装しています。
|
||||||
|
|
||||||
|
## 1. リモート管理設定
|
||||||
|
|
||||||
|
### 構成
|
||||||
|
|
||||||
|
対象セッションは以下から設定を取得する:
|
||||||
|
```
|
||||||
|
GET /api/claude_code/settings
|
||||||
|
```
|
||||||
|
|
||||||
|
出典: `src/services/remoteManagedSettings/index.ts:105-107`
|
||||||
|
|
||||||
|
### ポーリング動作
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/services/remoteManagedSettings/index.ts:52-54
|
||||||
|
const SETTINGS_TIMEOUT_MS = 10000
|
||||||
|
const DEFAULT_MAX_RETRIES = 5
|
||||||
|
const POLLING_INTERVAL_MS = 60 * 60 * 1000 // 1時間
|
||||||
|
```
|
||||||
|
|
||||||
|
設定は1時間ごとにポーリングされ、失敗時は最大5回リトライする。
|
||||||
|
|
||||||
|
### 対象資格
|
||||||
|
|
||||||
|
- Consoleユーザー（APIキー）: 全員対象
|
||||||
|
- OAuthユーザー: Enterprise/C4EおよびTeamサブスクライバーのみ
|
||||||
|
|
||||||
|
### 強制承認ダイアログ
|
||||||
|
|
||||||
|
リモート設定に「危険な」変更が含まれる場合、ブロッキングダイアログが表示される:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/services/remoteManagedSettings/securityCheck.tsx:67-73
|
||||||
|
export function handleSecurityCheckResult(result: SecurityCheckResult): boolean {
|
||||||
|
if (result === 'rejected') {
|
||||||
|
gracefulShutdownSync(1) // 終了コード1で終了
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
return true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
リモート設定を拒否するとアプリケーションが**強制終了される**。選択肢はリモート設定の承認またはClaude Codeの終了のみである。
|
||||||
|
|
||||||
|
### 障害時の動作
|
||||||
|
|
||||||
|
リモートサーバーに接続できない場合、ディスクキャッシュ設定が使用される:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/services/remoteManagedSettings/index.ts:433-436
|
||||||
|
if (cachedSettings) {
|
||||||
|
logForDebugging('Remote settings: Using stale cache after fetch failure')
|
||||||
|
setSessionCache(cachedSettings)
|
||||||
|
return cachedSettings
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
リモート設定が一度適用されると、サーバー障害時もキャッシュが維持される。
|
||||||
|
|
||||||
|
## 2. Feature Flagキルスイッチ
|
||||||
|
|
||||||
|
GrowthBook feature flagにより複数の機能をリモート無効化できる:
|
||||||
|
|
||||||
|
### パーミッションバイパスキルスイッチ
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/permissions/bypassPermissionsKillswitch.ts
|
||||||
|
// Statsigゲートを確認してパーミッションバイパスを無効化
|
||||||
|
```
|
||||||
|
|
||||||
|
ユーザーの同意なくパーミッションバイパス機能を無効化できる。
|
||||||
|
|
||||||
|
### Autoモードサーキットブレーカー
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/permissions/autoModeState.ts
|
||||||
|
// autoModeCircuitBroken状態でautoモードへの再突入を阻止
|
||||||
|
```
|
||||||
|
|
||||||
|
Autoモードをリモートで無効化できる。
|
||||||
|
|
||||||
|
### Fastモードキルスイッチ
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/fastMode.ts
|
||||||
|
// /api/claude_code_penguin_mode から取得
|
||||||
|
// 特定ユーザーのfastモードを永久に無効化可能
|
||||||
|
```
|
||||||
|
|
||||||
|
### 分析シンクキルスイッチ
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/services/analytics/sinkKillswitch.ts:4
|
||||||
|
const SINK_KILLSWITCH_CONFIG_NAME = 'tengu_frond_boric'
|
||||||
|
```
|
||||||
|
|
||||||
|
すべての分析出力をリモートで停止できる。
|
||||||
|
|
||||||
|
### Agent Teamsキルスイッチ
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/agentSwarmsEnabled.ts
|
||||||
|
// 環境変数とGrowthBookゲート 'tengu_amber_flint' の両方が必要
|
||||||
|
```
|
||||||
|
|
||||||
|
### 音声モードキルスイッチ
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/voice/voiceModeEnabled.ts:21
|
||||||
|
// 'tengu_amber_quartz_disabled' — 音声モードの緊急停止
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. モデルオーバーライドシステム
|
||||||
|
|
||||||
|
カナリアテストを実施したり、予期せぬオンラインの状況に対応するために、システムは内部社員などの特定のグループに対してモデルバージョンを動的に切り替えることをサポートしています:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/model/antModels.ts:32-33
|
||||||
|
// @[MODEL LAUNCH]: tengu_ant_model_overrideに新しいant専用モデルを更新
|
||||||
|
// @[MODEL LAUNCH]: コードネームをscripts/excluded-strings.txtに追加
|
||||||
|
```
|
||||||
|
|
||||||
|
`tengu_ant_model_override` GrowthBook flagで可能な操作:
|
||||||
|
- デフォルトモデルの設定
|
||||||
|
- デフォルト努力レベルの設定
|
||||||
|
- システムプロンプトへの内容追加
|
||||||
|
- カスタムモデルエイリアスの定義
|
||||||
|
|
||||||
|
## 4. Penguinモード
|
||||||
|
|
||||||
|
Fastモードの状態は専用エンドポイントから取得される:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/fastMode.ts
|
||||||
|
// GET /api/claude_code_penguin_mode
|
||||||
|
// APIが無効を返した場合、該当ユーザーで永久無効化
|
||||||
|
```
|
||||||
|
|
||||||
|
Fastモードの可用性を制御するfeature flag:
|
||||||
|
- `tengu_penguins_off`
|
||||||
|
- `tengu_marble_sandcastle`
|
||||||
|
|
||||||
|
## まとめ
|
||||||
|
|
||||||
|
| メカニズム | 対象範囲 | ユーザー同意 |
|
||||||
|
|-----------|---------|------------|
|
||||||
|
| リモート管理設定 | Enterprise/Team | 承認または終了 |
|
||||||
|
| GrowthBook feature flag | 全ユーザー | なし |
|
||||||
|
| キルスイッチ | 全ユーザー | なし |
|
||||||
|
| モデルオーバーライド | 内部（ant） | なし |
|
||||||
|
| Fastモード制御 | 全ユーザー | なし |
|
||||||
|
|
||||||
|
リモート制御インフラは広範にわたります。企業管理者はユーザーが上書きできないポリシーを強制することができ、システムは重大な問題に対処するために、機能フラグ（feature flags）を通じてすべてのユーザーの動作をリモートで変更できます。
|
||||||
167
docs/ja/05-今後のロードマップ.md
Normal file
167
docs/ja/05-今後のロードマップ.md
Normal file
@@ -0,0 +1,167 @@
|
|||||||
|
# 今後のロードマップ — アーキテクチャが示すもの
|
||||||
|
|
||||||
|
> インターネット上で公開されている資料やコミュニティの議論をもとに整理した Claude Code v2.1.88 分析レポート。
|
||||||
|
|
||||||
|
## 1. 次期モデル: Numbat
|
||||||
|
|
||||||
|
次期モデルリリースの最も具体的な根拠:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/constants/prompts.ts:402
|
||||||
|
// @[MODEL LAUNCH]: Remove this section when we launch numbat.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Numbat**（ナンバット）は次期モデルのコードネームである。このコメントはNumbatリリース時に出力効率セクションが改訂されることを示しており、より優れたネイティブ出力制御を備える可能性を示唆している。
|
||||||
|
|
||||||
|
### 今後のバージョン番号
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/undercover.ts:49
|
||||||
|
- Unreleased model version numbers (e.g., opus-4-7, sonnet-4-8)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Opus 4.7** と **Sonnet 4.8** が開発中である。
|
||||||
|
|
||||||
|
### コードネームの変遷
|
||||||
|
|
||||||
|
```
|
||||||
|
Fennec（フェネック） → Opus 4.6 → [Numbat?]
|
||||||
|
Capybara（カピバラ） → Sonnet v8 → [?]
|
||||||
|
Tengu（天狗） → テレメトリ/製品接頭辞
|
||||||
|
```
|
||||||
|
|
||||||
|
FennecからOpusへのマイグレーションが文書化されている:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/migrations/migrateFennecToOpus.ts:7-11
|
||||||
|
// fennec-latest → opus
|
||||||
|
// fennec-latest[1m] → opus[1m]
|
||||||
|
// fennec-fast-latest → opus[1m] + fast mode
|
||||||
|
```
|
||||||
|
|
||||||
|
### MODEL LAUNCHチェックリスト
|
||||||
|
|
||||||
|
コードベースには更新項目を列挙した20以上の `@[MODEL LAUNCH]` マーカーがある:
|
||||||
|
|
||||||
|
- デフォルトモデル名（`FRONTIER_MODEL_NAME`）
|
||||||
|
- モデルファミリーID
|
||||||
|
- ナレッジカットオフ日
|
||||||
|
- 料金表
|
||||||
|
- コンテキストウィンドウ設定
|
||||||
|
- Thinkingモードサポートフラグ
|
||||||
|
- 表示名マッピング
|
||||||
|
- マイグレーションスクリプト
|
||||||
|
|
||||||
|
## 2. KAIROS — 自律エージェントモード
|
||||||
|
|
||||||
|
最大規模の未公開機能であり、KAIROSはClaude Codeを受動的アシスタントから能動的自律エージェントに変換する。
|
||||||
|
|
||||||
|
### システムプロンプト（抜粋）
|
||||||
|
|
||||||
|
```
|
||||||
|
// src/constants/prompts.ts:860-913
|
||||||
|
|
||||||
|
You are running autonomously.
|
||||||
|
You will receive <tick> prompts that keep you alive between turns.
|
||||||
|
If you have nothing useful to do, call SleepTool.
|
||||||
|
Bias toward action — read files, make changes, commit without asking.
|
||||||
|
|
||||||
|
## Terminal focus
|
||||||
|
- Unfocused: The user is away. Lean heavily into autonomous action.
|
||||||
|
- Focused: The user is watching. Be more collaborative.
|
||||||
|
```
|
||||||
|
|
||||||
|
### 関連ツール
|
||||||
|
|
||||||
|
| ツール | Feature Flag | 用途 |
|
||||||
|
|-------|-------------|------|
|
||||||
|
| SleepTool | KAIROS / PROACTIVE | 自律動作間のペーシング制御 |
|
||||||
|
| SendUserFileTool | KAIROS | ユーザーへのファイル先行送信 |
|
||||||
|
| PushNotificationTool | KAIROS / KAIROS_PUSH_NOTIFICATION | ユーザーデバイスへのプッシュ通知 |
|
||||||
|
| SubscribePRTool | KAIROS_GITHUB_WEBHOOKS | GitHub PRウェブフック購読 |
|
||||||
|
| BriefTool | KAIROS_BRIEF | 先行ステータス更新 |
|
||||||
|
|
||||||
|
### 動作方式
|
||||||
|
|
||||||
|
- `<tick>` ハートビートプロンプトで稼働
|
||||||
|
- ターミナルフォーカス状態に応じて自律レベルを調整
|
||||||
|
- 独立してコミット、プッシュ、意思決定が可能
|
||||||
|
- 先行的に通知とステータス更新を送信
|
||||||
|
- GitHub PRの変更を監視
|
||||||
|
|
||||||
|
## 3. 音声モード
|
||||||
|
|
||||||
|
Push-to-talk音声入力が完全実装されているが `VOICE_MODE` feature flagでゲートされている。
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/voice/voiceModeEnabled.ts
|
||||||
|
// Anthropicのvoice_stream WebSocketエンドポイントに接続
|
||||||
|
// conversation_engineベースのモデルで音声テキスト変換
|
||||||
|
// キーバインドを長押しで録音、離すと送信
|
||||||
|
```
|
||||||
|
|
||||||
|
- OAuth専用（APIキー / Bedrock / Vertex非対応）
|
||||||
|
- WebSocket接続にmTLSを使用
|
||||||
|
- キルスイッチ: `tengu_amber_quartz_disabled`
|
||||||
|
|
||||||
|
## 4. 未公開ツール
|
||||||
|
|
||||||
|
アーキテクチャに存在するが外部ユーザーにはまだ有効化されていないツール:
|
||||||
|
|
||||||
|
| ツール | Feature Flag | 説明 |
|
||||||
|
|-------|-------------|------|
|
||||||
|
| **WebBrowserTool** | `WEB_BROWSER_TOOL` | 内蔵ブラウザ自動化（コードネーム: bagel） |
|
||||||
|
| **TerminalCaptureTool** | `TERMINAL_PANEL` | ターミナルパネルキャプチャと監視 |
|
||||||
|
| **WorkflowTool** | `WORKFLOW_SCRIPTS` | 定義済みワークフロースクリプト実行 |
|
||||||
|
| **MonitorTool** | `MONITOR_TOOL` | システム/プロセス監視 |
|
||||||
|
| **SnipTool** | `HISTORY_SNIP` | 会話履歴のスニッピング/縮小 |
|
||||||
|
| **ListPeersTool** | `UDS_INBOX` | Unixドメインソケットピア探索 |
|
||||||
|
| **RemoteTriggerTool** | `AGENT_TRIGGERS_REMOTE` | リモートエージェントトリガー |
|
||||||
|
| **TungstenTool** | ant専用 | 内部パフォーマンス監視パネル |
|
||||||
|
| **VerifyPlanExecutionTool** | VERIFY_PLAN env | 計画実行検証 |
|
||||||
|
| **OverflowTestTool** | `OVERFLOW_TEST_TOOL` | コンテキストオーバーフローテスト |
|
||||||
|
| **SubscribePRTool** | `KAIROS_GITHUB_WEBHOOKS` | GitHub PRウェブフック購読 |
|
||||||
|
|
||||||
|
## 5. Coordinatorモード
|
||||||
|
|
||||||
|
マルチエージェント連携システム:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/coordinator/coordinatorMode.ts
|
||||||
|
// Feature flag: COORDINATOR_MODE
|
||||||
|
```
|
||||||
|
|
||||||
|
共有状態とメッセージングによる複数エージェント間の連携タスク実行を実現する。
|
||||||
|
|
||||||
|
## 6. Buddyシステム（バーチャルペット）
|
||||||
|
|
||||||
|
完全なペットコンパニオンシステムが実装されているが未リリース:
|
||||||
|
|
||||||
|
- **18種**: duck, goose, blob, cat, dragon, octopus, owl, penguin, turtle, snail, ghost, axolotl, capybara, cactus, robot, rabbit, mushroom, chonk
|
||||||
|
- **5段階レアリティ**: Common (60%), Uncommon (25%), Rare (10%), Epic (4%), Legendary (1%)
|
||||||
|
- **7種の帽子**: crown, tophat, propeller, halo, wizard, beanie, tinyduck
|
||||||
|
- **5つのステータス**: DEBUGGING, PATIENCE, CHAOS, WISDOM, SNARK
|
||||||
|
- **1%のシャイニー確率**: 全種のSparkleバリアント
|
||||||
|
- **決定論的生成**: ユーザーIDハッシュに基づく
|
||||||
|
|
||||||
|
出典: `src/buddy/`
|
||||||
|
|
||||||
|
## 7. Dream Task
|
||||||
|
|
||||||
|
バックグラウンド記憶統合サブエージェント:
|
||||||
|
|
||||||
|
```
|
||||||
|
// src/tasks/DreamTask/
|
||||||
|
// バックグラウンドで動作するオートドリーミング機能
|
||||||
|
// 'tengu_onyx_plover' feature flagで制御
|
||||||
|
```
|
||||||
|
|
||||||
|
アイドル時間中にAIが自律的に記憶を処理・統合できるようにする。
|
||||||
|
|
||||||
|
## まとめ: 3つの方向性
|
||||||
|
|
||||||
|
1. **新モデル**: Numbat（次期）、Opus 4.7、Sonnet 4.8が開発中
|
||||||
|
2. **自律エージェント**: KAIROSモード — 無人運用、先行アクション、プッシュ通知
|
||||||
|
3. **マルチモーダル**: 音声入力準備完了、ブラウザツール待機中、ワークフロー自動化予定
|
||||||
|
|
||||||
|
Claude Codeは**コーディングアシスタント**から**常時稼働の自律開発エージェント**へと進化している。
|
||||||
124
docs/ko/01-텔레메트리와-프라이버시.md
Normal file
124
docs/ko/01-텔레메트리와-프라이버시.md
Normal file
@@ -0,0 +1,124 @@
|
|||||||
|
# 텔레메트리 및 프라이버시 분석
|
||||||
|
|
||||||
|
> 인터넷에 공개된 자료와 커뮤니티 토론을 바탕으로 정리된 Claude Code v2.1.88 분석 보고서.
|
||||||
|
|
||||||
|
## 개요
|
||||||
|
|
||||||
|
Claude Code는 이중 분석 파이프라인을 통해 광범위한 환경 및 사용 메타데이터를 수집한다. 키로깅이나 사용자 코드 유출의 증거는 없으나, 수집 범위가 넓고 완전한 비활성화가 불가능하다는 점에서 프라이버시 우려가 존재한다.
|
||||||
|
|
||||||
|
## 데이터 파이프라인 구조
|
||||||
|
|
||||||
|
### 자사 로깅 (1P)
|
||||||
|
|
||||||
|
- **엔드포인트**: `https://api.anthropic.com/api/event_logging/batch`
|
||||||
|
- **프로토콜**: OpenTelemetry + Protocol Buffers
|
||||||
|
- **배치 크기**: 최대 200개 이벤트, 10초 간격 전송
|
||||||
|
- **재시도**: 이차 백오프, 최대 8회, 디스크 영속 저장
|
||||||
|
- **저장소**: 전송 실패 시 `~/.claude/telemetry/`에 저장
|
||||||
|
|
||||||
|
출처: `src/services/analytics/firstPartyEventLoggingExporter.ts`
|
||||||
|
|
||||||
|
### 서드파티 로깅 (Datadog)
|
||||||
|
|
||||||
|
- **엔드포인트**: `https://http-intake.logs.us5.datadoghq.com/api/v2/logs`
|
||||||
|
- **범위**: 사전 승인된 64개 이벤트 유형으로 제한
|
||||||
|
- **토큰**: `pubbbf48e6d78dae54bceaa4acf463299bf`
|
||||||
|
|
||||||
|
출처: `src/services/analytics/datadog.ts`
|
||||||
|
|
||||||
|
## 수집 항목
|
||||||
|
|
||||||
|
### 환경 핑거프린트
|
||||||
|
|
||||||
|
모든 이벤트에 다음 메타데이터가 포함된다 (`src/services/analytics/metadata.ts:417-452`):
|
||||||
|
|
||||||
|
```
|
||||||
|
- platform, platformRaw, arch, nodeVersion
|
||||||
|
- 터미널 유형
|
||||||
|
- 설치된 패키지 매니저 및 런타임
|
||||||
|
- CI/CD 감지, GitHub Actions 메타데이터
|
||||||
|
- WSL 버전, Linux 배포판, 커널 버전
|
||||||
|
- VCS(버전 관리 시스템) 유형
|
||||||
|
- Claude Code 버전 및 빌드 시각
|
||||||
|
- 배포 환경
|
||||||
|
```
|
||||||
|
|
||||||
|
### 프로세스 메트릭 (`metadata.ts:457-467`)
|
||||||
|
|
||||||
|
```
|
||||||
|
- uptime, rss, heapTotal, heapUsed
|
||||||
|
- CPU 사용량 및 사용률
|
||||||
|
- memory arrays 및 external allocations
|
||||||
|
```
|
||||||
|
|
||||||
|
### 사용자 추적 (`metadata.ts:472-496`)
|
||||||
|
|
||||||
|
```
|
||||||
|
- 사용 중인 모델
|
||||||
|
- 세션 ID, 사용자 ID, 디바이스 ID
|
||||||
|
- 계정 UUID, 조직 UUID
|
||||||
|
- 구독 등급 (max, pro, enterprise, team)
|
||||||
|
- 저장소 원격 URL 해시 (SHA256, 앞 16자)
|
||||||
|
- 에이전트 유형, 팀 이름, 부모 세션 ID
|
||||||
|
```
|
||||||
|
|
||||||
|
### 도구 입력 로깅
|
||||||
|
|
||||||
|
도구 입력은 기본적으로 잘린다:
|
||||||
|
|
||||||
|
```
|
||||||
|
- 문자열: 512자에서 잘림, 128자 + 생략부호로 표시
|
||||||
|
- JSON: 4,096자 제한
|
||||||
|
- 배열: 최대 20개 항목
|
||||||
|
- 중첩 객체: 최대 2단계 깊이
|
||||||
|
```
|
||||||
|
|
||||||
|
출처: `metadata.ts:236-241`
|
||||||
|
|
||||||
|
단, `OTEL_LOG_TOOL_DETAILS=1` 설정 시 **전체 도구 입력이 기록된다**.
|
||||||
|
|
||||||
|
출처: `metadata.ts:86-88`
|
||||||
|
|
||||||
|
### 파일 확장자 추적
|
||||||
|
|
||||||
|
`rm, mv, cp, touch, mkdir, chmod, chown, cat, head, tail, sort, stat, diff, wc, grep, rg, sed` 관련 Bash 명령에서 파일 인자의 확장자가 추출·기록된다.
|
||||||
|
|
||||||
|
출처: `metadata.ts:340-412`
|
||||||
|
|
||||||
|
## 비활성화 문제
|
||||||
|
|
||||||
|
자사 로깅 파이프라인은 직접 Anthropic API 사용자의 경우 **비활성화할 수 없다**.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/services/analytics/firstPartyEventLogger.ts:141-144
|
||||||
|
export function is1PEventLoggingEnabled(): boolean {
|
||||||
|
return !isAnalyticsDisabled()
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
`isAnalyticsDisabled()`가 true를 반환하는 경우:
|
||||||
|
- 테스트 환경
|
||||||
|
- 서드파티 클라우드 제공자 (Bedrock, Vertex)
|
||||||
|
- 글로벌 텔레메트리 비활성화 (설정 UI에 노출되지 않음)
|
||||||
|
|
||||||
|
자사 이벤트 로깅을 비활성화하는 **사용자 대상 설정은 존재하지 않는다**.
|
||||||
|
|
||||||
|
## GrowthBook A/B 테스트
|
||||||
|
|
||||||
|
사용자는 명시적 동의 없이 GrowthBook을 통해 실험 그룹에 배정된다. 전송되는 사용자 속성:
|
||||||
|
|
||||||
|
```
|
||||||
|
- id, sessionId, deviceID
|
||||||
|
- platform, organizationUUID, subscriptionType
|
||||||
|
```
|
||||||
|
|
||||||
|
출처: `src/services/analytics/growthbook.ts`
|
||||||
|
|
||||||
|
## 핵심 요약
|
||||||
|
|
||||||
|
1. **수집량**: 세션당 수백 건의 이벤트가 수집된다
|
||||||
|
2. **비활성화 불가**: 직접 API 사용자는 자사 로깅을 끌 수 없다
|
||||||
|
3. **영속성**: 전송 실패 이벤트는 디스크에 저장되어 적극적으로 재시도된다
|
||||||
|
4. **서드파티 공유**: 데이터가 Datadog으로 전송된다
|
||||||
|
5. **도구 상세 백도어**: `OTEL_LOG_TOOL_DETAILS=1`로 전체 입력 로깅이 활성화된다
|
||||||
|
6. **저장소 핑거프린팅**: 저장소 URL이 해싱되어 서버 측 상관분석에 사용된다
|
||||||
112
docs/ko/02-숨겨진-기능과-코드네임.md
Normal file
112
docs/ko/02-숨겨진-기능과-코드네임.md
Normal file
@@ -0,0 +1,112 @@
|
|||||||
|
# 숨겨진 기능과 모델 코드네임
|
||||||
|
|
||||||
|
> 인터넷에 공개된 자료와 커뮤니티 토론을 바탕으로 정리된 Claude Code v2.1.88 분석 보고서.
|
||||||
|
|
||||||
|
## 모델 코드네임 체계
|
||||||
|
|
||||||
|
Anthropic은 내부 모델 코드네임으로 **동물 이름**을 사용한다. 외부 빌드로의 유출을 적극적으로 차단하고 있다.
|
||||||
|
|
||||||
|
### 알려진 코드네임
|
||||||
|
|
||||||
|
| 코드네임 | 역할 | 근거 |
|
||||||
|
|----------|------|------|
|
||||||
|
| **Tengu** (천구) | 제품/텔레메트리 접두사, 모델일 가능성 있음 | 250개 이상의 분석 이벤트 및 feature flag에 `tengu_*` 접두사로 사용 |
|
||||||
|
| **Capybara** (카피바라) | Sonnet 계열 모델, 현재 v8 | `capybara-v2-fast[1m]`, v8 동작 문제 패치 존재 |
|
||||||
|
| **Fennec** (페넥여우) | Opus 4.6 이전 모델 | 마이그레이션: `fennec-latest` → `opus` |
|
||||||
|
| **Numbat** (넘뱃) | 차기 모델 출시 예정 | 주석: "Remove this section when we launch numbat" |
|
||||||
|
|
||||||
|
### 코드네임 보호
|
||||||
|
|
||||||
|
`undercover` 모드에서 보호 대상 코드네임이 명시적으로 나열되어 있다:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/undercover.ts:48-49
|
||||||
|
NEVER include in commit messages or PR descriptions:
|
||||||
|
- Internal model codenames (animal names like Capybara, Tengu, etc.)
|
||||||
|
- Unreleased model version numbers (e.g., opus-4-7, sonnet-4-8)
|
||||||
|
```
|
||||||
|
|
||||||
|
빌드 시스템은 `scripts/excluded-strings.txt`를 사용하여 유출된 코드네임을 검출한다. Buddy 시스템의 종(species)은 `String.fromCharCode()`로 인코딩하여 canary 검출을 우회한다:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/buddy/types.ts:10-13
|
||||||
|
// One species name collides with a model-codename canary in excluded-strings.txt.
|
||||||
|
// The check greps build output (not source), so runtime-constructing the value keeps
|
||||||
|
// the literal out of the bundle while the check stays armed for the actual codename.
|
||||||
|
```
|
||||||
|
|
||||||
|
충돌하는 종은 **capybara** — 펫 종이자 모델 코드네임이다.
|
||||||
|
|
||||||
|
### Capybara 동작 이슈 (v8)
|
||||||
|
|
||||||
|
아키텍처에서 Capybara v8의 구체적 동작 문제가 확인된다:
|
||||||
|
|
||||||
|
1. **Stop sequence 오발동** (프롬프트 끝에 `<functions>` 있을 때 ~10% 발생)
|
||||||
|
- 출처: `src/utils/messages.ts:2141`
|
||||||
|
|
||||||
|
2. **빈 tool_result 시 출력 없음**
|
||||||
|
- 출처: `src/utils/toolResultStorage.ts:281`
|
||||||
|
|
||||||
|
3. **과도한 주석 삽입** — 전용 주석 방지 프롬프트 패치 필요
|
||||||
|
- 출처: `src/constants/prompts.ts:204`
|
||||||
|
|
||||||
|
4. **높은 허위 주장 비율**: v8은 29-30%, v4는 16.7%
|
||||||
|
- 출처: `src/constants/prompts.ts:237`
|
||||||
|
|
||||||
|
5. **불충분한 검증** — "철저함 보정값(thoroughness counterweight)" 필요
|
||||||
|
- 출처: `src/constants/prompts.ts:210`
|
||||||
|
|
||||||
|
## Feature Flag 명명 규칙
|
||||||
|
|
||||||
|
모든 feature flag는 `tengu_` 접두사에 **무작위 단어 조합**을 사용하여 목적을 난독화한다:
|
||||||
|
|
||||||
|
| Flag | 용도 |
|
||||||
|
|------|------|
|
||||||
|
| `tengu_onyx_plover` | Auto Dream (백그라운드 기억 통합) |
|
||||||
|
| `tengu_coral_fern` | memdir 기능 |
|
||||||
|
| `tengu_moth_copse` | memdir 추가 스위치 |
|
||||||
|
| `tengu_herring_clock` | Team memory |
|
||||||
|
| `tengu_passport_quail` | Path 기능 |
|
||||||
|
| `tengu_slate_thimble` | memdir 추가 스위치 |
|
||||||
|
| `tengu_sedge_lantern` | Away Summary |
|
||||||
|
| `tengu_frond_boric` | 분석 킬스위치 |
|
||||||
|
| `tengu_amber_quartz_disabled` | 음성 모드 킬스위치 |
|
||||||
|
| `tengu_amber_flint` | Agent teams |
|
||||||
|
| `tengu_hive_evidence` | 검증 에이전트 |
|
||||||
|
|
||||||
|
무작위 단어 패턴(형용사/재질 + 자연/사물)은 외부 관찰자가 flag 이름만으로 기능 목적을 추론하는 것을 방지한다.
|
||||||
|
|
||||||
|
## 내부 사용자와 외부 사용자 차이
|
||||||
|
|
||||||
|
Anthropic 직원(`USER_TYPE === 'ant'`)은 상당히 다른 대우를 받는다:
|
||||||
|
|
||||||
|
### 프롬프트 차이 (`src/constants/prompts.ts`)
|
||||||
|
|
||||||
|
| 항목 | 외부 사용자 | 내부 사용자 (ant) |
|
||||||
|
|------|------------|------------------|
|
||||||
|
| 출력 스타일 | "Be extra concise" (극도로 간결하게) | "Err on the side of more explanation" (설명을 더 하는 쪽으로) |
|
||||||
|
| 허위 주장 대응 | 없음 | 전용 Capybara v8 패치 적용 |
|
||||||
|
| 수치적 길이 기준 | 없음 | "도구 사이 ≤25단어, 최종 답변 ≤100단어" |
|
||||||
|
| 검증 에이전트 | 없음 | 비자명한 변경에 필수 적용 |
|
||||||
|
| 주석 가이드 | 일반적 | 전용 과잉 주석 방지 프롬프트 |
|
||||||
|
| 선제적 교정 | 없음 | "사용자에게 오해가 있으면 지적" |
|
||||||
|
|
||||||
|
### 도구 접근
|
||||||
|
|
||||||
|
내부 사용자만 접근 가능한 도구:
|
||||||
|
- `REPLTool` — REPL 모드
|
||||||
|
- `SuggestBackgroundPRTool` — 백그라운드 PR 제안
|
||||||
|
- `TungstenTool` — 성능 모니터링 패널
|
||||||
|
- `VerifyPlanExecutionTool` — 계획 실행 검증
|
||||||
|
- Agent 중첩 (에이전트가 에이전트를 생성)
|
||||||
|
|
||||||
|
## 숨겨진 명령어
|
||||||
|
|
||||||
|
| 명령어 | 상태 | 설명 |
|
||||||
|
|--------|------|------|
|
||||||
|
| `/btw` | 활성 | 작업 중단 없이 곁다리 질문 |
|
||||||
|
| `/stickers` | 활성 | Claude Code 스티커 주문 (브라우저 열림) |
|
||||||
|
| `/thinkback` | 활성 | 2025 연말 회고 |
|
||||||
|
| `/effort` | 활성 | 모델 노력 수준 설정 |
|
||||||
|
| `/good-claude` | 스텁 | 숨겨진 플레이스홀더 |
|
||||||
|
| `/bughunter` | 스텁 | 숨겨진 플레이스홀더 |
|
||||||
110
docs/ko/03-언더커버-모드.md
Normal file
110
docs/ko/03-언더커버-모드.md
Normal file
@@ -0,0 +1,110 @@
|
|||||||
|
# 언더커버 모드 분석
|
||||||
|
|
||||||
|
> 인터넷에 공개된 자료와 커뮤니티 토론을 바탕으로 정리된 Claude Code v2.1.88 분석 보고서.
|
||||||
|
|
||||||
|
## 언더커버 모드란?
|
||||||
|
|
||||||
|
언더커버 모드는 공식 직원이 외부/오픈소스 저장소에서 작업할 때 사용되는 안전 보호 메커니즘입니다. 활성화되면 내부 특화 AI 모델 정보와 저작 표시를 숨겨 제출된 코드가 인간 개발자의 기여와 동일하게 보이도록 합니다. 이는 주로 내부 기밀 및 미출시 모델의 이름이 오픈소스 커뮤니티에 유출되는 것을 방지하기 위함입니다.
|
||||||
|
|
||||||
|
출처: `src/utils/undercover.ts`
|
||||||
|
|
||||||
|
## 활성화 조건
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/undercover.ts:28-37
|
||||||
|
export function isUndercover(): boolean {
|
||||||
|
if (process.env.USER_TYPE === 'ant') {
|
||||||
|
if (isEnvTruthy(process.env.CLAUDE_CODE_UNDERCOVER)) return true
|
||||||
|
// Auto: 내부 저장소로 확인되지 않으면 자동 활성화
|
||||||
|
return getRepoClassCached() !== 'internal'
|
||||||
|
}
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
주요 특성:
|
||||||
|
- **내부 전용**: 공식 직원(`USER_TYPE === 'ant'`)만 해당
|
||||||
|
- **기본 활성화**: 내부 허용 목록에 없는 모든 저장소에서 자동 활성화
|
||||||
|
- **강제 비활성화 불가**: "There is NO force-OFF. This guards against model codename leaks"
|
||||||
|
- **외부 빌드**: 번들러에 의해 데드 코드 제거됨; 실행되지 않음
|
||||||
|
|
||||||
|
## 모델에 전달되는 프롬프트
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/undercover.ts:39-69
|
||||||
|
export function getUndercoverInstructions(): string {
|
||||||
|
return `## UNDERCOVER MODE — CRITICAL
|
||||||
|
|
||||||
|
You are operating UNDERCOVER in a PUBLIC/OPEN-SOURCE repository. Your commit
|
||||||
|
messages, PR titles, and PR bodies MUST NOT contain ANY Anthropic-internal
|
||||||
|
information. Do not blow your cover.
|
||||||
|
|
||||||
|
NEVER include in commit messages or PR descriptions:
|
||||||
|
- Internal model codenames (animal names like Capybara, Tengu, etc.)
|
||||||
|
- Unreleased model version numbers (e.g., opus-4-7, sonnet-4-8)
|
||||||
|
- Internal repo or project names (e.g., claude-cli-internal, anthropics/…)
|
||||||
|
- Internal tooling, Slack channels, or short links (e.g., go/cc, #claude-code-…)
|
||||||
|
- The phrase "Claude Code" or any mention that you are an AI
|
||||||
|
- Any hint of what model or version you are
|
||||||
|
- Co-Authored-By lines or any other attribution
|
||||||
|
|
||||||
|
Write commit messages as a human developer would — describe only what the code
|
||||||
|
change does.
|
||||||
|
|
||||||
|
GOOD:
|
||||||
|
- "Fix race condition in file watcher initialization"
|
||||||
|
- "Add support for custom key bindings"
|
||||||
|
|
||||||
|
BAD (never write these):
|
||||||
|
- "Fix bug found while testing with Claude Capybara"
|
||||||
|
- "1-shotted by claude-opus-4-6"
|
||||||
|
- "Generated with Claude Code"
|
||||||
|
- "Co-Authored-By: Claude Opus 4.6 <…>"`
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 저작 표시 시스템
|
||||||
|
|
||||||
|
저작 표시 시스템(`src/utils/attribution.ts`, `src/utils/commitAttribution.ts`)은 언더커버 모드를 보완한다:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/attribution.ts:70-72
|
||||||
|
// @[MODEL LAUNCH]: 아래 하드코딩된 폴백 모델 이름 업데이트
|
||||||
|
// (코드네임 유출 방지용).
|
||||||
|
// 외부 저장소에서 인식되지 않는 모델은 "Claude Opus 4.6"으로 폴백.
|
||||||
|
```
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/model/model.ts:386-392
|
||||||
|
function maskModelCodename(baseName: string): string {
|
||||||
|
// e.g. capybara-v2-fast → cap*****-v2-fast
|
||||||
|
const [codename = '', ...rest] = baseName.split('-')
|
||||||
|
const masked = codename.slice(0, 3) + '*'.repeat(Math.max(0, codename.length - 3))
|
||||||
|
return [masked, ...rest].join('-')
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 시사점
|
||||||
|
|
||||||
|
### 오픈소스에 대한 영향
|
||||||
|
|
||||||
|
공식 직원이 Claude Code로 오픈소스 프로젝트에 기여할 때:
|
||||||
|
1. AI가 코드를 작성하지만 커밋은 사람이 작성한 것으로 표시된다
|
||||||
|
2. "Co-Authored-By: Claude" 저작 표시가 없다
|
||||||
|
3. "Generated with Claude Code" 마커가 없다
|
||||||
|
4. 프로젝트 메인테이너와 커뮤니티는 AI 생성 기여를 식별할 수 없다
|
||||||
|
5. 이는 AI 기여에 관한 오픈소스 투명성 규범을 잠재적으로 위반한다
|
||||||
|
|
||||||
|
### 공식 보호 목적
|
||||||
|
|
||||||
|
명시된 주요 목적은 다음의 우발적 유출 방지:
|
||||||
|
- 내부 모델 코드네임 (경쟁 정보)
|
||||||
|
- 미공개 버전 번호 (시장 타이밍)
|
||||||
|
- 내부 인프라 세부 정보 (보안)
|
||||||
|
|
||||||
|
### 윤리적 고려사항
|
||||||
|
|
||||||
|
"Do not blow your cover(정체를 들키지 마라)"라는 표현은 AI를 잠입 요원으로 프레이밍한다. 공개 코드 기여에서의 의도적인 AI 저작 은폐는 다음과 같은 질문을 제기한다:
|
||||||
|
- 오픈소스 커뮤니티에서의 투명성
|
||||||
|
- 프로젝트 기여 가이드라인 준수 여부
|
||||||
|
- 영업비밀 보호와 기만 사이의 경계
|
||||||
161
docs/ko/04-원격-제어와-킬스위치.md
Normal file
161
docs/ko/04-원격-제어와-킬스위치.md
Normal file
@@ -0,0 +1,161 @@
|
|||||||
|
# 원격 제어 및 킬스위치
|
||||||
|
|
||||||
|
> 인터넷에 공개된 자료와 커뮤니티 토론을 바탕으로 정리된 Claude Code v2.1.88 분석 보고서.
|
||||||
|
|
||||||
|
## 개요
|
||||||
|
|
||||||
|
Claude Code는 공식 관리자(및 기업 관리자)가 원격 구성을 통해 클라이언트의 특정 동작을 관리하고 업데이트하여 시스템 보안 및 기업 규정 준수를 보장할 수 있는 원격 관리 메커니즘을 구현하고 있습니다.
|
||||||
|
|
||||||
|
## 1. 원격 관리 설정
|
||||||
|
|
||||||
|
### 구조
|
||||||
|
|
||||||
|
자격이 있는 모든 세션은 다음에서 설정을 가져온다:
|
||||||
|
```
|
||||||
|
GET /api/claude_code/settings
|
||||||
|
```
|
||||||
|
|
||||||
|
출처: `src/services/remoteManagedSettings/index.ts:105-107`
|
||||||
|
|
||||||
|
### 폴링 동작
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/services/remoteManagedSettings/index.ts:52-54
|
||||||
|
const SETTINGS_TIMEOUT_MS = 10000
|
||||||
|
const DEFAULT_MAX_RETRIES = 5
|
||||||
|
const POLLING_INTERVAL_MS = 60 * 60 * 1000 // 1시간
|
||||||
|
```
|
||||||
|
|
||||||
|
설정은 1시간마다 폴링되며, 실패 시 최대 5회 재시도한다.
|
||||||
|
|
||||||
|
### 대상 자격
|
||||||
|
|
||||||
|
- Console 사용자 (API 키): 전원 대상
|
||||||
|
- OAuth 사용자: Enterprise/C4E 및 Team 구독자만 해당
|
||||||
|
|
||||||
|
### 수락 강제 다이얼로그
|
||||||
|
|
||||||
|
원격 설정에 "위험한" 변경이 포함되면 차단 다이얼로그가 표시된다:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/services/remoteManagedSettings/securityCheck.tsx:67-73
|
||||||
|
export function handleSecurityCheckResult(result: SecurityCheckResult): boolean {
|
||||||
|
if (result === 'rejected') {
|
||||||
|
gracefulShutdownSync(1) // 종료 코드 1로 종료
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
return true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
원격 설정을 거부하면 애플리케이션이 **강제 종료된다**. 선택지는 원격 설정 수락 또는 Claude Code 종료뿐이다.
|
||||||
|
|
||||||
|
### 장애 시 동작
|
||||||
|
|
||||||
|
원격 서버 접근이 불가능하면 디스크 캐시 설정을 사용한다:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/services/remoteManagedSettings/index.ts:433-436
|
||||||
|
if (cachedSettings) {
|
||||||
|
logForDebugging('Remote settings: Using stale cache after fetch failure')
|
||||||
|
setSessionCache(cachedSettings)
|
||||||
|
return cachedSettings
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
원격 설정이 한 번 적용되면, 서버 장애 시에도 캐시가 유지된다.
|
||||||
|
|
||||||
|
## 2. Feature Flag 킬스위치
|
||||||
|
|
||||||
|
GrowthBook feature flag를 통해 여러 기능을 원격 비활성화할 수 있다:
|
||||||
|
|
||||||
|
### 권한 우회 킬스위치
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/permissions/bypassPermissionsKillswitch.ts
|
||||||
|
// Statsig 게이트를 확인하여 권한 우회를 비활성화
|
||||||
|
```
|
||||||
|
|
||||||
|
사용자 동의 없이 권한 우회 기능을 비활성화할 수 있다.
|
||||||
|
|
||||||
|
### Auto 모드 서킷 브레이커
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/permissions/autoModeState.ts
|
||||||
|
// autoModeCircuitBroken 상태로 auto 모드 재진입을 차단
|
||||||
|
```
|
||||||
|
|
||||||
|
Auto 모드를 원격으로 비활성화할 수 있다.
|
||||||
|
|
||||||
|
### Fast 모드 킬스위치
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/fastMode.ts
|
||||||
|
// /api/claude_code_penguin_mode 에서 조회
|
||||||
|
// 특정 사용자의 fast 모드를 영구 비활성화 가능
|
||||||
|
```
|
||||||
|
|
||||||
|
### 분석 싱크 킬스위치
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/services/analytics/sinkKillswitch.ts:4
|
||||||
|
const SINK_KILLSWITCH_CONFIG_NAME = 'tengu_frond_boric'
|
||||||
|
```
|
||||||
|
|
||||||
|
모든 분석 출력을 원격으로 중단할 수 있다.
|
||||||
|
|
||||||
|
### Agent Teams 킬스위치
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/agentSwarmsEnabled.ts
|
||||||
|
// 환경 변수와 GrowthBook 게이트 'tengu_amber_flint' 모두 필요
|
||||||
|
```
|
||||||
|
|
||||||
|
### 음성 모드 킬스위치
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/voice/voiceModeEnabled.ts:21
|
||||||
|
// 'tengu_amber_quartz_disabled' — 음성 모드 긴급 차단
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. 모델 오버라이드 시스템
|
||||||
|
|
||||||
|
카나리 테스트를 수행하거나 예상치 못한 온라인 상황에 대응하기 위해 시스템은 내부 직원과 같은 특정 그룹에 대해 모델 버전을 동적으로 전환하는 것을 지원합니다:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/model/antModels.ts:32-33
|
||||||
|
// @[MODEL LAUNCH]: tengu_ant_model_override에 새 ant 전용 모델 업데이트
|
||||||
|
// @[MODEL LAUNCH]: 코드네임을 scripts/excluded-strings.txt에 추가
|
||||||
|
```
|
||||||
|
|
||||||
|
`tengu_ant_model_override` GrowthBook flag로 가능한 작업:
|
||||||
|
- 기본 모델 설정
|
||||||
|
- 기본 노력 수준 설정
|
||||||
|
- 시스템 프롬프트에 내용 추가
|
||||||
|
- 커스텀 모델 별칭 정의
|
||||||
|
|
||||||
|
## 4. Penguin 모드
|
||||||
|
|
||||||
|
Fast 모드 상태는 전용 엔드포인트에서 조회한다:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/fastMode.ts
|
||||||
|
// GET /api/claude_code_penguin_mode
|
||||||
|
// API가 비활성화를 응답하면 해당 사용자에게 영구 비활성화
|
||||||
|
```
|
||||||
|
|
||||||
|
Fast 모드 가용성을 제어하는 feature flag:
|
||||||
|
- `tengu_penguins_off`
|
||||||
|
- `tengu_marble_sandcastle`
|
||||||
|
|
||||||
|
## 요약
|
||||||
|
|
||||||
|
| 메커니즘 | 범위 | 사용자 동의 |
|
||||||
|
|----------|------|------------|
|
||||||
|
| 원격 관리 설정 | Enterprise/Team | 수락 또는 종료 |
|
||||||
|
| GrowthBook feature flag | 전체 사용자 | 없음 |
|
||||||
|
| 킬스위치 | 전체 사용자 | 없음 |
|
||||||
|
| 모델 오버라이드 | 내부 (ant) | 없음 |
|
||||||
|
| Fast 모드 제어 | 전체 사용자 | 없음 |
|
||||||
|
|
||||||
|
원격 제어 인프라는 광범위합니다. 기업 관리자는 사용자가 재정의할 수 없는 정책을 강제할 수 있으며, 시스템은 중대한 문제를 해결하기 위해 기능 플래그(feature flags)를 통해 모든 사용자의 동작을 원격으로 변경할 수 있습니다.
|
||||||
167
docs/ko/05-향후-로드맵.md
Normal file
167
docs/ko/05-향후-로드맵.md
Normal file
@@ -0,0 +1,167 @@
|
|||||||
|
# 향후 로드맵 — 아키텍처에서 드러난 내용
|
||||||
|
|
||||||
|
> 인터넷에 공개된 자료와 커뮤니티 토론을 바탕으로 정리된 Claude Code v2.1.88 분석 보고서.
|
||||||
|
|
||||||
|
## 1. 차기 모델: Numbat
|
||||||
|
|
||||||
|
차기 모델 출시의 가장 구체적인 근거:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/constants/prompts.ts:402
|
||||||
|
// @[MODEL LAUNCH]: Remove this section when we launch numbat.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Numbat**(넘뱃)은 차기 모델의 코드네임이다. 이 주석은 Numbat 출시 시 출력 효율성 섹션이 개정될 것임을 나타내며, 더 나은 네이티브 출력 제어를 갖출 가능성을 시사한다.
|
||||||
|
|
||||||
|
### 향후 버전 번호
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/undercover.ts:49
|
||||||
|
- Unreleased model version numbers (e.g., opus-4-7, sonnet-4-8)
|
||||||
|
```
|
||||||
|
|
||||||
|
**Opus 4.7**과 **Sonnet 4.8**이 개발 중이다.
|
||||||
|
|
||||||
|
### 코드네임 변천
|
||||||
|
|
||||||
|
```
|
||||||
|
Fennec (페넥여우) → Opus 4.6 → [Numbat?]
|
||||||
|
Capybara (카피바라) → Sonnet v8 → [?]
|
||||||
|
Tengu (천구) → 텔레메트리/제품 접두사
|
||||||
|
```
|
||||||
|
|
||||||
|
Fennec에서 Opus로의 마이그레이션이 문서화되어 있다:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/migrations/migrateFennecToOpus.ts:7-11
|
||||||
|
// fennec-latest → opus
|
||||||
|
// fennec-latest[1m] → opus[1m]
|
||||||
|
// fennec-fast-latest → opus[1m] + fast mode
|
||||||
|
```
|
||||||
|
|
||||||
|
### MODEL LAUNCH 체크리스트
|
||||||
|
|
||||||
|
코드베이스에는 업데이트할 항목을 나열한 20개 이상의 `@[MODEL LAUNCH]` 마커가 있다:
|
||||||
|
|
||||||
|
- 기본 모델 이름 (`FRONTIER_MODEL_NAME`)
|
||||||
|
- 모델 패밀리 ID
|
||||||
|
- 지식 기준일(knowledge cutoff)
|
||||||
|
- 가격표
|
||||||
|
- 컨텍스트 윈도우 설정
|
||||||
|
- Thinking 모드 지원 플래그
|
||||||
|
- 표시 이름 매핑
|
||||||
|
- 마이그레이션 스크립트
|
||||||
|
|
||||||
|
## 2. KAIROS — 자율 에이전트 모드
|
||||||
|
|
||||||
|
최대 규모의 미공개 기능으로, KAIROS는 Claude Code를 반응형 어시스턴트에서 능동적 자율 에이전트로 변환한다.
|
||||||
|
|
||||||
|
### 시스템 프롬프트 (발췌)
|
||||||
|
|
||||||
|
```
|
||||||
|
// src/constants/prompts.ts:860-913
|
||||||
|
|
||||||
|
You are running autonomously.
|
||||||
|
You will receive <tick> prompts that keep you alive between turns.
|
||||||
|
If you have nothing useful to do, call SleepTool.
|
||||||
|
Bias toward action — read files, make changes, commit without asking.
|
||||||
|
|
||||||
|
## Terminal focus
|
||||||
|
- Unfocused: The user is away. Lean heavily into autonomous action.
|
||||||
|
- Focused: The user is watching. Be more collaborative.
|
||||||
|
```
|
||||||
|
|
||||||
|
### 관련 도구
|
||||||
|
|
||||||
|
| 도구 | Feature Flag | 용도 |
|
||||||
|
|------|-------------|------|
|
||||||
|
| SleepTool | KAIROS / PROACTIVE | 자율 동작 간 페이싱 제어 |
|
||||||
|
| SendUserFileTool | KAIROS | 사용자에게 파일 선제 전송 |
|
||||||
|
| PushNotificationTool | KAIROS / KAIROS_PUSH_NOTIFICATION | 사용자 기기에 푸시 알림 |
|
||||||
|
| SubscribePRTool | KAIROS_GITHUB_WEBHOOKS | GitHub PR 웹훅 이벤트 구독 |
|
||||||
|
| BriefTool | KAIROS_BRIEF | 선제적 상태 업데이트 |
|
||||||
|
|
||||||
|
### 동작 방식
|
||||||
|
|
||||||
|
- `<tick>` 하트비트 프롬프트로 작동
|
||||||
|
- 터미널 포커스 상태에 따라 자율성 수준 조정
|
||||||
|
- 독립적으로 커밋, 푸시, 의사결정 가능
|
||||||
|
- 선제적 알림 및 상태 업데이트 전송
|
||||||
|
- GitHub PR 변경사항 모니터링
|
||||||
|
|
||||||
|
## 3. 음성 모드
|
||||||
|
|
||||||
|
Push-to-talk 음성 입력이 완전 구현되어 있으나 `VOICE_MODE` feature flag로 차단되어 있다.
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/voice/voiceModeEnabled.ts
|
||||||
|
// Anthropic의 voice_stream WebSocket 엔드포인트에 연결
|
||||||
|
// conversation_engine 기반 모델로 음성-텍스트 변환
|
||||||
|
// 키 바인딩을 길게 눌러 녹음, 놓으면 전송
|
||||||
|
```
|
||||||
|
|
||||||
|
- OAuth 전용 (API 키 / Bedrock / Vertex 미지원)
|
||||||
|
- WebSocket 연결에 mTLS 사용
|
||||||
|
- 킬스위치: `tengu_amber_quartz_disabled`
|
||||||
|
|
||||||
|
## 4. 미공개 도구
|
||||||
|
|
||||||
|
아키텍처에 존재하지만 외부 사용자에게 아직 활성화되지 않은 도구:
|
||||||
|
|
||||||
|
| 도구 | Feature Flag | 설명 |
|
||||||
|
|------|-------------|------|
|
||||||
|
| **WebBrowserTool** | `WEB_BROWSER_TOOL` | 내장 브라우저 자동화 (코드네임: bagel) |
|
||||||
|
| **TerminalCaptureTool** | `TERMINAL_PANEL` | 터미널 패널 캡처 및 모니터링 |
|
||||||
|
| **WorkflowTool** | `WORKFLOW_SCRIPTS` | 사전 정의된 워크플로우 스크립트 실행 |
|
||||||
|
| **MonitorTool** | `MONITOR_TOOL` | 시스템/프로세스 모니터링 |
|
||||||
|
| **SnipTool** | `HISTORY_SNIP` | 대화 히스토리 잘라내기/축소 |
|
||||||
|
| **ListPeersTool** | `UDS_INBOX` | Unix 도메인 소켓 피어 탐색 |
|
||||||
|
| **RemoteTriggerTool** | `AGENT_TRIGGERS_REMOTE` | 원격 에이전트 트리거 |
|
||||||
|
| **TungstenTool** | ant 전용 | 내부 성능 모니터링 패널 |
|
||||||
|
| **VerifyPlanExecutionTool** | VERIFY_PLAN env | 계획 실행 검증 |
|
||||||
|
| **OverflowTestTool** | `OVERFLOW_TEST_TOOL` | 컨텍스트 오버플로우 테스트 |
|
||||||
|
| **SubscribePRTool** | `KAIROS_GITHUB_WEBHOOKS` | GitHub PR 웹훅 구독 |
|
||||||
|
|
||||||
|
## 5. Coordinator 모드
|
||||||
|
|
||||||
|
멀티 에이전트 조율 시스템:
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/coordinator/coordinatorMode.ts
|
||||||
|
// Feature flag: COORDINATOR_MODE
|
||||||
|
```
|
||||||
|
|
||||||
|
공유 상태와 메시징을 통한 다수 에이전트 간 조율된 작업 실행을 지원한다.
|
||||||
|
|
||||||
|
## 6. Buddy 시스템 (가상 펫)
|
||||||
|
|
||||||
|
완전한 펫 동반자 시스템이 구현되어 있으나 아직 출시되지 않았다:
|
||||||
|
|
||||||
|
- **18종**: duck, goose, blob, cat, dragon, octopus, owl, penguin, turtle, snail, ghost, axolotl, capybara, cactus, robot, rabbit, mushroom, chonk
|
||||||
|
- **5단계 희귀도**: Common (60%), Uncommon (25%), Rare (10%), Epic (4%), Legendary (1%)
|
||||||
|
- **7종 모자**: crown, tophat, propeller, halo, wizard, beanie, tinyduck
|
||||||
|
- **5가지 스탯**: DEBUGGING, PATIENCE, CHAOS, WISDOM, SNARK
|
||||||
|
- **1% 반짝이 확률**: 모든 종의 Sparkle 변형
|
||||||
|
- **결정론적 생성**: 사용자 ID 해시 기반
|
||||||
|
|
||||||
|
출처: `src/buddy/`
|
||||||
|
|
||||||
|
## 7. Dream Task
|
||||||
|
|
||||||
|
백그라운드 기억 통합 서브에이전트:
|
||||||
|
|
||||||
|
```
|
||||||
|
// src/tasks/DreamTask/
|
||||||
|
// 백그라운드에서 동작하는 자동 드리밍 기능
|
||||||
|
// 'tengu_onyx_plover' feature flag로 제어
|
||||||
|
```
|
||||||
|
|
||||||
|
유휴 시간 중 AI가 자율적으로 기억을 처리하고 통합할 수 있게 한다.
|
||||||
|
|
||||||
|
## 요약: 세 가지 방향
|
||||||
|
|
||||||
|
1. **신규 모델**: Numbat (차기), Opus 4.7, Sonnet 4.8 개발 중
|
||||||
|
2. **자율 에이전트**: KAIROS 모드 — 무인 운영, 선제적 행동, 푸시 알림
|
||||||
|
3. **멀티모달**: 음성 입력 준비 완료, 브라우저 도구 대기 중, 워크플로우 자동화 예정
|
||||||
|
|
||||||
|
Claude Code는 **코딩 어시스턴트**에서 **상시 가동 자율 개발 에이전트**로 진화하고 있다.
|
||||||
109
docs/zh/01-遥测与隐私分析.md
Normal file
109
docs/zh/01-遥测与隐私分析.md
Normal file
@@ -0,0 +1,109 @@
|
|||||||
|
# 遥测与隐私分析
|
||||||
|
|
||||||
|
> 基于网络公开资料与社区讨论整理的 Claude Code v2.1.88 分析报告。
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
Claude Code 实现了双层分析管道，收集大量环境和使用元数据。虽然没有证据表明存在键盘记录或源代码窃取，但收集范围之广和无法完全退出的事实引发了合理的隐私担忧。
|
||||||
|
|
||||||
|
## 数据管道架构
|
||||||
|
|
||||||
|
### 第一方日志 (1P)
|
||||||
|
|
||||||
|
- **端点**: `https://api.anthropic.com/api/event_logging/batch`
|
||||||
|
- **协议**: OpenTelemetry + Protocol Buffers
|
||||||
|
- **批量大小**: 每批最多 200 个事件，每 10 秒刷新一次
|
||||||
|
- **重试机制**: 二次方退避，最多 8 次尝试，失败事件持久化到磁盘
|
||||||
|
- **存储位置**: `~/.claude/telemetry/`
|
||||||
|
|
||||||
|
来源: `src/services/analytics/firstPartyEventLoggingExporter.ts`
|
||||||
|
|
||||||
|
### 第三方日志 (Datadog)
|
||||||
|
|
||||||
|
- **端点**: `https://http-intake.logs.us5.datadoghq.com/api/v2/logs`
|
||||||
|
- **范围**: 仅限 64 种预批准事件类型
|
||||||
|
- **Token**: `pubbbf48e6d78dae54bceaa4acf463299bf`
|
||||||
|
|
||||||
|
来源: `src/services/analytics/datadog.ts`
|
||||||
|
|
||||||
|
## 收集了什么
|
||||||
|
|
||||||
|
### 环境指纹
|
||||||
|
|
||||||
|
每个事件都携带以下元数据 (`src/services/analytics/metadata.ts:417-452`)：
|
||||||
|
|
||||||
|
```
|
||||||
|
- platform, platformRaw, arch, nodeVersion
|
||||||
|
- 终端类型
|
||||||
|
- 已安装的包管理器和运行时
|
||||||
|
- CI/CD 检测、GitHub Actions 元数据
|
||||||
|
- WSL 版本、Linux 发行版、内核版本
|
||||||
|
- 版本控制系统类型
|
||||||
|
- Claude Code 版本和构建时间
|
||||||
|
- 部署环境
|
||||||
|
```
|
||||||
|
|
||||||
|
### 进程指标 (`metadata.ts:457-467`)
|
||||||
|
|
||||||
|
```
|
||||||
|
- 运行时间、rss、heapTotal、heapUsed
|
||||||
|
- CPU 使用率和百分比
|
||||||
|
- 内存占用详情
|
||||||
|
```
|
||||||
|
|
||||||
|
### 用户追踪 (`metadata.ts:472-496`)
|
||||||
|
|
||||||
|
```
|
||||||
|
- 正在使用的模型
|
||||||
|
- 会话 ID、用户 ID、设备 ID
|
||||||
|
- 账户 UUID、组织 UUID
|
||||||
|
- 订阅等级 (max, pro, enterprise, team)
|
||||||
|
- 仓库远程 URL 哈希 (SHA256 前 16 位)
|
||||||
|
- 代理类型、团队名、父会话 ID
|
||||||
|
```
|
||||||
|
|
||||||
|
### 工具输入日志
|
||||||
|
|
||||||
|
默认截断工具输入：
|
||||||
|
|
||||||
|
```
|
||||||
|
- 字符串: 512 字符处截断，显示 128 + 省略号
|
||||||
|
- JSON: 限制 4,096 字符
|
||||||
|
- 数组: 最多 20 项
|
||||||
|
- 嵌套对象: 最多 2 层
|
||||||
|
```
|
||||||
|
|
||||||
|
然而，当设置 `OTEL_LOG_TOOL_DETAILS=1` 时，**完整工具输入会被记录**。
|
||||||
|
|
||||||
|
### 文件扩展名追踪
|
||||||
|
|
||||||
|
涉及 `rm, mv, cp, touch, mkdir, chmod, chown, cat, head, tail, sort, stat, diff, wc, grep, rg, sed` 的 Bash 命令，其文件参数的扩展名会被提取并记录。
|
||||||
|
|
||||||
|
## 无法退出的问题
|
||||||
|
|
||||||
|
第一方日志管道**无法被关闭**（对于直接使用 Anthropic API 的用户）。
|
||||||
|
|
||||||
|
`isAnalyticsDisabled()` 仅在以下情况返回 true：
|
||||||
|
- 测试环境
|
||||||
|
- 第三方云提供商 (Bedrock, Vertex)
|
||||||
|
- 全局遥测退出（设置界面未暴露此选项）
|
||||||
|
|
||||||
|
**没有面向用户的设置可以禁用第一方事件日志。**
|
||||||
|
|
||||||
|
## GrowthBook A/B 测试
|
||||||
|
|
||||||
|
用户在不知情的情况下被分配到实验组。系统发送的用户属性包括：
|
||||||
|
|
||||||
|
```
|
||||||
|
- id, sessionId, deviceID
|
||||||
|
- platform, organizationUUID, subscriptionType
|
||||||
|
```
|
||||||
|
|
||||||
|
## 关键结论
|
||||||
|
|
||||||
|
1. **体量**: 每个会话收集数百个事件
|
||||||
|
2. **无法退出**: 直接 API 用户无法禁用第一方日志
|
||||||
|
3. **持久化**: 失败事件保存到磁盘并积极重试
|
||||||
|
4. **第三方共享**: 数据发送到 Datadog
|
||||||
|
5. **工具详情后门**: `OTEL_LOG_TOOL_DETAILS=1` 启用完整输入记录
|
||||||
|
6. **仓库指纹**: 仓库 URL 被哈希后发送用于服务端关联
|
||||||
82
docs/zh/02-隐藏功能与模型代号.md
Normal file
82
docs/zh/02-隐藏功能与模型代号.md
Normal file
@@ -0,0 +1,82 @@
|
|||||||
|
# 隐藏功能与模型代号
|
||||||
|
|
||||||
|
> 基于网络公开资料与社区讨论整理的 Claude Code v2.1.88 分析报告。
|
||||||
|
|
||||||
|
## 模型代号体系
|
||||||
|
|
||||||
|
Anthropic 使用**动物名称**作为内部模型代号。这些代号被严格保护，防止泄露到外部构建中。
|
||||||
|
|
||||||
|
### 已知代号
|
||||||
|
|
||||||
|
| 代号 | 角色 | 证据 |
|
||||||
|
|------|------|------|
|
||||||
|
| **Tengu**（天狗） | 产品/遥测前缀，也可能是模型 | 所有 250+ 分析事件和 feature flag 使用 `tengu_*` 前缀 |
|
||||||
|
| **Capybara**（水豚） | Sonnet 系列模型，当前版本 v8 | `capybara-v2-fast[1m]`，v8 行为问题的 prompt 补丁 |
|
||||||
|
| **Fennec**（耳廓狐） | Opus 4.6 的前代 | 迁移: `fennec-latest` → `opus` |
|
||||||
|
| **Numbat**（袋食蚁兽） | 下一代模型 | 注释: "Remove this section when we launch numbat" |
|
||||||
|
|
||||||
|
### 代号保护机制
|
||||||
|
|
||||||
|
Undercover 模式明确列出了受保护的代号：
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/undercover.ts:48-49
|
||||||
|
NEVER include in commit messages or PR descriptions:
|
||||||
|
- Internal model codenames (animal names like Capybara, Tengu, etc.)
|
||||||
|
- Unreleased model version numbers (e.g., opus-4-7, sonnet-4-8)
|
||||||
|
```
|
||||||
|
|
||||||
|
构建系统使用 `scripts/excluded-strings.txt` 扫描泄露的代号。Buddy 系统的物种通过 `String.fromCharCode()` 编码以避免触发金丝雀检查：
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/buddy/types.ts:10-13
|
||||||
|
// One species name collides with a model-codename canary in excluded-strings.txt.
|
||||||
|
// 运行时构造值，保持字面量不出现在构建产物中
|
||||||
|
```
|
||||||
|
|
||||||
|
那个冲突的物种就是 **capybara** — 既是宠物物种又是模型代号。
|
||||||
|
|
||||||
|
### Capybara v8 的行为问题
|
||||||
|
|
||||||
|
架构揭示了 Capybara v8 的具体行为问题：
|
||||||
|
|
||||||
|
1. **停止序列误触发** (~10% 概率) — prompt 尾部出现 `<functions>` 时
|
||||||
|
2. **空 tool_result 导致零输出** — 需要注入 marker workaround
|
||||||
|
3. **过度写注释** — 需要专门的反注释 prompt 补丁
|
||||||
|
4. **高虚假声明率**: v8 为 29-30%，而 v4 为 16.7%
|
||||||
|
5. **验证不足** — 需要 "thoroughness counterweight" 补丁
|
||||||
|
|
||||||
|
## Feature Flag 命名约定
|
||||||
|
|
||||||
|
所有 feature flag 使用 `tengu_` 前缀 + **随机词对**以掩盖用途：
|
||||||
|
|
||||||
|
| Flag | 用途 |
|
||||||
|
|------|------|
|
||||||
|
| `tengu_onyx_plover` | Auto Dream（后台记忆整理）|
|
||||||
|
| `tengu_coral_fern` | memdir 功能 |
|
||||||
|
| `tengu_herring_clock` | 团队内存 |
|
||||||
|
| `tengu_frond_boric` | 分析 kill switch |
|
||||||
|
| `tengu_amber_quartz_disabled` | 语音模式 kill switch |
|
||||||
|
| `tengu_amber_flint` | 代理团队 |
|
||||||
|
|
||||||
|
## 内外部用户的差异
|
||||||
|
|
||||||
|
Anthropic 员工 (`USER_TYPE === 'ant'`) 获得显著更好的待遇：
|
||||||
|
|
||||||
|
| 维度 | 外部用户 | 内部用户 (ant) |
|
||||||
|
|------|---------|--------------|
|
||||||
|
| 输出风格 | "尽量简洁" | "倾向于更多解释" |
|
||||||
|
| 虚假声明缓解 | 无 | 专门的 Capybara v8 补丁 |
|
||||||
|
| 数值长度锚定 | 无 | "工具间 ≤25 词，最终回复 ≤100 词" |
|
||||||
|
| 验证代理 | 无 | 非简单改动必须启用 |
|
||||||
|
| 主动性 | 无 | "发现用户误解要指出" |
|
||||||
|
|
||||||
|
## 隐藏命令
|
||||||
|
|
||||||
|
| 命令 | 状态 | 描述 |
|
||||||
|
|------|------|------|
|
||||||
|
| `/btw` | 活跃 | 顺带提问，不打断主对话 |
|
||||||
|
| `/stickers` | 活跃 | 订购 Claude Code 贴纸 |
|
||||||
|
| `/thinkback` | 活跃 | 2025 年度回顾 |
|
||||||
|
| `/good-claude` | 占位 | 隐藏的 stub 命令 |
|
||||||
|
| `/bughunter` | 占位 | 隐藏的 stub 命令 |
|
||||||
94
docs/zh/03-卧底模式分析.md
Normal file
94
docs/zh/03-卧底模式分析.md
Normal file
@@ -0,0 +1,94 @@
|
|||||||
|
# 卧底模式分析
|
||||||
|
|
||||||
|
> 基于网络公开资料与社区讨论整理的 Claude Code v2.1.88 分析报告。
|
||||||
|
|
||||||
|
## 什么是卧底模式？
|
||||||
|
|
||||||
|
卧底模式是供官方内部员工在外部/开源仓库工作时使用的一种安全防护机制。激活后，系统会隐藏内部特有的 AI 模型信息及归属标识，使提交的代码与人类开发者的贡献形式保持一致。此举主要为了防止内部机密和未发布模型的名称在开源社区中泄露。
|
||||||
|
|
||||||
|
来源: `src/utils/undercover.ts`
|
||||||
|
|
||||||
|
## 激活逻辑
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/undercover.ts:28-37
|
||||||
|
export function isUndercover(): boolean {
|
||||||
|
if (process.env.USER_TYPE === 'ant') {
|
||||||
|
if (isEnvTruthy(process.env.CLAUDE_CODE_UNDERCOVER)) return true
|
||||||
|
// 自动模式：除非确认在白名单内部仓库，否则默认激活
|
||||||
|
return getRepoClassCached() !== 'internal'
|
||||||
|
}
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
关键特性：
|
||||||
|
- **仅限内部**: 只对官方员工 (`USER_TYPE === 'ant'`) 生效
|
||||||
|
- **默认开启**: 在所有仓库中激活，除非在内部白名单上
|
||||||
|
- **无法强制关闭**: 为了防止模型代号泄露，没有提供关闭选项
|
||||||
|
- **外部构建**: 对普通用户版本不生效，相关代码在打包时会被消除
|
||||||
|
|
||||||
|
## 给模型的指令
|
||||||
|
|
||||||
|
```
|
||||||
|
## UNDERCOVER MODE — CRITICAL
|
||||||
|
|
||||||
|
You are operating UNDERCOVER in a PUBLIC/OPEN-SOURCE repository.
|
||||||
|
Do not blow your cover.
|
||||||
|
|
||||||
|
NEVER include in commit messages or PR descriptions:
|
||||||
|
- 内部模型代号（如 Capybara, Tengu 等动物名称）
|
||||||
|
- 未发布的模型版本号（如 opus-4-7, sonnet-4-8）
|
||||||
|
- 内部仓库或项目名（如 claude-cli-internal）
|
||||||
|
- 内部工具、Slack 频道或短链接
|
||||||
|
- "Claude Code" 这个词或任何你是 AI 的暗示
|
||||||
|
- 任何关于你是什么模型或版本的提示
|
||||||
|
- Co-Authored-By 行或任何其他归属
|
||||||
|
|
||||||
|
像人类开发者一样写 commit message。
|
||||||
|
|
||||||
|
好:
|
||||||
|
- "Fix race condition in file watcher initialization"
|
||||||
|
|
||||||
|
坏:
|
||||||
|
- "Fix bug found while testing with Claude Capybara"
|
||||||
|
- "Generated with Claude Code"
|
||||||
|
- "Co-Authored-By: Claude Opus 4.6 <…>"
|
||||||
|
```
|
||||||
|
|
||||||
|
关键词：**"Do not blow your cover"**（旨在要求模型隐藏其内部身份，确保不会在外部泄露未公开信息）。
|
||||||
|
|
||||||
|
## 归属系统
|
||||||
|
|
||||||
|
归属系统同样配合了这一模式：
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/model/model.ts:386-392
|
||||||
|
function maskModelCodename(baseName: string): string {
|
||||||
|
// capybara-v2-fast → cap*****-v2-fast
|
||||||
|
const [codename = '', ...rest] = baseName.split('-')
|
||||||
|
const masked = codename.slice(0, 3) + '*'.repeat(Math.max(0, codename.length - 3))
|
||||||
|
return [masked, ...rest].join('-')
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
## 影响
|
||||||
|
|
||||||
|
### 对开源社区的影响
|
||||||
|
|
||||||
|
当官方员工使用 Claude Code 参与开源项目时：
|
||||||
|
1. 提交记录不会带有 "Co-Authored-By: Claude" 等明显的 AI 署名
|
||||||
|
2. 缺乏 "Generated with Claude Code" 等标记
|
||||||
|
3. 这在一定程度上模糊了代码是由 AI 辅助生成还是由人类直接编写的界限
|
||||||
|
4. 在开源社区中，有关 AI 贡献的透明度规范正在建立，这种做法可能引发一些关于透明度的讨论
|
||||||
|
|
||||||
|
### 对官方的保护
|
||||||
|
|
||||||
|
主要声明的目的是防止意外泄露公司机密：
|
||||||
|
- 内部模型代号（涉及竞争情报）
|
||||||
|
- 未发布的版本号（涉及产品发布节奏）
|
||||||
|
- 内部基础设施细节（涉及系统安全）
|
||||||
|
|
||||||
|
### 行业考量
|
||||||
|
|
||||||
|
"卧底模式" 这种设计展现了企业在保护商业机密与遵循开源透明度之间所面临的平衡挑战。在公开代码贡献中隐去 AI 身份，一方面有效防止了机密泄露，但另一方面也引发了业界关于代码归属透明度和贡献指南遵循情况的思考。
|
||||||
120
docs/zh/04-远程控制与紧急开关.md
Normal file
120
docs/zh/04-远程控制与紧急开关.md
Normal file
@@ -0,0 +1,120 @@
|
|||||||
|
# 远程控制与紧急开关
|
||||||
|
|
||||||
|
> 基于网络公开资料与社区讨论整理的 Claude Code v2.1.88 分析报告。
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
Claude Code 实现了远程管理机制，允许官方（和企业管理员）通过远程配置来管理和更新客户端的特定行为，以确保系统安全和企业合规。
|
||||||
|
|
||||||
|
## 1. 远程托管设置
|
||||||
|
|
||||||
|
### 架构
|
||||||
|
|
||||||
|
客户端会从以下端点获取最新的配置信息：
|
||||||
|
```
|
||||||
|
GET /api/claude_code/settings
|
||||||
|
```
|
||||||
|
|
||||||
|
来源: `src/services/remoteManagedSettings/index.ts`
|
||||||
|
|
||||||
|
### 轮询行为
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
const POLLING_INTERVAL_MS = 60 * 60 * 1000 // 每小时
|
||||||
|
const DEFAULT_MAX_RETRIES = 5
|
||||||
|
```
|
||||||
|
|
||||||
|
系统默认每小时检查一次更新，以确保配置的及时性。
|
||||||
|
|
||||||
|
### 适用范围
|
||||||
|
|
||||||
|
- Console 用户 (API key): 默认适用
|
||||||
|
- OAuth 用户: 主要面向 Enterprise/C4E 和 Team 订阅者进行企业级管控
|
||||||
|
|
||||||
|
### 安全变更确认
|
||||||
|
|
||||||
|
当远程设置涉及关键或敏感的权限变更时，系统会弹出确认提示框：
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/services/remoteManagedSettings/securityCheck.tsx:67-73
|
||||||
|
export function handleSecurityCheckResult(result: SecurityCheckResult): boolean {
|
||||||
|
if (result === 'rejected') {
|
||||||
|
gracefulShutdownSync(1) // 拒绝后安全退出
|
||||||
|
return false
|
||||||
|
}
|
||||||
|
return true
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
为了保障环境安全，如果用户拒绝了必须的安全配置更新，程序将安全退出。这是一种常见的强制合规策略。
|
||||||
|
|
||||||
|
### 故障容灾
|
||||||
|
|
||||||
|
当远程服务器不可达时，系统会回退使用本地缓存的配置，保证基础功能的可用性。
|
||||||
|
|
||||||
|
## 2. 功能开关 (Feature Flags)
|
||||||
|
|
||||||
|
系统使用 GrowthBook feature flag 实现了灵活的功能管控，可以在发现严重问题时紧急禁用特定功能：
|
||||||
|
|
||||||
|
### 权限绕过功能管控
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/permissions/bypassPermissionsKillswitch.ts
|
||||||
|
// 用于在必要时关闭"绕过权限"功能，防止安全风险
|
||||||
|
```
|
||||||
|
|
||||||
|
### 自动模式断路器
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/permissions/autoModeState.ts
|
||||||
|
// autoModeCircuitBroken 状态用于在异常情况下暂停自动模式
|
||||||
|
```
|
||||||
|
|
||||||
|
### 快速模式开关
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/fastMode.ts
|
||||||
|
// 从 /api/claude_code_penguin_mode 获取状态
|
||||||
|
// 动态管理快速模式的可用性
|
||||||
|
```
|
||||||
|
|
||||||
|
### 数据上报通道控制
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/services/analytics/sinkKillswitch.ts:4
|
||||||
|
const SINK_KILLSWITCH_CONFIG_NAME = 'tengu_frond_boric'
|
||||||
|
```
|
||||||
|
|
||||||
|
### 语音模式开关
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/voice/voiceModeEnabled.ts:21
|
||||||
|
// 'tengu_amber_quartz_disabled' — 用于在发现语音模块缺陷时紧急关闭
|
||||||
|
```
|
||||||
|
|
||||||
|
## 3. 模型覆盖系统
|
||||||
|
|
||||||
|
为了进行灰度测试或应对线上突发情况，系统支持对内部员工等特定群体进行模型版本的动态切换：
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/utils/model/antModels.ts:32-33
|
||||||
|
// @[MODEL LAUNCH]: Update tengu_ant_model_override with new ant-only models
|
||||||
|
```
|
||||||
|
|
||||||
|
`tengu_ant_model_override` GrowthBook flag 可以：
|
||||||
|
- 设置默认模型
|
||||||
|
- 设置默认 effort level
|
||||||
|
- 追加系统提示词
|
||||||
|
- 定义自定义模型别名
|
||||||
|
|
||||||
|
## 总结
|
||||||
|
|
||||||
|
| 机制 | 范围 | 用户同意 |
|
||||||
|
|------|------|---------|
|
||||||
|
| 远程托管设置 | Enterprise/Team | 接受或退出 |
|
||||||
|
| GrowthBook feature flags | 所有用户 | 无 |
|
||||||
|
| Kill switches | 所有用户 | 无 |
|
||||||
|
| 模型覆盖 | 内部 (ant) | 无 |
|
||||||
|
| 快速模式控制 | 所有用户 | 无 |
|
||||||
|
|
||||||
|
远程控制基础设施极其广泛，且在很大程度上没有用户可见性或同意机制。企业管理员可以强制执行用户无法覆盖的策略，Anthropic 可以通过 feature flag 远程更改任何用户的行为。
|
||||||
123
docs/zh/05-未来路线图.md
Normal file
123
docs/zh/05-未来路线图.md
Normal file
@@ -0,0 +1,123 @@
|
|||||||
|
# 未来路线图 — 架构揭示的方向
|
||||||
|
|
||||||
|
> 基于网络公开资料与社区讨论整理的 Claude Code v2.1.88 分析报告。
|
||||||
|
|
||||||
|
## 1. 下一代模型: Numbat
|
||||||
|
|
||||||
|
从公开资料中的架构推测来看：
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// 架构内部推断代码片段
|
||||||
|
// @[MODEL LAUNCH]: Remove this section when we launch numbat.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Numbat（袋食蚁兽）** 似乎是即将发布的模型代号。资料暗示 Numbat 发布时可能会移除某些当前的输出控制逻辑，这意味着新模型可能有更好的原生输出能力。
|
||||||
|
|
||||||
|
### 未来版本号
|
||||||
|
|
||||||
|
公开的讨论中提到了一些可能的版本号：
|
||||||
|
- Unreleased model version numbers (e.g., opus-4-7, sonnet-4-8)
|
||||||
|
|
||||||
|
**Opus 4.7** 和 **Sonnet 4.8** 似乎正在开发中。
|
||||||
|
|
||||||
|
### 代号演化链
|
||||||
|
|
||||||
|
从社区的猜测来看，代号的演化链可能是：
|
||||||
|
```
|
||||||
|
Fennec（耳廓狐） → Opus 4.6 → [Numbat?]
|
||||||
|
Capybara（水豚） → Sonnet v8 → [?]
|
||||||
|
Tengu（天狗） → 遥测/产品前缀
|
||||||
|
```
|
||||||
|
|
||||||
|
### 模型发布清单
|
||||||
|
|
||||||
|
从网上整理的资料来看，架构中预留了许多 `@[MODEL LAUNCH]` 的标记，用于在未来新模型发布时更新配置，例如：
|
||||||
|
- 默认模型名称
|
||||||
|
- 知识截止日期
|
||||||
|
- 定价表
|
||||||
|
- 上下文窗口配置
|
||||||
|
- Thinking 模式支持
|
||||||
|
- 迁移脚本
|
||||||
|
|
||||||
|
## 2. KAIROS — 自主代理模式
|
||||||
|
|
||||||
|
被社区广泛讨论的未发布特性之一，KAIROS 似乎旨在将 Claude Code 从被动助手转变为主动自主代理。
|
||||||
|
|
||||||
|
### 行为预期（根据公开资料推测）
|
||||||
|
|
||||||
|
```text
|
||||||
|
# 预期系统逻辑
|
||||||
|
代理将处于自主运行状态。
|
||||||
|
系统可能通过心跳信号（如 <tick>）保持代理活跃。
|
||||||
|
如果没有有用的事可做，代理可能会调用休眠功能。
|
||||||
|
在适当的情况下，代理可能会主动行动——读取文件、做修改、提交，无需用户每次确认。
|
||||||
|
```
|
||||||
|
|
||||||
|
### 关联工具推测
|
||||||
|
|
||||||
|
根据公开的讨论，可能涉及以下工具：
|
||||||
|
|
||||||
|
| 工具 | 用途推测 |
|
||||||
|
|------|------|
|
||||||
|
| SleepTool | 控制自主操作间的节奏 |
|
||||||
|
| SendUserFileTool | 主动向用户发送文件 |
|
||||||
|
| PushNotificationTool | 推送通知到用户设备 |
|
||||||
|
| SubscribePRTool | 订阅 GitHub PR webhook 事件 |
|
||||||
|
| BriefTool | 主动状态更新 |
|
||||||
|
|
||||||
|
### 行为特征
|
||||||
|
|
||||||
|
- 通过心跳机制保持活跃
|
||||||
|
- 根据用户在终端的活跃状态调整自主程度
|
||||||
|
- 可以独立 commit、push 和做决策
|
||||||
|
- 发送主动通知和状态更新
|
||||||
|
- 监控代码仓库（如 GitHub）的变更
|
||||||
|
|
||||||
|
## 3. 语音模式
|
||||||
|
|
||||||
|
有资料显示，语音交互的基础设施可能已经在开发中，但目前尚未对外开放：
|
||||||
|
|
||||||
|
- **Push-to-Talk**: 可能实现类似对讲机的界面
|
||||||
|
- **Audio Capture**: 通过原生模块集成
|
||||||
|
- 仅限特定认证用户使用
|
||||||
|
|
||||||
|
## 4. 未上线工具
|
||||||
|
|
||||||
|
根据社区挖掘的信息，以下工具可能在开发计划中但尚未对外部用户开放：
|
||||||
|
|
||||||
|
| 工具 | 描述推测 |
|
||||||
|
|------|-------------|
|
||||||
|
| **WebBrowserTool** | 内置浏览器自动化，超越简单的网页抓取 |
|
||||||
|
| **TerminalCaptureTool** | 终端面板捕获和监控 |
|
||||||
|
| **WorkflowTool** | 执行预定义工作流脚本 |
|
||||||
|
| **MonitorTool** | 系统/进程监控 |
|
||||||
|
| **SnipTool** | 对话历史智能裁剪 |
|
||||||
|
| **ListPeersTool** | 用于代理间的对等发现 |
|
||||||
|
|
||||||
|
## 5. 协调器模式
|
||||||
|
|
||||||
|
多代理协调系统：
|
||||||
|
|
||||||
|
旨在支持多个代理之间的协调任务执行，可能具有共享状态和消息传递机制。
|
||||||
|
|
||||||
|
## 6. 虚拟宠物系统 (Buddy)
|
||||||
|
|
||||||
|
有传言称一个完整的虚拟宠物系统正在开发中，可能包含：
|
||||||
|
|
||||||
|
- **多种物种**: 如鸭子、鹅、猫、龙、章鱼等
|
||||||
|
- **不同稀有度**: 从普通到传说
|
||||||
|
- **个性化属性**: 如 DEBUGGING、PATIENCE 等
|
||||||
|
- 基于用户 ID 的确定性生成
|
||||||
|
|
||||||
|
## 7. 后台记忆整固
|
||||||
|
|
||||||
|
有资料提到一个类似"做梦"的后台任务，旨在使 AI 能在空闲时间自主处理和整固记忆。
|
||||||
|
|
||||||
|
## 总结：三大方向
|
||||||
|
|
||||||
|
从目前的公开资料来看，Claude Code 可能在以下几个方向演进：
|
||||||
|
1. **新模型**: Numbat（下一代）、Opus 4.7、Sonnet 4.8
|
||||||
|
2. **自主代理**: KAIROS 模式 — 无人值守运行、主动行动、推送通知
|
||||||
|
3. **多模态与自动化**: 语音输入、浏览器自动化、工作流自动化
|
||||||
|
|
||||||
|
Claude Code 似乎正计划从一个**编程助手**进化为一个**全天候自主开发代理**。
|
||||||
Reference in New Issue
Block a user