AtomCode v5.0.9 新子系统深度分析 — 交互工具族：结构化输入、输出工件与凭证门禁

基于 strings 工具契约 + 系统提示注入 + i18n 证据 + 模块枚举的还原分析 2026-09-09 前置报告：05-version-diff-v4.25.5-to-v5.0.9.md 姊妹报告：40_Execution_Policy_Intervention.md（共享 policyRecovery UI）、39_AtomGit_Tools_Security_Gates.md（Bash 门禁族）、42_Review_Scope（scope 确认回环）

---

1. 全新工具模块（tools/ 目录扩展）

crates/atomcode-capabilities/src/tools/
  ├── request_user_input.rs      ← 结构化用户提问（single/multiple/text）
  ├── output_artifact.rs         ← 大输出工件落盘 + fetch_output 读取
  ├── credential_bash_gate.rs    ← 凭据感知 Shell 门禁（credential-shell）
  ├── bash_workspace_gate.rs     ← 工作区边界 Shell 门禁
  ├── memory.rs                  ← /remember //forget //memory 工具面
  ├── repair.rs                  ← 会话修复工具（见 44 号）
  ├── task.rs                    ← 后台任务工具
  ├── atomgit_bash_gate.rs       ← AtomGit 凭据门禁（39 号已覆盖）
  └── mod.rs

→ 旧版 16 个工具模块（bash/grep/read/edit/write/…）→ 新增 9 个交互/安全/持久化工具。 这是 v5.0.9 tool 面的三大增长点：问用户、存大输出、挡凭据。

---

2. request_user_input — 结构化用户提问

2.1 工具自描述（逐字还原）

Ask the user structured question(s) and wait for their answer before continuing.
Use ONLY for decisions that are genuinely the user's to make

→ 明确阻塞语义：提问后必等答复再继续；且只用于真正属于用户决定的决策。

2.2 三种模式

Prefer `single` or `multiple` with concrete `options` when you can enumerate
  the choices; use `text` for an open answer.
call `request_user_input` to ask instead of guessing.

→ single（单选）/ multiple（多选，带 concrete options）/ text（开放作答）三模式； 优先级设计：能枚举→选择题；不能→问而非猜。

2.3 用量纪律（防骚扰）

Ask ONLY for what you genuinely cannot decide, look up, or verify yourself
do NOT make several `request_user_input` calls in the same turn
point, put them ALL into ONE `request_user_input` call's `questions` array
and never write a multiple-choice question as prose;
  the user answers them together in one form.
Never ask the user to type a secret (password, API key, token) into the prompt

→ 四重约束：Ask ONLY 可自行查证的不问；同回合单次调用；多问题合并进 questions 数组；选择题禁写散文（合并成一个表单）；禁把 secret 打进提问框。

2.4 校验与错误

invalid request_user_input arguments:
request_user_input: `questions` must be a non-empty array
single/multiple mode requires a non-empty `options` array
request_user_input: serialize failed:
acp: request_user_input: bad payload (          ← ACP 回放侧
No answer (declined) / No answer was provided.
struct UserInputOption  ·  with 2 elements

→ 入参强校验（questions/options 非空）；ACP 回放有独立 bad-payload 错误；免答返回 No answer (declined)；UserInputOption 结构体 2 字段。

---

3. output_artifact / fetch_output — 大输出工件

3.1 截断 → 工件落盘提示

... bytes. Full output saved as artifact            ← 保存成功
... bytes. Full output unavailable (exceeds -byte artifact ceiling).]  ← 超上限
... bytes. Full output unavailable (could not be saved).] ← 保存失败
atomcode: output truncated      [Truncated at ...]
To read more: fetch_output(artifact_id="<id>")

→ 三段式输出治理：小输出→内联；大输出→截断 + 落盘为 artifact； 超上限/保存失败→明确 unavailable 理由。[Truncated at ...] 标记截断点。

3.2 fetch_output 工具

