架构设计 Kernel ↔ Client

一、关于 Liskin

Liskin 是一款专注研发提效的 Coding Agent。产品目前提供 IDE 插件，web和 CLI 多种形态，主要解决的是通用编程 Agent 在大型代码库里反复暴露的几个老问题：

看不懂代码库。通用 Agent 对大型工程缺乏全局认知，回答经常跑偏，开发者只能不停追问、手动补约束。
其次是生成的代码不合规范，常常偏离业务逻辑或 UI 标准，存在幻觉，设计稿还原得也不理想。
复杂任务接不住——单轮 Agent 既缺上下文也缺工具，跨模块、多步骤的活难以完成。
质量缺乏反馈，代码写完没有客观评估，开发者对产出好坏没有把握。

二、相对业界主流 Agent 的技术创新

深度代码检索

Liskin 用 Code RAG 配合基于 LSP AST 的代码索引做跨文件检索，把准确的上下文主动喂给模型，而不是让模型盲猜，也省去了开发者手动粘贴代码片段的环节。这套检索能力后续计划做 MCP 化，作为标准工具服务对外开放。

单 Agent 全程上下文与无痕微压缩

主流的多 Agent 编排有一个共性缺陷，Liskin 早期的 Subagent 串联也踩过这个坑：每个子 Agent 各自维护记忆，切换时上下文就断了。

Liskin 换了思路，借鉴 Claude Skills 的渐进式披露，以及 Manus、Claude Code 的微压缩机制，让单个 Agent 在一次任务里全程保持完整上下文，只在阶段之间做无痕微压缩。这样既压住了上下文膨胀，又保住了对话的连续性。实测显示，引入渐进式加载后 Token 消耗下降约 50%，平均任务完成时间缩短约 50%，指令遵循度提升约 7%。这条路线与 Cursor、Trae 的多 Agent 编排有明显区别。

双模式 + Auto 智能路由

业界产品大多用一个 Agent 应对所有任务，比如 Cursor 的单 Agent、Windsurf 的 Cascade 全自动流。Liskin 走的是另一条路：把深度规划和快速执行拆成两个独立的执行模式，二者在 LLM 选型、Prompt 策略、工具集和上下文管理上完全分开，而每个模式内部仍由单个 Agent 全程持有上下文。

上层的 Auto 路由会根据任务复杂度和需求明确度自动分发——复杂的架构性任务交给深度规划，明确的单点修改交给快速执行。这样"PRD 到架构拆解"和"即时 Bugfix"这两类差异极大的任务都能稳定接住，而不是拿同一套配置硬扛到底。

架构创新与云端-本地协同

产品以一个统一内核为中心，对外提供 Web、CLI、IDE 插件乃至移动端 App 等多种客户端，开发者在任意终端都能随时开工。再通过 MCP 打通 GitHub、Vercel、Cloudflare 等开发与部署链路，把研发流程串成一个闭环。

这套架构的关键在于内核与外壳解耦。同一份内核代码靠不同的 KernelClient 适配多端——CLI 走 InProcessKernelClient，Web 走 HttpSseKernelClient，未来 IDE 走 JsonRpcKernelClient；而 Claude Code 的 VSCode 扩展和 CLI 是两条相对独立的实现路径。内核并不知道自己是被 CLI、Web 还是 IDE 调用的——LLMPort、ToolPort、StorePort 三个端口接口让内核只跟抽象契约打交道，换模型、换工具来源、换存储后端，都不必改动内核代码。这个设计便于日后的插件化扩展

新增Sandbox，路径白名单加命令黑名单，再配合 auto/ask/deny 三档确认策略，权限粒度比 Claude Code 更细。

Harness 框架支撑长程任务自迭代

Harness 是 Liskin 专为复杂长程任务设计的执行框架。它把任务拆成可中断、可恢复、可审计的节点序列，用 Markdown 文件落盘记录意图、阶段、闸门和完成状态。借助它，Agent 在多轮执行中能够始终对齐目标，即便中途中断，也能从断点精确接回。其长任务可中断、可恢复、可审计，状态落盘在 .liskin/harness/ 目录，这是 Claude Code 目前没有的机制。

评测驱动迭代

