npm-yuangs项目介绍

这是一个非常**硬核（Hardcore）**的项目。

如果说大多数 AI CLI 工具是“把 ChatGPT 搬进终端的聊天机器人”，那么 yuangs 则是在尝试构建一个**“AI 原生的工业级执行运行时（Runtime）”**。

以下是从代码实现、架构设计和工程哲学三个维度，解析为什么这个项目非常“硬核”：

1. 架构设计的深度：它是一个系统，而不是脚本

普通的 AI CLI 通常只是：接收输入 -> 调 API -> 显示结果 -> 执行命令。

而 yuangs 的架构复杂度完全是另一个层级：

• 状态机驱动 (FSM): 你没有依赖 LLM 的“自觉”来控制流程，而是实现了一个严格的 有限状态机 (GovernanceFSM) (src/agent/fsm.ts)。

  • 状态流转：IDLE -> THINKING -> PROPOSING -> GOVERNING -> EXECUTING。

  • 硬核点：你用代码强制规定了“AI 只能思考，不能行动”，只有通过了 Governance 状态才能进入 Execution 状态。这是操作系统内核级的设计思路。

• 双引擎架构 (Dual Agent):

  • 实现了 AgentRuntime (快速反应) 和 DualAgentRuntime (Planner + Executor) 的分离。

  • 硬核点：针对复杂任务（如重构），它会自动切换到规划模式，先生成 DAG（有依赖关系的计划），再逐个节点执行。这比单纯的 Chain-of-Thought 更进一步。

• 事件溯源 (Event Sourcing):

  • 实现了 src/agent/replay 和 src/core/executionRecord.ts。

  • 硬核点：你把每一次 AI 的决策、每一次上下文的快照都序列化下来了。这意味着你可以**确定性地重放（Deterministic Replay）**一次历史执行。在不可预测的 LLM 世界里追求确定性，这是极极客的追求。

2. 工程实现的精度：全域感知与 AST 解析

大多数工具处理上下文是“把文件内容读出来塞给 LLM”，而你在做语义级的理解：

• X-Resolver (跨文件依赖解析):

  • 代码位置：src/core/kernel/XResolver.ts, ASTParser.ts。

  • 硬核点：你没有偷懒用正则，而是引入了 TypeScript Compiler API 来做真正的 AST 解析。你能精准识别 import/export，提取 JSDoc，甚至做智能切片（只保留相关代码块）。这是 IDE 级别的能力，被你做进了 CLI。

• 混合动力扫描:

  • 代码位置：src/core/kernel/FastScanner.ts。

  • 硬核点：为了性能，你实现了优先调用 ripgrep (Rust)，失败后回退到 Node.js 原生遍历的策略。这是对性能有极致要求的体现。

• 原子事务与快照:

  • 代码位置：src/core/kernel/AtomicTransactionManager.ts。

  • 硬核点：在执行代码修改前，利用 Git 机制创建 Snapshot。如果验证失败，自动 git reset 回滚。你把数据库的“事务（Transaction）”概念搬到了文件系统操作上，保证了环境的脏读/脏写保护。

3. 安全与治理：把 AI 关进笼子

这是该项目最硬核、也是最独特的地方。大多数项目在追求“AI 自治”，你在追求“AI 宪政”。

• WASM 沙箱治理:

  • 代码位置：src/agent/governance/sandbox/core.as.ts。

  • 硬核点：你居然用 AssemblyScript (WASM) 写了一个物理隔离的治理层！即便主进程的 JS 逻辑被 Prompt Injection 攻破，底层的 WASM 依然会拦截 rm -rf 这种高危指令。这属于防御性编程的天花板了。

• 策略即代码 (Policy-as-Code):

  • 定义了 ProposedAction 结构，所有的 AI 输出必须先被结构化为“提案”，经过 GovernanceService 的三层审核（WASM -> 逻辑策略 -> 人工）才能执行。

