erbilnas/clawd-code
GitHub: erbilnas/clawd-code
一个为教育和防御性安全研究提供的TypeScript源代码静态镜像，专注于软件供应链分析和架构评审。
Stars: 30 | Forks: 40
# Clawd Code — 安全研究镜像
本仓库托管了一个用于**教育用途、防御性安全研究和软件供应链分析**的 **TypeScript `src/` 目录树的静态镜像**。它由一名独立的大学生作为个人研究项目维护。
**命名说明。** **Splinterworks**、**Clawd** 和 **Clawd Code** 是对供应商、助手和终端编码智能体 CLI 的虚构代称——其用意类似于用 **Macrohard** 指代一家大型软件公司。它们为这个镜像定义了一种 _产品风格_，而非真实存在的商业品牌。
## 重要声明
**请在使用或再分发本仓库中的任何内容前，阅读此部分。**
## 目的与可接受用途
- 研究真实世界 CLI 工具中的**构建产物、打包和发布流程风险**
- 对智能体开发工具进行**安全软件工程**与**防御性分析**
- 此类系统的**架构评审**与结构讨论
请仅在符合适用法律和第三方条款的方式下使用本仓库。**请勿**使用本仓库损害他人、绕过安全措施或滥用上游服务。
## 背景（概要）
2026年3月的公开讨论指出，与某个 **npm** 发行版相关的**源映射**产物可能使得 **TypeScript 源码**比预期更易获取。
## 仓库内容
该目录树包含了一个保留用于研究和分析的镜像 **`src/`** 快照。
**Clawd Code**（上游）是一个终端导向的 CLI，与 Splinterworks 的编码助手栈配合使用，用于执行文件编辑、运行命令、搜索代码库和协调工作流等任务。**此镜像不是官方产品的受支持构建、分叉或替代品。**
| 属性 | 详情 |
| ---------------------- | ------------------------------------------------ |
| 快照背景 | 2026-03-31 公开讨论 |
| 编程语言 | TypeScript |
| 运行时（上游） | Bun |
| 终端 UI（上游） | React + [Ink](https://github.com/vadimdemedes/ink) |
| 规模（近似） | ~1,900 文件，512,000+ 行代码 |
## 文档（VitePress）
`src/` 目录树的可导航文档位于 [`docs/`](docs/) 目录下。它镜像并扩展了本 README，形成侧边栏导航（指南、架构、参考），并包含了一个顶层 `src/` 条目的生成索引。
从仓库根目录运行：
```
npm install
npm run docs:dev # local dev server
npm run docs:gen # regenerate docs/reference/src-index.md
npm run docs:build # production build (runs docs:gen first; output in docs/.vitepress/dist)
npm run docs:preview # preview the production build
```
## 下架与联系
如果您是权利持有人或授权代表，并认为本仓库中的材料侵犯了您的权利或违反了适用法律，**请联系维护者**：在本仓库创建一个 **GitHub Issue**（或使用维护者在其 GitHub 个人资料上公布的任何联系方式）。
在收到**有效的法律通知**后（例如，在适用情况下满足法定要求的 DMCA 通知），维护者将**及时审查**，并在适当时**禁用或移除**被标识的内容或该仓库。善意合作不放弃任何一方的法律权利或救济。
## 目录结构
```
src/
├── main.tsx # Entrypoint orchestration (Commander.js-based CLI path)
├── commands.ts # Command registry
├── tools.ts # Tool registry
├── Tool.ts # Tool type definitions
├── QueryEngine.ts # LLM query engine
├── context.ts # System/user context collection
├── cost-tracker.ts # Token cost tracking
│
├── commands/ # Slash command implementations (~50)
├── tools/ # Agent tool implementations (~40)
├── components/ # Ink UI components (~140)
├── hooks/ # React hooks
├── services/ # External service integrations
├── screens/ # Full-screen UIs (Doctor, REPL, Resume)
├── types/ # TypeScript type definitions
├── utils/ # Utility functions
│
├── bridge/ # IDE and remote-control bridge
├── coordinator/ # Multi-agent coordinator
├── plugins/ # Plugin system
├── skills/ # Skill system
├── keybindings/ # Keybinding configuration
├── vim/ # Vim mode
├── voice/ # Voice input
├── remote/ # Remote sessions
├── server/ # Server mode
├── memdir/ # Persistent memory directory
├── tasks/ # Task management
├── state/ # State management
├── migrations/ # Config migrations
├── schemas/ # Config schemas (Zod)
├── entrypoints/ # Initialization logic
├── ink/ # Ink renderer wrapper
├── buddy/ # Companion sprite
├── native-ts/ # Native TypeScript utilities
├── outputStyles/ # Output styling
├── query/ # Query pipeline
└── upstreamproxy/ # Proxy configuration
```
## 架构概要
以下描述了在镜像目录树中为研究目的而**观察到的结构**。这是**描述性分析**，并非官方产品文档。
### 1. 工具系统 (`src/tools/`)
每个可调用工具都实现为一个独立的模块，定义了输入模式、权限模型和执行逻辑。
| 工具 | 描述 |
| ------------------------------------------ | ---------------------------------------------- |
| `BashTool` | Shell 命令执行 |
| `FileReadTool` | 文件读取（图像、PDF、笔记本） |
| `FileWriteTool` | 文件创建/覆盖 |
| `FileEditTool` | 文件部分修改（字符串替换） |
| `GlobTool` | 文件模式匹配搜索 |
| `GrepTool` | 基于 ripgrep 的内容搜索 |
| `WebFetchTool` | 获取 URL 内容 |
| `WebSearchTool` | 网络搜索 |
| `AgentTool` | 子智能体生成 |
| `SkillTool` | 技能执行 |
| `MCPTool` | MCP 服务器工具调用 |
| `LSPTool` | 语言服务器协议集成 |
| `NotebookEditTool` | Jupyter 笔记本编辑 |
| `TaskCreateTool` / `TaskUpdateTool` | 任务创建与管理 |
| `SendMessageTool` | 智能体间消息传递 |
| `TeamCreateTool` / `TeamDeleteTool` | 团队智能体管理 |
| `EnterPlanModeTool` / `ExitPlanModeTool` | 计划模式切换 |
| `EnterWorktreeTool` / `ExitWorktreeTool` | Git 工作树隔离 |
| `ToolSearchTool` | 延迟工具发现 |
| `CronCreateTool` | 定时触发器创建 |
| `RemoteTriggerTool` | 远程触发器 |
| `SleepTool` | 主动模式等待 |
| `SyntheticOutputTool` | 结构化输出生成 |
### 2. 命令系统 (`src/commands/`)
用户通过 `/` 前缀调用的斜杠命令。
| 命令 | 描述 |
| -------------------- | ------------------------------ |
| `/commit` | 创建 git 提交 |
| `/review` | 代码审查 |
| `/compact` | 上下文压缩 |
| `/mcp` | MCP 服务器管理 |
| `/config` | 设置管理 |
| `/doctor` | 环境诊断 |
| `/login` / `/logout` | 身份验证 |
| `/memory` | 持久化记忆管理 |
| `/skills` | 技能管理 |
| `/tasks` | 任务管理 |
| `/vim` | Vim 模式切换 |
| `/diff` | 查看更改 |
| `/cost` | 检查使用成本 |
| `/theme` | 更改主题 |
| `/context` | 上下文可视化 |
| `/pr_comments` | 查看 PR 评论 |
| `/resume` | 恢复上一个会话 |
| `/share` | 分享会话 |
| `/desktop` | 桌面应用切换 |
| `/mobile` | 移动应用切换 |
### 3. 服务层 (`src/services/`)
| 服务 | 描述 |
| ------------------------ | ------------------------------------------ |
| `api/` | Splinterworks API 客户端、文件 API、引导 |
| `mcp/` | 模型上下文协议服务器连接与管理 |
| `oauth/` | OAuth 2.0 身份验证流程 |
| `lsp/` | 语言服务器协议管理器 |
| `analytics/` | 基于 GrowthBook 的功能标志与分析 |
| `plugins/` | 插件加载器 |
| `compact/` | 会话上下文压缩 |
| `policyLimits/` | 组织策略限制 |
| `remoteManagedSettings/` | 远程管理设置 |
| `extractMemories/` | 自动记忆提取 |
| `tokenEstimation.ts` | 令牌计数估算 |
| `teamMemorySync/` | 团队记忆同步 |
### 4. 桥接系统 (`src/bridge/`)
IDE 扩展（VS Code、JetBrains）与 CLI 之间的双向通信。
- `bridgeMain.ts` — 桥接主循环
- `bridgeMessaging.ts` — 消息协议
- `bridgePermissionCallbacks.ts` — 权限回调
- `replBridge.ts` — REPL 会话桥接
- `jwtUtils.ts` — 基于 JWT 的身份验证
- `sessionRunner.ts` — 会话执行管理
### 5. 权限系统 (`src/hooks/toolPermission/`)
工具调用时的权限检查：根据配置的权限模式（`default`、`plan`、`bypassPermissions`、`auto` 等），通过用户提示或自动解决。
### 6. 功能标志
通过 Bun 的 `bun:bundle` 功能标志进行死代码消除：
```
import { feature } from "bun:bundle";
// Inactive code is completely stripped at build time
const voiceCommand = feature("VOICE_MODE")
? require("./commands/voice/index.js").default
: null;
```
显著标志：`PROACTIVE`、`KAIROS`、`BRIDGE_MODE`、`DAEMON`、`VOICE_MODE`、`AGENT_TRIGGERS`、`MONITOR_TOOL`
## 关键文件详述
### `QueryEngine.ts` (~46K 行)
用于 LLM API 调用的核心引擎：流式响应、工具调用循环、思维模式、重试逻辑、令牌计数。
### `Tool.ts` (~29K 行)
工具的基础类型和接口——输入模式、权限模型、进度状态类型。
### `commands.ts` (~25K 行)
斜杠命令的注册和执行；针对特定环境的命令集的条件导入。
### `main.tsx`
基于 Commander.js 的 CLI 解析和 React/Ink 渲染器设置；启动路径包括 MDM 设置、密钥链预取和 GrowthBook 初始化以优化启动性能。
## 技术栈
| 类别 | 技术 |
| ----------------- | ---------------------------------------------------------------------- |
| 运行时 | [Bun](https://bun.sh) |
| 编程语言 | TypeScript（严格模式） |
| 终端 UI | [React](https://react.dev) + [Ink](https://github.com/vadimdemedes/ink) |
| CLI 解析 | [Commander.js](https://github.com/tj/commander.js)（额外类型定义） |
| 模式验证 | [Zod v4](https://zod.dev) |
| 代码搜索 | [ripgrep](https://github.com/BurntSushi/ripgrep) |
| 协议 | [MCP SDK](https://modelcontextprotocol.io)、LSP |
| API | [Splinterworks SDK](https://docs.splinterworks.invalid) |
| 遥测 | OpenTelemetry + gRPC |
| 功能标志 | GrowthBook |
| 身份验证 | OAuth 2.0、JWT、macOS 钥匙串 |
## 显著设计模式
### 并行预取
```
// main.tsx — fired as side-effects before other imports
startMdmRawRead();
startKeychainPrefetch();
```
### 延迟加载
重量级模块（OpenTelemetry、gRPC、分析和某些功能门控子系统）通过动态 `import()` 延迟到需要时加载。
### 智能体群
通过 `AgentTool` 生成子智能体；`coordinator/` 用于多智能体编排；`TeamCreateTool` 用于团队级别的并行工作。
### 技能系统
`skills/` 目录下的工作流通过 `SkillTool` 执行；上游产品支持用户自定义技能。
### 插件架构
通过 `plugins/` 子系统加载插件。
## 页脚
**无关联。** 与 Splinterworks 或任何指名的权利持有人无关、未经其背书或维护。
**知识产权。** 原创作品仍归其各自所有者所有；此镜像不转让任何权利。
**免责声明。** “按原样”提供，不作任何保证；不构成法律建议。使用风险自担。
标签：npm, TypeScript, 个人研究项目, 供应链分析, 反取证, 发布流程风险, 安全插件, 安全评估, 开发工具安全, 教育用途, 数据管道, 构建工件, 架构审查, 源码分析, 源码镜像, 研究分析, 终端工具, 终端编码代理, 网络安全, 自动化攻击, 软件供应链安全, 软件工程, 远程方法调用, 防御性安全, 隐私保护, 静态镜像