Liskin 建立了一套系统化的 Agent 评测机制，并把行为日志结构化成 RLHF/DPO 训练数据，形成 post-coding 数据飞轮。依托评测持续发现并改进 System Prompt、链路、工具和模型上的问题。

在建能力

D2C 是当前的核心抓手，配合 AGENTS.md 的项目级规范注入和 Harness 真相文档，把业务规则与 UI 标准显式传给模型，不再依赖模型自行揣摩。围绕落地链路，还在推进 GitHub CI/CD、Vercel、Cloudflare 等平台从 SCM 研发到上线部署的全流程集成，以及基于 ContextDB 的上下文管理集成和文档形式的 stage 管理。

三、与 Claude Code / Trae / Cursor 的对比

维度	Claude Code	Liskin
多端支持	本地 CLI / VSCode 扩展	CLI + Web + IDE 插件，共用同一 daemon
Provider	仅 Anthropic API	原生支持多 Provider 热切换
上下文工程	系统 Prompt + 项目记忆	同样支持 AGENTS.md，外加 Harness 工程基础设施
工具系统	内置工具（Bash/Read/Write/Edit 等）	内置 fs/shell + Sandbox 防护 + 可扩展 ToolPort
多 Provider	仅 Anthropic 模型	动态 Provider 路由，Web UI 切换，配置持久化

当然，Claude Code 在 System Prompt 与工具链的打磨、PR/Issue 评论和 CI 集成等企业协作能力上更为成熟，这些是 Liskin 后续需要补齐的方向。

架构设计 Kernel ↔ Client

内核（Agent 状态机 + 工具 + 模型适配）与调用方（CLI / Web / IDE）进行解耦

内核不感知调用内核的对象，越靠内的层越稳定。

四层单向依赖的架构

flowchart TB
    %% 样式定义
    classDef l4 fill:#eff6ff,stroke:#3b82f6,stroke-width:1.5px,color:#1e3a8a
    classDef trans fill:#f5f3ff,stroke:#8b5cf6,stroke-width:1.5px,color:#4c1d95
    classDef proto fill:#fffbeb,stroke:#f59e0b,stroke-width:1.5px,stroke-dasharray: 5 5,color:#92400e
    classDef l3l2 fill:#ecfdf5,stroke:#10b981,stroke-width:1.5px,color:#064e3b
    classDef l1 fill:#f8fafc,stroke:#64748b,stroke-width:2px,color:#0f172a

    subgraph L4["L4 接入层"]
        direction LR
        Clients["CLI, Web, IDE Plugin"]:::l4
    end

    subgraph Transport["传输适配"]
        Server["Hono Server<br/><small>packages/server</small>"]:::trans
    end

    subgraph Protocol["协议边界"]
        Proto["KernelClient / Op / EventMsg"]:::proto
    end

    subgraph L3["L3 模型适配"]
        LLM["LLMProvider → LLMPort<br/><small>packages/llm</small>"]:::l3l2
    end

    subgraph L2["L2 工具/执行"]
        Tools["ToolRegistry + Sandbox<br/><small>packages/tools</small>"]:::l3l2
    end

    subgraph L1["L1 内核"]
        Core["runAgent + 状态机<br/><small>packages/core</small>"]:::l1
    end

    %% 数据流向与依赖
    Clients ==>|"KernelClient 接口"| Server
    Server --> Proto
    Proto --> LLM
    Proto --> Tools
    LLM --> Core
    Tools --> Core

    style L4 fill:transparent,stroke:#3b82f6,stroke-width:2px
    style L1 fill:#f1f5f9,stroke:#64748b,stroke-width:2px

包	层	职责
`packages/core`	L1	Agent 状态机、主循环、Op/EventMsg 协议、KernelClient 接口
`packages/tools`	L2	工具注册 + 沙箱（路径白名单/危险命令拦截）、fs.read/fs.write/shell.exec
`packages/llm`	L3	LLMProvider 接口 + OpenAI 兼容适配器（已验证 GLM5.2）
`packages/server`	L4	Hono daemon，HTTP/SSE + SQLite 持久化
`client/`	L4	CLI 入口：agent serve（daemon）、agent exec（headless）、agent chat（交互式 REPL）
`web/`	L4	React + Vite + Tailwind 前端（待重写为时间线渲染）

依赖边界