explorer.exe / wsl / view(headless)   ← 打开方式（跨平台）
fetch_output(artifact_id="..."
fetch_output args:  /  invalid fetch_output args:  /  fetch_output failed:

→ 以 artifact_id 拉回完整大输出；headless 下 view 查看、桌面平台调原生 explorer.exe/wsl。WebUI 侧同族：turn-artifact-chip / chat.artifacts:"Files"。

3.3 与 WebUI 展示联动

turn-artifacts-list  ·  turn-artifact-chip  ·  turn-artifact-more
chat.artifacts: `Files`

→ 每回合 UI 渲染 artifact 芯片列表（前 6 个 + more）；与老版纯文本截断不同， v5.0.9 让大输出以"文件"形式回到对话。

---

4. Bash 门禁族（3 个新 gate）

4.1 凭据感知门禁（credential_bash_gate.rs）

Tool call blocked by security policy: credentials cannot be passed through generic
  shell arguments, temporary files, or environment variables
credential-shell::
credential_shell_blocked                      ← WebUI 事件码
<credential observation failed; preserving current provider:

→ 凭据不可经通用 shell 参数/临时文件/环境变量透传——这是硬性安全策略； 阻断时给 WebUI 下发 credential_shell_blocked 事件；观察失败时保持现 provider 不变。

4.2 与 policyRecovery 恢复流联动

policyRecovery.question: `Credential protection blocked an unsafe shell operation.
  Choose a safe next step:`
I completed it externally  /  Skip this step  /  End task
View safe instructions  /  Show fixed local guidance with placeholder
policyRecovery.endedLocally: `Security recovery ended without calling the model.`

→ 阻断后弹出恢复决策：本地完成（不回叫模型）/ 跳过 / 结束任务 / 查看安全指引；endedLocally 明确"安全恢复未调用模型"。

4.3 工作区门禁（bash_workspace_gate.rs）

• 与 atomgit_bash_gate.rs（凭据注入门禁）同族
• 约束 Shell 在工作区内执行，阻断越界写/逃逸命令
• 三个 gate 共用 Tools allowed to pass through 判定逻辑

---

5. memory 工具面（tools/memory.rs + /remember //forget //memory）

Show saved memories   → Saved memories: / No saved memories
Remembered ({scope})                                    ← scope = local|project|global
/remember --global for global memory
/forget <keyword>    →  for get.done: `Removed {n} memory entries`
memory: action=forget requires a non-empty `keyword`.
memory: action=remember/list/forget                       ← 工具 action 枚举
concise line. remember a fact, forget entries by keyword, or list current memory

→ 三层作用域（local/project/global：project = this repo only; global = all projects）； 工具 action 枚举 remember/list/forget；斜杠命令三件套与其一一对应。

---

6. 与既有系统的关系

系统	关系
DEEP_ANALYSIS_40 policyRecovery	共享恢复 UI：credential 阻断走同一 policyRecovery action 面
DEEP_ANALYSIS_39 AtomGit gates	同族第三/四个 Bash 门禁（credential/workspace）
DEEP_ANALYSIS_42 confirm_scope	request_user_input 复用为 scope 确认回环工具（Ask the user to confirm this exact scope）
DEEP_ANALYSIS_44 session	fetch_output artifact_id 与转录/快照持久化联动
DEEP_ANALYSIS_41 todo	memory 工具与 todo/next_prompt 同属提示词注入面
ACP v2（32）	acp: request_user_input: bad payload 证明工具跨 ACP 回放

---

7. 逆向方法论备注

1. Ask the user structured question(s)... ONLY for decisions that are genuinely the user's to make 一字不漏还原提问工具语义边界
2. do NOT make several ... ALL into ONE ... questions array 暴露回合内单次合并协议
3. credentials cannot be passed through generic shell arguments, temporary files, or environment variables 是凭据门禁的逐字安全策略
4. [Truncated at ...] + fetch_output(artifact_id=...) 还原大输出截断→工件拉回管线
5. policyRecovery.question/endedLocally i18n 串证明凭据阻断走既存恢复 UI
6. UserInputOption 2 字段 / memory: action=... 枚举暴露工具 JSON schema
7. explorer.exe / wsl / view(headless) 给出 artifact 的跨平台打开方式

---

本报告由持续分析循环生成 — v5.0.9 交互工具族：结构化输入、输出工件与凭证门禁深度分析