aisuite-code 本地编码 CLI 如何安装运行并理解 shell 命令与文件写操作的审批流程【免费下载链接】aisuiteSimple, unified interface to multiple Generative AI providers项目地址: https://gitcode.com/GitHub_Trending/ai/aisuiteaisuite-code是 aisuite 仓库里的一个本地编码 agent CLI一个对话循环、限定在--cwd内的文件工具、带审批的 shell 与文件写工具以及可写入本地 trace 文件并在 viewer 里查看的执行轨迹。这篇文章对应的任务是在本地把aisuite-code安装并跑起来然后在实际使用中弄清楚哪些操作会弹审批、审批选项各是什么效果、shell 命令的默认允许范围是什么。适用前提是你已经在本地拿到了 aisuite 仓库有 Python 3.10 以上环境CLI 包 pyproject.toml 声明python ^3.10并且持有默认模型openai:gpt-4o-mini所需的OPENAI_API_KEY。准备条件安装和运行前需要确认三件事依据是 cli/py/aisuite-code-cli/README.mdpoetryCLI 包用 poetry 管理依赖安装命令是python3 -m poetry install。aisuite 本体CLI 包的依赖声明里aisuite { path ../../.., develop true }即它直接以开发模式依赖仓库根目录的 aisuite 包所以必须在完整的仓库目录结构内安装不能把cli/py/aisuite-code-cli单独拷出来装。OPENAI_API_KEYCLI 包默认依赖 OpenAI provider默认模型是openai:gpt-4o-mini运行前要在 shell 里设置OPENAI_API_KEY或者先 source 仓库里的.env文件如果其中有这个变量。TRY_IT.md 给出的写法是set -a source .env set a安装与首次运行两种等价入口任选其一方式一在 CLI 包目录内用 poetry 运行cd cli/py/aisuite-code-cli python3 -m poetry install python3 -m poetry run aisuite-code --cwd /tmp/aisuite-cli-play --viewer方式二从仓库根目录使用便捷脚本./scripts/aisuite-code --cwd /tmp/aisuite-cli-play --viewerscripts/aisuite-code 就是一个 shim定位到cli/py/aisuite-code-cli目录后执行python3 -m poetry run aisuite-code $所以前提是方式一里的poetry install已经执行过。命令里的--cwd /tmp/aisuite-cli-play是 TRY_IT.md 的示例值表示 agent 的工作目录替换成你实际要让它操作的项目目录即可该目录必须已存在。--viewer可选表示启动 CLI 时同时启动本地 trace viewer。启动后 CLI 会打印一段 Session 头见 app.py 的_print_header包含model、cwd、toolswrites on/off · shell all/limited · reviewer on/off、traces和artifacts。这是判断配置是否生效的第一道检查点如果你传了--read-only这里应显示writes off没传--allow-shell-all时显示shell limited。trace 文件默认在cwd/.aisuite/code.jsonlartifact 根目录默认cwd/.aisuite/artifacts。一次最短的手把手流程TRY_IT.md 给出了一组试跑 prompt 和对应的预期行为可以直接照着执行List files in this directory and tell me what you see.Create app.py with an add(a, b) function and a small main block that prints add(2, 3). Then run it.Show git status and git diff.预期行为TRY_IT.md 原文文件读取和git status/git diff是只读操作不会要求审批文件写操作和 shell 命令在执行前会要求审批shell 审批支持四种结果本次允许、拒绝、本会话始终允许该工具、本会话始终允许该条命令原文/viewer start可以在启动时没开 viewer 时再补开/status显示当前 model、cwd、trace 文件、artifact 根目录和 shell 命令策略。第二条 prompt 会依次触发文件写审批和 shell 审批创建app.py再运行它是观察完整审批流程的最短路径。审批流程什么操作会弹审批审批逻辑实现在 approval.py 的ApprovalController.evaluate中判定顺序是命令原文已在“会话级始终允许命令”集合中 → 直接放行reason:command allowed for session工具名已在“会话级始终允许工具”集合中 → 直接放行reason:tool allowed for session工具的ToolMetadata为None或requires_approval为假 → 直接放行reason:low risk不弹任何提示其余情况打印审批请求等待你输入。落到具体工具上run_shell在注册时元数据就是categoryshell, risk_levelhigh, requires_approvalTrue见 shell.py 的shell函数所以任何 shell 命令都会弹审批文件写类工具write_file、replace_in_file、apply_patch、apply_unified_diff同样需要审批而文件读取、git_status、git_diff这类只读工具不带审批要求静默执行。审批提示的四个组成部分触发审批时终端会输出四段信息_print_approval_requestAction要做的事例如run shell command: npm run build、write file: app.py、edit file: ...Risk风险级别和类别格式risk_level · category例如high · shell、medium · filesystemEffect一句话影响说明例如 shell 固定是Executes a command in the configured workspace.write_file会区分May create or overwrite a file默认还是May create if missing a fileoverwriteFalse时Preview参数预览。长文本不会整段打印而是压缩成N chars · M lines · preview...的形式避免把大 patch 内容整个倒进终端。然后是提示行测试用例test_aisuite_code_cli.py 中test_approval_controller_denies_high_risk_tool_by_default对渲染结果有逐字断言展示的 shell 审批形如Permission required Action run shell command: npm run build Risk high · shell Effect Executes a command in the configured workspace. Preview command: npm run build Allow? [y] once [n] deny [a] always this tool [c] always this command 以上为文档示例测试中构造的渲染输出不是每次都会出现的固定文案具体 Action/Preview 内容随实际命令变化。四个选项的实际效果输入解析在_read_choicey/yes、a/always、c/command都按对应选项处理其他任何输入包括空行都按n拒绝输入效果作用范围y只允许这一次单次调用n拒绝reason 为denied by user无a本会话内该工具的所有调用不再询问当前 CLI 进程reason:tool allowed for sessionc本会话内该条命令原文不再询问当前 CLI 进程仅对run_shell出现此选项reason:command allowed for session注意两个边界[c]选项只在操作是 shell 命令时才会出现在提示行里_exact_command只认run_shella和c的“始终允许”都存在内存集合里只作用于当前进程——重新启动 CLI 后一切归零重新询问。测试test_approval_controller_can_allow_tool_for_session验证了选a之后第二次调用同一工具直接放行且Permission required只打印了一次。shell 命令的允许范围审批之外的第二道关卡通过审批只是第一关shell 工具本身还有一层命令策略在 shell.py 的_validate_command中执行默认允许列表不传--allow-command时CLI 使用 config.py 中的DEFAULT_ALLOWED_COMMANDSnpm、npx、node、python、python3、pytest、git status、git diff、git log、mkdir、ls、pwd。匹配规则是命令与允许项完全相等或以允许项 空格开头所以python3 app.py可以但python3x不行。不在允许列表内会抛PermissionError: Command is not allowed: 命令而不是静默执行。--allow-command可以多次传入追加允许的前缀。注意 config.py 中是args.allowed_commands or list(DEFAULT_ALLOWED_COMMANDS)——只要你显式传了任意--allow-command默认列表就不再参与此时允许范围只有你列出的前缀。--allow-shell-all跳过允许列表检查任何命令仍需逐条审批都能执行。shell 语法限制默认配置下禁止管道、重定向、命令链接|、||、、;、、等、heredoc 和多行命令违反会报Shell redirection, pipes, heredocs, and command chaining are disabled for this tool...提示改用write_file、apply_unified_diff等文件工具。这与 agent 指令中“不要用 shell heredoc 或重定向做文件编辑”是同一约束。执行细节超时默认 30 秒超时返回timed_out: true而不是抛出输出超过 20000 字符会截断。文件写操作的边界默认--cwd内可读可写但所有写操作都要过审批README 原文write operations still require approval。--read-only参数关闭写文件工具启动头里会显示writes off此时 agent 只剩只读文件工具、git 工具和 shell 工具。写文件有四种途径主 agent 的指令agent.py对它们的分工是明确的replace_in_file用于精确的小段替换apply_patch用于多行定向编辑且只接受 Codex 风格封套*** Begin Patch…*** End Patchapply_unified_diff接受标准 unified diffwrite_file用于新建或整文件替换。审批提示里的 Effect/Preview 会区分这几种方便你在按下y之前看清改动方式。主 agent 还默认带一个只读 reviewer 子 agentreview_changes可审查但不能编辑文件和执行命令不需要时可用--no-reviewer关闭它不属于本文的审批主线这里只提一句以免你在工具列表里看到它。用 /status 和 /last 验证审批策略是否按预期生效在 CLI 会话内两个斜杠命令可以直接核对配置与执行结果/status输出包含model、cwd、trace_file、artifact_root、trace_http、write_tools、reviewer以及allowed_commands列出当前生效的完整允许前缀列表——这是核对--read-only、--allow-shell-all、--allow-command是否起作用的直接方式。/last显示上一轮的traceid、status、输入、输出和各 step工具名与参数摘要。每一轮结束还会打印Trace: trace_idtrace 持续追加写入.aisuite/code.jsonl如果用了--viewer或/viewer start终端会给出聚焦到该 trace 的 viewer 链接?embed1trace_id...可以在浏览器里回看审批时的 reason如approved by user、denied by user。会话内其他常用命令/help列出全部斜杠命令/examples列出建议的起手 prompt/clear清空对话状态下一轮起算新 run/exit退出。常见问题CLI 内置了两条错误提示app.py 的_print_error对应安装/首次使用时最容易卡住的两个点报错含No module named openaiCLI 包依赖没装全回到cli/py/aisuite-code-cli目录执行python3 -m poetry install。报错含OPENAI_API_KEY或API key在 shell 里设置OPENAI_API_KEY或按前文方式 source 仓库.env。其他错误CLI 会提示用/status检查当前 model、cwd 和 trace 文件配置是否正确。限制汇总agent 的所有文件工具和 shell 工具都限定在--cwd内shell 命令的实际执行目录就是该目录subprocess.run(..., cwdself.cwd)。会话级“始终允许”a/c选项只在当前 CLI 进程内存中生效进程退出即失效。shell 工具默认禁用管道/重定向/链接语法--allow-shell-all只放开命令白名单不放开这些语法限制。默认模型是openai:gpt-4o-mini可以通过--model覆盖但 provider 支持范围以 aisuite 主库文档为准。完成以上流程后你得到的是一套可复现的操作路径poetry 安装 → 设置OPENAI_API_KEY→ 带--cwd启动 → 用/status核对工具与命令策略 → 用 TRY_IT.md 的 prompt 依次观察只读静默、写入审批、shell 审批四种选项。更细的行为可以直接读 approval.py、shell.py 和 tests/cli/test_aisuite_code_cli.py 中的断言。【免费下载链接】aisuiteSimple, unified interface to multiple Generative AI providers项目地址: https://gitcode.com/GitHub_Trending/ai/aisuite创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 aisuite-code 本地编码 CLI 如何安装运行并理解 shell 命令与文件写操作的审批流程
aisuite-code 本地编码 CLI 如何安装运行并理解 shell 命令与文件写操作的审批流程【免费下载链接】aisuiteSimple, unified interface to multiple Generative AI providers项目地址: https://gitcode.com/GitHub_Trending/ai/aisuiteaisuite-code是 aisuite 仓库里的一个本地编码 agent CLI一个对话循环、限定在--cwd内的文件工具、带审批的 shell 与文件写工具以及可写入本地 trace 文件并在 viewer 里查看的执行轨迹。这篇文章对应的任务是在本地把aisuite-code安装并跑起来然后在实际使用中弄清楚哪些操作会弹审批、审批选项各是什么效果、shell 命令的默认允许范围是什么。适用前提是你已经在本地拿到了 aisuite 仓库有 Python 3.10 以上环境CLI 包 pyproject.toml 声明python ^3.10并且持有默认模型openai:gpt-4o-mini所需的OPENAI_API_KEY。准备条件安装和运行前需要确认三件事依据是 cli/py/aisuite-code-cli/README.mdpoetryCLI 包用 poetry 管理依赖安装命令是python3 -m poetry install。aisuite 本体CLI 包的依赖声明里aisuite { path ../../.., develop true }即它直接以开发模式依赖仓库根目录的 aisuite 包所以必须在完整的仓库目录结构内安装不能把cli/py/aisuite-code-cli单独拷出来装。OPENAI_API_KEYCLI 包默认依赖 OpenAI provider默认模型是openai:gpt-4o-mini运行前要在 shell 里设置OPENAI_API_KEY或者先 source 仓库里的.env文件如果其中有这个变量。TRY_IT.md 给出的写法是set -a source .env set a安装与首次运行两种等价入口任选其一方式一在 CLI 包目录内用 poetry 运行cd cli/py/aisuite-code-cli python3 -m poetry install python3 -m poetry run aisuite-code --cwd /tmp/aisuite-cli-play --viewer方式二从仓库根目录使用便捷脚本./scripts/aisuite-code --cwd /tmp/aisuite-cli-play --viewerscripts/aisuite-code 就是一个 shim定位到cli/py/aisuite-code-cli目录后执行python3 -m poetry run aisuite-code $所以前提是方式一里的poetry install已经执行过。命令里的--cwd /tmp/aisuite-cli-play是 TRY_IT.md 的示例值表示 agent 的工作目录替换成你实际要让它操作的项目目录即可该目录必须已存在。--viewer可选表示启动 CLI 时同时启动本地 trace viewer。启动后 CLI 会打印一段 Session 头见 app.py 的_print_header包含model、cwd、toolswrites on/off · shell all/limited · reviewer on/off、traces和artifacts。这是判断配置是否生效的第一道检查点如果你传了--read-only这里应显示writes off没传--allow-shell-all时显示shell limited。trace 文件默认在cwd/.aisuite/code.jsonlartifact 根目录默认cwd/.aisuite/artifacts。一次最短的手把手流程TRY_IT.md 给出了一组试跑 prompt 和对应的预期行为可以直接照着执行List files in this directory and tell me what you see.Create app.py with an add(a, b) function and a small main block that prints add(2, 3). Then run it.Show git status and git diff.预期行为TRY_IT.md 原文文件读取和git status/git diff是只读操作不会要求审批文件写操作和 shell 命令在执行前会要求审批shell 审批支持四种结果本次允许、拒绝、本会话始终允许该工具、本会话始终允许该条命令原文/viewer start可以在启动时没开 viewer 时再补开/status显示当前 model、cwd、trace 文件、artifact 根目录和 shell 命令策略。第二条 prompt 会依次触发文件写审批和 shell 审批创建app.py再运行它是观察完整审批流程的最短路径。审批流程什么操作会弹审批审批逻辑实现在 approval.py 的ApprovalController.evaluate中判定顺序是命令原文已在“会话级始终允许命令”集合中 → 直接放行reason:command allowed for session工具名已在“会话级始终允许工具”集合中 → 直接放行reason:tool allowed for session工具的ToolMetadata为None或requires_approval为假 → 直接放行reason:low risk不弹任何提示其余情况打印审批请求等待你输入。落到具体工具上run_shell在注册时元数据就是categoryshell, risk_levelhigh, requires_approvalTrue见 shell.py 的shell函数所以任何 shell 命令都会弹审批文件写类工具write_file、replace_in_file、apply_patch、apply_unified_diff同样需要审批而文件读取、git_status、git_diff这类只读工具不带审批要求静默执行。审批提示的四个组成部分触发审批时终端会输出四段信息_print_approval_requestAction要做的事例如run shell command: npm run build、write file: app.py、edit file: ...Risk风险级别和类别格式risk_level · category例如high · shell、medium · filesystemEffect一句话影响说明例如 shell 固定是Executes a command in the configured workspace.write_file会区分May create or overwrite a file默认还是May create if missing a fileoverwriteFalse时Preview参数预览。长文本不会整段打印而是压缩成N chars · M lines · preview...的形式避免把大 patch 内容整个倒进终端。然后是提示行测试用例test_aisuite_code_cli.py 中test_approval_controller_denies_high_risk_tool_by_default对渲染结果有逐字断言展示的 shell 审批形如Permission required Action run shell command: npm run build Risk high · shell Effect Executes a command in the configured workspace. Preview command: npm run build Allow? [y] once [n] deny [a] always this tool [c] always this command 以上为文档示例测试中构造的渲染输出不是每次都会出现的固定文案具体 Action/Preview 内容随实际命令变化。四个选项的实际效果输入解析在_read_choicey/yes、a/always、c/command都按对应选项处理其他任何输入包括空行都按n拒绝输入效果作用范围y只允许这一次单次调用n拒绝reason 为denied by user无a本会话内该工具的所有调用不再询问当前 CLI 进程reason:tool allowed for sessionc本会话内该条命令原文不再询问当前 CLI 进程仅对run_shell出现此选项reason:command allowed for session注意两个边界[c]选项只在操作是 shell 命令时才会出现在提示行里_exact_command只认run_shella和c的“始终允许”都存在内存集合里只作用于当前进程——重新启动 CLI 后一切归零重新询问。测试test_approval_controller_can_allow_tool_for_session验证了选a之后第二次调用同一工具直接放行且Permission required只打印了一次。shell 命令的允许范围审批之外的第二道关卡通过审批只是第一关shell 工具本身还有一层命令策略在 shell.py 的_validate_command中执行默认允许列表不传--allow-command时CLI 使用 config.py 中的DEFAULT_ALLOWED_COMMANDSnpm、npx、node、python、python3、pytest、git status、git diff、git log、mkdir、ls、pwd。匹配规则是命令与允许项完全相等或以允许项 空格开头所以python3 app.py可以但python3x不行。不在允许列表内会抛PermissionError: Command is not allowed: 命令而不是静默执行。--allow-command可以多次传入追加允许的前缀。注意 config.py 中是args.allowed_commands or list(DEFAULT_ALLOWED_COMMANDS)——只要你显式传了任意--allow-command默认列表就不再参与此时允许范围只有你列出的前缀。--allow-shell-all跳过允许列表检查任何命令仍需逐条审批都能执行。shell 语法限制默认配置下禁止管道、重定向、命令链接|、||、、;、、等、heredoc 和多行命令违反会报Shell redirection, pipes, heredocs, and command chaining are disabled for this tool...提示改用write_file、apply_unified_diff等文件工具。这与 agent 指令中“不要用 shell heredoc 或重定向做文件编辑”是同一约束。执行细节超时默认 30 秒超时返回timed_out: true而不是抛出输出超过 20000 字符会截断。文件写操作的边界默认--cwd内可读可写但所有写操作都要过审批README 原文write operations still require approval。--read-only参数关闭写文件工具启动头里会显示writes off此时 agent 只剩只读文件工具、git 工具和 shell 工具。写文件有四种途径主 agent 的指令agent.py对它们的分工是明确的replace_in_file用于精确的小段替换apply_patch用于多行定向编辑且只接受 Codex 风格封套*** Begin Patch…*** End Patchapply_unified_diff接受标准 unified diffwrite_file用于新建或整文件替换。审批提示里的 Effect/Preview 会区分这几种方便你在按下y之前看清改动方式。主 agent 还默认带一个只读 reviewer 子 agentreview_changes可审查但不能编辑文件和执行命令不需要时可用--no-reviewer关闭它不属于本文的审批主线这里只提一句以免你在工具列表里看到它。用 /status 和 /last 验证审批策略是否按预期生效在 CLI 会话内两个斜杠命令可以直接核对配置与执行结果/status输出包含model、cwd、trace_file、artifact_root、trace_http、write_tools、reviewer以及allowed_commands列出当前生效的完整允许前缀列表——这是核对--read-only、--allow-shell-all、--allow-command是否起作用的直接方式。/last显示上一轮的traceid、status、输入、输出和各 step工具名与参数摘要。每一轮结束还会打印Trace: trace_idtrace 持续追加写入.aisuite/code.jsonl如果用了--viewer或/viewer start终端会给出聚焦到该 trace 的 viewer 链接?embed1trace_id...可以在浏览器里回看审批时的 reason如approved by user、denied by user。会话内其他常用命令/help列出全部斜杠命令/examples列出建议的起手 prompt/clear清空对话状态下一轮起算新 run/exit退出。常见问题CLI 内置了两条错误提示app.py 的_print_error对应安装/首次使用时最容易卡住的两个点报错含No module named openaiCLI 包依赖没装全回到cli/py/aisuite-code-cli目录执行python3 -m poetry install。报错含OPENAI_API_KEY或API key在 shell 里设置OPENAI_API_KEY或按前文方式 source 仓库.env。其他错误CLI 会提示用/status检查当前 model、cwd 和 trace 文件配置是否正确。限制汇总agent 的所有文件工具和 shell 工具都限定在--cwd内shell 命令的实际执行目录就是该目录subprocess.run(..., cwdself.cwd)。会话级“始终允许”a/c选项只在当前 CLI 进程内存中生效进程退出即失效。shell 工具默认禁用管道/重定向/链接语法--allow-shell-all只放开命令白名单不放开这些语法限制。默认模型是openai:gpt-4o-mini可以通过--model覆盖但 provider 支持范围以 aisuite 主库文档为准。完成以上流程后你得到的是一套可复现的操作路径poetry 安装 → 设置OPENAI_API_KEY→ 带--cwd启动 → 用/status核对工具与命令策略 → 用 TRY_IT.md 的 prompt 依次观察只读静默、写入审批、shell 审批四种选项。更细的行为可以直接读 approval.py、shell.py 和 tests/cli/test_aisuite_code_cli.py 中的断言。【免费下载链接】aisuiteSimple, unified interface to multiple Generative AI providers项目地址: https://gitcode.com/GitHub_Trending/ai/aisuite创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考