1. 项目分为两个进程

p1：RuiZN-core  (服务端 / Daemon 进程)：

角色：大脑与大脑执行引擎。

职责：长驻后台运行（asyncio 异步事件循环）。所有的“重活儿”——调用大模型 (LLM)、跑本地命令、读写文件、管理 Agent 的上下文状态、处理权限控制，全都在这个进程里完成

p2：RuiZN-cli/tui  (客户端 / CLI 进程)：

角色：壳子 / 交互界面。

职责：轻量级。只是一个命令行工具（CLI）或者将来的终端界面（TUI）。它不持有任何核心业务状态，只负责把用户的输入打包发给 Core，然后把 Core 返回的结果渲染显示在屏幕上。一次性命令（比如敲完 kama ping）运行完就会退出。

2. 如何通信：它们怎么通信？

传输协议：TCP 127.0.0.1:7437（本地 Loopback 套接字连接）。

数据格式：NDJSON (Newline Delimited JSON，即按换行符分隔的 JSON 帧)。

C++ 视角：每个 Request/Response 都是一个 JSON 结构，末尾带一个 \n。Core 端只要逐行 readline() 就能天然解决粘包/拆包问题

3. 为什么不先写成单进程，后面再拆？（核心设计哲学）

如果你先写成单进程（比如把所有逻辑写成一个 Python 脚本），后期想改成客户端-服务端架构时，会面临极度痛苦的重构：你需要把所有直接的“函数调用”全部改成“网络通信、对象序列化、异步响应、超时重试”。

一开始就强行拆进程的硬好处：

解耦极佳：GUI/CLI 怎么改、崩溃与否，完全不影响后台 Agent 的任务执行。

多端支持：今天用简单的命令行 kama 调 Core，明天写 kama-tui 界面，后天甚至能写个 Web 前端，Core 的代码一行都不用改。

迫使规范：强制你在第一天就考虑“网络失败”、“序列化/反序列化”、“异步响应”等真实生产环境中必踩的坑。

💡 总结一句话： Core 是真正的核心后台，CLI 只是一个发命令的遥控器。两者通过 TCP 套接字用 JSON 聊天。

4. 在面试中，如果面试官问出：“为什么要采用‘协程/异步 + 多进程’，而不是直接用‘多线程’？”

回答的核心逻辑是：结合 Python 的语言特性（GIL）与 AI Agent 的应用场景特点（既有 IO 密集又有 CPU 密集），从“解决什么问题”和“收益是什么”两个维度切入。

你可以按照以下三分式逻辑进行回答，既展现出深刻的语言特性理解，又能突出架构设计的能力：

第一步：指出 Python 的核心限制（GIL 锁）

“首先，这与 Python 自身的并发机制 密切相关。Python（CPython 解释器）存在 GIL（全局解释器锁）。

如果使用多线程（threading），在处理 CPU 密集型任务（如大数据的序列化/反序列化、本地上下文压缩、复杂 Prompt 解析或数值计算）时，多个线程无法利用多核 CPU 进行真正的并行计算，反而会因为线程频繁切换和锁竞争带来额外的性能开销。”

第二步：解释为什么单个进程内部用“协程/异步（asyncio）”

“对于单进程内部的 IO 任务，我们选择了**协程（async/await）**而不是多线程，原因有两个：

极致的 IO 吞吐与低开销：AI Agent 系统充斥着大量的网络 IO（等待大模型 API 返回、流式响应、网络请求）。协程是用户态的轻量级调度，没有 OS 线程上下文切换（Context Switch）的内核态开销，单线程运行 asyncio 事件循环即可轻松支撑高并发的异步 IO。

避开线程安全问题：多线程并发时，共享内存需要大量的互斥锁（Mutex）来保证数据一致性，极易引发死锁和竞态条件（Race Condition）。而协程基于单线程事件循环，天然避免了复杂的锁机制，使得 Agent 的状态管理更清晰。”

第三步：解释为什么整体架构采用“多进程（IPC）”

“为了突破单进程和 GIL 的限制，我们采用多进程来隔离不同的职责模块（例如 Daemon 后台服务与 CLI/TUI 前端交互，或者未来的密集计算节点）：

真正利用多核与 CPU 隔离：多进程各自拥有独立的 Python 解释器和内存空间，彻底绕过了 GIL 锁，能够真正实现多核并行。

故障隔离与状态解耦：前端 CLI 挂掉或崩溃，完全不会影响后台长考（Thinking）的 Daemon 进程；同时强制要求进程间通过标准的网络/管道协议（如 TCP + NDJSON）通信，使得‘界面层’与‘业务大脑’强解耦，极大地提高了系统的容错性和扩展性。”

5. 命令解析器 /cli/main.py

主解析器负责捕获 git --version 这种全局标志；

add_subparsers(dest="command") 负责生成一个名叫 args.command 的变量；

add_parser("ping") 则是往许可列表里塞入 "ping"。

用户在终端敲下 RuiZN ping 时，args.command 就会被赋值为 "ping"，随后驱动 if args.command == "ping": 分支执行。

步骤 1：创建主解析器 (parser)

parser = argparse.ArgumentParser(prog="RuiZN",description="RuiZNClaude CLI")

参数解析：

prog="RuiZN"：指定程序在帮助文档（Help Message）里显示的名字。如果你在终端敲 RuiZN --help，第一行就会显示 usage: RuiZN [-h] [--version] ...。

description：对这个工具的总说明。

git 类比：这一步相当于你编写了 git 这个主程序的最外层入口。

步骤 2：添加全局参数 (--version)

parser.add_argument("--version", action="store_true", help="Print version and exit")

参数解析：

"--version"：以双短横线开头，代表这是一个可选的标志（Flag）。

action="store_true"（核心）：

默认状态：如果不敲 --version，解析出来的 args.version 就是 False。

触发状态：只要用户在终端敲了 --version，不需要在后面传任何值（不需要写 --version true），argparse 就会自动把 args.version 赋值为 True。

git 类比：这就完全等同于你在终端敲：git --version 此时命令作用于 git 全局，直接打印 Git 版本，不需要也不跟任何子命令。

步骤 3：衍生子解析器容器 (subparsers)

subparsers = parser.add_subparsers(dest="command")

参数解析：

dest="command"（最灵魂的参数）：

dest 是 Destination（目标属性名） 的缩写。

它的作用是告诉 Python：“等会儿不管用户敲了哪个具体的子命令（比如 ping、run、status），请把这个子命令的名字作为一个字符串，存到解析结果 args 的 command 属性里。”

git 类比：这一步是在为 git 建立子命令目录树。

如果你敲 git commit，dest="command" 就会让 args.command = "commit"；

如果你敲 git push，args.command 就等于 "push"。

步骤 4：注册具体的子解析器 (ping)

subparsers.add_parser("ping", help="Ping the core daemon")

参数解析：

"ping"：注册子命令的具体名称。只有在这里注册过的字符串，命令行才认可。

help：当用户敲 kama --help 或 kama ping --help 时显示的子命令说明。

git 类比：这就相当于你在 Git 项目里实现了 git status 或 git checkout 这样的具体功能点。