通过 dependency-cruiser 强制执行单向依赖规则：core 不依赖 tools/llm/server，tools 不依赖 llm/server，依此类推。任何反向 import 在 pnpm deps:check 阶段直接阻塞。

前端

类别	选型	用途
框架	React + TypeScript	SPA，Vite 构建
路由	react-router	客户端路由，非 Next 文件路由
远端状态	SWR	请求缓存、重试、revalidate
本地状态	Zustand	跨组件共享，替代 Redux
局部状态	React hooks + ahooks	页面/组件级交互
样式	TailwindCSS + cva + clsx + tailwind-merge	原子化 + 变体管理
无样式组件	Radix UI	Dialog、Select、Tooltip 等
业务组件	HeroUI	快速搭建（待 React 19 + Tailwind 4 升级后深度启用）
动画	Framer Motion	过渡与手势
通知	Sonner	Toast 通知

编辑与内容渲染

类别	选型
Markdown	react-markdown + remark-gfm + rehype 系列
图表	mermaid
代码编辑	monaco-editor + @monaco-editor/react
节点流程图	reactflow

快速开始

前置

Node ≥ 20、pnpm 9
一个 LLM API Key（OpenAI 兼容协议；）

# 克隆代码仓库
git clone https://github.com/Zhongye1/liskin.git

pnpm install
pnpm -r run build

cp .env.example .env
# 编辑 .env，填入 OPENAI_API_KEY（填入你的 API 地址和模型）

3) 跑任务（agent exec，in-process，无 daemon）

./scripts/dev.sh exec "用 matplotlib 画个柱状图存到 output/bar.png 并写 README 附图"
# 指定工作目录与最大轮数
./scripts/dev.sh exec "..." --cwd /tmp/my-task --max-turns 30

agent exec 用 InProcessKernelClient 直连内核，auto 批准工具，实时渲染事件流到终端，跑完即退出。事件流包含 Token（流式文本）、ToolCall/ToolProgress/ToolResult（工具调用 + 实时 stdout/stderr）、TurnEnd（回合结束）。

4) 交互式 REPL（agent chat，in-process，无 daemon）

# 最简启动（确认策略默认 ask）
pnpm run cli

./scripts/dev.sh chat

# 指定模型和自定义 system prompt
./scripts/dev.sh chat --model gpt-4o --system "你是 Python 专家"

# 关闭工具确认（全自动执行）
./scripts/dev.sh chat --confirm auto

# 不持久化（退出即丢会话）
./scripts/dev.sh chat --no-save

# 恢复之前保存的会话
./scripts/dev.sh chat --resume <sessionId>

# 使用第三方 API
./scripts/dev.sh chat --base-url https://api.openrouter.ai/v1 --model anthropic/claude-sonnet-4

agent chat 同样用 InProcessKernelClient 直连内核，与 exec 共享同一套渲染函数。核心差异：

多轮对话：readline REPL 循环，持续交互直到 /exit
工具确认：默认 ask，终端内联 [y/n] 问询（可用 --confirm auto 关闭）
持久化：默认存到 ~/.liskin/chat-sessions.sqlite，--resume 恢复
中断：Ctrl-C 中断当前 turn 回到 prompt（不同于 exec 直接退出）

REPL 内置命令：

命令	作用
`/exit`	退出 REPL
`/help`	打印帮助信息
`/sessions`	列出已保存的会话

5) 启动全栈（agent serve + web）

./scripts/dev.sh          # 构建 + 启动 server(8787) + web(5173)
./scripts/dev.sh --no-build   # 跳过构建
./scripts/dev.sh stop         # 停止
./scripts/dev.sh logs         # 看日志
./scripts/dev.sh watch     # 并行 tsup watch（core/tools/llm/server/client） 开发用

CLI

# headless 一次性任务（已验证闭环）
agent exec --model opensource/glm5.2 --base-url https://api.openai.com/v1 \
 --cwd /tmp/task "你的任务"

# 起 daemon（给 Web 用）
agent serve --port 8787 --cwd /your/workspace --cors http://localhost:5173

当前进度

Phase 0 已闭环。五个核心包全部可构建、可测试，端到端通路已验证。

已交付

M0 — monorepo 骨架。 pnpm workspace 立起五个包，共享 tsconfig，dependency-cruiser 守住架构红线，oxlint/prettier/commitlint 工具链完整。

