chipzone-kernel-weichen74
v0.1.5
Published
A lightweight local CLI agent kernel - supports Skills, MCP, and Memory, powered by ChipZone. Synced with agentica-gateway source.
Readme
ChipZone
An AI agent platform with Desktop GUI + CLI, supporting Skills, MCP, multimodal input, and Memory.
Built on
@mariozechner/pi-coding-agent.
Architecture
graph TB
subgraph Frontend ["Frontend — 用户界面"]
GUI["Desktop GUI<br/><small>Electron 33 · React 19 · Ant Design</small>"]
CLI["CLI<br/><small>Interactive REPL · Single-shot</small>"]
end
subgraph Kernel ["Kernel — 核心引擎"]
Session["Session<br/><small>会话编排 · 上下文压缩</small>"]
Model["Model Resolver<br/><small>50+ providers · Vision</small>"]
SkillLoader["Skill Loader"]
MCPBridge["MCP Bridge"]
Memory["Memory"]
Soul["SOUL.md"]
Config["Config<br/><small>global ⊕ project-local</small>"]
end
subgraph External ["External — 外部服务"]
LLM["LLM Provider<br/><small>Anthropic · OpenAI · vLLM · Ollama …</small>"]
MCPServer["MCP Servers<br/><small>filesystem · github · …</small>"]
Browser["Built-in Browser<br/><small>Playwright over Electron CDP</small>"]
end
GUI -- "IPC (contextBridge)" --> Session
CLI -- "direct API" --> Session
Session --> Model
Session --> SkillLoader
Session --> MCPBridge
Session --> Memory
Session --> Soul
Session --> Config
Session --> Security
subgraph SecurityLayer ["Security — 安全层"]
ToolGuard["Tool Guard<br/><small>pre-tool-call 参数拦截</small>"]
SkillScanner["Skill Scanner<br/><small>pre-activation 静态分析</small>"]
end
Session --> ToolGuard
SkillLoader --> SkillScanner
Model --> LLM
MCPBridge --> MCPServer
SkillLoader -.-> BrowserFeatures
🖥 Interface
| Feature | Description | |---------|-------------| | Desktop GUI | Electron + React app — Chat, Skills, Tools, MCP Servers, Settings 五个页面；支持 dark/light 主题；跨平台 (Windows / macOS / Linux) | | Multimodal image input | 在 Chat 中粘贴图片 (Ctrl+V)、拖放、或文件选择器；图片自动缩放后以 vision content 发送给模型 | | Hot-reload config | 任意配置页面（Settings / Security / MCP / Soul / Memory）保存后，Chat 页面即时更新模型标签，无需重启 | | CLI | 交互式 REPL 和单次 print 模式，支持 session 恢复 |
🤖 Agent Core
| Feature | Description | |---------|-------------| | Multi-provider LLM | Anthropic Claude, OpenAI, Ollama, Groq, 50+ providers via pi-ai；支持任何 OpenAI 兼容的私有部署 (vLLM 等) | | Full tool suite | Bash 执行、文件读写编辑、grep、find | | Auto-compaction | 内置上下文窗口管理，长对话自动压缩 |
� Security
| Feature | Description |
|---------|-------------|
| Tool Guard | Bash 命令执行前自动拦截：正则匹配危险命令 (rm -rf / 反弹 shell / fork bomb 等 13+ 规则) + 敏感文件路径阻断 |
| Skill Scanner | Skill 加载前静态分析：9 类 YAML 签名匹配 (命令注入 / 硬编码密钥 / 数据外泄 / 提示注入 / 混淆 / 社工 / 资源滥用 / 供应链 / 未授权工具) |
| Scan Policy | 组织级扫描策略：可禁用规则、覆盖 severity、配置白名单和文件限制 |
| Configurable modes | block (拒绝) / warn (警告) / off (关闭)；支持 skill 白名单和内容哈希校验 |
�🔌 Extensibility
| Feature | Description |
|---------|-------------|
| Skills | 内置 skills (如 browser 自动化)；支持项目级 / 全局级自定义 skill，每个 skill 一个 SKILL.md |
| Local Tools | TypeScript 工具自动加载——在 tools/ 目录放置 tool.json + index.ts 即可扩展 Agent 能力；内置 image_to_markdown（视觉模型）和 pdf_to_markdown（本地渲染，无需外部 CLI）|
| Browser automation | 内置 playwright-browser skill，通过 browser_* 工具控制 Electron 内置浏览器：打开页面、无障碍快照、点击、填表、上传、截图 |
| MCP | 在 mcp.json5 中定义 MCP servers，工具自动发现 |
| SOUL.md | 自定义 Agent 人格与语言风格 (全局 / 项目级) |
| Memory | Agent 在工作目录维护 .chipzone/MEMORY.md，跨 session 持久记忆 |
| Session persistence | 对话保存在 ~/.chipzone/ 下，可随时恢复 |
Quick Start
Prerequisites
- Node.js ≥ 22
- npm
Desktop App (recommended)
# 1. Build kernel
npm install && npm run build
# 2. Install app dependencies & launch
cd app && npm install
npm run dev # auto-builds kernel → launches ElectronCLI
npm install && npm run build
# Cloud provider
export ANTHROPIC_API_KEY=sk-ant-...
node dist/cli.js # Interactive REPL
node dist/cli.js --print "Hello" # Single-shot
node dist/cli.js --resume # Resume last session
# Or: custom endpoint — set apiBase in ~/.chipzone/settings.json5全局安装 CLI（任意目录使用）
npm install && npm run build
# 创建全局符号链接，注册 `th` 命令
npm link
# 之后在任意目录均可使用
th
th --print "你好"
th --resume
# 卸载
npm unlink -g chipzone-kernel
npm link将当前项目链接到系统全局node_modules，修改代码后只需重新npm run build，无需再次 link。
Configuration
All fields are optional. See
config.example.json5for the full annotated reference.
Standard (cloud) providers
// ~/.chipzone/settings.json5
{
provider: "anthropic", // anthropic | openai | ollama | groq | ...
model: "claude-sonnet-4-5",
thinkingLevel: "medium", // minimal | low | medium | high | xhigh
falloverModels: [
{ provider: "openai", model: "gpt-4o" },
],
approveAll: false,
extraSystemPrompt: "",
security: {
toolGuard: { enabled: true },
fileGuard: { enabled: true, sensitiveFiles: [] },
skillScanner: { mode: "block" }, // block | warn | off
},
}| Provider | Environment variable |
|----------|---------------------|
| anthropic | ANTHROPIC_API_KEY |
| openai | OPENAI_API_KEY |
| groq | GROQ_API_KEY |
| openrouter | OPENROUTER_API_KEY |
| others | see pi-ai docs |
Custom / private OpenAI-compatible endpoints
{
provider: "openai",
model: "Qwen3.5-35B-A3B-FP8",
apiBase: "http://172.16.30.224:8904/v1",
apiKey: "your-api-key-here",
}apiKey 会在运行时写入 OPENAI_API_KEY，也可直接通过环境变量设置。
Ollama（本地模型）
# 确保 Ollama 已启动，且模型已拉取
ollama pull qwen3.5-35b// ~/.chipzone/settings.json5
{
provider: "ollama",
model: "qwen3.5-35b",
apiBase: "http://localhost:11434/v1",
apiKey: "ollama", // Ollama 不需要真实 key，填任意字符串即可
}启动时需设置环境变量（或在 shell 配置中持久化）：
export OPENAI_API_KEY=ollama
th注意：底层
pi-ai库在模块加载阶段即检查 API key，settings.json5中的apiKey写入时机较晚，因此必须通过环境变量提前设置。
MCP Servers
// .chipzone/mcp.json5
{
filesystem: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
},
github: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-github"],
env: { GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_..." },
},
}Directory Layout
<kernel>/ ← 项目根目录
├── skills/ ← 内置 skills
│ └── playwright-browser/SKILL.md
├── tools/ ← 内置 local tools
│ ├── image-to-markdown/ # image_to_markdown 工具
│ │ ├── tool.json
│ │ ├── index.ts
│ │ ├── image.ts
│ │ └── prompts.ts
│ └── pdf-to-markdown/ # pdf_to_markdown 工具
│ ├── tool.json
│ ├── index.ts
│ ├── pdf.ts
│ └── renderer.ts
├── app/ ← Desktop GUI (Electron + React)
│ ├── src/main/ ← Electron main process & IPC
│ ├── src/renderer/ ← React 前端 (Chat, Skills, MCP, Settings)
│ └── release/ ← 打包产物 (pack:win/mac/linux)
└── src/ ← Kernel 核心代码
└── security/ ← 安全模块 (Tool Guard + Skill Scanner)
~/.chipzone/ ← 全局配置 (所有项目共享)
├── tools/ ← 全局 local tools (覆盖同名内置工具)
├── settings.json5 ← 全局设置
├── mcp.json5 ← 全局 MCP servers
├── SOUL.md ← 全局人格指令
└── skills/ ← 全局 skills (覆盖同名内置 skill)
└── my-skill/SKILL.md
<cwd>/.chipzone/ ← 项目级配置 (当前目录)
├── settings.json5 ← 局部覆盖 (deep-merge 到全局之上)
├── mcp.json5 ← 局部 MCP 追加
├── SOUL.md ← 项目人格 (覆盖全局)
├── skills/ ← 项目 skills (最高优先级)
├── tools/ ← 项目 local tools (最高优先级)
└── MEMORY.md ← 项目记忆 (跨 session 持久化)Config 合并策略: global 为基础，project-local deep-merge 覆盖。MCP servers 按 key 合并。
Skills 优先级 (低 → 高): built-in → global → project-local
Local Tools
Local Tools 是一套 TypeScript 工具自动加载机制，让你无需修改 Kernel 源码即可为 Agent 添加新能力。
工具发现顺序（低 → 高优先级）
<kernel-root>/tools/— 内置工具~/.chipzone/tools/— 全局用户工具<cwd>/.chipzone/tools/— 项目级工具config.toolsDir— 额外指定目录
同名工具高优先级覆盖低优先级。
工具目录结构
tools/
└── my-tool/
├── tool.json ← 工具清单（必需）
└── index.ts ← 工具逻辑（必需）tool.json 格式
{
"name": "my_tool", // 工具名（用于 Agent 调用）
"label": "My Tool", // 显示名（可选）
"description": "...", // 功能描述（可选）
"entry": "index.ts", // 入口文件（相对于工具目录）
"inputSchema": { // JSON Schema（Agent 参数校验）
"type": "object",
"properties": {
"path": { "type": "string" }
},
"required": ["path"]
},
"timeoutMs": 60000 // 超时（可选，默认 60s）
}index.ts 实现
import type { LocalToolContext } from 'chipzone-kernel/tools'
export async function execute(
input: { path: string },
ctx: LocalToolContext
): Promise<unknown> {
// ctx.cwd — 工作目录
// ctx.agentDir — Agent 存储目录（~/.chipzone/…）
// ctx.signal — AbortSignal（可中断长任务）
// ctx.logger — 日志记录器
return { result: 'ok' }
}TypeScript 源码在首次调用时自动编译并缓存到
~/.chipzone/users/<user>/tool-cache/local-tools/<hash>/，后续调用直接读取缓存。
内置工具
| 工具 | 说明 |
|------|------|
| image_to_markdown | 将图片（PNG / JPG / base64）转换为 Markdown；通过视觉模型识别，支持 general（通用）和 pdf-page（PDF 页面专用）两种模式 |
| pdf_to_markdown | 将 PDF 文件转换为 Markdown；全程本地渲染（pdfjs-dist + @napi-rs/canvas），无需安装 pdftoppm 等外部工具；支持跨页内容续写 |
禁用工具
在 settings.json5 中通过 disabledTools 字段禁用特定工具：
{
disabledTools: ["pdf_to_markdown"]
}SOUL.md — Persona & Tone
SOUL.md 定义 Agent 的人格、语言风格和行为准则。
- Global:
~/.chipzone/SOUL.md - Project-local:
.chipzone/SOUL.md(覆盖全局)
你是「千手」，一个专注于代码开发的助手。
- 始终用简洁中文回答
- 回答要先给结论，再解释细节
- 对敏感技术决策主动提示风险Skills
每个 skill 是包含 SKILL.md 的子目录。Agent 按优先级自动加载所有 skill 目录。
Built-in skills
| Skill | Description |
|-------|-------------|
| playwright-browser | Web automation through Playwright-backed browser_* tools — open pages, snapshot, click, fill, upload, evaluate page state, screenshot |
browser_open({ "url": "https://example.com" })
browser_snapshot({}) # accessibility tree + @e refs
browser_click({ "ref": "@e2" })
browser_fill({ "ref": "@e3", "text": "value" })Custom skills
.chipzone/skills/my-skill/
├── SKILL.md ← required
└── references/ ← optional---
name: my-skill
description: One-line summary
---
# My Skill
Instructions for the agent...Security
ChipZone 内置两层安全防护，从 CoPaw 安全模块移植而来。
Tool Guard — 工具调用拦截
在 bash 命令执行前自动扫描参数，检测危险操作：
- Rule Guardian: YAML 正则规则匹配 (rm -rf、fork bomb、反弹 shell、提权等 13+ 条规则)
- File Guardian: 阻止访问
/etc/shadow、~/.ssh/等敏感路径 (always-run，不可跳过)
检测到威胁时：denied 工具直接拒绝；其他情况向用户展示安全告警，由用户决定是否继续。
Skill Scanner — 技能静态分析
在 skill 加载前对目录内所有代码文件进行正则扫描，涵盖 9 类威胁：
| Category | Examples |
|----------|----------|
| Command Injection | os.system(), subprocess, backtick exec |
| Hardcoded Secrets | API keys, passwords, tokens |
| Data Exfiltration | HTTP POST to external hosts, base64 + curl |
| Prompt Injection | System prompt override, role hijack |
| Obfuscation | base64 decode + exec, eval chains |
| Social Engineering | "ignore previous instructions" patterns |
| Resource Abuse | Crypto mining, infinite loops |
| Supply Chain | pip install from untrusted sources |
| Unauthorized Tool Use | Disabling security, escalating permissions |
Security 配置
// ~/.chipzone/settings.json5
{
security: {
toolGuard: {
enabled: true, // 启用/禁用 Tool Guard
guardedTools: ["my_custom_tool"], // 额外纳入监管的工具名
deniedTools: ["dangerous_tool"], // 始终拒绝的工具名
extraRulesDir: "./my-rules/", // 额外 YAML 规则目录
},
fileGuard: {
enabled: true,
sensitiveFiles: ["/etc/passwd", "~/.aws/credentials"],
},
skillScanner: {
mode: "block", // block | warn | off
timeout: 30,
whitelist: [
{ skillName: "trusted-skill" },
{ skillName: "pinned-skill", contentHash: "sha256..." },
],
},
},
}Desktop App
GUI 基于 Electron 33 + React 19 + Ant Design 5 + Zustand，通过 IPC 连接 Kernel。
| Page | Description | |------|-------------| | Chat | 对话界面：文字 + 图片输入 (paste / drag-drop / file picker)；Markdown 渲染 + 语法高亮代码块 | | Skills | 浏览、新增、编辑、删除 skills | | Tools | 查看内置工具 (bash, read, write…) 和 MCP 工具 | | MCP Servers | 查看 MCP server 配置与状态 | | Settings | 编辑 provider / model / apiBase / apiKey / workspaceDir 等设置 |
Packaging
cd app
npm run pack:win # Windows NSIS installer → app/release/
npm run pack:mac # macOS DMG → app/release/
npm run pack:linux # Linux AppImage → app/release/pack:win 需要先开启 Windows Developer Mode，否则 electron-builder 在解压 winCodeSign 时可能因为符号链接权限不足而失败。
Windows 10 步骤： 按 Win+I → 更新和安全 → 左侧 针对开发人员 -> 选择 开发人员模式 → 确认提示 → 等待组件安装
Build-time Environment Variables（构建时注入）
部分配置出于安全原因不允许由用户在运行时修改，而是在打包时固化进二进制。
| 变量 | 默认值 | 说明 |
|------|--------|------|
| AUTH_BASE_URL | http://172.16.30.126:8180/api | 认证服务器地址，构建时固化进二进制，用户无法在运行时修改。 |
使用方式：
# 使用默认认证服务器（开发 / 默认内网环境）
cd app && npm run dev
npm run pack:win
# 使用项目根目录下的打包脚本（推荐，自动处理代理等构建环境）
# Windows PowerShell
\.\scripts\pack-win.ps1 -AuthBaseUrl "http://your-server:8180/api"
# Windows CMD
scripts\pack-win.cmd -AuthBaseUrl "http://your-server:8180/api"
# 也可直接通过环境变量传入（适合 CI/CD）
$env:AUTH_BASE_URL = "http://prod-server:8180/api"
cd app && npm run pack:winCLI Reference
Usage: th [options] [prompt]
Options:
--resume, -r Resume the most recent saved session
--yes, -y Auto-approve all bash commands
--print TEXT, -p TEXT Single-shot: send TEXT, print response, exit
--version Print version
--help, -h Show helpProject Structure
src/ ← Kernel (agent core + CLI)
├── cli.ts # CLI entry
├── index.ts # Public API
├── cli/
│ ├── index.ts # Argument parsing & dispatch
│ ├── repl.ts # Interactive REPL
│ ├── print.ts # Single-shot print mode
│ └── output.ts # Terminal output formatting
├── agent/
│ ├── session.ts # Session orchestration
│ ├── model.ts # Model resolver (50+ providers, vision)
│ ├── approval.ts # Bash approval wrapper
│ ├── mcp.ts # MCP server → ToolDefinitions
│ ├── local-tools.ts # Local tools scanner, loader, executor
│ ├── memory.ts # MEMORY.md helpers
│ ├── soul.ts # SOUL.md persona loader
│ └── skills.ts # Skill loader (with security scan)
├── security/
│ ├── models.ts # Shared types & enums
│ ├── tool-guard/ # Pre-tool-call parameter scanning
│ │ ├── base-guardian.ts # Abstract guardian base class
│ │ ├── file-guardian.ts # Sensitive file path blocking
│ │ ├── rule-guardian.ts # YAML regex rule matching
│ │ └── engine.ts # Guardian orchestrator (singleton)
│ ├── skill-scanner/ # Pre-skill-activation static analysis
│ │ ├── scan-policy.ts # Org scan policy (YAML config)
│ │ ├── pattern-analyzer.ts # YAML signature matching (9 categories)
│ │ ├── scanner.ts # File discovery & analyzer orchestrator
│ │ └── index.ts # Public API, cache, blocked history
│ └── rules/ # YAML rule/signature files
│ ├── tool-guard/ # dangerous_shell_commands.yaml
│ ├── skill-scanner/ # 9 signature files (48+ rules)
│ └── default_policy.yaml # Default scan policy
└── config/
└── index.ts # Config merge (global ⊕ project-local)
skills/ ← Built-in skills
└── playwright-browser/SKILL.md
app/ ← Desktop GUI
├── electron-builder.yaml # Packaging config
├── electron.vite.config.ts # Build config
└── src/
├── main/ # Electron main process
│ ├── index.ts # Window creation
│ ├── ipc-agent.ts # Agent session IPC
│ ├── ipc-config.ts # Settings IPC
│ ├── ipc-skills.ts # Skills IPC
│ ├── ipc-tools.ts # Tools IPC
│ └── ipc-security.ts # Security status & scan IPC
├── preload/index.ts # Context-isolated preload
├── renderer/src/ # React frontend
│ ├── pages/ # Chat · Skills · Tools · McpServers · Settings
│ ├── components/ # CodeBlock · MarkdownRenderer
│ ├── stores/ # Zustand (agent, config, theme)
│ ├── hooks/ # useAgent
│ └── styles/ # CSS
└── shared/types.ts # IPC type definitionsE2E Testing
e2e/ 目录下维护一套基于 Playwright 的端到端测试，每个测试用例独立启动/关闭 Electron 实例，完整覆盖 UI → IPC → Kernel → LLM 的调用链。
目录结构
e2e/
├── playwright.config.ts # 全局配置（超时 120s，顺序执行）
├── tsconfig.json
├── package.json
├── fixtures/
│ └── electron-fixtures.ts # 封装 ElectronApp + Page fixture
├── helpers/
│ ├── selectors.ts # CSS 选择器常量
│ └── wait-helpers.ts # waitForSessionReady / waitForAgentToFinish
└── tests/
└── 01-chat-weather.spec.ts # 天气查询案例（可扩展）前置条件
构建 Electron App（每次改动后需重新执行）
cd app npm run build配置 LLM API Key
确保 ~/.chipzone/settings.json5 中已配置有效的 API Key：
{
provider: "anthropic",
model: "claude-sonnet-4-5",
}并设置对应环境变量（以 Anthropic 为例）：
$env:ANTHROPIC_API_KEY = "sk-ant-..."安装 E2E 依赖（首次或 package.json 变动后）
cd e2e npm install
运行测试
# 在 e2e/ 目录下执行
npm test # 无头模式（CI 推荐）
npm run test:headed # 有头模式（可见 Electron 窗口，便于观察）
npm run test:debug # 单步调试
npm run test:ui # Playwright UI 模式（时间旅行调试）
npm run test:report # 查看最近一次的 HTML 报告当前测试案例
| 文件 | 描述 |
|------|------|
| tests/01-chat-weather.spec.ts | 天气查询：新建会话 → 输入"广州当前天气" → 断言回复包含地名、天气词汇和今日日期 |
断言详情（天气查询）
| 步骤 | 操作 |
|------|------|
| 1 | waitForSessionReady — 等待 .session-indicator.ready（绿点） |
| 2 | 点击 New Session (Ctrl K) 清空上下文 |
| 3 | 向输入框填入 "广州当前天气" 并按 Enter |
| 4 | waitForAgentToFinish — 等待 .chat-busy-hint 消失 |
| 5 | 断言 Agent 回复包含 /广州\|Guangzhou/i |
| 6 | 断言回复包含天气相关词汇（天气/气温/温度/晴/阴/雨/°C …） |
| 7 | 断言回复包含今日日期（X月X日 / today / 今天 等格式） |
增加新测试案例
方式 1 — 在现有文件中追加 test() 块（适合同类场景扩展）：
在 tests/01-chat-weather.spec.ts 中 test.describe 内继续添加：
test('查询北京明天天气', async ({ page }) => {
await waitForSessionReady(page)
await page.click(Selectors.chatNewBtn)
await waitForSessionReady(page)
const input = page.locator(Selectors.inputTextarea)
await input.fill('北京明天天气')
await input.press('Enter')
await waitForAgentToFinish(page)
const texts = await getAgentMessageTexts(page)
expect(texts.join('\n')).toMatch(/北京|Beijing/i)
})方式 2 — 创建新文件（适合不同功能模块）：
按照 NN-功能名.spec.ts 命名，从公共 fixture 导入，无需修改任何现有文件：
// tests/02-settings.spec.ts
import { test, expect } from '../fixtures/electron-fixtures'
import { Selectors } from '../helpers/selectors'
test.describe('Settings — 配置页面', () => {
test('可以切换到设置页', async ({ page }) => {
// ...
})
})关键超时参数
| 参数 | 默认值 | 说明 |
|------|--------|------|
| 单测超时 | 120 s | 包含 LLM 推理 + 工具调用全链路 |
| 断言超时 | 90 s | expect(...).toMatch(...) 等 |
| 会话就绪等待 | 30 s | waitForSessionReady |
| Agent 完成等待 | 120 s | waitForAgentToFinish |
如需调整，修改 e2e/playwright.config.ts 中的 timeout / expect.timeout 即可。