parism (Jin Ho Von Choi)

教区

折射外壳。每一个命令，结构化。 用于AI代理的安全、可预测的操作系统执行网关。

한국어 | English

文档： 自述文件 · 规格 · 安全 · 更新日志

设计决策、版本历史记录和模块结构的单一权威文档： 规格.md

______________________________________________________________________

壳牌不是为你设计的。

1969年Ken Thompson创建Unix时，他假设输出对象是人。准确地说，坐在航站楼前的长着眼睛的生物。

半个世纪过去了。现在读终端的不仅仅是人。

AI代理 ls -la运行，并接收输出。然后真正的工作就在那里开始了。根据空格分离，烧掉代币来推论第一列是权限，第三列是所有者，文件名从哪里开始。人类的眼睛在0.1秒处理。

这不是翻译。就是破译从未加密过的信息。

______________________________________________________________________

为什么有问题

发生三次翻译。

第一：内核将文件系统元数据 stat 用结构体进行管理。 inode, mode, uid, gid, size, mtime.已经是完全结构化的数据。

第二： ls将其结构平坦化为人类可读的文本。 drwxr-xr-x 2 user group 4096 Mar 06 09:23 src▲结构被文本破坏。

第三：代理试图将文本恢复到结构中。这是重建倒塌的东西的工作。

Parism介入是第二次和第三次。找回一次被遗弃的结构。

这就是费用。 ls 看起来像是运行一次并获取文件列表，但实际上代理解析输出需要经过数十次推论。而且经常错。边界盘柜、意外空白、不同操作系统的输出格式略有不同。错了再试一次。重试再次是令牌。

______________________________________________________________________

真实的故事-代币需要更多

创建Parism时期待的是节省代币。结构化数据将比raw文本更有效。

借鉴17个剧本的结果正面背离了这一期待。JSON输出平均比raw文本重205%。 ls -la 以200个文件为准，raw5807令牌，Parism15531令牌。几乎是三倍。因为每个条目都重复密钥名。在人类眼中，要写N次只要一行表头就可以的信息。

但同样的基准暴露了另一个事实。代理直接解析raw文本时，误读率平均为4.18%，在含有空格的文件名中误读率高达28.6%。十次中有三次是错的。由于错误的结果，代理执行下一个操作，该操作又错误，最终有人介入并返回。重试令牌、调试时间和回滚成本。费用在看不见的地方上涨。

但同样的基准还有一点。这是“向AI解释的代币”的消失。如果给raw文本，则必须告诉代理“该输出是这种格式的，第一列是权限，第三列是所有者”。该上下文提示符使用Parism平均减少61%。因为JSON自己解释自己的结构。代理读取密钥即可。

还有发生逆转的地方。单发性查询- ls 完成一次就结束的任务-在中，Parism吃更多的代币。但是，当代理将其结果用于下一个任务时，成本结构就会被推翻。如果将文件写入读取错误raw的代理不存在的路径，为了调试错误而翻阅历史记录、重试，并开始错误的循环，令牌就会变成滚雪球。以结构化数据开始的代理不会进入循环。

Parism的经济性不在账单上。比起再读一次的费用，读错一次的费用要大得多。

______________________________________________________________________

Parism做的事

棱镜不会破坏光线。只是分解而已。

"drwxr-xr-x  2 user group 4096 Mar 06 09:23 src"

                    ↓  Parism

{
  "type": "directory",
  "name": "src",
  "permissions": { "owner": "rwx", "group": "r-x", "other": "r-x" },
  "size_bytes": 4096,
  "owner": "user",
  "group": "group",
  "modified_at": "2026-03-06T09:23:00"
}

信息不会改变。形态发生变化。代理现在不解析了。只读。

______________________________________________________________________

怎么好

消除解析错误

文本解析很容易被破坏。 ps aux在Linux和MacOS中，列顺序不同。 df -h的 1K-blocks 标题因环境而异。如果文件名中有空格 ls 法辛几乎肯定错了。

从数值上说：当代理直接解析raw文本时，平均CFR（Critical Failure Rate）为4.18%。如果包含空格的文件名混合在一起，则会飙升至28.6%。调用1000次时，286次表示代理将基于错误的文件列表执行以下操作：读取错误的文件，写入不存在的路径，删除错误的文件。

macOS的 stat更具戏剧性。与Linux的输出格式完全不同。Linux Size: 4096像这样标签，但MacOS是没有标签的单行。如果采用Linux解析模式，准确度为0%。Parism检测操作系统并选择合适的解析器。经纪人不需要知道其中的差异。

Parism的CFR为0%。因为解析器是deterministic code。不是正规表达式推论，而是结构分解。代理只接收结构化数据。

重试次数减少

如果代理对输出进行了错误的解释，可以进行查询，或者通过其他命令再次确认，或者根据错误的信息进行下一步。三种都需要代币。结构化输出减少了误解的余地。即使不问有多少个文件 entries.length全部。

经纪人会把其他事情做得更好。