M1 — Agent Core 状态机。 runAgent 异步生成器驱动主循环：idle → streaming → awaiting_tool → awaiting_user → done。LLMPort / ToolPort / StorePort 三个端口接口定义在内核中，具体实现在外层注入。HarnessPort 接口预留，NoopHarness 占位。6 个单测覆盖纯对话、工具回灌、确认门、maxTurns 保护、错误传播、取消信号。

M2 — OpenAI Provider。 OpenAIProvider implements LLMPort，覆盖 SSE 流式解析、按 index 增量拼接 tool_call、Msg/ToolDef ↔ OpenAI 协议互转、错误归一化（API 错误 / 网络错误 / 流异常 / 取消）。createProvider 工厂函数支持动态路由。30 个单测。

M3 — 工具系统 + 沙箱。 ToolRegistry implements ToolPort，zod schema 校验。内置 fs.read（行号范围）、fs.write（diff 预览）、shell.exec（sh -c 管道）。Sandbox 三层：路径白名单（防路径穿越）、命令黑名单（9 条危险模式）、确认策略（auto/ask/deny）。ConfirmRequiredError 携带 callId 支持外部确认回灌。40 个单测。

M4 — 接入层 + CLI + Web。 packages/server：Hono daemon，POST /v1/chat SSE 端点，SQLite 持久化。动态 Provider 路由，Web UI 可配置多服务商、热切换、API key 掩码。client/：CLI 入口，agent serve 启 daemon，agent exec 一次性任务。web/：React 前端，SSE AgentEvent 消费，工具调用面板，确认弹窗，ProviderSettings 配置面板。

累计：88 个测试（14 个文件），全仓 typecheck / build / lint / deps:check 通过。

遗留

server/（Go + Gin + faasrouter + Thrift IDL）暂时搁置，Phase 2 后端需时开始进行评估。

接下来的工作

按优先级排列，每条支线相互独立，可按需切入。

1. 收尾清理

前端 MVP 样式优化
清掉未使用的依赖（@radix-ui 部分组件、ahooks、axios、swr、usehooks-ts）
bundle 拆分：react-markdown / highlight.js 改用 dynamic import，消除 614KB chunk
修复 lint-staged 在部分环境下的 stash-restore 异常

2. MCP 协议支持

Phase 1 价值最大的一项。接入 Model Context Protocol，让 agent 能消费外部工具和数据源（stdio 和 HTTP 两种 transport）。内核的 ToolPort 已为此预留接口——MCP 客户端只需作为 ToolPort 的另一个实现注入，内核零改动。

3. 多 Provider 扩展

当前 LLM 层只有 OpenAI 兼容适配器。LLMPort 接口天然支持新增 Anthropic 等 Provider。dynamic-llm.ts 已有骨架，主要是 packages/llm 内加适配器实现。

4. 项目记忆

让 agent 读取并遵守项目根目录的 AGENTS.md 约定文件。内容按层级组织：根目录放全局规范（架构、编码规范、Agent 路由决策树），业务目录放模块知识。记忆文件只描述"在哪查、怎么查"，不存易变数据。

5. 终端 UI 增强

agent chat 交互式 REPL 已交付（Phase 1，基于 Node readline 原生实现，零新依赖）。后续增强方向：ANSI 光标控制（流式输出时隐藏光标、spinner 动画）、输入历史（readline history 持久化）、多行输入（粘贴代码块）。不引入 Ink/React 等重型 TUI 框架，保持 CLI 轻量。

6. Harness 框架

将 NoopHarness 替换为 MarkdownHarness：复杂任务自动在 .liskin/harness/active/ 下创建 Markdown 任务文档，记录用户意图、待办节点、已完成节点、闸门、控制状态。每个工具调用闭环后落盘节点结果。目标：任务中断能续跑、长任务可审计、执行过程可回溯。

7. 沙箱执行加固

--sandbox 标志，接入 OS 级隔离（Linux bubblewrap / macOS sandbox-exec）
写/删文件前的 diff 预览
撤销栈

阶段路线图

Phase 0（已完成）

单体本地 Agent 跑通端到端：用户对话 → 模型流式输出 → 工具调用 → 沙箱确认 → 执行 → 结果回灌 → 继续对话 → 完成。

Web UI、CLI、Hono daemon 全部到位。

Phase 1（当前阶段）