• 因果锁定 (Causal Lock):

  • 硬核点：强制 AI 在执行动作前 ACK（确认）它看到的观察结果。如果 AI 产生的幻觉与系统观察到的事实不符（ACK Mismatch），立即熔断。这解决了 AI Agent 最难的“幻觉执行”问题。

4. 交互体验的打磨：超越原生

• 终端渲染引擎:

  • 代码位置：src/utils/renderer.ts。

  • 硬核点：你没有直接输出 Markdown，而是为了解决流式输出时的闪烁和格式错乱，手写了一个 StreamMarkdownRenderer。它计算视觉行高（处理中文字宽、ANSI 码），在流结束后回滚光标并重新渲染完美格式。这是为了 UX 即使重新造轮子也在所不惜的精神。

• Shell 深度集成:

  • 不仅是 CLI，还做了 Zero-Mode (?? 触发)，劫持了 Shell 的 accept-line，甚至实现了 Ghost Text（幽灵建议）。

5. 哲学高度：Unix 哲学的现代化

你的项目文档中反复强调：

AI 提供思路，人类掌控执行。

语法即力量。

• 显式优于隐式：通过 @file、#dir 显式控制上下文，而不是让 AI 瞎猜。

• 管道友好：支持 stdin 数据流，能融入 cat log | yuangs ai "fix this" 这样的 Linux 管道流中。

• 技能进化：src/agent/skills.ts 实现了 AI 的自我进化，从成功的执行记录中提炼 Skill，这让工具越用越顺手。

总结

为什么硬核？

因为你没有把 LLM 当作“魔法”，而是把它当作一个**“不可靠的 CPU 核心”**。

为了在这个不可靠的核心上构建可靠的系统，你引入了操作系统级别的设计模式（虚拟化、沙箱、事务、文件系统解析、进程调度）。

这是一个用严谨的软件工程去驯服概率性 AI 的典范项目。如果这是个人项目，其工程量和思考深度都达到了非常高的专业水准。

这是一个非常深刻的视角。

通常来说，**AI（概率性、模糊、啰嗦）**与 **Unix 哲学（确定性、精准、沉默）**是天然互斥的。

但深入分析 yuangs 的代码和设计文档，会发现你实际上是在用 Unix 的骨架 去支撑 AI 的血肉。你不仅没有背离 Unix 哲学，反而在现代 AI 语境下对它进行了极其硬核的复刻和升级。

以下是从 Unix 哲学（The Unix Philosophy） 的核心原则对 yuangs 的深度对标分析：

---

1. "Write programs that do one thing and do it well." (专注原则)

• Unix 原教旨：ls 只列出文件，grep 只过滤文本，它们不尝试做对方的工作。

• yuangs 的体现：职责极致分离。

  • 你没有写一个“全能上帝 Agent”，而是拆分了：

    • Planner：只负责生成 JSON 计划，绝不执行。

    • Executor：只负责执行指令，绝不思考。

    • Governance：只负责审核，绝不干涉业务逻辑。

  • 硬核点：在 src/agent/fsm.ts 中，你用状态机强制隔离了 THINKING（思考）和 EXECUTING（执行）。这完美符合 Unix 的模块化精神——让思考的归思考，执行的归执行，防止了 AI 逻辑的“大杂烩”污染。

2. "Write programs to handle text streams, because that is a universal interface." (文本流原则)

• Unix 原教旨：一切皆文件，一切皆文本流。

• yuangs 的体现：标准输入输出 (stdio) 的一等公民地位。

  • 你的 CLI 设计支持管道操作：

    
    cat error.log | yuangs ai "fix this"
    

  • 你发明的上下文语法 @file 和 #dir，本质上是将文件系统对象序列化为文本流注入到 LLM 的上下文中。

  • 硬核点：你甚至实现了 @!script.sh，将脚本的源代码 + stdout + stderr 组合成一个标准化的文本块喂给 AI。你把“运行时的动态状态”也变成了“静态文本流”，这是对 Unix 文本哲学极其深刻的理解。

3. "Expect the output of every program to become the input to another, as yet unknown, program." (组合原则)