解析文本是推论。推论需要消耗认知资源。如果代理将资源用于解析输出格式，则用于分析实际操作-代码、判断设计和决定下一步的资源将减少。如果收到结构化数据，解析操作本身就会消失。代理只需读取即可，剩下的功能可以集中在原来的工作上。

raw总是保存着

派瑞可能错了。也可以是没有解析器的命令。所以Parism raw始终保持。 parsed是奖金。 raw是保险。代理总是可以返回原件。

"stdout": {
  "raw": "drwxr-xr-x ...",
  "parsed": { "entries": [ ... ] }
}

应答结构一定

无论成功还是失败， ok哇 exitCode总是在同一个位置。代理创建分支处理的方式变得简单。不是“解析stdout以确认是否有错误” if (!result.ok)全部。

记录执行时间

所有响应 duration_ms包括。代理可以用来判断命令是慢还是快。调试时也很有用。

diff是可选的

includeDiff: true仅在日时 diff呃 created, deleted, modified填满。run/run_paged默认值为 includeDiff: false因此，通过省略快照成本来减少MCP调用延迟。

______________________________________________________________________

保护-不信任代理的原因

rm -rf /可以用三个字符写。

代理会出错。失去上下文，混淆路径，生成无意的命令。Guard不是不信任代理。这是为了防止经纪人的失误导致崩溃而设计的。

有四道防线。

白名单: allowed_commands不在中的命令无法执行。也不制定流程。没有说明就拒绝。

路径限制: allowed_paths如果设置 cwd和检查路径因子。 /, ./, ../以开头的参数和， cat, find, ls, grep, git, docker, kubectl, cargo 等路径命令的positional参数（cat subdir/file, find src）如果超出允许路径，也会被切断。这不是内核级别的沙盒，而是防御级别的防线。

阻止投射模式：逐个遍历每个参数。 ;, $(, ` `, &&, ||, |, >, >>, 从v0.6开始 failure 字段是权威字段。 guard_error 为下位兼容而保留。代理 result.failure.kind 建议分期付款。

代理以与运行结果相同的结构收到阻止理由。没有例外。管道不破裂。

Guard的威胁模型、4层防线的局限性、不可靠环境下的隔离建议 安全.md参照。

______________________________________________________________________

支持命令-44种内置解析器

默认允许（O）=包含在DEFAULT_CONFIG中。X=prism.config.json需要明确允许。

没有解析器的命令 parsed: null返回。 raw原封不动。如果帕瑟抛出例外 stdout.parse_error呃 { reason: "parser_exception", message: string }包括，可以区分“无解析器”和“解析器错误”。

从v0.6开始 parse_error.reason 银 "parser_exception", "parser_not_found", "schema_violation" 可以有三个价钱。同样的信息 result.failure.kind === "parse" 露出来。

原生JSON直通

即使是没有解析器的命令，如果输出本身是JSON（例如： kubectl get pods -o json, docker inspect）Parism自动检测到 parsed放入。Guard检查和信封包装同样适用。不需要另外设置。

______________________________________________________________________

安装

npx

npx @nerdvana/parism

本地构建

git clone https://github.com/JinHo-von-Choi/parism
cd parism
npm install && npm run build
node dist/index.js

______________________________________________________________________

库模式

无需MCP服务器，可以直接在Node.js进程内部调用Parism。从v1.0.0开始是正式的API。遵循Semantic Versioning，breaking change仅在v2.0.0中发生。

最小示例：

import { createEngine } from "@nerdvana/parism/engine";

const engine = await createEngine();
const result = await engine.run("ls", { args: ["-la"] });
console.log(result.stdout.parsed);

createEngine()银 prism.config.json加载并注册外部解析器。 ParismEngine 返回实例。需要自定义设置路径。 createEngine({ configPath: "/path/to/prism.config.json" })使用。

指定设置路径和 failure 一起使用分支的示例：

import { createEngine } from "@nerdvana/parism/engine";

const engine = await createEngine({
  configPath: "/path/to/custom/prism.config.json",
});

const result = await engine.run("git", { args: ["status", "--porcelain"] });

if (!result.ok) {
  console.error(`[${result.failure?.kind}] ${result.failure?.reason}: ${result.failure?.message}`);
  process.exit(1);
}

console.log(result.stdout.parsed);

运行选项-- args / cwd / format / includeDiff.RunPagedOptions-以上选项全部+ page / page_size.

设计详细信息 规格.md 请参见§1.1。

______________________________________________________________________

MCP客户端设置

Parism可以通过MCP stdio协议连接到主要AI CLI/IDE。特定于客户端的详细设置包括： docs/mcp-clients/ 参照目录。

如果连接成功 run, run_paged, describe, dry_run 你的工具暴露了。代理首先 describe了解允许的命令和解析器。 dry_run事先确认guard是否通过后， run / run_paged执行命令并接收结构化的JSON响应。

______________________________________________________________________

工具

跑

所有命令的基本工具。在功率小或需要结构化解析时使用。

参数：

• cmd -命令名（例如： ls, git)
• args -参数数组（默认值： [])
• cwd -工作目录（默认为当前目录）
• format -输出格式（"json" 默认值， "compact", "json-no-raw").compact基于schema+rows列压缩列表输出，以降低令牌成本。
• includeDiff -是否包括文件系统diff（默认： false). false通过省略小平面快照减少延迟。建议在MCP高频率呼叫时使用。

