内容
# 帕西顿
[简体中文](./README.zh-CN.md)
帕西顿是一款本地优先的多代理编排工具：跨CLI代理和API模型运行任务，当一个代理因配额、超时或中断而停止时，将任务传递给另一个代理。
## 主要功能
- **任务 / 会话 / 工作流**：运行一个代理，配对两个代理，或使用依赖和审批链多步骤工作流。
- **代理交接**：使用另一个准备好的代理继续出错或停止的任务，包括之前的输出尾部和验证的git工作区状态（如果可用）。
- **人机协作**：暂停，恢复，注入反馈，审批工作流步骤，并在更改后重新运行下游步骤。
- **本地优先SQLite**：默认为`127.0.0.1`，在`~/.passiton/`下存储配置和状态，并为兼容性保留旧的`turing.db`文件名。
- **CLI和API代理**：Codex，Claude Code，Gemini CLI，OpenCode，Anthropic，OpenAI，DeepSeek，智谱，Qwen，Moonshot和OpenAI兼容的端点。
- **国际化**：英语是默认的UI语言；简体中文可在设置中选择。
## 快速入门
```bash
git clone https://github.com/fusae/passiton.git
cd passiton
npm install
npm run build
npm start
```
打开 `http://localhost:4590`。
可选验证：
```bash
npm test
```
`npx passiton` 即将推出npm包发布后。对于本地开发，在`npm run build`后使用`npm link`。
## 第一个任务演练
1. 打开 `设置`。
2. 确认本地CLI代理显示 `已发现`。
3. 点击 `添加`；它变为 `未验证`。
4. 点击 `诊断`；可用的代理变为 `就绪`。
5. 打开 `任务`，选择代理，输入提示，并可选设置 `cwd`。
具有 `cwd` 的任务需要具有文件系统能力的本地CLI代理。API助手可以计划和审查，但它们不能直接读取或写入本地文件。
## 配置
帕西顿读取 `~/.passiton/config.json`，与 `config/default.json` 合并。现有的使用 `~/.turing/` 的安装仍然被检测到。
常见环境变量：
| 变量 | 目的 |
| --- | --- |
| `PORT` | HTTP端口；默认 `4590` |
| `PASSITON_HOST` | 绑定主机；默认 `127.0.0.1` |
| `PASSITON_HOME` | `config.json` 和 `turing.db` 的数据目录 |
| `PASSITON_JWT_SECRET` | 暴露/服务器模式的稳定JWT秘密 |
| `PASSITON_ENCRYPTION_KEY` | 加密提供者密钥的密钥材料 |
| `PASSITON_LOCAL_ACCESS` | 本地自动登录；默认 `true` |
| `PASSITON_ALLOW_REGISTRATION` | 用户注册；默认 `false` |
| `PASSITON_ALLOWED_ORIGINS` | 除了localhost之外的逗号分隔的CORS源 |
| `PASSITON_LOCAL_CLI_AGENTS` | 自动发现本地CLI代理；默认 `true` |
| `PASSITON_ALLOWED_WORKSPACES` | CLI代理可以使用的路径分隔根目录 |
| `PASSITON_CODEX_COMMAND` / `PASSITON_CLAUDE_COMMAND` / `PASSITON_GEMINI_COMMAND` / `PASSITON_OPENCODE_COMMAND` | 覆盖CLI二进制路径 |
| `PASSITON_DREAMINA_COMMAND` / `PASSITON_GEMINI_SKILL_SCRIPT` | 启用捆绑的实验提供者 |
旧的 `TURING_*` 变量被接受为匹配的 `PASSITON_*` 名称的后备。
## 安全模型
帕西顿设计用于单个受信任用户本地使用。默认：
- 服务器绑定到 `127.0.0.1`
- 启用本地自动登录
- 禁用注册
- JWT和加密秘密在首次运行时生成
- CLI代理作为本地进程运行，可以在允许的工作区内操作
如果您通过LAN、隧道或公共主机将帕西顿暴露在localhost之外，则启动需要：
1. `PASSITON_LOCAL_ACCESS=false`
2. `PASSITON_JWT_SECRET` 或 `auth.jwtSecret`
3. 非空 `policy.allowedWorkspaces`
仅在受信任的代理和狭窄范围内使用 `trusted` 权限模式 `cwd` 值。参见 [SECURITY.md](./SECURITY.md)。
## HTTP API
服务器为代理、任务、会话、工作流、提供者密钥、身份验证令牌、文件预览、日志和统计数据公开JSON端点。从机器可读的引用开始：
```text
GET /api/docs
```
大多数 `/api/*` 端点需要 `Authorization: Bearer <token>`。本地模式可以通过 `POST /api/auth/local` 获取令牌。
## MCP集成
帕西顿在 `POST /mcp` 和 `POST /api/mcp` 处提供可流式传输的HTTP MCP网关。使用Bearer令牌或令牌查询参数。
工具名称使用 `passiton_*` 前缀，包括：
- `passiton_list_agents`
- `passiton_create_task`
- `passiton_get_task_result`
- `passiton_create_session`
- `passiton_send_feedback`
- `passiton_get_progress`
- `passiton_create_workflow`
- `passiton_get_workflow`
- `passiton_approve_step`
- `passiton_retry_step`
- `passiton_stop_run`
- `passiton_read_artifact`
从远程MCP客户端连接时，请使用HTTPS和上述暴露要求。
## 外部任务提供者
核心路由器与供应商无关。提交远程作业并轮询直到完成的集成实现了 `ExternalTaskProvider`，并在 `router.registerExternalTaskProvider(provider)` 处注册。
提供者可以：
- 解析代理输出以获取外部作业ID
- 通过 `handledNodeTypes` 拥有工作流步骤
- 轮询完成情况并附加输出路径
- 在服务器重启后恢复轮询
捆绑示例：
- `src/examples/dreamina/` 中的Dreamina视频提供者，由 `PASSITON_DREAMINA_COMMAND` 启用
- Gemini Image适配器，由 `PASSITON_GEMINI_SKILL_SCRIPT` 和 `GEMINI_WEB_COOKIE_PATH` 启用
## 数据保留
持久状态默认存储在 `~/.passiton/turing.db` 中。现有的 `~/.turing/` 数据在存在时会被重用。
消息默认保留30天，通过 `policy.messageRetentionMs` 实现。提供者密钥在存储时加密。像保护其他本地凭证存储一样保护数据目录。
## 更多文档
- [HTTP API用法](./docs/EXTERNAL_AGENT_USAGE.md)
- [社区适配器](./docs/community-adapters.md)
- [贡献](./CONTRIBUTING.md)
- [安全](./SECURITY.md)
