AI Platform Local Coding Host
查看版本
执行 aip version 查看当前命令所使用的 CLI 和 Runtime 版本，无需登录或联网。该命令不查询后台 Host 进程状态；后台状态使用 aip host status。
提交已有成果
aip outcome 用于已有本地成果和已本地接管的原工单。建单、预览与接收只需用户登录，不要求研发 Host 在线。新建输入包含真实摘要、项目及业务归属，不选择执行目标或知识处理。
aip outcome requirements --workspace ID
aip outcome create --workspace ID --input outcome.json
aip outcome show --workspace ID --work-item ID
aip outcome preview --workspace ID --work-item ID
aip outcome complete --workspace ID --work-item ID --input completion.json
complete 输入仅为 previewId 与可选 idempotencyKey。成功后固定材料已接收，工单回到平台待关闭，仍为 ACTIVE；不自动执行、归档、放弃知识或关单。已有工单直接复用，不重复建单。未知结果保留同一请求标识，先查询真实状态。
后续通过同一套通用节点操作：
aip handoff show --workspace ID --work-item ID
aip handoff next --workspace ID --work-item ID --input next.json
aip handoff execution --workspace ID --work-item ID
aip handoff recovery --workspace ID --work-item ID --input check.json
aip handoff start --workspace ID --work-item ID --input start.json
next 只把工单放到 target：DEVELOPMENT、REVIEW、DEPLOYMENT、QA、ACCEPTANCE、RELEASE_PREPARATION、KNOWLEDGE_ORGANIZATION 或 REQUIREMENT_CLOSURE，并以 show 返回的 pipeline.visit.id 作为 expectedVisitId；不启动任何执行。没有工作区时，除关闭确认外都先放到准备工作区，准备完成后进入所选节点。start 以 visitId 启动当前待启动的访问，同一请求可带 execution、employeeId 和 recovery；启动条件不满足时返回原因，修正后可再次启动。已有会话开发恢复需在开发节点显式 CHECK，再把真实恢复选择放进 start.recovery。知识选择、提案审核、实际上线日期及真正关单均使用节点的原有明确动作。
aip outcome skill 输出随 Runtime 分发的完整指南。以上命令支持 aip --local；CLI 不自动进行 Git、MR、合并或上线。
本地存储回收
Host 按 profile 独立回收自己管理的 Runtime 和工作目录，不清理用户自己的仓库或远端成果。
- Runtime 安装成功并确认新 Host 启动后清理历史版本；
aip update已是最新版时也会清理。正在使用、用于安装回滚或尚未激活的版本暂时保留，清理失败单独记录。 - Daemon 启动 30 秒后开始扫描，之后每 2 小时检查。工单完成或取消且最后更新超过 24 小时后，回收对应开发、部署及独立 QA 工作目录，包括其中未保存的本地文件。
- 执行结束超过 12 小时，仍需保留的工作目录可释放
node_modules、.next、.turbo；下次执行按原流程重新准备依赖。 - 确认由 Host 管理的孤立目录闲置超过 72 小时后回收；网络或服务错误不会被当作工单不存在。共享 Git 缓存须超过 30 天未用于检出、没有 worktree 且无有效项目引用才会回收。
- 正在执行任务或 CLI 使用目录时跳过回收。日志记录删除原因、结果和估算空间；失败留待后续扫描处理。共享 QA 项目检出不随单个工单结束删除，未成功回传的 QA 执行附件继续由原回传流程管理。
本地与云端环境
云端使用 aip（default profile），本地使用 aip --local（local profile）。例如 aip --local login、aip --local host status、aip --local doctor。本地首次登录默认 API 为 http://127.0.0.1:3000；云端首次登录需通过安装脚本或 --platform URL 明确地址。
两套凭证、模型配置、任务、Runtime 和日志分别位于 ~/.aip/profiles/default、~/.aip/profiles/local；后台服务名称独立，可同时运行。已绑定的平台地址不能通过再次登录覆盖；退出登录保留地址绑定。没有全局环境切换。
AIP_HOME 表示安装基础目录；AIP_PROFILE 是后台服务和子进程继承的内部环境标识。下文 $AIP_HOME/workspaces 等旧示例中的 Host 数据根目录现在应使用 $AIP_HOME/profiles/<default 或 local>。共享 CLI 入口位于 $AIP_HOME/bin，不从另一 profile 回退读取配置。既有安装需执行经核实的一次性迁移，不自动读取旧目录。
本地 Coding Host 支持 Windows x64、macOS Apple Silicon/Intel，以及 Linux x64/arm64。安装器下载自带 Node.js 的预构建 Runtime，用户不需要预装 Node.js 或 npm。
用户安装统一从平台「本地开发环境」复制当前系统的一键安装命令。安装器按系统和架构下载对应 Runtime，下载、校验或启动失败即中止，不会继续注册为可用 Host。
npm 仅作为手动安装入口，要求 Node.js >=24。平台 Runtime 在 npm 中使用 optionalDependencies，以跳过其他系统的包；当前系统对应、与 CLI 匹配的 Runtime 是必需的。npm 安装 CLI 成功不代表 Host 已安装成功，必须继续执行 aip host install 与 aip doctor。若 Runtime 被 npm 跳过，按错误中的包名和版本从安装 CLI 的同一 Registry 补装，不混用版本。
从 0.0.32 起，npm 支持 macOS Apple Silicon 和 Windows x64。执行 npm install -g @bf-meishijian/aip 安装当前稳定版，再执行 aip host install 安装 Host。发布新版本时，先发布这两个平台的同版本 Runtime，确认都可下载后再将 CLI 的 latest 指向该版本。
本地 Docker 验收环境的一条命令如下。
Windows PowerShell：
irm "http://127.0.0.1:4174/downloads/aip/install.ps1" | iex
macOS 或 Linux：
curl -fsSL "http://127.0.0.1:4174/downloads/aip/install.sh" | bash
脚本自动选择当前系统与 CPU 架构对应的 Runtime，完成下载、SHA-256 校验、一次解压、后台服务安装、平台登录、设备注册和启动。相同版本重复执行时复用已校验的 Runtime，不再次下载和解压。注册不会自动使用 --yes 替换已有活动机器。
Runtime 构建时将 Host 与 Pi 的 JavaScript 依赖合并为少量文件；只保留工作区命令所需的 npm，以及依赖旁置 WASM 的 Photon 图像模块。五个平台的 Runtime 清单均约 2,000 个文件。构建脚本在本机目标上验证 CLI、npm、Pi 会话和图像 Worker；发布后的隔离安装还需通过 scripts/test-aip-fast-install.ps1 实测。安装耗时会随磁盘、杀毒软件和下载网络变化。
交互式安装会提示输入平台 Web 根地址；直接回车使用脚本中的默认地址。该地址必须能打开平台页面并代理 /api/health/live 与 /api/v1，不能填仅提供 API 的 :3000 端口。非交互安装可预先设置 AIP_PLATFORM_URL。一键安装用选定地址生成验证码页面链接，登录和 Host 注册也连接该地址；下载脚本和 Runtime 的来源不随平台地址变化。手动执行 aip login --platform <API 地址> 时仍使用平台 API 返回的验证码页面链接。
平台页面的“运行诊断”复核安装包校验凭据和启动关键文件，避免每次扫描上万文件；命令行 aip doctor 仍执行 Runtime 清单的逐文件 SHA-256 完整校验。
本地自动验收先构建并发布 Windows Runtime、启动 platform-web，再执行：
powershell.exe -NoProfile -ExecutionPolicy Bypass -File scripts/test-aip-fast-install.ps1
全平台发布使用以下命令生成五种目标的 Runtime 压缩包及 .sha256；本次 0.0.28 只按两平台发布说明单独构建两个目标，不执行全平台命令：
pnpm runtime:release:local-coding-host
发布服务必须把 install.ps1、install.sh 与 releases/ 保持在同一版本。正式公网通过 HTTPS 提供；公司内网阶段允许私网 IPv4 HTTP，并在页面提示明文下载风险。云端发布时将脚本中的平台地址和下载基址渲染为对应环境的固定地址，最终用户只复制无参数的一条命令。
node scripts/render-aip-installers.mjs \
--platform-url "https://platform.example.com" \
--download-base "https://download.example.com/downloads/aip/releases" \
--output ".artifacts/aip-release"
渲染输出不包含凭证；下载地址和平台地址可以不同。将输出脚本与五种 Runtime 发布包部署到固定 HTTPS 或公司私网 IPv4 HTTP 地址后，Windows 使用 irm <install.ps1> | iex，macOS/Linux 使用 curl -fsSL <install.sh> | bash。
S3 安装包发布
项目附件使用的 S3_BUCKET 存放私有图片和 QA 附件，安装包使用单独的桶。为专用桶配置持续在线的 HTTPS 下载域名，使 https://download.example.com/aip/ 映射到桶内 aip/ 对象；脚本和 Runtime 必须可由未登录、没有 S3 凭证的客户端读取。发布环境配置以下变量，不把密钥写进仓库或脚本：
| 变量 | 用途 |
|---|---|
AIP_RELEASE_S3_BUCKET | 安装包专用桶，不能与 S3_BUCKET 相同 |
AIP_RELEASE_PUBLIC_BASE_URL | HTTPS 根地址，或公司私网 IPv4 HTTP 根地址 |
AIP_RELEASE_PLATFORM_URL | 安装时显示的默认平台 Web 地址；HTTPS 或私网 IPv4 HTTP，用户仍可输入其他平台 |
AIP_RELEASE_S3_REGION | S3 区域；未设置时使用 S3_REGION 或 us-east-1 |
AIP_RELEASE_S3_ENDPOINT | 使用 S3 兼容服务时的 API 端点，AWS S3 可省略 |
AIP_RELEASE_KEY_PREFIX | 桶内对象前缀，默认 aip；公开地址路径需匹配 |
AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY | 仅发布环境使用的上传凭证 |
先运行 pnpm runtime:release:local-coding-host，再运行 node scripts/publish-aip-release.mjs 做只读发布计划检查；配置完成后显式添加 --publish 才写入 S3。脚本先校验五平台包及 SHA-256，上传带版本号的 Runtime 与校验文件，检查公开下载可访问，最后更新固定的 install.ps1 和 install.sh。上传中途失败不会让安装脚本指向尚未发布的 Runtime。
GitLab 中 aip-v<版本号> 标签提供手动的 aip-s3-release 作业；配置上述 CI 变量后触发发布。无专用桶或可访问的 HTTPS/私网 IPv4 HTTP 地址时只可本地验证发布计划，不能向用户提供云端安装命令。发布后从没有 S3/GitLab 凭证的另一台电脑核对两个脚本、五平台包和 SHA-256，再公布固定命令。
更新 Host
包含更新命令的版本安装完成后，执行 aip update 更新云端 Host，或 aip --local update 更新本地 profile。0.0.25 起查询当前平台 Runtime 包的 npm latest，仅在正式版本号更高时安装；相等或更低时保持当前版本。使用当前 Runtime 自带的 npm 下载对应系统架构的运行时，校验并调用现有安装器激活。登录、注册和工作区保留；有任务或请求正在执行时提示稍后再试，更新期间暂停领取新任务。已经是最新版本时不重启。
新 Runtime 启动并通过平台心跳验证后，会同步当前版本到平台注册记录和本地状态。同步失败不会伪报成功版本；后续心跳会重新尝试。旧版 0.0.7 尚无 update 命令，需要先用 npm install -g @bf-meishijian/aip@latest 和 aip host install 升级到包含此功能的版本。
Windows 安装与后台运行
install.ps1 使用纯 ASCII 源码，同时兼容 Windows PowerShell 5.1 的 -File 和 irm | iex 两种执行方式。脚本使用系统自带的 tar.exe 解压 Runtime，并通过计划任务 AI Platform Local Coding Host 隐藏启动。
Windows 安装器生成 .aip/bin/host-daemon.ps1，由计划任务 AI Platform Local Coding Host 使用隐藏 PowerShell 启动 Runtime。任务在当前用户登录 Windows 后自动启动，不依赖安装终端保持打开；不是未登录时运行的系统服务。aip host stop/restart 同时检查该 Runtime 的 daemon 是否退出，不停止其他 Node.js 程序。
重复安装先校验并自检候选，再停止 Host，将 runtime/current junction 切换到独立的版本目录。Windows 不再覆盖同名版本目录或删除仍被安装 CLI 占用的 node.exe。候选启动失败时停止候选、恢复旧链接并重新启动；失败原因继续返回给用户。历史 Runtime 目录保留供恢复，不在安装过程中清理；登录凭证、工作区和模型配置不变。
以上修复需要重新构建并分发 Runtime 压缩包，已经发布的 npm 0.0.5 包不会因仓库修改自动更新。打包验收遵循 docs/development/local-acceptance.md，不通过重复安装旧 npm 包验证修复。
macOS 与 Linux 后台运行
macOS 使用当前用户的 LaunchAgent，登录系统后自动启动。Linux 写入 ~/.config/systemd/user/aip-local-coding-host.service，并执行 systemctl --user enable 和 restart。Linux 环境必须可用 systemd user service；缺失时安装保留已下载 Runtime，但明确返回后台服务安装失败。
云平台设备授权地址
手动运行 aip login --platform <平台 API 可访问地址> 的设备确认链接由 Platform API 返回。云端仍应将 PLATFORM_WEB_URL 设置为用户浏览器实际访问的 Web origin（协议、主机、端口），不要使用开发默认的 http://127.0.0.1:4174。一键安装使用用户选择的 Web 地址生成确认链接。测试环境当前入口示例：
PLATFORM_WEB_URL=http://10.254.208.127:4173
部署时核对真实入口，不把示例 IP 写死进安装器。配置生效后重新执行 aip login，确认输出链接的 origin 正确，并完成一次浏览器设备授权。旧验证码不应作为验收凭证复用。
上线准备与 GitLab MR
Host 管理的开发、部署及 QA 仓库使用 SSH 拉取和推送。平台根据已配置 GitLab 返回的真实 SSH 地址下发，支持独立 SSH 主机名及端口；无需设置全局 Git URL 映射。运行 Host 的系统用户须有可用 SSH 密钥和仓库权限，并完成正常的 SSH 主机身份验证。已有 Host 仓库在核对项目后更新 origin 与显式推送地址，保留分支和修改；失败不会退回 HTTPS。平台 API 与云端源码同步仍使用各自的现有认证。
开发阶段产出 release_checklist.md，测试期间随修复维护。人工验收通过后恢复原开发会话，先读取测试交接和最新分支代码，核实清单后提交 MR。配置发布分支时，Runtime 直接以远端发布分支为 MR 来源。留空时，Runtime 推送工单开发分支后准备 MR。平台用自己的读取权限核实、登记和查询状态。
Runtime 的 MR 提交能力复用 GitLab CLI glab。运行 Runtime 的系统用户需要已安装 glab、能从 Runtime 的 PATH 找到它，并已通过 glab auth login 登录对应 GitLab（或使用 glab 官方支持的凭证环境变量）。该身份需具备项目 MR 创建权限，Git 推送仍使用本机 Git 凭证。不读取平台全局 Token，也不把 Token 传入 Agent 参数。缺少 glab、登录失效、权限不足或网络失败时会返回中文处理提示，不降级使用平台写权限。
会话内的 submit_pull_requests 工具自动绑定工单、项目分支和执行身份。独立命令必须明确工单与项目，并匹配此 Runtime 已接收的唯一执行上下文：
aip mr submit --work-item BAOFU-91 --project scf-member --description-file ./mr-description.md
aip mr register --work-item BAOFU-91 --project scf-member --iid 128
submit 可用 --title 指定标题；说明文件应包含任务目的、本项目变更、测试与验收结果、发布注意事项、跨项目依赖、风险回滚及上线清单/测试报告入口。已有打开的同向 MR 时复用。无差异时可登记同向已合并的 MR，找不到则登记无需 MR。register 用于登记已由其他工具创建的同向 MR，不推送分支。
MR 创建成功但平台登记失败时，Runtime 保存待登记结果。重试同一命令会登记原 MR，即使原 MR 后来已合并或关闭，也不会因登记失败重复创建。登记成功后平台保留 MR 历史及当前关联。
用户明确要求修改应用代码时，开发会话调用 request_code_changes 返回开发，再交接原测试会话和人工确认。仅解释、更新清单或 MR 说明不自动退回。整个研发流程仅按项目及源/目标分支推进，不使用 commit ID 或 tree hash 一致性门禁；实际发布、知识整理和关单不属于上线准备。
测试项目本地仓库
目录采集和正式测试共用 $AIP_HOME/workspaces/qa-projects/<projectId>/repository。每个项目首次创建仓库，之后增量 fetch 并检出请求固定的提交；同项目任务串行，不同项目互不占用。通过现有 proper-lockfile 防止 CLI 与 daemon 同时改动同一目录，跨进程占用会如实报错，不重试业务执行。
这是 Host 专用运行目录，不是开发工作区。更新前清理其中的旧产物与修改，防止复用旧 JUnit 结果。同项目同远端同提交最近一次成功采集的 manifest 保存在项目目录，正式运行可复用它并跳过 collect；点击“加载最新 main 目录”仍执行 collect，便于主动刷新。命令事实只记录本次实际执行的阶段，不伪造缓存命中时的 collect。
执行附件先复制到 $AIP_HOME/workspaces/qa-executions/<executionId>/artifacts，独立于可更新的项目仓库。平台确认附件和结果回传成功后删除该执行附件目录；回传失败保留原文件供显式重传，后续项目更新不会覆盖。结果 JSON 与回传标记保留用于阻止重复执行。旧版本遗留的逐次仓库不自动删除，也不为失败证据设置隐式过期删除。
用例与验收标准
仓库 manifest 只描述可复用用例，不声明 ac。工单的 AC 与 caseId 通过本工单测试计划中的 ac、automationCaseIds 建立关联；正式执行绑定计划版本。独立回归没有工单 AC 关联。旧执行原始证据保留，但目录中的旧 AC 不再参与覆盖或验收判断。
移除 AC 契约须与测试仓库、平台 API 和 Host 一起更新。旧格式目录会被新契约拒绝；仍使用旧分支的工单应先将测试资产更新到新契约，再执行，不由平台猜测或补写关联。
命令并发与准备排障（0.0.10）
心跳领取与命令执行分离，最多同时处理 4 条任务命令；同一 Run / QA 会话仍按顺序领取。诊断、模型刷新、供应商登录独立于任务槽位，各类型自身串行。多个 Run 使用同一 Git 镜像时，仅该仓库的准备操作串行，避免并发修改镜像缓存。任务命令完成表示已处理命令，不表示后台 Agent 会话已经结束。
准备请求排队超过 30 秒不再判失败。请求仍受原有 24 小时命令有效期约束；Host 已接收后失联或重启则显示中断，不自动重放。消息发送的 30 秒领取期限不受此修改影响。API 发布过程中执行结果回执失败会记录 command_result_unknown，不能当作命令执行失败，也不会自动重执行。
Windows 计划任务将标准输出和错误追加到 $HOME\.aip\profiles\default\logs\host.log；使用 --local 时目录为 profiles\local，设置 AIP_HOME 时基址随之改变。PowerShell 实时查看：
Get-Content "$HOME\.aip\profiles\default\logs\host.log" -Tail 100 -Wait
按 commandId / runId 定位；command_started、command_input_loaded、workspace_preparation_started、repository_preparation_started/completed、workspace_materials_ready、command_completed 标识执行进度。停在仓库开始阶段通常需要检查本机 Git 网络和凭证；heartbeat_failed / command_result_unknown 表明平台通信或回执失败，结合相同标识查询 API 日志。日志不包含命令正文、凭证和环境变量。
需要重新安装新 Runtime 才能获得并发执行与 Windows 日志；仅部署 API/Web 或重启旧 Host 不会更新本地代码。重新运行平台账户页的安装命令会保留本机身份、凭证与工作目录，无需解绑重新注册。
诊断失败日志
后台状态上报及主动诊断会在上述 host.log 中记录工具失败：host_tool_check_failed 包含 checkId（SHELL、CONTENT_SEARCH、FILE_SEARCH）、来源、Host 标识、耗时和安全错误分类。已知系统异常保留 ENOENT/EACCES/EPERM 等错误码；Pi 已知的 rg/fd 非零退出格式保留数字退出码。其他无法安全分类的错误标记为 EXECUTION_ERROR，不推测原因。探测目录、文件、工具初始化或清理失败记录 host_tool_check_error 和阶段，原异常继续返回。
完整诊断逐项记录 diagnostic_check_failed（含 FAIL 和 ACTION_REQUIRED），并在上传结果之前写入 diagnostics_completed_locally，包含各项 ID、状态及错误码摘要。诊断中途异常记录 diagnostic_execution_failed；检查完成但回传失败记录 diagnostic_result_report_failed，附命令 ID、失败阶段及可用的 HTTP 状态/业务错误码，不自动重跑或把执行成功反写为失败。CLI aip doctor 使用相同结构记录到标准错误。
这些新增日志不包含命令正文、工具原始输出、异常正文、环境变量值、处理指引或本地绝对路径。只有安装包含本次改动的新 Runtime 后，后续执行才会产生这些字段；历史日志无法补回已经丢失的检查明细。新增日志本身不修复诊断接口契约拒收或页面等待问题。
0.0.13 同步修复诊断回执与页面等待：接口接收完整且 ID 不重复的 11 项检查；工具检查失败仍能返回诊断报告，不会伪报就绪。诊断命令超过既有有效期后，查询返回 EXPIRED，页面停止等待并提示在本机执行 aip doctor，不会自动重发命令。API/Web 更新与各电脑 Runtime 升级需要分别完成。