autopilot-agent 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +104 -100
  2. package/package.json +4 -4
  3. package/schema/cc-compatible-settings.schema.json +20 -1
package/README.md CHANGED
@@ -1,133 +1,137 @@
1
- <!-- 本文件用于 npm 用户了解 CLI 安装、配置和使用方式。 -->
2
- # Autopilot Agent CLI
3
-
4
- 本地工作区中的 AI 编程助手，可以读写文件、执行命令、调用已授权 MCP 工具并保存会话。敏感操作受工作区 Trust、权限与审批控制。
1
+ <p align="center">
2
+ <img src="https://raw.githubusercontent.com/C-Clay-W/autopilot/main/.github/Autopilot-logo.png" alt="Autopilot TUI logo" width="440">
3
+ </p>
4
+
5
+ <p align="center">
6
+ <strong>Autopilot Agent</strong><br>
7
+ 本地 AI 编程助手：阅读与修改项目、执行开发命令、跟踪后台任务、管理会话。<br>
8
+ CLI 和本地 Web 共享 TypeScript Agent Runtime。
9
+ </p>
10
+
11
+ <p align="center">
12
+ <a href="https://www.npmjs.com/package/autopilot-agent"><img src="https://img.shields.io/npm/v/autopilot-agent?style=flat-square" alt="npm version"></a>
13
+ <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/Node.js-%3E%3D20.11-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node.js 20.11 or later"></a>
14
+ <a href="https://github.com/C-Clay-W/autopilot/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue?style=flat-square" alt="License: MIT"></a>
15
+ </p>
16
+
17
+ <p align="center">作者：ClayW</p>
18
+
19
+ ## 为什么做 Autopilot
20
+
21
+ **一个 Agent 编排不依赖第三方框架、Provider 中立、按五个包分层的本地 AI 编程助手。** 主循环、上下文预算与压缩、工具调度、会话与审批由项目自行实现；CLI 与本地 Web 共用同一套 Runtime。
22
+
23
+ - **掌握执行链路**：从模型采样、工具调用到结果回填与 checkpoint 恢复，关键状态与控制逻辑都可在源码中追溯。
24
+ - **模型协议与内核分离**：内核使用 Provider 中立消息，由协议 Adapter 处理 OpenAI Chat Completions 与 Anthropic Messages，避免把某一家模型的 wire 格式写进主循环。
25
+ - **同一内核，多种界面**：Core 管执行，Adapters 接宿主，Presentation 投影事件，CLI 与 Web 消费这些能力；无需为不同界面维护两套 Agent 编排。
26
+ - **把依赖用在合适的边界**：保留文件解析、向量存储、数据库驱动、参数校验、终端渲染和系统沙箱等成熟实现，把自研投入放在 Agent 的行为与控制链路上。
27
+
28
+ 这里的“零框架依赖”指 **Agent 编排源码不调用第三方 Agent 框架**，不是零第三方包；当前依赖清单仍有待清理的 LangChain 声明。具体证据与取舍见 [依赖审计：哪些自研，哪些交给成熟库](https://github.com/C-Clay-W/autopilot/blob/main/docs/dependency-audit.md)。
29
+
30
+ ## 架构一览
31
+
32
+ ```mermaid
33
+ flowchart TB
34
+ entry[autopilot-agent 安装入口] --> cli[CLI：Controller / Ink TUI / 文本与 JSONL]
35
+ cli --> presentation[Presentation：安全事件投影与展示协议]
36
+ web[本地 Web：Chat / Work] --> presentation
37
+ cli --> core[Core：Agent Runtime]
38
+ web --> core
39
+ presentation --> core
40
+ core --> kernel[自研：主循环 / 工具调度 / 上下文压缩 / 会话与审批]
41
+ core --> protocol[Provider 中立协议与 Adapter]
42
+ protocol --> models[OpenAI Chat Completions / Anthropic Messages]
43
+ cli --> adapters[Adapters：Node 宿主能力]
44
+ web --> adapters
45
+ adapters -->|注入 RuntimePorts| core
46
+ ```
5
47
 
6
- 本 npm 包分发 CLI，不包含 Web 或 Desktop 应用，也不提供私有知识库 RAG、AutoMemory 或内置浏览器预览。
48
+ 图中箭头表示安装、调用或能力装配关系。五个可发布包是入口包、CLI、Presentation、Core 和 Adapters；Web 是独立源码应用。RAG 是 Core 可供宿主装配的能力，npm CLI 不提供私有知识库 RAG。
7
49
 
8
- ## 安装
50
+ ## 安装 CLI
9
51
 
10
- 需要 **Node.js >=20.11.0 且 <22** 和 npm。首次安装需要网络连接；部分依赖包含平台二进制或安装脚本。
52
+ 需要 Node.js `>=20.11.0 <22`，建议 Node 20.20.2 与 npm 10。
11
53
 
12
54
  ```bash
13
- npm install -g autopilot-agent
55
+ npm install -g autopilot-agent@0.2.0
14
56
  ap --help
15
57
  ```
16
58
 
17
- 只需安装这个包，npm 会自动安装匹配版本的 Core、Adapters、Presentation 和 CLI。`ap` 与 `autopilot` 是等价命令。
18
-
19
- ## 配置 settings.json
20
-
21
- CLI 不读取开发仓库的 Web `.env.local`，用户无需复制该文件。用户配置位于 Windows 的 `%USERPROFILE%\.autopilot\settings.json`，macOS 的 `~/.autopilot/settings.json`。目录不存在时自行创建；只创建一个 JSON 对象文件，不写注释、尾随逗号或 `schemaVersion`。显式 schemaVersion 会导致整份来源被忽略。
22
-
23
- ### 默认 Anthropic Messages 连接
59
+ 主包自动带入 Core、Adapters、Presentation 和 CLI。ap 与 autopilot 等价。完整安装、模型配置、使用和排错见 [主包使用手册](https://github.com/C-Clay-W/autopilot/blob/main/packages/autopilot-agent/README.md)。npm CLI 不包含 Web 应用。
24
60
 
25
- 替换以下占位密钥和模型 ID：
61
+ ## 从源码运行
26
62
 
27
- ```json
28
- {
29
- "env": {
30
- "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
31
- "ANTHROPIC_API_KEY": "YOUR_API_KEY"
32
- },
33
- "model": "YOUR_MODEL_ID"
34
- }
35
- ```
36
-
37
- 认证也可以使用 `ANTHROPIC_AUTH_TOKEN`，但它与 `ANTHROPIC_API_KEY` 只能配置一个；同时配置会产生认证冲突。默认连接按 Anthropic Messages 协议发送请求，不能只改 URL 就接入任意 Chat Completions 服务。Base URL 不手工追加 `/v1/messages`，不得包含 URL 用户名/密码、query 或 fragment。
38
-
39
- ### 显式 Chat Completions 连接
40
-
41
- 需要使用经过验证的 OpenAI Chat Completions 兼容服务时，声明协议、模型目录和凭据引用：
42
-
43
- ```json
44
- {
45
- "env": { "USER_SETTINGS_CUSTOM_API_KEY": "YOUR_API_KEY" },
46
- "providerRoutes": {
47
- "custom": {
48
- "id": "custom",
49
- "apiProtocol": "openai-chat-completions",
50
- "baseUrl": "https://api.example.com/v1",
51
- "credentialRef": { "provider": "custom", "key": "USER_SETTINGS_CUSTOM_API_KEY" },
52
- "models": [{ "id": "YOUR_MODEL_ID" }]
53
- }
54
- },
55
- "model": "custom/YOUR_MODEL_ID"
56
- }
63
+ ```bash
64
+ git clone https://github.com/C-Clay-W/autopilot.git
65
+ cd autopilot
66
+ npm ci
67
+ npm run build -w packages/core
68
+ npm run build -w packages/adapters
69
+ npm run build -w packages/presentation
70
+ npm run build -w apps/cli
71
+ node apps/cli/dist/main.js --help
57
72
  ```
58
73
 
59
- 示例域名和模型必须替换。route 的 id 必须等于字典 key，credentialRef.provider 必须等于该 id，key 对应用户文件 env 中的凭据名，models 非空且 id 不重复；Base URL 不追加 `/chat/completions`。不要同时设置 `env.ANTHROPIC_MODEL`，它会优先选择默认主连接。
74
+ 共享包构建后，Web 使用 `npm run dev -w apps/web -- --hostname 127.0.0.1`。用户配置、工作区和日常开发见 [源码使用指南](https://github.com/C-Clay-W/autopilot/blob/main/agent/doc/HowToUse.md)；构建与测试见 [BUILD.md](https://github.com/C-Clay-W/autopilot/blob/main/BUILD.md)。
60
75
 
61
- route 的 apiProtocol 只接受 `anthropic-messages` 或 `openai-chat-completions`。可选 displayName 是非空字符串，models 项可声明 1–10,000,000 的整数 contextWindowTokens。兼容 profile 需与实际服务匹配：Anthropic profile 只含 apiProtocol；Chat Completions profile 恰含 apiProtocol、assistantToolCallContent（empty-string/null）、supportsReasoningContent（布尔）、supportsUsageInStreaming（布尔）。profile 可放在 route 或 models 项上，不声明未经验证的能力。
76
+ ## 项目组成
62
77
 
63
- ### 常用可选参数
64
-
65
- | 字段 | settings.json 中的写法与限制 |
78
+ | 包 / 目录 | 职责 |
66
79
  |---|---|
67
- | `model` | 模型 ID 或已声明的 routeId/modelId；opus/sonnet/haiku alias 必须先通过 User env 的 ANTHROPIC_DEFAULT_OPUS_MODEL/SONNET_MODEL/HAIKU_MODEL 映射 |
68
- | `env.ANTHROPIC_MODEL` | 可接受模型 ID/alias，但优先于顶层 model；推荐省略，避免覆盖后续 config set model |
69
- | `availableModels` | User-only，非空且无重复的字符串数组；限制默认连接的主/子模型选择，不声明能力；route 模型仍使用其 models 清单 |
70
- | `modelOverrides` | User-only，字符串映射对象；只允许单跳替换，禁止自映射、链和循环；结果仍需属于合法模型目录 |
71
- | `effortLevel` | 顶层字符串 low/medium/high；最终效果受模型与协议能力限制 |
72
- | `env.CLAUDE_CODE_EFFORT_LEVEL` | 字符串 low/medium/high/max/auto/unset，优先于顶层；auto/unset 清除显式 effort，不等于关闭思考 |
73
- | `alwaysThinkingEnabled` | JSON 布尔值，不写成字符串；实际请求仍取决于模型能力 |
74
- | `maxOutputTokens` | User-only，JSON 整数 1–1,000,000；输出预算，不是上下文大小 |
75
- | `env.API_TIMEOUT_MS` | User-only，默认主连接超时的整数字符串，1,000–600,000 毫秒，例如 `"60000"` |
76
- | `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW` | User-only，十进制整数字符串 1–10,000,000，声明 compact 窗口 |
77
- | `visionModel` | User-only，false 关闭，或已声明 Chat Completions route 的 routeId/modelId；省略时继承主模型 |
78
- | `webSearch` | User-only，false 关闭；完整对象需 provider/baseUrl/model/credentialRef 四字段，provider 为 deepseek/openai-compatible/xiaomi-mimo 且引用 provider 一致 |
79
- | `sandbox` | mode 为 read-only/workspace-write；allowedDomains、deniedRead、deniedWrite 为无重复字符串数组，不能含裸星号；mode/allowedDomains 仅 User，deny 可由各层收窄 |
80
+ | [autopilot-agent](https://github.com/C-Clay-W/autopilot/blob/main/packages/autopilot-agent/README.md) | 用户安装入口，关联安装其余四包 |
81
+ | [@autopilot-agent/cli](https://github.com/C-Clay-W/autopilot/blob/main/apps/cli/README.md) | 命令解析、Controller、Ink TUI 与文本/JSONL 输出 |
82
+ | [@autopilot-agent/core](https://github.com/C-Clay-W/autopilot/blob/main/packages/core/README.md) | Runtime、审批、会话、工具、RAG 与宿主接口 |
83
+ | [@autopilot-agent/adapters](https://github.com/C-Clay-W/autopilot/blob/main/packages/adapters/README.md) | Node 存储、工作区、配置、沙箱及外部能力 |
84
+ | [@autopilot-agent/presentation](https://github.com/C-Clay-W/autopilot/blob/main/packages/presentation/README.md) | 共享安全事件投影、时间线、分组和展示文案 |
85
+ | [apps/web](https://github.com/C-Clay-W/autopilot/blob/main/apps/web/README.md) | Next.js 本地 Chat / Work 界面，源码运行，不作为 npm 应用分发 |
80
86
 
81
- env 的值必须是字符串；模型和默认连接凭据不含首尾空白或控制字符，其他凭据也应避免空白。未知 env 项不会自动成为进程环境变量，显式 route 的凭据通过引用从原始用户文件读取。不要在 settings 中声明 danger-full-access。
87
+ 本次 npm 发布版本为 **0.2.0**，包含匹配版本的五个 CLI 包；Web 仍仅通过源码运行。详见 [更新日志](https://github.com/C-Clay-W/autopilot/blob/main/CHANGELOG.md)。
82
88
 
83
- 工作区可另有 `.autopilot/settings.json` 和 `.autopilot/settings.local.json`，仅 Trust 后读取；通常按 User → Project → Local 覆盖允许字段。模型连接、凭据、providerRoutes、availableModels、modelOverrides 等来自 User，项目不能自行引入未授权模型或凭据。不要把密钥放进项目文件或版本控制。
89
+ Web Work 新增内置预览面板及 `open_preview`：模型只准备导航，不读取或验证网页；Chat/CLI 不提供此工具。预览与后台 Job 绑定由宿主核验，仍需完整浏览器与 Provider 实机验收。
84
90
 
85
- `ap config set` 只允许 model、effortLevel、availableModels 三个 key，并需显式 `--scope`；文件中的 availableModels 是数组，命令参数则是逗号列表。config set 成功不代表所有 resolver 诊断都通过，Project/Local 的 availableModels 不生效。凭据和 endpoint 用手工编辑用户文件配置，config show 不回显它们。
91
+ ## 文档
86
92
 
87
- 当前 writer 会拒绝含 providerRoutes.credentialRef 或 maxOutputTokens 等字段的文件上的普通 config set；这类完整配置请直接编辑用户文件。config get/show 读取所选 scope 的脱敏文件值，不是多层合并后的最终有效配置。
93
+ - 更新日志见 [CHANGELOG.md](https://github.com/C-Clay-W/autopilot/blob/main/CHANGELOG.md)。
94
+ - [依赖审计与自研边界](https://github.com/C-Clay-W/autopilot/blob/main/docs/dependency-audit.md)
95
+ - [CLI 命令参考](https://github.com/C-Clay-W/autopilot/blob/main/agent/doc/CLI-Reference.md)
96
+ - [Core API 参考](https://github.com/C-Clay-W/autopilot/blob/main/agent/doc/Core-API.md)
97
+ - [源码启动与使用](https://github.com/C-Clay-W/autopilot/blob/main/agent/doc/HowToUse.md)
88
98
 
89
- ```bash
90
- ap config set model YOUR_MODEL_ID --scope user
91
- ap config set effortLevel high --scope user
92
- ap config set availableModels MODEL_A,MODEL_B --scope user
93
- ```
99
+ 必要测试、配置及合成 fixture 随源码提供。真实 env、凭据、会话/数据库和内部运行记录不公开。
94
100
 
95
- 不要同时使用 env.ANTHROPIC_MODEL 和 config set model；声明 availableModels 后，当前默认主模型也必须在列表中。CLI 不因用户 settings 含有 RAG 配置而获得私有知识库工具。
101
+ ## 界面截图
96
102
 
97
- ## 开始使用
103
+ <p align="center">
104
+ <img src="https://raw.githubusercontent.com/C-Clay-W/autopilot/main/.github/Autopilot-web2.png" alt="Autopilot Web 对话与任务界面" width="960"><br>
105
+ <em>Autopilot Web 对话与任务操作</em>
106
+ </p>
98
107
 
99
- 进入要处理的项目目录后运行：
108
+ <p align="center">
109
+ <img src="https://raw.githubusercontent.com/C-Clay-W/autopilot/main/.github/Autopilot-web.png" alt="Autopilot Web 工作界面" width="960"><br>
110
+ <em>Autopilot Web 工作区</em>
111
+ </p>
100
112
 
101
- ```bash
102
- ap
103
- ```
113
+ <p align="center">
114
+ <img src="https://raw.githubusercontent.com/C-Clay-W/autopilot/main/.github/Autopilot-orca.png" alt="Autopilot CLI TUI 界面" width="960"><br>
115
+ <em>Autopilot CLI TUI</em>
116
+ </p>
104
117
 
105
- 首次使用按提示确认工作区 Trust，再运行 `ap doctor` 核对 settings、model 和 credential；未 Trust 时这些检查会 SKIP。`ap doctor` 默认离线，只有显式 `ap doctor --connectivity` 才探测 Provider。`ap` 进入交互模式；也可以提交单次任务：
118
+ ## 已知限制与平台边界
106
119
 
107
- ```bash
108
- ap chat "分析当前项目结构，不修改文件"
109
- ```
120
+ Autopilot 仍有已知限制，实际能力受操作系统、运行环境和工具链影响：
110
121
 
111
- 常用管理命令：
122
+ - Windows 不启用 OS 进程沙箱：`run_command`、后台 Job 等进程工具逐次审批后以当前用户权限直接执行，审批只代表你接受该执行方式，不代表已隔离。macOS 继续使用 Seatbelt 沙箱，沙箱不可用时受隔离保护的命令照旧拒绝执行。
123
+ - 后台 Job 的停止依赖平台进程树与运行时支持。遇到进程脱离跟踪、平台接口不支持或环境权限不足时，停止结果可能失败，进程树也未必能被精确、完整地终止；不要仅凭根进程退出判断整棵进程树已停止。
124
+ - Windows 宿主执行与后台 Job 的进程树生命周期仍有未闭合的真实环境验收；macOS 沙箱实机验证目前暂缓。因此，自动化测试或单一环境的成功不能代表所有系统均已验证。
125
+ - Windows 下 `npm`/`npx`/`pnpm` 经受信 `node.exe` + CLI 脚本解析启动，不执行 `.cmd` shim，也不经 shell 拼接；受信 CLI 缺失时命令拒绝执行。
112
126
 
113
- ```bash
114
- ap session list
115
- ap trust status
116
- ap sandbox status
117
- ```
127
+ 当前版本不提供 `/plan` 和 `/goal` 模式。`/plan` 属于较早期 Agent 工作流设计：先规划、再执行，用来降低当时模型能力有限时的执行风险。现阶段可直接使用默认 Edit/Agent 模式，并明确要求“只分析和规划，不修改任何文件”，获得同等的规划效果。`/goal` 模式当前也未实现。
118
128
 
119
- 查看各命令的具体参数与限制：`ap --help`。更新和卸载：
129
+ ## 安全与贡献
120
130
 
121
- ```bash
122
- npm install -g autopilot-agent@latest
123
- npm uninstall -g autopilot-agent
124
- ```
131
+ Trust、工具审批和 OS 沙箱各有职责，full_access 仍受路径、Schema 和破坏性命令门禁约束。保留重要项目备份，审查模型改动，不把本地 Web 直接暴露到公网。
125
132
 
126
- 卸载 npm 包不表示删除用户配置、凭据或会话数据。
133
+ 欢迎 Issue 和 PR，描述复现、环境及相关验证，避免提交密钥和原始会话。公开分支由开发主线筛选同步，贡献经审查纳入开发主线后再同步。当前为早期版本，平台和沙箱限制见主包手册。
127
134
 
128
- ## 当前限制
135
+ ## 许可证
129
136
 
130
- - Windows 和 macOS 的沙箱需要相应平台条件；安装成功不表示已完成沙箱初始化或隔离验收。通过 `ap doctor` 和 `ap sandbox status` 检查实际状态。
131
- - Windows 后台 Job 全进程树停止、显式 sandbox MCP 的 stdin 转发目前存在已知问题；默认 host MCP 未提供 OS 隔离。不要依赖这些路径处理不可信任务或需要可靠回收的长任务。
132
- - macOS 全链路验收尚未完成，Linux 未纳入本次支持验收。Provider 可用性、限额和调用费用由所配置的服务决定。
133
- - 当前为早期版本，重要工作区请保留版本控制或备份；不承诺任意平台、协议端点和外部工具的兼容性。
137
+ 项目代码使用 [MIT](https://github.com/C-Clay-W/autopilot/blob/main/LICENSE)，第三方材料保留独立授权，见 [THIRD_PARTY_NOTICES.md](https://github.com/C-Clay-W/autopilot/blob/main/THIRD_PARTY_NOTICES.md)。
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "autopilot-agent",
3
- "version": "0.1.0",
3
+ "version": "0.2.0",
4
4
  "description": "Autopilot Agent CLI：本地工作区中的 AI 编程助手。",
5
5
  "type": "module",
6
6
  "bin": {
@@ -34,8 +34,8 @@
34
34
  "prepack": "node ../../scripts/check-npm-pack.mjs packages/autopilot-agent"
35
35
  },
36
36
  "dependencies": {
37
- "@autopilot-agent/adapters": "0.1.0",
38
- "@autopilot-agent/cli": "0.1.0",
39
- "@autopilot-agent/core": "0.1.0"
37
+ "@autopilot-agent/adapters": "0.2.0",
38
+ "@autopilot-agent/cli": "0.2.0",
39
+ "@autopilot-agent/core": "0.2.0"
40
40
  }
41
41
  }
package/schema/cc-compatible-settings.schema.json CHANGED
@@ -34,7 +34,26 @@
34
34
  "additionalProperties": { "type": "string", "minLength": 1 }
35
35
  },
36
36
  "alwaysThinkingEnabled": { "type": "boolean" },
37
- "effortLevel": { "enum": ["low", "medium", "high"] }
37
+ "maxTurns": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
38
+ "effortLevel": { "enum": ["low", "medium", "high"] },
39
+ "permissions": {
40
+ "type": "object",
41
+ "additionalProperties": false,
42
+ "properties": {
43
+ "allow": {
44
+ "type": "array",
45
+ "items": { "type": "string", "pattern": "^(Read|Write|Edit)\\((?:[A-Za-z]:[\\\\/]|/).+\\)$" }
46
+ },
47
+ "deny": {
48
+ "type": "array",
49
+ "items": { "type": "string", "pattern": "^(Read|Write|Edit)\\((?:[A-Za-z]:[\\\\/]|/).+\\)$" }
50
+ },
51
+ "ask": {
52
+ "type": "array",
53
+ "items": { "type": "string", "pattern": "^(Read|Write|Edit)\\((?:[A-Za-z]:[\\\\/]|/).+\\)$" }
54
+ }
55
+ }
56
+ }
38
57
  },
39
58
  "additionalProperties": true
40
59
  }