atelier 怎么用：三种形态、四个概念、一条最短路径
内容提要
atelier 是纯仓颉实现的 Agent Harness，提供循环、上下文、工具、权限、会话、协议等机制，不替用户编排流程。核心概念有四个：HarnessSpec 装配零件、AgentConfig 定义 Agent、AgentRuntime 执行、消息进事件流出。最短上手路径为 cjpm build、配置 OPENAI_API_KEY 环境变量、运行 cli.app run。它支持终端、HTTP、ACP/A2A 宿主接入及库嵌入三种形态，共用同一装配束。注意 tools 是白名单，默认装配不读 TOML。
延伸解读
先分清 Harness 与框架：它不替你画流程
文章把 atelier 定位为 Agent Harness，与模型 SDK、编排框架并列比较：SDK 只发请求收响应，框架替你声明流程，而 Harness 只提供循环、上下文、工具、权限、会话、协议等机制，不决定做什么。这决定了它的适用边界——适合给已有产品加 Agent，或直接以 Agent 为核心做新产品；不适合只想调一次 API、做可视化 DAG 编排或多机分布式。判断是否采用时，先看你要的是机制还是流程。
零配置能跑，但两个默认行为容易踩坑
最短路径是 cjpm build、配 OPENAI_API_KEY 环境变量、运行 cli.app run。但文章特别提醒两个反直觉点：一是 tools 字段是白名单，不写就等于不给任何工具，而 HarnessSpec.default() 实际注册了十个内置工具；二是默认装配不读 TOML，只认环境变量里的 OpenAI 兼容端点。想用 DeepSeek、Ollama、多 Agent 或 MCP，必须写 ~/.atelier.toml。先理解这两点，能少走很多弯路。
上下文窗口写在 provider 下，直接影响压缩
配置里一个容易写错的地方是 contextWindow 的位置：它属于 (provider, model) 这一对，而不是 Agent 的属性。文章解释，同名模型走官方端点和走截断过的代理，窗口可能不同，声明在 provider 下才诚实。这并非形式问题——压缩要按「窗口 − 完成预算 − 余量」留预算，窗口填错压缩就会算错。因此配置 provider.model 时应填真实窗口，而不是照抄模型名对应的默认值。
无人值守模式没有提问通道，信任要提前声明
文章列出首次运行常见问题，其中 run 模式值得展开：它不读 stdin，也没有提问通道，需要用户拍板的一律按取消处理。因此 bash、write_file 等工具在目录未信任时会被全部拒绝，这不是 bug 而是设计——无人值守时不该有等人确认的分支。解决办法是提前用 ATELIER_TRUST_DIR 声明信任目录，或在 TUI 里审批一次。理解这一点，才能正确区分交互式与脚本化两种用法。
Q&A
atelier 是什么？它和编排框架、模型 SDK 有什么区别？
atelier 是一个纯仓颉实现的 Agent Harness，即把模型变成 Agent 的脚手架。它不替你决定流程，而是提供循环、上下文、工具、权限、会话、协议等机制。与模型 SDK（只发请求收响应）和编排框架（声明流程、框架执行）不同，harness 提供自主干活所需的全部机制，但不要求你画流程图。
atelier 的四个核心概念是什么？它们之间是什么关系？
四个核心概念是：HarnessSpec（装配束，定义用哪些零件）、AgentConfig（一个 Agent 的定义，如名字、模型、系统提示词、工具）、AgentRuntime（运行时，执行循环，chat() 出事件流）、Message/Event（输入消息，输出事件流）。前两个是声明，后两个是执行，关系为：HarnessSpec + AgentConfig → AgentRuntime.chat(msgs) → EventStream。
如何用最短路径把 atelier 跑起来？
前置需要仓颉工具链（cjc 1.1.x）和 cjpm。步骤：1) git clone 仓库后执行 cjpm build -j 16 构建；2) 配置环境变量 OPENAI_API_KEY（和可选的 OPENAI_BASE_URL）；3) 运行 ./target/release/bin/cli.app run "你好，介绍一下你自己"。产物在 target/release/bin/cli.app。
atelier 的配置文件怎么写？上下文窗口为什么配置在 provider 下？
配置文件为 ~/.atelier.toml，包含 [[provider]]、[[agent]]、[[mcpServer]] 三段。上下文窗口写在 [[provider.model]] 下，因为窗口是 (provider, model) 对的属性，不是 Agent 的属性；同名模型走不同端点窗口可能不同，声明在 provider 下更诚实，且直接影响压缩预算的计算。
atelier 支持哪三种使用形态？分别怎么用？
三种形态：1) 终端产品：cli.app tui（交互式）或 cli.app run（单次）；2) HTTP 服务：cli.app serve 8080，或通过 AtelierHttpHandler 挂进既有服务；3) 被其他宿主拉起：cli.app acp（ACP 协议，供 Zed 等编辑器）或 cli.app a2a（A2A 协议，供其他 Agent 调用）。此外还可作为库嵌入仓颉项目，使用 Harness.open(spec)。
第一次使用 atelier 常遇到哪些问题？如何解决？
常见问题：1) 模型说没有工具——tools 是白名单，需在 [[agent]] 中显式列出；2) 工具被拒——目录未信任，需在 TUI 中审批或使用 /trust <path>，无人值守时设 ATELIER_TRUST_DIR 环境变量；3) 压缩异常——contextWindow 未声明或填错，需在 [[provider.model]] 中声明真实窗口；4) 配了 DEEPSEEK_API_KEY 却用不上——默认装配只认 OPENAI_API_KEY，需改环境变量名或写 TOML。
