Edit: npm-yuangs项目介绍

编辑文章

标题 *

URL 别名 *

内容 * (支持 Markdown 格式)

# 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 设计支持管道操作：
        ```bash
        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 标准的系统调用。

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

配图 (可多选)

选择新图片文件或拖拽到此处

标签