BaseBuilder CLI

BaseBuilder CLI 是 BaseBuilder 注册用户的本地命令行客户端。用户态 AI 请求必须通过 weave-ai-api，CLI 只负责登录、协议编排、本地 run metadata、manual 和 per-Base Skill 产物。

请求地址约定

• 生产默认请求地址是 https://www.basebuilder.cn，也就是 HTTPS 默认 443 端口。
• basebuilder login 的生产登录、device approval 和 token exchange 都走 https://www.basebuilder.cn。
• http://127.0.0.1:8999 只用于本地开发 smoke，需要通过 --api-base 或 BB_API_BASE 显式覆盖。
• CLI 不能配置或请求 Builder 直连地址；用户态 AI 请求只能进入 www.basebuilder.cn 背后的 weave-ai-api。

Quick Start

安装

推荐用 pipx 从 GitHub main 安装，避免污染系统 Python：

pipx install git+https://github.com/MetaInFLow/basebuilder-cli.git
basebuilder doctor
basebuilder skill install --target codex

没有 pipx 时也可以用用户级 pip 安装：

python3 -m pip install --user git+https://github.com/MetaInFLow/basebuilder-cli.git
basebuilder doctor
basebuilder skill install --target codex

升级到 GitHub main 最新版本：

pipx install --force git+https://github.com/MetaInFLow/basebuilder-cli.git

登录和创建

basebuilder login
basebuilder doctor
basebuilder whoami --format json
basebuilder create --input input.json --format json

basebuilder login 成功后会自动为本机 agent 注册/轮换 agent token，不需要用户再打开一个 agent 注册确认页。只有 doctor 提示 token 缺失、吊销或需要重新注册时，才单独运行 basebuilder agent register。

生产环境不需要配置 API 地址。本地联调才显式覆盖：

basebuilder --api-base http://127.0.0.1:8999 login
export BB_API_BASE=http://127.0.0.1:8999

本地状态默认写入 ~/.basebuilder。生成的 manual 和 Skill 可能包含 Base URL、表结构和业务字段，不要写到共享目录。

Doctor 诊断

遇到“不能用、登录失败、连不上、没次数、任务还在跑、run 断了”等问题，先运行：

basebuilder doctor
basebuilder doctor --format json

doctor 会检查：

• 当前 API 地址是否能连通，生产默认是 https://www.basebuilder.cn。
• 本地是否已经登录，token 是否过期/吊销。
• 当前账号是否还有可识别的构建次数；次数为 0 时会提示去 Web 充值。
• 本地最近 run 是否仍在运行，并提示 basebuilder runs inspect <run_id> --format json。
• 本地是否安装 larkcli / lark-cli，用于复制到自己的 Lark 空间。

doctor 本身不会发起构建，也不会直连 Builder。它只读取本地状态，并通过 weave-ai-api 做健康、登录和 run snapshot 检查。

多输入和 Excel/CSV 模式

结构化输入贴近 GUI 人类首屏模版，不要把这些字段提前拼成一句长 prompt：

basebuilder create --input input.json --format json

input.json 示例：

{
  "mode": "text",
  "我想要构建": "客户成功续费跟进系统",
  "我是": "客户成功团队负责人",
  "主要使用者": "客户成功经理、销售主管",
  "业务背景": "续费前 90 天识别风险并跟进",
  "核心痛点": ["续费风险靠人工记忆", "跟进动作分散在聊天记录"],
  "已有资料": "历史客户清单、续费记录、服务备注",
  "希望输出": ["客户健康度视图", "高风险续费跟进表"],
  "constraints": ["不处理财务收款"],
  "背景知识": "企业客户续费通常需要提前触达使用率下降和关键人变更。"
}

CLI 仍保留 --prompt 作为兼容入口；新 agent 或正式使用应优先生成上述 input.json。

AI 方案初稿确认

CLI 里的“AI 方案初稿”就是 Web 里的三要素页面。分析完成后会一次性输出：

• 管理对象
• 管理流程
• 关键信息
• 背景知识

默认不会直接开始搭建。交互模式可以直接输入 accept；非交互模式返回 confirmationRequired=true 和本地草稿 runId 后，必须先向用户展示三要素，确认后恢复该草稿：

basebuilder create confirm <draft-run-id> --format json

confirm 会复用草稿中的 message_id、task_id 和三要素，不会再次执行 analyze。不要在用户确认后重新运行 create 或 create --auto-accept，否则会破坏同一任务的会话 lineage；CLI 也会用 DRAFT_CONFIRMATION_REQUIRED 阻止相同需求绕过待确认草稿。--auto-accept 只用于用户从一开始就明确授权跳过 review 的可信自动化。需要修改时可以选择 edit，或用 optimize 加一句调整要求；optimize 可以继续附加多个文件作为上下文。