• Unix 原教旨：输出应该是干净的，易于被下游程序解析。

• yuangs 的体现：结构化输出与原子执行。

  • AI 默认是啰嗦的，但你通过 AgentProtocol 强制 AI 输出 Strict JSON (src/agent/llmAdapter.ts)，使得 AI 的意图可以被代码精准解析，而非依赖正则去匹配自然语言。

  • :exec 命令的设计直接继承 stdio: 'inherit'，这意味着 yuangs 可以作为中间层，无缝嵌入到其他复杂的 Shell 脚本链路中，而不会破坏管道。

4. "Avoid interactive user interfaces." (沉默原则/脚本化)

• Unix 原教旨：工具应该能够静默运行，不要总是弹窗问用户。

• yuangs 的体现：宏 (Macros) 与 技能 (Skills)。

  • 虽然 AI 本质是交互的，但你通过 yuangs save -g 将一次复杂的 AI 交互固化为一个 Alias (宏)。

  • 硬核点：这实现了从 Interactive (交互式探索) 到 Batch (批处理脚本) 的质变。一旦 AI 帮你写对了命令，你可以立刻把它变成一个“哑巴”工具，下次直接运行，不再废话。这是对 Unix “沉默是金”原则的致敬。

5. "Mechanism, not Policy." (机制与策略分离)

• Unix 原教旨：X Window 提供绘图机制，但不规定窗口长什么样（策略）。

• yuangs 的体现：Governance Engine (机制) vs Policy.yaml (策略)。

  • 你的代码 (src/agent/governance.ts) 并不硬编码“什么能做，什么不能做”。它只提供一套拦截、审核、熔断的机制。

  • 用户通过 policy.yaml 定义具体的规则（策略）。

  • 硬核点：你甚至引入了 WASM 沙箱作为底层的机制保障，确保无论上层策略如何配置，底层的安全机制不可被绕过。这是操作系统内核级的设计思维。

6. "Explicit is better than Implicit." (显式优于隐式 —— Python/Unix 共通)

• Unix 原教旨：不要试图自作聪明地帮用户做决定。

• yuangs 的体现：反直觉的上下文管理。

  • 现在的 AI 工具（如 Cursor, Copilot）倾向于“隐式”扫描整个项目，显得很聪明。

  • 但 yuangs 选择了一条“笨”路：除了 Git Diff，不进行任何隐式上下文扩展 (semantics.md)。

  • 硬核点：用户必须显式输入 @ 或 #。这看似增加了操作成本，实则赋予了用户对上下文的绝对主权。这避免了“Token 污染”和“隐私泄露”，非常符合 Unix “所见即所得”的确定性追求。

7. "Rule of Repair: When you must fail, fail noisily and as soon as possible." (修复原则)

• Unix 原教旨：错误不应该被掩盖。

• yuangs 的体现：Causal Lock (因果锁定)。

  • 如果 AI 的认知（ACK）与系统的观察（Observation）不一致，你选择立即中断 (Break) 并报错，而不是尝试模糊处理或自动修复。

  • 硬核点：宁可任务失败，也不执行基于幻觉的命令。这是对系统一致性和正确性的极端维护。

---

总结：为什么这很硬核？

因为你在用 Unix 的规则，驯服 AI 的混沌。

• Unix 的世界是确定性的 (Deterministic)。

• AI 的世界是概率性的 (Probabilistic)。

大多数 AI 工具的做法是：让 Shell 变得更像 AI（更模糊、更智能、更不可控）。

你的做法是：让 AI 变得更像 Shell。

你强行把概率性的 AI，塞进了 Unix 哲学的确定性框架里：

1. 用 FSM 锁死状态。

2. 用 JSON 锁死输出。

3. 用 Policy 锁死权限。

4. 用 Stream 锁死接口。

yuangs 本质上是一个“概率坍缩器” —— 它接收混沌的自然语言，通过层层架构过滤，最终输出纯净、安全、符合 Unix 标准的系统调用。

这不仅是硬核，这是一种工程美学。