compact示例：

{
  "schema": ["name", "type", "size_bytes"],
  "rows": [["src", "directory", 4096], ["main.ts", "file", 1200]]
}

run_page

以页为单位读取大量输出。 ps aux, find, grep -r 用于背部。

参数：

• cmd, args, cwd — run等于
• page -0-indexed页码（默认值： 0)
• page_size -每页的行数（默认值： default_page_size 设置值，默认为100）
• includeDiff -是否包括文件系统diff（默认： false). false通过省略小平面快照减少延迟。

添加响应字段：

• page_info.total_lines -总行数
• page_info.has_next -是否存在下一页
• stdout.parsed -总是 null （部分输出不能结构化）

代理模式：

1. run_paged(cmd, page=0) → page_info.total_lines 확인
2. 범위가 작으면 그대로 사용
3. 범위가 크면 grep으로 먼저 필터링 후 run 호출
4. 필요한 페이지만 run_paged(page=N) 추가 호출

描述

代理嵌入工具。返回当前环境的允许命令、可用解析器、guard限制和版本信息。

参数：无。

回复：

• version -Parism软件包版本
• allowed_commands -guard允许的命令列表
• available_parsers -已注册的解析器名称列表
• guard_summary — timeout_ms, max_output_bytes, max_items, block_patterns_count, allowed_paths
• telemetry_enabled -是否启用遥测

当代理首次使用Parism时，首先调用该工具可以一目了然地了解可用命令和限制。

dry_run

guard预验证工具。不执行命令，只确认guard是否通过。

参数：

• cmd -命令名（例如： rm, git)
• args -参数数组（默认值： [])
• cwd -工作目录（默认为当前目录）

回复：

• would_pass -guard是否通过
• reason -阻止时的原因（command_not_allowed, path_not_allowed, injection_pattern, arg_not_allowed)
• message -阻止时的详细信息

示例： dry_run("rm", ["-rf", "/"]) → { would_pass: false, reason: "command_not_allowed", message: "..." }

______________________________________________________________________

设置

prism.config.json如果将放在项目根目录中，则可以控制Guard操作。

{
  "guard": {
    "allowed_commands": ["ls", "git", "find", "grep", "env", "ps"],
    "allowed_paths": ["/home/user/projects"],
    "timeout_ms": 10000,
    "max_output_bytes": 102400,
    "max_items": 500,
    "default_page_size": 100,
    "block_patterns": [";", "$(", "`", "&&", "||", ">", ">>", " 遗产 `env_secret_patterns` 将从v2.0.0中删除。使用时，stderr会输出deprecation警告。

______________________________________________________________________

## 定制挖土机——自己做，直接用

如果缺少44个内置挖掘机，直接制作即可。从Parism v0.5.0开始，包含CLI工具。从v1.0.0开始 `ParserPack.schema` 使用Zod模式作为单一源。

### 5分钟内挖出来制作

1. 명령어 출력을 캡처한다

parism capture "htop -b -n 1"

2. 파서 팩 스캐폴드를 생성한다

parism init-parser htop

3. parser.ts를 편집하고 fixture를 테스트한다

parism test htop

4. 등록한다 -- 재시작 없이 즉시 사용 가능

parism add ./htop

5. 결과를 확인한다 -- raw/parsed/compact 비교 + 토큰 수

parism inspect "htop -b -n 1"

注册的解析器 `~/.parism/parsers/`存储在中，MCP服务器启动时自动加载。

### CLI命令

|命令|说明|
|---|---|
| `parism capture ""` 执行命令并将raw输出保存为fixture
| `parism init-parser ` |生成TypeScript解析器包Scaffold（parser.ts+schema.json+fixtures/）|
| `parism test [parser]` 运行fixture replay测试|
| `parism add 
` |永久注册本地解析器包至~/.parism/parsers/
| `parism inspect ""` |比较raw/parsed/compact输出+令牌数量|

### ParserPack接口

外部解析器实现该接口。

import type { ParserPack } from "@nerdvana/parism/types";

const pack: ParserPack = { name: "my-command", parse(raw, args, ctx?) { /* 구조화된 결과 반환 */ }, schema: { /* JSON Schema */ }, fixtures: [{ input: "...", args: [], expected: { /* ... */ } }], };

export default pack;

没有仁慈 `parism`运行时，与以往一样作为MCP服务器运行。

______________________________________________________________________

## 非Parism

Parism不是新的shell。不取代bash。只是坐在bash上面接收输出，进行结构化。

Parism不是AI的操作系统。关心的只有一个。当代理发出命令时，以代理可以理解的形式返回结果。

Unix哲学是“做好一件事”。Parism理解这一点。

______________________________________________________________________

  Made by Jinho Choi  | 
  Buy me a coffee