Excel/CSV 结构优先模式：

basebuilder create --mode excel --file renewal.csv --format json
basebuilder create --mode excel --file workbook.xlsx --file renewal.csv --file tickets.csv --format json

--mode excel 会把一个或多个表格文件作为共同的 source of truth 写入结构化 intake envelope。普通文本需求附带文件时，用 --mode text --file spec.md --file notes.md，表示文件只是背景上下文。

三要素页面动态修改时也可以继续丢文件。交互模式里选择 optimize 后，CLI 会询问可选补充文件路径，多个路径用逗号分隔；agent 自动化调用 CreateFlow 时可以传 {"action":"optimize","instruction":"...","files":["a.md","b.csv"]}。

进度、Report 和产物

basebuilder create --prompt "..." --format json
basebuilder create confirm <draft-run-id> --format json
basebuilder runs inspect <run_id> --format json
basebuilder report generate <run_id> --out ./report.json
basebuilder report render <run_id> --report ./report.json --out ./report.md
basebuilder artifacts manual <run_id> --from-report ./report.json --out ./manual.md
basebuilder artifacts skill <run_id> --from-report ./report.json --out ./base-skill

create 通过 JSON 异步协议启动任务，成功后立即返回，不建立生成 SSE。之后只用 runs inspect 读取服务器状态：queued/running/retrying 继续等待，succeeded 表示完成，failed/timed_out/cancelled/interrupted 表示终止，unknown 表示当前无法确认。CLI 本地文件只是 run 句柄缓存；重复创建前必须先刷新服务器状态，无法确认时停止新建，避免重复扣费。

report.json 是 manual 和 per-Base Skill 的机器真相源。它来自 API 返回的 sanitized final artifact，不包含 token、cookie、raw prompt 或内部 Builder 诊断。

复制到自己的 Lark 空间

CLI 不保存 Lark 凭据，只通过本地 larkcli / lark-cli 的 profile 做用户自有空间操作。当前安全纵切不猜测深复制命令；复制完成后，把本地 copy-result.json 合并进 report：

basebuilder lark copy <run_id> --report ./report.json --copy-result ./copy-result.json
basebuilder artifacts skill <run_id> --from-report ./report.json --out ./base-skill
basebuilder skill install --source ./base-skill --target codex

copy-result.json 示例：

{
  "base": {
    "url": "https://your-lark-space/base/copied",
    "appToken": "copied_base_token"
  },
  "tableIdMap": {
    "tbl_original": "tbl_copied"
  },
  "fieldIdMap": {},
  "viewIdMap": {}
}

如果没有 --copy-result，CLI 会检查本地是否存在 larkcli。找不到时返回结构化 LARKCLI_NOT_FOUND；找得到但没有 copy result 时返回 LARK_COPY_RESULT_REQUIRED，让用户先通过本地 larkcli 完成交互式复制并导出 id map。

Agent 注册

basebuilder agent register
basebuilder agent status --format json
basebuilder agent unregister

有有效 token 时，agent register 会直接调用受保护 API 完成本机 agent 注册/轮换，不再弹出浏览器确认。没有 token 时，它才会向 weave-ai-api 发起 intent=agent_register 的 device session，并打印/打开授权、登录、注册和充值 URL。生产 URL 仍然来自 https://www.basebuilder.cn；本地 127.* 只在显式 dev override 下出现。

CLI 会在本地计算隐私安全指纹，只上传 fingerprint_hash 和低敏摘要，不上传 raw MAC、hostname、username、环境变量、cookie 或 secret。

给 Agent 使用的 Skill

仓库内置通用 Skill：skills/basebuilder-cli/SKILL.md。它用于让支持 Skills 的 agent 正确调用 CLI 登录、agent 注册、创建多维表、恢复 run、生成 manual 和 per-Base Skill。

安装到 Codex 本地 Skills：

basebuilder skill install --target codex

安装到通用 agents skills 目录：

basebuilder skill install --target agents

生成某个具体 Base 的专用 Skill：

basebuilder runs inspect <run_id> --format json
basebuilder report generate <run_id> --out ./report.json
basebuilder artifacts manual <run_id> --out ./manual.md
basebuilder artifacts skill <run_id> --from-report ./report.json --out ./base-skill
basebuilder skill install --source ./base-skill --target codex

skills/basebuilder-cli 是“使用 CLI 的 Skill”；basebuilder artifacts skill 生成的是“操作某个具体多维表的 Skill”。后者可能包含 Base URL、表结构和业务字段，只保存到可信目录。