目标：终端常驻可用，覆盖 80% 日常编码需求。

Agent Loop 完善：Read → Plan → Act → Verify 循环，工具集扩展（read_file、write_file、run_shell、list_files、grep、edit）
沙箱隔离：OS 级机制（Landlock/seccomp）限制文件系统和网络访问，默认最小权限，按需扩展
项目感知：读取 AGENTS.md 和项目配置文件，构建指令链，让 Agent 理解项目结构和约定
审批机制：多级审批（只读→需确认→全自动），可编程 hook 系统拦截生命周期事件
工具协议标准化：MCP 客户端消费外部工具，工具 schema 以 JSON Schema 传给模型，支持 stdio 和 HTTP 两种 transport
上下文管理：自动压缩（compaction），session 持久化和恢复，上下文健康度监控

Phase 2

可观测性：结构化日志（JSONL session transcripts），OpenTelemetry Tracing，Token 用量计量
多 Agent 协作：子 Agent 定义（TOML），并行执行 + 结果聚合，MCP Server 模式（自身也能被其他 agent 调用）

Phase 3+

后端网关：Key 托管、多用户、审计、限流（激活 server/ Go 代码）
IDE 插件：VSCode / JetBrains 插件，连接同一个 agent serve daemon
工作流编排：多 Agent DAG 执行。设计文档明确警告——不要把 Agent 多步骤误当成工作流引擎，不要把 Harness 当 DAG 节点。

其他

参考资料：构建AGENT 一般roadmap

Step 1：确定 Agent Loop 实现 Read → Plan → Act → Verify 循环给模型配备工具：read_file、write_file、run_shell、list_files

Step 2：沙箱隔离用 OS 级机制（Landlock/seccomp/Seatbelt）限制文件系统和网络默认最小权限，按需扩展

Step 3：项目感知读取 AGENTS.md/ 项目配置文件构建指令链（instruction chain）

Step 4：审批机制实现多级审批模式（从只读到全自动）提供可编程的 hook 系统拦截生命周期事件

Step 5：工具协议实现 MCP 客户端（消费外部工具）将工具 schema 作为 JSON schema 传给模型支持 stdio 和 HTTP 传输

Step 6：上下文管理实现自动压缩（compaction）支持 session 持久化和恢复监控上下文健康度

Step 7：可观测性结构化日志（JSONL session transcripts） Tracing（OpenTelemetry 导出） Token 计量

Step 8：多代理扩展子代理定义（TOML 格式）并行执行 + 结果聚合 MCP Server 模式（让自己也能被其他 agent 调用）

Name		Name	Last commit message	Last commit date
Latest commit History 71 Commits
.husky		.husky
.omp		.omp
assets		assets
client		client
docs		docs
packages		packages
scripts		scripts
server		server
web		web
.dependency-cruiser.cjs		.dependency-cruiser.cjs
.env.example		.env.example
.gitignore		.gitignore
.nvmrc		.nvmrc
.oxlintrc.json		.oxlintrc.json
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
AGENTS.md		AGENTS.md
LEGACY.md		LEGACY.md
Readme.md		Readme.md
commitlint.config.cjs		commitlint.config.cjs
liskin-PR-description.md		liskin-PR-description.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json

Folders and files

Latest commit

History

Repository files navigation

一、关于 Liskin

二、相对业界主流 Agent 的技术创新

深度代码检索

单 Agent 全程上下文与无痕微压缩

双模式 + Auto 智能路由

架构创新与云端-本地协同

Harness 框架支撑长程任务自迭代

评测驱动迭代

在建能力

三、与 Claude Code / Trae / Cursor 的对比

架构设计 Kernel ↔ Client

依赖边界

前端

编辑与内容渲染

快速开始

前置

3) 跑任务（agent exec，in-process，无 daemon）

4) 交互式 REPL（agent chat，in-process，无 daemon）

5) 启动全栈（agent serve + web）

CLI

当前进度

已交付

遗留

接下来的工作

1. 收尾清理

2. MCP 协议支持

3. 多 Provider 扩展

4. 项目记忆

5. 终端 UI 增强

6. Harness 框架

7. 沙箱执行加固

阶段路线图

Phase 0（已完成）

Phase 1（当前阶段）

Phase 2

Phase 3+

其他

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages