autopilot-agent 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,133 @@
-# Temporary Holding Version
+<!-- 本文件用于 npm 用户了解 CLI 安装、配置和使用方式。 -->
+# Autopilot Agent CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+本地工作区中的 AI 编程助手，可以读写文件、执行命令、调用已授权 MCP 工具并保存会话。敏感操作受工作区 Trust、权限与审批控制。
+
+本 npm 包分发 CLI，不包含 Web 或 Desktop 应用，也不提供私有知识库 RAG、AutoMemory 或内置浏览器预览。
+
+## 安装
+
+需要 **Node.js >=20.11.0 且 <22** 和 npm。首次安装需要网络连接；部分依赖包含平台二进制或安装脚本。
+
+```bash
+npm install -g autopilot-agent
+ap --help
+```
+
+只需安装这个包，npm 会自动安装匹配版本的 Core、Adapters、Presentation 和 CLI。`ap` 与 `autopilot` 是等价命令。
+
+## 配置 settings.json
+
+CLI 不读取开发仓库的 Web `.env.local`，用户无需复制该文件。用户配置位于 Windows 的 `%USERPROFILE%\.autopilot\settings.json`，macOS 的 `~/.autopilot/settings.json`。目录不存在时自行创建；只创建一个 JSON 对象文件，不写注释、尾随逗号或 `schemaVersion`。显式 schemaVersion 会导致整份来源被忽略。
+
+### 默认 Anthropic Messages 连接
+
+替换以下占位密钥和模型 ID：
+
+```json
+{
+  "env": {
+    "ANTHROPIC_BASE_URL": "https://api.anthropic.com",
+    "ANTHROPIC_API_KEY": "YOUR_API_KEY"
+  },
+  "model": "YOUR_MODEL_ID"
+}
+```
+
+认证也可以使用 `ANTHROPIC_AUTH_TOKEN`，但它与 `ANTHROPIC_API_KEY` 只能配置一个；同时配置会产生认证冲突。默认连接按 Anthropic Messages 协议发送请求，不能只改 URL 就接入任意 Chat Completions 服务。Base URL 不手工追加 `/v1/messages`，不得包含 URL 用户名/密码、query 或 fragment。
+
+### 显式 Chat Completions 连接
+
+需要使用经过验证的 OpenAI Chat Completions 兼容服务时，声明协议、模型目录和凭据引用：
+
+```json
+{
+  "env": { "USER_SETTINGS_CUSTOM_API_KEY": "YOUR_API_KEY" },
+  "providerRoutes": {
+    "custom": {
+      "id": "custom",
+      "apiProtocol": "openai-chat-completions",
+      "baseUrl": "https://api.example.com/v1",
+      "credentialRef": { "provider": "custom", "key": "USER_SETTINGS_CUSTOM_API_KEY" },
+      "models": [{ "id": "YOUR_MODEL_ID" }]
+    }
+  },
+  "model": "custom/YOUR_MODEL_ID"
+}
+```
+
+示例域名和模型必须替换。route 的 id 必须等于字典 key，credentialRef.provider 必须等于该 id，key 对应用户文件 env 中的凭据名，models 非空且 id 不重复；Base URL 不追加 `/chat/completions`。不要同时设置 `env.ANTHROPIC_MODEL`，它会优先选择默认主连接。
+
+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 项上，不声明未经验证的能力。
+
+### 常用可选参数
+
+| 字段 | settings.json 中的写法与限制 |
+|---|---|
+| `model` | 模型 ID 或已声明的 routeId/modelId；opus/sonnet/haiku alias 必须先通过 User env 的 ANTHROPIC_DEFAULT_OPUS_MODEL/SONNET_MODEL/HAIKU_MODEL 映射 |
+| `env.ANTHROPIC_MODEL` | 可接受模型 ID/alias，但优先于顶层 model；推荐省略，避免覆盖后续 config set model |
+| `availableModels` | User-only，非空且无重复的字符串数组；限制默认连接的主/子模型选择，不声明能力；route 模型仍使用其 models 清单 |
+| `modelOverrides` | User-only，字符串映射对象；只允许单跳替换，禁止自映射、链和循环；结果仍需属于合法模型目录 |
+| `effortLevel` | 顶层字符串 low/medium/high；最终效果受模型与协议能力限制 |
+| `env.CLAUDE_CODE_EFFORT_LEVEL` | 字符串 low/medium/high/max/auto/unset，优先于顶层；auto/unset 清除显式 effort，不等于关闭思考 |
+| `alwaysThinkingEnabled` | JSON 布尔值，不写成字符串；实际请求仍取决于模型能力 |
+| `maxOutputTokens` | User-only，JSON 整数 1–1,000,000；输出预算，不是上下文大小 |
+| `env.API_TIMEOUT_MS` | User-only，默认主连接超时的整数字符串，1,000–600,000 毫秒，例如 `"60000"` |
+| `env.CLAUDE_CODE_AUTO_COMPACT_WINDOW` | User-only，十进制整数字符串 1–10,000,000，声明 compact 窗口 |
+| `visionModel` | User-only，false 关闭，或已声明 Chat Completions route 的 routeId/modelId；省略时继承主模型 |
+| `webSearch` | User-only，false 关闭；完整对象需 provider/baseUrl/model/credentialRef 四字段，provider 为 deepseek/openai-compatible/xiaomi-mimo 且引用 provider 一致 |
+| `sandbox` | mode 为 read-only/workspace-write；allowedDomains、deniedRead、deniedWrite 为无重复字符串数组，不能含裸星号；mode/allowedDomains 仅 User，deny 可由各层收窄 |
+
+env 的值必须是字符串；模型和默认连接凭据不含首尾空白或控制字符，其他凭据也应避免空白。未知 env 项不会自动成为进程环境变量，显式 route 的凭据通过引用从原始用户文件读取。不要在 settings 中声明 danger-full-access。
+
+工作区可另有 `.autopilot/settings.json` 和 `.autopilot/settings.local.json`，仅 Trust 后读取；通常按 User → Project → Local 覆盖允许字段。模型连接、凭据、providerRoutes、availableModels、modelOverrides 等来自 User，项目不能自行引入未授权模型或凭据。不要把密钥放进项目文件或版本控制。
+
+`ap config set` 只允许 model、effortLevel、availableModels 三个 key，并需显式 `--scope`；文件中的 availableModels 是数组，命令参数则是逗号列表。config set 成功不代表所有 resolver 诊断都通过，Project/Local 的 availableModels 不生效。凭据和 endpoint 用手工编辑用户文件配置，config show 不回显它们。
+
+当前 writer 会拒绝含 providerRoutes.credentialRef 或 maxOutputTokens 等字段的文件上的普通 config set；这类完整配置请直接编辑用户文件。config get/show 读取所选 scope 的脱敏文件值，不是多层合并后的最终有效配置。
+
+```bash
+ap config set model YOUR_MODEL_ID --scope user
+ap config set effortLevel high --scope user
+ap config set availableModels MODEL_A,MODEL_B --scope user
+```
+
+不要同时使用 env.ANTHROPIC_MODEL 和 config set model；声明 availableModels 后，当前默认主模型也必须在列表中。CLI 不因用户 settings 含有 RAG 配置而获得私有知识库工具。
+
+## 开始使用
+
+进入要处理的项目目录后运行：
+
+```bash
+ap
+```
+
+首次使用按提示确认工作区 Trust，再运行 `ap doctor` 核对 settings、model 和 credential；未 Trust 时这些检查会 SKIP。`ap doctor` 默认离线，只有显式 `ap doctor --connectivity` 才探测 Provider。`ap` 进入交互模式；也可以提交单次任务：
+
+```bash
+ap chat "分析当前项目结构，不修改文件"
+```
+
+常用管理命令：
+
+```bash
+ap session list
+ap trust status
+ap sandbox status
+```
+
+查看各命令的具体参数与限制：`ap --help`。更新和卸载：
+
+```bash
+npm install -g autopilot-agent@latest
+npm uninstall -g autopilot-agent
+```
+
+卸载 npm 包不表示删除用户配置、凭据或会话数据。
+
+## 当前限制
+
+- Windows 和 macOS 的沙箱需要相应平台条件；安装成功不表示已完成沙箱初始化或隔离验收。通过 `ap doctor` 和 `ap sandbox status` 检查实际状态。
+- Windows 后台 Job 全进程树停止、显式 sandbox MCP 的 stdin 转发目前存在已知问题；默认 host MCP 未提供 OS 隔离。不要依赖这些路径处理不可信任务或需要可靠回收的长任务。
+- macOS 全链路验收尚未完成，Linux 未纳入本次支持验收。Provider 可用性、限额和调用费用由所配置的服务决定。
+- 当前为早期版本，重要工作区请保留版本控制或备份；不承诺任意平台、协议端点和外部工具的兼容性。

package/bin/autopilot-agent.mjs

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * 无 scope 用户入口；只解析已安装的 CLI 包并转发参数，不复制 Runtime 或状态逻辑。
+ */
+import { spawnSync } from "node:child_process";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+const require = createRequire(import.meta.url);
+
+/** 根据 CLI 公共入口定位同包内的实际 dist/main.js 启动文件。 */
+function resolveCliMainPath() {
+  const cliEntryPath = require.resolve("@autopilot-agent/cli");
+  return join(dirname(cliEntryPath), "main.js");
+}
+
+/** 使用当前 Node 进程同步转发 CLI，保留 stdout/stderr、退出码和信号语义。 */
+function runCli() {
+  const result = spawnSync(process.execPath, [resolveCliMainPath(), ...process.argv.slice(2)], {
+    stdio: "inherit",
+    windowsHide: false,
+  });
+
+  if (result.error) {
+    console.error(result.error.message);
+    process.exit(1);
+  }
+
+  if (result.signal) {
+    process.kill(process.pid, result.signal);
+  }
+
+  process.exit(result.status ?? 1);
+}
+
+runCli();

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "autopilot-agent",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Autopilot Agent CLI：本地工作区中的 AI 编程助手。",
+  "type": "module",
+  "bin": {
+    "ap": "bin/autopilot-agent.mjs",
+    "autopilot": "bin/autopilot-agent.mjs"
+  },
+  "files": [
+    "bin/autopilot-agent.mjs",
+    "schema/cc-compatible-settings.schema.json",
+    "!**/*.map",
+    "!**/*.{test,spec,bench}.*",
+    "!**/*-fixture*.*",
+    "!**/{test,tests,test-*,__tests__,__mocks__,contract-test,fixtures,coverage,playwright-report,test-results}/**",
+    "!**/{agent,agents,.agent-tests,.agents,.codex,.cursor,.idea,.vscode}/**",
+    "!**/{.git,.hg,.svn,.github,.gitlab}/**",
+    "!**/{.local,.autopilot,.cache,.npm-cache,.turbo,.next,.vite,__pycache__,node_modules,src,dist-types}/**",
+    "!**/*.{log,tsbuildinfo,tmp,temp,bak,orig,rej,swp,swo,pyc,pyo,tgz,tar,zip,7z,rar,db,sqlite,sqlite3,wal,shm}",
+    "!**/*.{pem,key,p12,pfx,crt,cer}",
+    "!**/{.env*,.npmrc*,.yarnrc*,.pnp.*,AGENTS.md,CLAUDE.md,.DS_Store,Thumbs.db}",
+    "!**/{settings.json,settings.local.json,mcp.json,credentials.json,credentials.local.json,package-lock.json,npm-shrinkwrap.json,yarn.lock,pnpm-lock.yaml,bun.lockb}",
+    "!**/{tsconfig*,vitest.config.*,vite.config.*,playwright.config.*,eslint.config.*,jest.config.*,turbo.json}"
+  ],
+  "engines": {
+    "node": ">=20.11.0 <22"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "prepack": "node ../../scripts/check-npm-pack.mjs packages/autopilot-agent"
+  },
+  "dependencies": {
+    "@autopilot-agent/adapters": "0.1.0",
+    "@autopilot-agent/cli": "0.1.0",
+    "@autopilot-agent/core": "0.1.0"
+  }
+}

package/schema/cc-compatible-settings.schema.json

@@ -0,0 +1,40 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Autopilot CC-compatible provider settings",
+  "type": "object",
+  "properties": {
+    "$schema": { "type": "string" },
+    "env": {
+      "type": "object",
+      "additionalProperties": { "type": "string" },
+      "properties": {
+        "ANTHROPIC_BASE_URL": { "type": "string" },
+        "ANTHROPIC_AUTH_TOKEN": { "type": "string" },
+        "ANTHROPIC_API_KEY": { "type": "string" },
+        "ANTHROPIC_MODEL": { "type": "string" },
+        "ANTHROPIC_DEFAULT_OPUS_MODEL": { "type": "string" },
+        "ANTHROPIC_DEFAULT_SONNET_MODEL": { "type": "string" },
+        "ANTHROPIC_DEFAULT_HAIKU_MODEL": { "type": "string" },
+        "CLAUDE_CODE_SUBAGENT_MODEL": { "type": "string" },
+        "CLAUDE_CODE_EFFORT_LEVEL": { "enum": ["auto", "unset", "low", "medium", "high", "max"] },
+        "CLAUDE_CODE_AUTO_COMPACT_WINDOW": { "type": "string", "pattern": "^[1-9][0-9]*$" },
+        "API_TIMEOUT_MS": { "type": "string", "pattern": "^[1-9][0-9]*$" },
+        "CLAUDE_CODE_DISABLE_AUTO_UPDATE": { "type": "string" }
+      }
+    },
+    "model": { "type": "string" },
+    "availableModels": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "modelOverrides": {
+      "type": "object",
+      "additionalProperties": { "type": "string", "minLength": 1 }
+    },
+    "alwaysThinkingEnabled": { "type": "boolean" },
+    "effortLevel": { "enum": ["low", "medium", "high"] }
+  },
+  "additionalProperties": true
+}