内容
# Pallium
[](https://www.npmjs.com/package/pallium)
[](https://www.npmjs.com/package/pallium)
[](https://github.com/tszaks/pallium/releases/latest)
[](https://github.com/tszaks/pallium/pkgs/npm/pallium)
Pallium 是一个本地优先的 AI 编程代理控制平面。
它为代理提供存储库内存、风险上下文、验证历史、会话回忆，
以及类似 Claude 的动态工作流，可以独立于主聊天运行。
核心思想很简单：将编排、状态和验证置于模型上下文之外，
以便代理可以执行更大的任务而不会丢失线程。
## Pallium 的功能
Pallium 有三个主要任务：
1. 在编辑之前构建存储库上下文。
2. 记住以前的代理会话和决策。
3. 运行可审计、可恢复的多代理工作流。
在代理需要了解以下信息时使用：
- 哪些文件存在风险
- 哪些文件通常一起移动
- 工作树中发生了什么变化
- 哪些测试很重要
- 最近哪些验证通过或失败
- 任务是否超出了其计划范围
- 哪些以前的会话或决策解释了当前工作
- 如何将工作干净地移交给另一个代理或人类
大多数面向用户的命令都支持 `--json` 格式，以便于代理解析。
## 快速入门
```bash
pallium index
pallium doctor
pallium changed-now --json
pallium explain cmd/workflow.go --json
pallium safe internal/workflow/runtime.go --json
pallium plan internal/workflow/runtime.go --json
pallium verify fast --json
pallium handoff origin/main --json
```
对于动态工作流：
```bash
pallium workflow tools list --json
pallium workflow template list --json
pallium workflow preflight "review workflow changes" --scope internal/workflow --json
pallium workflow run "review workflow changes"
```
对于生成的 工作流脚本：
```bash
pallium workflow generate "fix tests until green" \
--style test-fix \
--test-command "go test ./..." \
--output fix.workflow.js
pallium workflow validate fix.workflow.js
pallium workflow run --script fix.workflow.js "fix tests until green"
```
## 动态工作流
`pallium workflow` 是 Pallium 的本地动态工作流运行时。
它灵感来自 Claude Code 的动态工作流，但它是与代理无关的，
并且基于 Pallium 的存储库内存。
代理应该在编写自定义工作流脚本之前阅读 `PALLIUM_WORKFLOW.md`。
工作流是一个由 Pallium 的 Go 运行时执行的异步 JavaScript 脚本。
脚本通过以下原语协调工作线程：
- `phase(name, fn?)`
- `await agent(prompt, options)`
- `await parallel(items, fn)`
- `await pipeline(items, stage1, stage2, ...)`
- `await check(command, options)`
- `await verify.untilGreen(command, options)`
- `await workflow(savedName, args)`
- `await gate(name, prompt, options)`
- `await coordinator.replan(goal, options)`
- `await pallium.preflight(task, ...scopes)`
- `await pallium.decisions.record(title, body, ...tags)`
- `await pallium.decisions.search(query, limit)`
脚本负责编排。工作线程负责思考、使用 shell 和编辑。
Pallium 持久化每个运行在 SQLite 中，并将工件存储在 `~/.pallium/workflow-runs/` 下。
运行具有稳定的 ID、阶段、工作线程、输出、补丁、报告、门和状态。
### 示例工作流
```js
phase("scope");
const preflight = await pallium.preflight(
"review workflow runtime changes",
"internal/workflow",
"cmd/workflow.go"
);
phase("inspect");
const findings = await parallel(preflight.files_to_inspect || [], file =>
agent("Review " + file + " for correctness risks", {
label: "review-" + file,
mode: "read-only"
})
);
phase("verify");
const verification = await verify.untilGreen("go test ./...", {
label: "tests",
maxRounds: 3
});
return { findings, verification };
```
## 与普通代理循环的区别
普通代理工作将规划、状态、验证输出和下一步骤保留在一个聊天上下文中。
这适用于小型任务，但会变得杂乱无章。
Pallium 工作流将控制流移动到可执行 JavaScript 中：
- 循环是普通代码
- 中间状态存储在变量和 SQLite 中
- 工作线程可以并行运行
- 已完成的工作线程在恢复时被缓存
- 测试被视为外部检查
- 报告和补丁在运行后可检查
- 门、触发器、API 调用和 MCP 客户端可以在聊天之外继续工作
这是使其感觉类似于 Claude 风格的动态工作流的部分：
模型可以编写脚本，Pallium 运行脚本，子代理在跟踪的运行时下执行工作。
`pipeline(items, stage1, stage2, ...)` 使用 Ultracode 风格的流式阶段：
每个项目在前一阶段完成后移动到下一阶段。慢速项目不会阻碍较快的项目。
## 代理工作线程
默认工作线程提供程序是 Codex：
```js
await agent("Inspect auth routes", {
label: "auth-review",
mode: "read-only"
});
```
工作线程模式：
- `read-only`: 使用只读沙箱检查代码
- `test`: 运行验证命令并总结失败情况
- `edit`: 在隔离的工作树中进行更改并生成补丁
编辑工作线程不会直接编辑目标检出。它们在 `~/.pallium/workflow-runs/` 下的 git 工作树中运行，
然后 Pallium 在工作流成功完成后再将补丁应用回目标存储库。
在应用补丁之前，Pallium 会扫描添加的行以查找常见的机密模式，
例如 API 密钥、令牌、密码、OpenAI 样式的密钥和 AWS 访问密钥。
如果设置了 `PALLIUM_WORKFLOW_ALLOW_SECRET_PATCH=1`，则阻止匹配的补丁。
使用 `workflow revert <run-id>` 在应用补丁后反转工作流补丁。
## 任意代理，任意模型
Pallium 不仅限于 Codex。工作流代理可以针对任何已配置的提供程序：
```js
await agent("Review this design decision", {
label: "claude-review",
provider: "claude-code",
mode: "read-only"
});
```
使用环境变量配置提供程序：
```bash
export PALLIUM_WORKFLOW_PROVIDER_CLAUDE_CODE_COMMAND='claude -p "$(cat "$PALLIUM_WORKFLOW_PROMPT_FILE")" > "$PALLIUM_WORKFLOW_OUTPUT_FILE"'
```
提供程序命令通过 `sh -c` 在工作线程 cwd 中运行，并接收：
- `PALLIUM_WORKFLOW_RUN_ID`
- `PALLIUM_WORKFLOW_AGENT_ID`
- `PALLIUM_WORKFLOW_PROVIDER`
- `PALLIUM_WORKFLOW_LABEL`
- `PALLIUM_WORKFLOW_MODE`
- `PALLIUM_WORKFLOW_MODEL`
- `PALLIUM_WORKFLOW_REPO`
- `PALLIUM_WORKFLOW_CWD`
- `PALLIUM_WORKFLOW_PROMPT`
- `PALLIUM_WORKFLOW_PROMPT_FILE`
- `PALLIUM_WORKFLOW_OUTPUT_FILE`
- `PALLIUM_WORKFLOW_SCHEMA_FILE`
提供程序应将其最终的工作线程消息写入 `PALLIUM_WORKFLOW_OUTPUT_FILE`。
如果没有指定输出文件，则使用 stdout 作为备用。
代理还可以针对其他存储库：
```js
await agent("Inspect backend API contract", {
label: "backend",
repo: "/path/to/backend",
mode: "read-only"
});
```
对于编辑工作线程，补丁会应用回工作线程存储库。
## 工作流 CLI
发现和生成：
```bash
pallium workflow tools list --json
pallium workflow template list --json
pallium workflow template show test-fix --json
pallium workflow library list --json
pallium workflow library show security-audit --json
pallium workflow library install security-audit --cwd .
pallium workflow generate "review auth" --style review --output review.js
pallium workflow generate "custom migration workflow" --llm --output custom.js
pallium workflow validate custom.js
```
运行和检查：
```bash
pallium workflow run "review this branch"
pallium workflow run --script review.js "review this branch"
pallium workflow run --workflow review-branch "review this branch"
pallium workflow run /review-branch "review this branch"
pallium workflow run --background "audit route handlers for missing auth"
pallium workflow list
pallium workflow status <run-id>
pallium workflow inspect <run-id>
pallium workflow show <run-id>
pallium workflow read <run-id>
pallium workflow report <run-id> --json
pallium workflow watch <run-id>
```
控制：
```bash
pallium workflow pause <run-id>
pallium workflow resume <run-id>
pallium workflow stop <run-id>
pallium workflow save <run-id> --name review-branch
pallium workflow apply <run-id>
pallium workflow revert <run-id>
```
自动化和舰队：
```bash
pallium workflow trigger add daily-review "review workflow changes" --cwd .
pallium workflow trigger add changed-review "review workflow changes" --kind on-changed --cwd .
pallium workflow trigger list
pallium workflow trigger run changed-review
pallium workflow trigger watch --once
pallium workflow fleet status --json
pallium workflow analytics --json
```
代理门：
```js
await gate("patch-safety", "Verify patches are safe to apply", {
criteria: "tests pass, no secrets are introduced, and scope matches the task"
});
```
API 和 MCP：
```bash
pallium workflow serve --addr 127.0.0.1:8765
pallium workflow serve --addr 0.0.0.0:8765 --token "$PALLIUM_WORKFLOW_API_TOKEN"
pallium workflow mcp
```
审计：
```bash
pallium workflow audit --json
pallium workflow audit --run-acceptance --json
scripts/workflow-acceptance.sh
```
## 验证循环
在脚本需要根据命令结果分支时使用 `check()`：
```js
const result = await check("go test ./...", { label: "go-tests" });
if (!result.ok) {
await parallel(result.failures || [], failure =>
agent("Fix this failure: " + JSON.stringify(failure), {
label: "fix-" + failure.name,
mode: "edit",
isolation: "worktree"
})
);
}
```
在 Pallium 应该拥有检查、修复、重新检查循环时使用 `verify.untilGreen()`：
```js
return verify.untilGreen("go test ./...", {
label: "go-tests",
maxRounds: 3
});
```
循环在命令通过、达到轮数限制或失败停止更改时停止。
## 成本和预算
Pallium 不添加计费层。工作流成本来自运行的 worker 提供程序，
例如 Codex、Claude 或另一个模型 CLI。
Pallium 跟踪估计的每个代理成本，以便代理可以做出预算决策：
```bash
export PALLIUM_WORKFLOW_AGENT_COST_USD=0.02
pallium workflow run "large review" --max-budget-usd 1.00
pallium workflow analytics --json
```
估计是本地记账。它不是提供程序的计费数据，除非您的提供程序命令使其如此。
## 存储库内存命令
```bash
pallium index
pallium doctor
pallium explain <path>
pallium risk <path>
pallium neighbors <path>
pallium decisions <query>
pallium safe <path>
pallium plan <path>
pallium changed-now
pallium review [base-ref]
pallium verify <fast|safe|full>
pallium handoff [base-ref]
pallium task start "Tighten auth flow" src/auth cmd
pallium task show
pallium task clear
```
`verify` 在存储库本地的 Pallium 数据库中记录每次运行，
以便未来的 `review` 和 `handoff` 可以包括最近的验证历史。
## 会话内存
Pallium 从 `~/.codex/sessions/**/*.jsonl` 索引 Codex CLI 转录，
并从 `~/.claude/projects/**/*.jsonl` 索引 Claude Code 转录。
```bash
pallium sessions live --details
pallium sessions index
pallium sessions index --safety-buffer 30m
pallium sessions index --force
pallium sessions index --provider claude
pallium sessions index --provider codex
pallium sessions list --limit 20
pallium sessions search "MCP auth" --limit 10
pallium sessions search "MCP auth" --hybrid --limit 10
pallium sessions related . --file cmd/app.go --limit 5
pallium sessions grep "Timed out waiting for PGLite lock" --limit 20
pallium sessions show <session-id> --transcript
pallium sessions embed --batch-size 8
pallium sessions semantic "find the session where we debugged MCP startup failures"
pallium sessions stats
```
索引是增量的。最近 2 分钟内修改的活动转录文件将被跳过，
以便 Pallium 不会在代理仍在写入日志时追踪日志。
会话内存数据存储在 `~/.pallium/codex-sessions.sqlite`。
如果存在较旧的数据库，Pallium 可以回退到 `~/.codex-memory/codex-sessions.sqlite`。
嵌入使用 `OPENAI_API_KEY` 或 `OPENAI_ADMIN_API_KEY`。
对于另一台机器的会话：
```bash
pallium sessions index --include /path/to/other/.codex/sessions --machine tylers-macbook
pallium sessions index --provider claude --include /path/to/other/.claude/projects --machine tylers-macbook
```
## 控制台协调
`pallium console` 是一个用于代理会话的本地协调界面。
它可以检查实时 Codex 和 Claude Code 会话、存储清单、
创建移交、跟踪文件声明、请求权限和管理审查门。
Pallium 还可以启动它拥有的会话：
```bash
pallium console ls --details
pallium console run --id owned-demo -- /bin/sh -c 'echo hello'
pallium console run --background --id owned-worker -- /bin/sh -c 'sleep 30'
pallium console owned list
pallium console owned show owned-worker
pallium console read owned-worker --tail 50
pallium console interrupt owned-worker
```
当前控制边界是保守的：Pallium 控制它自己启动的会话。
它不会将命令注入任意现有的 Codex 或 Claude Code 会话。
## HTTP API 和 SDK
启动本地工作流 API：
```bash
pallium workflow serve --addr 127.0.0.1:8765
```
绑定到 localhost 以外时，请设置 `--token` 或 `PALLIUM_WORKFLOW_API_TOKEN`。
身份验证请求使用 `Authorization: Bearer <token>`。`GET /healthz` 保持开放，
用于本地健康检查。
端点：
- `GET /healthz`
- `GET /workflows/fleet`
- `GET /workflows/analytics`
- `GET /workflows/library`
- `GET /workflows/library/{name}`
- `POST /workflows/library/install`
- `GET /workflows/runs/{id}`
- `POST /workflows/run`
`pkg/workflowclient` 中的 Go 客户端包装此 API。
## 开源运营
存储库管理文件位于 `.github/`：
- 用于错误和功能请求的 issue 模板
- 拉取请求检查清单
- `CODEOWNERS`
- Go、npm 和 GitHub Actions 的 Dependabot 更新
- CI、CodeQL、OpenSSF Scorecard 和发布资产门
项目策略文件：
- `CONTRIBUTING.md`
- `SECURITY.md`
- `CODE_OF_CONDUCT.md`
- `SUPPORT.md`
安全问题应遵循 `SECURITY.md` 而不是公共问题线程。
## 证明门
工作流系统有一个已安装的 CLI 验收门：
```bash
PALLIUM_BIN="$(which pallium)" scripts/workflow-acceptance.sh
pallium workflow audit --run-acceptance --json
```
验收脚本锻炼：
- 并行工作线程计时
- 恢复缓存重用
- 工作流生成和验证
- 与保存的工作流组合
- 预算失败行为
- 结构化报告
- 存储库预飞行检查
- `verify.untilGreen`
- 持久决策
- 多存储库代理
- 库安装
- 配置的提供程序
- 协调者重规划
- 编辑补丁应用和恢复
- 机密补丁阻止
- 更改触发器
- 代理门
- 舰队限制
- 分析
- HTTP API
- MCP 工具列表
- v1-v7 审计检查清单
对于正常开发：
```bash
go test ./...
go vet ./...
scripts/workflow-acceptance.sh
```
## 安装
从 npm 安装：
```bash
npm install -g pallium
pallium version
```
npm 包直接从 GitHub 安装 Pallium 发布二进制文件，并将其保存在 `~/.pallium/npm/<version>/`。
直接安装发布 tarball：
```bash
npm install -g https://github.com/tszaks/pallium/releases/download/vX.Y.Z/pallium-X.Y.Z.tgz
```
使用 Go 安装：
```bash
go install github.com/tszaks/pallium@latest
```
从 GitHub Packages 安装：
```bash
npm config set @tszaks:registry https://npm.pkg.github.com
npm install -g @tszaks/pallium
```
从源代码构建：
```bash
git clone https://github.com/tszaks/pallium.git
cd pallium
go test ./...
go run . --help
```
## 数据位置
- 存储库本地索引和验证数据：`.pallium/`
- 会话内存数据库：`~/.pallium/codex-sessions.sqlite`
- 工作流运行工件：`~/.pallium/workflow-runs/`
- 用户工作流库：`~/.pallium/workflows/`
- 旧版会话数据库备用：`~/.codex-memory/codex-sessions.sqlite`
## 许可
MIT
连接信息
猜你喜欢
暂无推荐服务器