@kodax-ai/kodax 0.7.78 → 0.7.79

package/README_CN.md

@@ -41,25 +41,26 @@
 ```bash
 npm i -g @kodax-ai/kodax
 
-# 选一个你有 API key 的 provider（`kodax setup --help` 会列出全部）
-export ZHIPU_API_KEY=...        # ANTHROPIC_API_KEY / OPENAI_API_KEY / DEEPSEEK_API_KEY /
-                                # KIMI_API_KEY / KIMI_CODE_API_KEY / QWEN_API_KEY /
-                                # QWEN_TOKEN_API_KEY / ZHIPU_CODING_API_KEY /
-                                # ZAI_CODING_API_KEY / MINIMAX_CODING_API_KEY /
-                                # MIMO_API_KEY / MIMO_CODING_API_KEY / ARK_CODING_API_KEY
+# 选一个你有 API key 的 provider（`kodax setup --help` 会列出全部）
+export ZHIPU_API_KEY=...        # ANTHROPIC_API_KEY / OPENAI_API_KEY / DEEPSEEK_API_KEY /
+                                # KIMI_API_KEY / KIMI_CODE_API_KEY / QWEN_API_KEY /
+                                # QWEN_TOKEN_API_KEY / ZHIPU_CODING_API_KEY /
+                                # ZAI_CODING_API_KEY / MINIMAX_CODING_API_KEY /
+                                # MIMO_API_KEY / MIMO_CODING_API_KEY / ARK_CODING_API_KEY
 
 kodax
 ```
 
-就这样。进 REPL，自然语言提问。新机器只要还没有选择 provider，交互式运行
-`kodax` 就会先进入 setup，即使已经存在受支持的 API Key 环境变量。setup 会检查
-core、MCP、Extensions、A2A 的活跃配置和注释模板，不覆盖已有文件，也不会要求输入
-或保存 Key。选择 provider/model 后，按提示设置对应环境变量、重启终端，再运行
-`kodax`。使用 `kodax setup --custom` 配置自定义 provider；使用
-`kodax setup --help` 或 REPL `/setup --help` 查看完整路径、环境变量、命令和快捷键。
-交互式 setup 还会检查一次可选 ASRT sandbox：Windows 可能弹出一次 UAC；
-macOS/Linux 会报告 Seatbelt/bubblewrap 所需依赖。拒绝 UAC 或缺少依赖不会破坏普通
-权限管理，日常启动也不会反复提醒。
+就这样。进 REPL，自然语言提问。新机器第一次交互式运行 `kodax` 时，会先检查受支持
+的 API Key 环境变量。如果一个都没有，KodaX 只显示 Windows、macOS 和 Linux 的
+添加方法并退出，不创建配置，也不收集或保存 Key。添加后请关闭当前终端，打开新终端，
+再运行 `kodax`。如果已经存在受支持的环境变量但尚未选择 provider，KodaX 才进入
+provider/model 元数据设置。使用 `kodax setup` 重新运行设置，
+使用 `kodax setup --custom` 配置自定义 provider；使用 `kodax setup --help` 或
+REPL `/setup --help` 查看完整路径、环境变量、命令和快捷键。交互式 setup 还会检查
+一次可选 ASRT sandbox：Windows 可能弹出一次 UAC；
+macOS/Linux 会报告 Seatbelt/bubblewrap 所需依赖。拒绝 UAC 或缺少依赖不会破坏普通
+权限管理，日常启动也不会反复提醒。
 
 > **不装 Node 的目标机器**：从 [GitHub Releases](https://github.com/icetomoyo/KodaX/releases) 拿 Bun 编译的单文件二进制（Win / macOS / Linux × x64 + arm64）。详见 [docs/release.md](docs/release.md)。
 
@@ -109,111 +110,128 @@ packaged Electron 回归连续执行 20 次普通查询并检查控制台可见
 澄清”，只为符合资格的 Sidecar `revise` 发布预算审批状态，并在 embedded 与
 daemon Runtime 边界保留结构化 blocked 原因。
 
-**v0.7.76 Kimi Code 模型目录更新**：`kimi-code` 现在默认使用官方
-`k3-256k` Model ID，并直接发送该同名 ID。`kimi-for-coding` 继续作为 K2.7 Code
-可选模型，同时保留 `kimi-for-coding-highspeed` 与 1M `k3` tier。K3 支持
-`low` / `high` / `max` 思考强度，默认 `high`；256K 路由支持图片但不支持视频输入。
-
-**v0.7.77 正式版**：AMA 现在通过现有 Actor 控制面按需组合六种具名问题解决
-模式，不引入固定拓扑或隐藏 Workflow。可选策略元数据会形成有界、仅记录事实的
-`PatternTrace`，现有 Sidecar 仍是唯一的终态答案质量裁决者。治理式记忆可在工具
-失败、验证失败或已提交 compact 之后稀疏触发，在下一次 Action-LLM 请求前注入最多
-三条 prompt-safe、低权威证据；默认路径不增加 selector 模型调用，SDK 宿主可在
-进程内显式注入 `memoryRecallRunner`。公开 `kimi` provider 同时新增 1M
-`kimi-k3` 路由，并继续以 K2.7 Code 为默认。详见
-[v0.7.77 设计](docs/features/v0.7.77.md)与
-[发布检查清单](docs/release.md#v0777-release-ready-candidate-verification)。
-冻结的 F274/F275 付费评测已完成；F274 最终 Layer 2/Layer 3 与 F275 pilot 盲审均
-为 `recommend-ship`，随后形成发布确定性契约的联合 `SHIP` 决策。语义记忆选择仍为
-实验性、宿主显式启用能力；本版本不宣称任务质量、token 或延迟改善。
-
-**v0.7.78 证据门禁学习、首次配置与权限/沙盒正式版**：后台学习遵循
-Memory-first；只有重复且独立验证的证据，或带已验证终态证据的显式
-preserve-as-Skill 请求，才能把低风险声明式 Skill 放入不可变、项目级的有界
-canary。自动项目信任需要完成三次精确 revision 使用并取得独立验证成功；每个
-revision 都可在 `/learn` 中查看、禁用、回滚、信任或拒绝。受保护/正式 Skill、
-全局提升和 Extension 编写仍必须由用户显式决定。
-
-### 将 learned Skill 提升到用户正式目录
-
-自动 canary 激活和用户目录提升不是一回事：
-
-- 独立验证成功会把项目 Learned Area 中的 `testing` 变为
-  `active_learned`；
-- `/learn promote` 是一次显式所有权转移：它把精确 fingerprint 对应、且已审查的
-  `ready` 或 `active_learned` revision 复制到用户正式 Skill 目录，并把生命周期
-  改为 `promoted_user`。
-
-先检查具体 revision，再按名称、slug 或精确 capability ID 提升：
-
-```text
-/learn show normalize-release-notes
-/learn promote normalize-release-notes --scope user
-```
-
-`--scope user` 是目前唯一支持的 scope，也可以省略。错误 scope、未知或重复
-option，以及多余参数都会失败且不改变目录。目标位置是所配置 KodaX home 下的
-`skills/<slug>/SKILL.md`，通常为
-`~/.kodax/skills/<slug>/SKILL.md`；不同内容的同名正式 Skill 永远不会被覆盖。
-
-专属帮助入口为 `/learn promote --help`、`/learn help promote` 和
-`/help learn promote`。在 Ink Learning Center 中可执行 `/learn`，选择一个
-`active_learned` Skill，再选择 **Promote to user catalog**。
-
-首次 setup 会创建并校验 core/MCP/Extensions/A2A 分离配置及带注释模板，不覆盖
-现有配置，也不收集密钥。Auto[LLM] 在 classifier 延迟之前放行可精确建模的普通
-读取及 workspace/temp 变更；classifier 基础设施失败只重试一次，随后按
-Accept-edits 边界降级，绝不切换到 rules。ASRT 是可选执行期 containment，不是
-权限裁决者；`/sandbox` 是显式诊断入口，SDK 宿主也可独立使用 `/sandbox`
-subpath，且不可用时不会静默改为非隔离执行。KodaX 自身的 workspace containment
-会拒绝读取常见的用户主目录凭据路径及完整的已解析 agent home，同时不把普通外部
-读取收窄成 allowlist。详见
-[v0.7.78 设计](docs/features/v0.7.78.md)、
-[发布检查清单](docs/release.md#v0778-release-verification)与
-[SDK 指南第 29–30 节](docs/SDK_EMBEDDER_GUIDE.md#29-evidence-gated-background-skill-learning-feature_263-v0778)。
-
-本次发布收口同时保证相邻表面不扭曲意图：Edit/Plan 可加载静态 Skill 指令，但不
-预授权其后续副作用；动态 Skill 命令必须由宿主显式控制 executor；根 AMA 使用受
-治理的 `memory_intent` 生命周期（包括在后续取消前已捕获的显式意图）；Workflow
-Actor wait 只有在 workflow 显式设置
-deadline 时才超时；embedded、Worker 与 daemon 的 Runtime Auto v4 均声明
-`fallbackPersistsEngine:false`。Actor owner 还会验证 Runtime identity，而不是只看
-PID，因此 PID 复用不会卡住已崩溃 owner。恢复 Session 选择器也改为显示宿主本地时区。
-
-v0.7.77 还增加了由宿主显式配置的 Shell Execution Contract。Runtime Session
-设置或单次 Run 可以选择 `pwsh`、Windows PowerShell、`cmd`、`bash`、`zsh`
-或 Git Bash 的绝对路径；KodaX 会在实际项目 cwd 中解析 shell 环境，再通过同一
-解释器执行命令。环境缓存按 contract 与 cwd 隔离，使用有界 TTL，也可由宿主显式
-刷新。Provider 凭据与执行控制变量会在加载 profile/setup 前以及实际执行前分别
-过滤。没有配置 `shellExecution` 的调用保持原有命令行为。详见
-[SDK Embedder Guide 第 28 节](docs/SDK_EMBEDDER_GUIDE.md#28-host-configurable-shell-execution-contract-v0777)
-与 [Issue 214 回归指南](docs/test-guides/ISSUE_214_v0.7.77_REGRESSION_GUIDE.md)。
-
-Kimi Code 请求现在还会携带由 Runtime 逻辑上下文派生的稳定、不透明 Prompt Cache
-affinity key。它会在跨 Run、重试、fallback、恢复与压缩时复用；递归子 Agent 则按
-规范 Agent 路径获得与 root 和临时 transcript Session 隔离的 key。公开 Kimi 与
-官方 OpenAI 使用对应的 `prompt_cache_key`；其他兼容网关保持显式 opt-in，因为
-部分严格端点会拒绝未知字段。该能力提高缓存路由稳定性，但不能绕过 Provider TTL
-或缓存分片。详见
-[Issue 215 回归指南](docs/test-guides/ISSUE_215_v0.7.77_REGRESSION_GUIDE.md)。
-Codex CLI 的缓存读取/写入与 Gemini CLI 的缓存读取现在会原样贯穿 CLI bridge
-和 Runtime diagnostics，不做估算；Provider 明确报告的 `0` 与未报告字段保持
-可区分。详见
-[Issue 216 回归指南](docs/test-guides/ISSUE_216_v0.7.77_REGRESSION_GUIDE.md)。
-CLI bridge 还会让首个原生 CLI turn 以 fresh 模式启动，只恢复 CLI 自己报告的
-原生 session ID；无 conversation ID 的 stateless 调用每次创建独立 ACP Session，
-非零 CLI 退出会显式失败。用户主动取消保持安静，hard/idle timeout 的 Abort 则会
-作为失败进入 Runtime 恢复路径，不再伪装成空成功；已经报告成功但迟迟不退出的
-CLI 也会在配置的 deadline 被终止。详见
-[Issue 217 回归指南](docs/test-guides/ISSUE_217_v0.7.77_REGRESSION_GUIDE.md)。
-
-**v0.7.72–v0.7.73 Runtime 权限契约：**Auto Mode 的权限决策由 Runtime Session 持有，
-不再由 UI hook 抢先决定。Runtime 会跨 turn 复用 LLM/rules guardrail，先分类、
-仅在 `escalate` 时创建共享 permission 请求，并持久化显式选择的 engine。
-Session 也可设置 classifier model 和有界 timeout；`auto` 默认使用 LLM
-分类，没有有效 classifier model 时会在调用 provider 或创建审批前返回可恢复配置错误，
-绝不静默退回 rules。v0.7.78 中 classifier 失败会重试一次，再按 Accept-edits
-安全边界降级，绝不把 engine 改为 rules。Runtime 权限请求可给出由 Runtime 生成的精确作用域建议：一次允许、
+**v0.7.76 Kimi Code 模型目录更新**：`kimi-code` 现在默认使用官方
+`k3-256k` Model ID，并直接发送该同名 ID。`kimi-for-coding` 继续作为 K2.7 Code
+可选模型，同时保留 `kimi-for-coding-highspeed` 与 1M `k3` tier。K3 支持
+`low` / `high` / `max` 思考强度，默认 `high`；256K 路由支持图片但不支持视频输入。
+
+**v0.7.77 正式版**：AMA 现在通过现有 Actor 控制面按需组合六种具名问题解决
+模式，不引入固定拓扑或隐藏 Workflow。可选策略元数据会形成有界、仅记录事实的
+`PatternTrace`，现有 Sidecar 仍是唯一的终态答案质量裁决者。治理式记忆可在工具
+失败、验证失败或已提交 compact 之后稀疏触发，在下一次 Action-LLM 请求前注入最多
+三条 prompt-safe、低权威证据；默认路径不增加 selector 模型调用，SDK 宿主可在
+进程内显式注入 `memoryRecallRunner`。公开 `kimi` provider 同时新增 1M
+`kimi-k3` 路由，并继续以 K2.7 Code 为默认。详见
+[v0.7.77 设计](docs/features/v0.7.77.md)与
+[发布检查清单](docs/release.md#v0777-release-ready-candidate-verification)。
+冻结的 F274/F275 付费评测已完成；F274 最终 Layer 2/Layer 3 与 F275 pilot 盲审均
+为 `recommend-ship`，随后形成发布确定性契约的联合 `SHIP` 决策。语义记忆选择仍为
+实验性、宿主显式启用能力；本版本不宣称任务质量、token 或延迟改善。
+
+**v0.7.78 证据门禁学习、首次配置与权限/沙盒正式版**：后台学习遵循
+Memory-first；只有重复且独立验证的证据，或带已验证终态证据的显式
+preserve-as-Skill 请求，才能把低风险声明式 Skill 放入不可变、项目级的有界
+canary。自动项目信任需要完成三次精确 revision 使用并取得独立验证成功；每个
+revision 都可在 `/learn` 中查看、禁用、回滚、信任或拒绝。受保护/正式 Skill、
+全局提升和 Extension 编写仍必须由用户显式决定。
+
+### 将 learned Skill 提升到用户正式目录
+
+自动 canary 激活和用户目录提升不是一回事：
+
+- 独立验证成功会把项目 Learned Area 中的 `testing` 变为
+  `active_learned`；
+- `/learn promote` 是一次显式所有权转移：它把精确 fingerprint 对应、且已审查的
+  `ready` 或 `active_learned` revision 复制到用户正式 Skill 目录，并把生命周期
+  改为 `promoted_user`。
+
+先检查具体 revision，再按名称、slug 或精确 capability ID 提升：
+
+```text
+/learn show normalize-release-notes
+/learn promote normalize-release-notes --scope user
+```
+
+`--scope user` 是目前唯一支持的 scope，也可以省略。错误 scope、未知或重复
+option，以及多余参数都会失败且不改变目录。目标位置是所配置 KodaX home 下的
+`skills/<slug>/SKILL.md`，通常为
+`~/.kodax/skills/<slug>/SKILL.md`；不同内容的同名正式 Skill 永远不会被覆盖。
+
+专属帮助入口为 `/learn promote --help`、`/learn help promote` 和
+`/help learn promote`。在 Ink Learning Center 中可执行 `/learn`，选择一个
+`active_learned` Skill，再选择 **Promote to user catalog**。
+
+首次 setup 会创建并校验 core/MCP/Extensions/A2A 分离配置及带注释模板，不覆盖
+现有配置，也不收集密钥。Auto[LLM] 在 classifier 延迟之前放行可精确建模的普通
+读取及 workspace/temp 变更；classifier 基础设施失败只重试一次，随后按
+Accept-edits 边界降级，绝不切换到 rules。ASRT 是可选执行期 containment，不是
+权限裁决者；`/sandbox` 是显式诊断入口，SDK 宿主也可独立使用 `/sandbox`
+subpath，且不可用时不会静默改为非隔离执行。KodaX 自身的 workspace containment
+会拒绝读取常见的用户主目录凭据路径及完整的已解析 agent home，同时不把普通外部
+读取收窄成 allowlist。详见
+[v0.7.78 设计](docs/features/v0.7.78.md)、
+[发布检查清单](docs/release.md#v0778-release-verification)与
+[SDK 指南第 29–30 节](docs/SDK_EMBEDDER_GUIDE.md#29-evidence-gated-background-skill-learning-feature_263-v0778)。
+
+本次发布收口同时保证相邻表面不扭曲意图：Edit/Plan 可加载静态 Skill 指令，但不
+预授权其后续副作用；动态 Skill 命令必须由宿主显式控制 executor；根 AMA 使用受
+治理的 `memory_intent` 生命周期（包括在后续取消前已捕获的显式意图）；Workflow
+Actor wait 只有在 workflow 显式设置
+deadline 时才超时；embedded、Worker 与 daemon 的 Runtime Auto v4 均声明
+`fallbackPersistsEngine:false`。Actor owner 还会验证 Runtime identity，而不是只看
+PID，因此 PID 复用不会卡住已崩溃 owner。恢复 Session 选择器也改为显示宿主本地时区。
+
+**v0.7.79 发布准备候选版**：configured outbound A2A Agent 现在可持久化两项彼此独立、
+默认拒绝的网络权限：private-address 访问与非 loopback 明文 HTTP。embedded Worker
+与共享 daemon 会协调并执行同一份授权配置。Runtime 宿主同时获得唯一权威的
+Session 状态、有界只读诊断、字节保持的 Session 导出、严格 transcript 观测，
+证据约束的普通对话投影，以及通过 capability 协商并仅在 daemon 空闲时升级的
+有界流式事件合并。standalone 子进程、Session lineage、shell 清理、发布 sidecar
+和并行 admission 路径也完成了相应的发布加固。
+
+OpenAI-compatible 自定义 provider 现在可在 provider 或 model 级选择 `max_tokens`
+或 `max_completion_tokens`。DeepSeek V4 Flash/Pro 使用各自的 reasoning profile，
+并正确标记为纯文本。详见 [v0.7.79 设计](docs/features/v0.7.79.md)与
+[发布准备清单](docs/release.md#v0779-release-preparation)。FEATURE_280 已显式改期到
+v0.7.81，本候选版没有把它表述为已交付。Issue 256 同样已显式改期到 v0.7.84，
+本候选版没有把它表述为已交付。
+
+v0.7.77 还增加了由宿主显式配置的 Shell Execution Contract。Runtime Session
+设置或单次 Run 可以选择 `pwsh`、Windows PowerShell、`cmd`、`bash`、`zsh`
+或 Git Bash 的绝对路径；KodaX 会在实际项目 cwd 中解析 shell 环境，再通过同一
+解释器执行命令。环境缓存按 contract 与 cwd 隔离，使用有界 TTL，也可由宿主显式
+刷新。Provider 凭据与执行控制变量会在加载 profile/setup 前以及实际执行前分别
+过滤；旧的 platform-shell 路径同样会过滤凭据型变量。用户级 `sandbox.envPass`
+明确列出的变量只会在最终命令目标中恢复。没有配置 `shellExecution` 时仍保持原有
+解释器路径。详见
+[SDK Embedder Guide 第 28 节](docs/SDK_EMBEDDER_GUIDE.md#28-host-configurable-shell-execution-contract-v0777)
+与 [Issue 214 回归指南](docs/test-guides/ISSUE_214_v0.7.77_REGRESSION_GUIDE.md)。
+
+Kimi Code 请求现在还会携带由 Runtime 逻辑上下文派生的稳定、不透明 Prompt Cache
+affinity key。它会在跨 Run、重试、fallback、恢复与压缩时复用；递归子 Agent 则按
+规范 Agent 路径获得与 root 和临时 transcript Session 隔离的 key。公开 Kimi 与
+官方 OpenAI 使用对应的 `prompt_cache_key`；其他兼容网关保持显式 opt-in，因为
+部分严格端点会拒绝未知字段。该能力提高缓存路由稳定性，但不能绕过 Provider TTL
+或缓存分片。详见
+[Issue 215 回归指南](docs/test-guides/ISSUE_215_v0.7.77_REGRESSION_GUIDE.md)。
+Codex CLI 的缓存读取/写入与 Gemini CLI 的缓存读取现在会原样贯穿 CLI bridge
+和 Runtime diagnostics，不做估算；Provider 明确报告的 `0` 与未报告字段保持
+可区分。详见
+[Issue 216 回归指南](docs/test-guides/ISSUE_216_v0.7.77_REGRESSION_GUIDE.md)。
+CLI bridge 还会让首个原生 CLI turn 以 fresh 模式启动，只恢复 CLI 自己报告的
+原生 session ID；无 conversation ID 的 stateless 调用每次创建独立 ACP Session，
+非零 CLI 退出会显式失败。用户主动取消保持安静，hard/idle timeout 的 Abort 则会
+作为失败进入 Runtime 恢复路径，不再伪装成空成功；已经报告成功但迟迟不退出的
+CLI 也会在配置的 deadline 被终止。详见
+[Issue 217 回归指南](docs/test-guides/ISSUE_217_v0.7.77_REGRESSION_GUIDE.md)。
+
+**v0.7.72–v0.7.73 Runtime 权限契约：**Auto Mode 的权限决策由 Runtime Session 持有，
+不再由 UI hook 抢先决定。Runtime 会跨 turn 复用 LLM/rules guardrail，先分类、
+仅在 `escalate` 时创建共享 permission 请求，并持久化显式选择的 engine。
+Session 也可设置 classifier model 和有界 timeout；`auto` 默认使用 LLM
+分类，没有有效 classifier model 时会在调用 provider 或创建审批前返回可恢复配置错误，
+绝不静默退回 rules。v0.7.78 中 classifier 失败会重试一次，再按 Accept-edits
+安全边界降级，绝不把 engine 改为 rules。Runtime 权限请求可给出由 Runtime 生成的精确作用域建议：一次允许、
 本 Session 允许，或（仅安全场景）持久允许；客户端只能回传不透明 suggestion id，不能从
 预览内容自行扩大范围。持久授权由 daemon 持有并通过 revision 管理。没有宿主审批回调时，
 不会向模型暴露 `exit_plan_mode`。完整 SDK 接入见
@@ -222,9 +240,9 @@ Session 也可设置 classifier model 和有界 timeout；`auto` 默认使用 LL
 **v0.7.74 Auto 切换可靠性：**默认用 `Shift+Tab` 在 `Plan -> Edits -> Auto`
 之间循环，`Shift+Enter` 仍用于换行。进入 Auto 时状态栏会立即显示已解析的
 `Auto[LLM]` 或 `Auto[RULES]`，同一 Session 的 Runtime 设置按键入顺序串行提交，
-快速循环不会让较早的异步结果覆盖最后一次选择。`Auto[RULES]` 是手动选择后的
-合法粘性状态；从 v0.7.78 起它只由显式/持久化选择产生。使用
-`/auto-engine llm` 可显式选择 LLM 分类。
+快速循环不会让较早的异步结果覆盖最后一次选择。`Auto[RULES]` 是手动选择后的
+合法粘性状态；从 v0.7.78 起它只由显式/持久化选择产生。使用
+`/auto-engine llm` 可显式选择 LLM 分类。
 
 ## 为什么用 KodaX
 
@@ -307,61 +325,83 @@ kodax
 
 可以先运行不会收集 Key 的交互配置：
 
-```bash
-kodax setup
-
-# 交互配置自定义 OpenAI/Anthropic-compatible provider
-kodax setup --custom
-
-# 只显示完整指导，不修改文件
-kodax setup --help
-```
-
-setup 会检查以下活跃文件以及对应的 `*.example.jsonc` 注释模板：
-
-- `~/.kodax/config.json` 与 `~/.kodax/config.example.jsonc`
-- `~/.kodax/integrations/mcp.json`
-- `~/.kodax/integrations/extensions.json`
-- `~/.kodax/integrations/a2a.json`
-
-活跃 `config.json` 仍是严格 JSON；`config.example.jsonc` 第一行指向全部分离配置，
-并注释说明所有受支持的 core 配置项。setup 不覆盖已有文件；创建空的权威分离配置
-前会先保全可读取的旧 `config.json#mcpServers` / `config.json#extensions`。命令会
-先验证已有活动配置；发现无效文件时会报告并停止，不创建或覆盖任何配置。随后才会
-保存 provider/model，告诉你准确的环境变量名，然后退出以便重启终端。也可以直接设置 API Key：
+```bash
+kodax setup
+
+# 交互配置自定义 OpenAI/Anthropic-compatible provider
+kodax setup --custom
+
+# 只显示完整指导，不修改文件
+kodax setup --help
+```
+
+setup 会检查以下活跃文件以及对应的 `*.example.jsonc` 注释模板：
+
+- `~/.kodax/config.json` 与 `~/.kodax/config.example.jsonc`
+- `~/.kodax/integrations/mcp.json`
+- `~/.kodax/integrations/extensions.json`
+- `~/.kodax/integrations/a2a.json`
+
+活跃 `config.json` 仍是严格 JSON；`config.example.jsonc` 第一行指向全部分离配置，
+并注释说明所有受支持的 core 配置项。setup 不覆盖已有文件；创建空的权威分离配置
+前会先保全可读取的旧 `config.json#mcpServers` / `config.json#extensions`。命令会
+先验证已有活动配置；发现无效文件时会报告并停止，不创建或覆盖任何配置。随后才会
+保存 provider/model，告诉你准确的环境变量名，然后退出以便重启终端。配置自定义
+provider 时，setup 要求填写的 `apiKeyEnv` 是环境变量名（例如
+`MY_LLM_API_KEY`），不是 API Key 本身；`config.json` 只保存这个名字。setup 完成后，
+必须把该 provider 的真实 API Key 设置为这个同名环境变量的值；KodaX 不会代为写入
+系统环境变量。也可以直接设置：
 
 ```bash
 # macOS / Linux
 export ZHIPU_API_KEY=your_api_key
 
 # PowerShell
-$env:ZHIPU_API_KEY="your_api_key"
-```
-
-### 2.1 激活可选 sandbox
-
-`kodax setup` 与首次安装 setup 会检查 sandbox。也可以显式检查或激活：
-
-```bash
-kodax sandbox doctor
-kodax sandbox setup
-```
-
-- Windows 使用受限 sandbox 账户和网络策略。普通 Terminal 即可，按提示同意一次
-  UAC；不必先以管理员身份启动 Terminal。
-- macOS 使用 Seatbelt/`sandbox-exec`，需要 ripgrep：
-  `brew install ripgrep`。
-- Linux 使用 bubblewrap，需要 `bubblewrap`、`socat` 和 `ripgrep`，请根据发行版用
-  `apt`、`dnf` 或 `pacman` 安装。
-
-KodaX 不会自动运行 `sudo` 或系统包管理器。sandbox 未激活时，确定性安全操作与
-Auto[LLM] 的权限体验保持一致，只缺少 OS 级 containment；普通运行不会反复打扰。
-在 REPL 中，`/sandbox` 会刷新 ready 状态与诊断，但不会激活 backend 或请求提权。
-逐命令 sandbox 路由属于内部机制，不显示在普通命令历史中。SDK 嵌入方还可通过
-`@kodax-ai/kodax/sandbox` 在 Auto[LLM] 之外独立使用该能力，
-见 [SDK sandbox 指南](docs/SDK_EMBEDDER_GUIDE.md#30-standalone-sandbox-sdk-v0778)。
-
-Qwen Token Plan 需要选择 `qwen-token-plan` 并使用单独的凭据；`QWEN_API_KEY`
+$env:ZHIPU_API_KEY="your_api_key"
+```
+
+### 2.1 激活可选 sandbox
+
+`kodax setup` 与首次安装 setup 会检查 sandbox。也可以显式检查或激活：
+
+```bash
+kodax sandbox doctor
+kodax sandbox setup
+```
+
+- Windows 使用受限 sandbox 账户和网络策略。普通 Terminal 即可，按提示同意一次
+  UAC；不必先以管理员身份启动 Terminal。
+- macOS 使用 Seatbelt/`sandbox-exec`，需要 ripgrep：
+  `brew install ripgrep`。
+- Linux 使用 bubblewrap，需要 `bubblewrap`、`socat` 和 `ripgrep`，请根据发行版用
+  `apt`、`dnf` 或 `pacman` 安装。
+
+KodaX 不会自动运行 `sudo` 或系统包管理器。sandbox 未激活时，确定性安全操作与
+Auto[LLM] 的权限体验保持一致，只缺少 OS 级 containment；普通运行不会反复打扰。
+在 REPL 中，`/sandbox` 会刷新 ready 状态与诊断，但不会激活 backend 或请求提权。
+逐命令 sandbox 路由属于内部机制，不显示在普通命令历史中。SDK 嵌入方还可通过
+`@kodax-ai/kodax/sandbox` 在 Auto[LLM] 之外独立使用该能力，
+见 [SDK sandbox 指南](docs/SDK_EMBEDDER_GUIDE.md#30-standalone-sandbox-sdk-v0778)。
+
+模型发起的 shell 命令默认会过滤名称形似凭据的环境变量。若要把指定宿主变量
+透传给命令目标（包括 ASRT），只需在用户级 core 配置中列出变量名：
+
+```json
+{
+  "sandbox": {
+    "envPass": ["GH_TOKEN", "GITHUB_TOKEN", "OPENAI_API_KEY"]
+  }
+}
+```
+
+默认列表为空；`config.json` 只保存变量名，不保存值，项目配置也不能扩大该列表。
+变量名精确匹配（Windows 不区分大小写），`NODE_OPTIONS`、`BASH_ENV` 等执行控制
+变量即使列入仍会被阻止。修改宿主环境变量或该配置后需重启 KodaX；若使用常驻
+daemon，还需先停止并重新启动 daemon，让它获取新的环境与配置。
+SDK 调用方可按 Run 传入同结构的 `KodaXOptions.sandbox`，并发 Run 无需修改全局配置，
+也可以各自使用不同的变量名列表。
+
+Qwen Token Plan 需要选择 `qwen-token-plan` 并使用单独的凭据；`QWEN_API_KEY`
 不能用于该路由：
 
 ```bash
@@ -426,14 +466,14 @@ import { createImageArtifactFromPath } from '@kodax-ai/kodax/media'; // 输入 a
 import { SkillRegistry } from '@kodax-ai/kodax/skills';         // 零依赖 skill loader
 import { loadConfig } from '@kodax-ai/kodax/repl';              // REPL 配置 / session 工具
 import { createMcpManager } from '@kodax-ai/kodax/mcp';         // MCP popout manager（v0.7.42 起）
-import { listSessions } from '@kodax-ai/kodax/session';         // session 历史工具
-import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';   // embedded/Worker/daemon 宿主 API
-import { runKodaXSandboxed } from '@kodax-ai/kodax/sandbox';    // 独立 ASRT 受控执行
-import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';    // A2A 1.0 双向接入
-import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-in 实验性记忆 SDK
-```
-
-13 个 SDK 入口（root + 12 subpath）通过 ESM 共享 chunk 复用底层代码 —— 只 import `/agent` 不会把 `/repl` 的 Ink + React 一起拉进来。
+import { listSessions } from '@kodax-ai/kodax/session';         // session 历史工具
+import { createKodaXRuntime } from '@kodax-ai/kodax/runtime';   // embedded/Worker/daemon 宿主 API
+import { runKodaXSandboxed } from '@kodax-ai/kodax/sandbox';    // 独立 ASRT 受控执行
+import { createKodaXA2AServer } from '@kodax-ai/kodax/a2a';    // A2A 1.0 双向接入
+import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-in 实验性记忆 SDK
+```
+
+13 个 SDK 入口（root + 12 subpath）通过 ESM 共享 chunk 复用底层代码 —— 只 import `/agent` 不会把 `/repl` 的 Ink + React 一起拉进来。
 
 完整的宿主集成契约——包括 embedded/Worker/daemon 所有权、外部 Agent 注册与任务控制、session cursor 分页、workflow 模型分层和效率遥测——见 [SDK Embedder Integration Guide](docs/SDK_EMBEDDER_GUIDE.md)。
 
@@ -463,6 +503,10 @@ import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-
 }
 ```
 
+这里的 `"apiKeyEnv": "MY_LLM_API_KEY"` 表示环境变量名，不是 API Key 值。
+请把自定义 provider 的真实 API Key 设置到 `MY_LLM_API_KEY` 环境变量中，然后关闭
+当前终端、打开新终端，再运行 `kodax`。
+
 `userAgentMode` 默认 `"compat"`（发送 `KodaX` 而非上游 SDK 的 User-Agent）；如果你的网关要求原生 SDK header，再切到 `"sdk"`。
 
 自定义 reasoning 模型优先使用 v0.7.57 的 `reasoning: { efforts, default }`；无 thinking 能力的模型使用 `"reasoning": "none"`。SDK 宿主的 effort 选择器应从 `reasoningProfile.supportedEfforts` / `defaultEffort` 动态生成，不要假定固定五档。
@@ -480,31 +524,39 @@ import { createMemoryAgent } from '@kodax-ai/kodax/experimental-memory'; // opt-
       "baseUrl": "https://example.com/v1",
       "apiKeyEnv": "MY_DEEPSEEK_API_KEY",
       "model": "deepseek-v4-flash",
-      "reasoningPreset": "deepseek-v4-openai",
+      "maxOutputTokensField": "max_tokens",
+      "reasoningPreset": "deepseek-v4-flash-openai",
       "replayReasoningContent": true
     }
   ]
 }
 ```
 
-如果网关同时代理 DeepSeek 和 OpenAI proper，建议用 per-model override，避免把 `reasoning_content` 发给不接受该字段的模型：
+DeepSeek Chat Completions 使用 `max_tokens`，OpenAI proper 默认使用
+`max_completion_tokens`。如果网关同时代理两者，建议对这两个字段都使用
+per-model override，避免把 `reasoning_content` 或不兼容的 token 字段发给错误模型：
 
 ```json
 {
   "models": [
-    { "id": "deepseek-v4-flash", "replayReasoningContent": true },
+    {
+      "id": "deepseek-v4-flash",
+      "maxOutputTokensField": "max_tokens",
+      "reasoningPreset": "deepseek-v4-flash-openai",
+      "replayReasoningContent": true
+    },
     { "id": "gpt-5", "replayReasoningContent": false }
   ]
-}
-```
-
-如果已确认自定义端点支持缓存 affinity 路由，可以设置
-`"promptCacheAffinity": true`。Anthropic-compatible 请求会把不透明逻辑上下文
-key 写入 `metadata.user_id`，OpenAI-compatible 请求写入 `prompt_cache_key`。
-默认值为 `false`，因为部分严格兼容网关会拒绝未知请求字段；不要只因端点宣称协议
-兼容就开启。
-
-Sidecar verifier 的结构化裁决请求会优先使用 provider 级 `tool_choice` 强制工具调用；如果某个兼容端点明确拒绝 `tool_choice` 参数，KodaX 会对该 verifier 请求自动重试一次“不强制但仍带 tools”的兼容模式，并保持 fail-open，不会阻塞主 Worker。
+}
+```
+
+如果已确认自定义端点支持缓存 affinity 路由，可以设置
+`"promptCacheAffinity": true`。Anthropic-compatible 请求会把不透明逻辑上下文
+key 写入 `metadata.user_id`，OpenAI-compatible 请求写入 `prompt_cache_key`。
+默认值为 `false`，因为部分严格兼容网关会拒绝未知请求字段；不要只因端点宣称协议
+兼容就开启。
+
+Sidecar verifier 的结构化裁决请求会优先使用 provider 级 `tool_choice` 强制工具调用；如果某个兼容端点明确拒绝 `tool_choice` 参数，KodaX 会对该 verifier 请求自动重试一次“不强制但仍带 tools”的兼容模式，并保持 fail-open，不会阻塞主 Worker。
 
 调试 Worker 结束后的 verifier 行为时可设置：
 
@@ -522,7 +574,7 @@ Verifier 的 `revise` / `blocked` 可执行消息；JSONL 输出使用同形
 
 #### 给自定义 provider 开图片 / vision 输入（FEATURE_134 v0.7.40）
 
-如果你的自定义 provider 后面的模型支持 vision，加 `capabilityProfile.multimodalSupport: "image-input"` 显式开启，KodaX 的 SA-path policy gate 就不会人为拦截多模态请求。内置 vision-capable alias（Anthropic、OpenAI、DeepSeek、Kimi、Qwen、Zhipu、MiniMax、MiMo、Ark，以及通过 CLI `@<path>` file-include 语法传图的 Gemini-CLI）已经默认开了这个 flag。Codex-CLI 和自定义 provider 在底层模型支持图片输入时需要手动 opt-in。
+如果你的自定义 provider 后面的模型支持 vision，加 `capabilityProfile.multimodalSupport: "image-input"` 显式开启，KodaX 的 SA-path policy gate 就不会人为拦截多模态请求。内置 vision-capable alias（Anthropic、OpenAI、Kimi、Qwen、Zhipu、MiniMax、MiMo、Ark，以及通过 CLI `@<path>` file-include 语法传图的 Gemini-CLI）已经默认开了这个 flag。DeepSeek V4 和 Codex-CLI 是纯文本模型；自定义 provider 在底层模型支持图片输入时需要手动 opt-in。
 
 ```json
 {
@@ -664,7 +716,7 @@ dist/binary/linux-x64/
 | kimi | `KIMI_API_KEY` | Native | kimi-k2.7-code（262,144 token；可 `/model` 切换 `kimi-k3`〔1M〕/ `kimi-k2.7-code-highspeed` / `kimi-k2.6` / `kimi-k2.5`） |
 | kimi-code | `KIMI_CODE_API_KEY` | Native | k3-256k（Moderato+，256K，直接请求同名上游模型；可 `/model` 切换 `k3`〔Allegretto+，1M〕/ `kimi-for-coding`〔K2.7 Code〕/ `kimi-for-coding-highspeed`） |
 | qwen | `QWEN_API_KEY` | Native | qwen3.5-plus |
-| qwen-token-plan | `QWEN_TOKEN_API_KEY` | Native | qwen3.8-max-preview（Anthropic 协议；可 `/model` 切换 `qwen3.7-max` / `qwen3.7-plus` / `qwen3.6-flash` / `glm-5.2` / `deepseek-v4-pro`；均为 1M ctx；Qwen 3.8 / 3.7 Plus / 3.6 Flash 支持图片理解） |
+| qwen-token-plan | `QWEN_TOKEN_API_KEY` | Native | qwen3.8-max（Anthropic 协议；可 `/model` 切换兼容项 `qwen3.8-max-preview` 及 `qwen3.7-max` / `qwen3.7-plus` / `qwen3.6-flash` / `glm-5.2` / `deepseek-v4-pro`；均为 1M ctx；两个 Qwen 3.8 ID / 3.7 Plus / 3.6 Flash 支持图片理解） |
 | zhipu | `ZHIPU_API_KEY` | Native | glm-5（可 `/model` 切换 `glm-5.2` 1M ctx / `glm-5.1` / `glm-5-turbo`） |
 | zhipu-coding | `ZHIPU_CODING_API_KEY` | Native | glm-5.2（1M ctx；仍可通过 `/model` 显式选择兼容模型 `glm-5.1` / `glm-5-turbo`） |
 | zai-coding | `ZAI_CODING_API_KEY` | Native | glm-5.2（GLM Coding Plan 海外站，通过 `api.z.ai` 接入，Anthropic 协议 — 模型清单和 `zhipu-coding` 完全一致） |
@@ -673,8 +725,8 @@ dist/binary/linux-x64/
 | mimo-coding | `MIMO_CODING_API_KEY` | Native | mimo-v2.5-pro（小米 MiMo Token Plan，Anthropic 协议） |
 | ark-coding | `ARK_CODING_API_KEY` | Native | glm-5.2（火山方舟 Coding Plan — GLM-5.2（别名 `glm-latest`） · Kimi K2.7 Code / K2.6 · MiniMax M3 / M2.7 · DeepSeek V4 Pro / V4 Flash · Doubao Seed 2.0 Code / Pro / Lite · Doubao Seed Code） |
 | deepseek | `DEEPSEEK_API_KEY` | Native | deepseek-v4-flash（可 `/model` 切换 `deepseek-v4-pro`） |
-| gemini-cli | 由 Provider CLI 完成认证（无 KodaX API-key 环境变量） | Prompt-only / CLI bridge | （通过 gemini CLI） |
-| codex-cli | 由 Provider CLI 完成认证（无 KodaX API-key 环境变量） | Prompt-only / CLI bridge | （通过 codex CLI） |
+| gemini-cli | 由 Provider CLI 完成认证（无 KodaX API-key 环境变量） | Prompt-only / CLI bridge | （通过 gemini CLI） |
+| codex-cli | 由 Provider CLI 完成认证（无 KodaX API-key 环境变量） | Prompt-only / CLI bridge | （通过 codex CLI） |
 
 > 不在表里的端点：用上面"自定义 Provider"那一节加进来即可。
 
@@ -757,7 +809,7 @@ kodax --repo-intelligence full --repo-intelligence-trace
 
 ## 仓库结构
 
-KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 workspace 包**（FEATURE_194 v0.7.43 包合并 — 9 → 4，ADR-036），npm 上以单 bundle 包 `@kodax-ai/kodax` 发布 + 12 个 SDK subpath exports（`/agent`、`/llm`、`/coding`、`/media`、`/repl`、`/skills`、`/mcp`、`/session`、`/runtime`、`/sandbox`、`/a2a`、`/experimental-memory`；ADR-024 + ADR-032 + ADR-038）。核心包：
+KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 workspace 包**（FEATURE_194 v0.7.43 包合并 — 9 → 4，ADR-036），npm 上以单 bundle 包 `@kodax-ai/kodax` 发布 + 12 个 SDK subpath exports（`/agent`、`/llm`、`/coding`、`/media`、`/repl`、`/skills`、`/mcp`、`/session`、`/runtime`、`/sandbox`、`/a2a`、`/experimental-memory`；ADR-024 + ADR-032 + ADR-038）。核心包：
 
 | Workspace 包 | 作用 | 主要依赖 |
 |----|------|---------|
@@ -766,20 +818,20 @@ KodaX 是基于 npm workspaces 的 TypeScript monorepo，**源码层 4 个 works
 | `@kodax-ai/coding` | Coding Agent:50+ 工具（含 canonical Actor 协作工具）、role prompts、agent loop、auto-continue + repo-intelligence protocol(v0.7.43 inline) | `@kodax-ai/llm`, `@kodax-ai/agent` |
 | `@kodax-ai/repl` | 完整交互式终端 UI（Ink / React、权限模式、命令系统、流式渲染） | `@kodax-ai/coding`, `ink`, `react` |
 
-根目录 `src/kodax_cli.ts` 是 CLI 入口；`src/sdk-{agent,llm,coding,media,repl,skills,mcp,session,runtime,sandbox,a2a,experimental-memory}.ts` 是 SDK subpath 入口；构建产物在 `dist/`，单文件二进制在 `dist/binary/<target>/`。
+根目录 `src/kodax_cli.ts` 是 CLI 入口；`src/sdk-{agent,llm,coding,media,repl,skills,mcp,session,runtime,sandbox,a2a,experimental-memory}.ts` 是 SDK subpath 入口；构建产物在 `dist/`，单文件二进制在 `dist/binary/<target>/`。
 
 ### 源码层 vs npm 发布层
 
 KodaX 有两层结构，SDK 用户需要分开理解：
 
 - **源码层**：上面 4 个 workspace 包（开发者读代码时看到的物理结构）。
-- **npm 发布层**：单个 bundled 包 `@kodax-ai/kodax`，对外暴露 12 个 SDK subpath（SDK 消费者 `import` 时看到的接口）。subpath 分两种角色：
+- **npm 发布层**：单个 bundled 包 `@kodax-ai/kodax`，对外暴露 12 个 SDK subpath（SDK 消费者 `import` 时看到的接口）。subpath 分两种角色：
   - **完整包 subpath**（`/agent`、`/llm`、`/coding`、`/repl`）—— 每个 1:1 对应一个源码包，暴露完整公开 API。
-  - **集成与窄子集 subpath**（`/media`、`/skills`、`/mcp`、`/session`、`/runtime`、`/sandbox`、`/a2a`、`/experimental-memory`）—— 聚焦能力或宿主集成边界；`/experimental-memory` 明确为 opt-in 不稳定接口。
+  - **集成与窄子集 subpath**（`/media`、`/skills`、`/mcp`、`/session`、`/runtime`、`/sandbox`、`/a2a`、`/experimental-memory`）—— 聚焦能力或宿主集成边界；`/experimental-memory` 明确为 opt-in 不稳定接口。
 
 | 源码包 | npm subpath | 类型 | 内容 | 典型消费者 |
 |---|---|---|---|---|
-| `packages/llm`    | `@kodax-ai/kodax/llm`     | 完整包 | 16-alias LLM 抽象 (108 exports) | 独立 LLM 客户端 |
+| `packages/llm`    | `@kodax-ai/kodax/llm`     | 完整包 | 16-alias LLM 抽象 (108 exports) | 独立 LLM 客户端 |
 | `packages/agent`  | `@kodax-ai/kodax/agent`   | 完整包 | Runner / fan-out / 外部 Agent plane / session-lineage / capabilities / tracing (331 exports) | 自定义 agent 框架 |
 | `packages/agent`  | `@kodax-ai/kodax/skills`  | **窄子集** | 仅 Skills 系统 —— `SkillRegistry` / `loadFullSkill` / `expandSkillForLLM` 等 (26 exports = v0.7.43 之前 `@kodax-ai/skills` 完整 API) | Skill 加载器、IDE 插件 |
 | `packages/agent`  | `@kodax-ai/kodax/mcp`     | **窄子集** | 仅 MCP —— `McpCapabilityProvider` / `createMcpTransport` / `searchMcpCatalog` 等 (23 exports) | MCP server 宿主 |
@@ -787,10 +839,10 @@ KodaX 有两层结构，SDK 用户需要分开理解：
 | `packages/agent`  | `@kodax-ai/kodax/experimental-memory` | **实验性子集** | F228-backed `MemoryAgent` / `MemorySession` scope、recall、query、observation、outcome 契约 | 显式评估 FEATURE_260 的 SDK 宿主 |
 | `packages/coding` | `@kodax-ai/kodax/coding`  | 完整包 | Coding agent + 50+ 工具 + repo-intelligence (505 exports) | 构建 Claude Code 形态产品 |
 | `packages/repl`   | `@kodax-ai/kodax/repl`    | 完整包 | Ink TUI + 权限模式 + 命令系统 (217 exports) | 终端 UI 消费者 |
-| `packages/repl`   | `@kodax-ai/kodax/session` | **窄子集** | 仅会话管理 —— `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` 等 (17 exports) | 读取 session 历史的 IDE 插件和桌面宿主 |
-| `src`             | `@kodax-ai/kodax/runtime` | 宿主 API | Embedded/Worker/daemon facade，含 sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics/外部 Agent 和 daemon schema (10 exports) | SDK 宿主、Space/IDE、daemon client |
-| `src`             | `@kodax-ai/kodax/sandbox` | 宿主 API | 显式 ASRT capability/doctor/setup 与宿主自有受控命令执行；不可用时绝不静默普通执行 | 需要独立进程 containment 的 SDK 宿主 |
-| `src`             | `@kodax-ai/kodax/a2a` | 集成边界 | A2A 1.0 Agent Card 发现、JSON-RPC/SSE F258 executor、安全 fetch 与鉴权 Runtime Agent server | Agent 编排器和 KodaX 宿主 |
+| `packages/repl`   | `@kodax-ai/kodax/session` | **窄子集** | 仅会话管理 —— `listSessions` / `loadFullTranscript` / `appendClientNotice` / `forkSession` / `compactSession` / `watchSessions` 等 (17 exports) | 读取 session 历史的 IDE 插件和桌面宿主 |
+| `src`             | `@kodax-ai/kodax/runtime` | 宿主 API | Embedded/Worker/daemon facade，含 sessions/runs/events/permissions/catalog/MCP/artifacts/diagnostics/外部 Agent 和 daemon schema (10 exports) | SDK 宿主、Space/IDE、daemon client |
+| `src`             | `@kodax-ai/kodax/sandbox` | 宿主 API | 显式 ASRT capability/doctor/setup 与宿主自有受控命令执行；不可用时绝不静默普通执行 | 需要独立进程 containment 的 SDK 宿主 |
+| `src`             | `@kodax-ai/kodax/a2a` | 集成边界 | A2A 1.0 Agent Card 发现、JSON-RPC/SSE F258 executor、安全 fetch 与鉴权 Runtime Agent server | Agent 编排器和 KodaX 宿主 |
 
 **经验法则**：需要 Runner / Agent / fan-out 时从 `/agent` 引入；只需要 skills 或 mcp API 时从 `/skills` 或 `/mcp` 引入，bundle 更小。窄子集是完整包的真子集 —— **不会**有额外符号。
 
@@ -808,7 +860,7 @@ runtime、消息、UI 历史、lineage、artifact、extension 状态、标题、
 
 **实验性 Memory Agent SDK（FEATURE_260，v0.7.68）**：`/experimental-memory` 暴露基于既有 F228 治理平面的薄 `MemoryAgent` 与 scoped `MemorySession`。被动 recall 零等待，`query()` 只读且由主 Action LLM 主动选择；持久化仍必须经过 proposal/preview/fingerprint/apply。召回内容保持低权限，安全与 scope 边界仍由确定性代码门禁承担。直接 session 示例与宿主边界见 [SDK Embedder Guide §21](docs/SDK_EMBEDDER_GUIDE.md#21-experimental-governed-memory--experimental-memory-feature_260-v0768)。
 
-**双向 A2A 1.0（FEATURE_267，v0.7.69）**：`/a2a` 可发现 allowlist 内的 Agent Card，并通过既有 F258 plane 安装 JSON-RPC/SSE executor。配置中的出站 Agent 还会作为 `external:<name>` 自动注册到 embedded CLI 与用户 daemon Runtime，因此主 Agent 无需宿主代码即可编排。一个 `a2a.json` 可保存多个出站注册，但最多只有一个入站 server；入站可发布 Runtime 默认 Agent，或发布一个经过验证的 `~/.kodax/agents/*.md` Agent。内置 listener 仅允许 loopback，且不会返回 Fetch 兼容客户端禁止的端口；公网部署必须由宿主用 TLS、鉴权和授权包住 `handle()`。不宣称支持 A2A 0.3、gRPC、HTTP+JSON、push notification，也不会自动把本地 Agent 暴露到网络。详见 [SDK Embedder Guide §22](docs/SDK_EMBEDDER_GUIDE.md#22-bidirectional-a2a-10--a2a-feature_267-v0769)。
+**双向 A2A 1.0（FEATURE_267，v0.7.69）**：`/a2a` 可发现 allowlist 内的 Agent Card，并通过既有 F258 plane 安装 JSON-RPC/SSE executor。配置中的出站 Agent 还会作为 `external:<name>` 自动注册到 embedded CLI 与用户 daemon Runtime，因此主 Agent 无需宿主代码即可编排。一个 `a2a.json` 可保存多个出站注册，但最多只有一个入站 server；入站可发布 Runtime 默认 Agent，或发布一个经过验证的 `~/.kodax/agents/*.md` Agent。内置 listener 仅允许 loopback，且不会返回 Fetch 兼容客户端禁止的端口；公网部署必须由宿主用 TLS、鉴权和授权包住 `handle()`。不宣称支持 A2A 0.3、gRPC、HTTP+JSON、push notification，也不会自动把本地 Agent 暴露到网络。详见 [SDK Embedder Guide §22](docs/SDK_EMBEDDER_GUIDE.md#22-bidirectional-a2a-10--a2a-feature_267-v0769)。
 
 **A2A 互操作与认证加固**：发现得到的 interface 必须与受信 Agent Card 同源，且只有
 完整满足 Card/Skill 的一个 security requirement 时才会携带凭据。无代码 client
@@ -837,6 +889,10 @@ kodax a2a add research https://agent.example/.well-known/agent-card.json --effec
 kodax a2a test research
 kodax a2a call research "总结这个主题"
 
+# 显式授权私网明文端点（可用时仍应优先 HTTPS）
+kodax a2a add intranet http://10.20.30.40/.well-known/agent-card.json \
+  --allow-private --allow-insecure-http --effect read
+
 # 先保存受 OAuth 保护的 Agent，再热启用/停用
 export RESEARCH_A2A_CLIENT_SECRET='由你的授权服务器分配'
 # PowerShell：$env:RESEARCH_A2A_CLIENT_SECRET='由你的授权服务器分配'
@@ -858,9 +914,9 @@ kodax a2a expose                 # 或：kodax a2a expose document-agent
 kodax a2a serve                  # 仅监听 http://127.0.0.1:8765
 ```
 
-MCP、A2A、Extension 分别使用 `~/.kodax/integrations/` 下的一个用户级文件。
-可以通过 `kodax config paths` 查看全部活跃/模板路径，通过
-`kodax config template <core|mcp|a2a|extensions>` 查看模板，通过
+MCP、A2A、Extension 分别使用 `~/.kodax/integrations/` 下的一个用户级文件。
+可以通过 `kodax config paths` 查看全部活跃/模板路径，通过
+`kodax config template <core|mcp|a2a|extensions>` 查看模板，通过
 `kodax integrations migrate --apply` 迁移旧配置，并用 `kodax mcp`、
 `kodax a2a`、`kodax extensions` 管理。迁移只导入旧
 `config.json#mcpServers` 与 `config.json#extensions`；A2A 没有旧来源，且不会
@@ -874,7 +930,11 @@ MCP、A2A、Extension 分别使用 `~/.kodax/integrations/` 下的一个用户
 确认。`a2a add --disabled` 默认仍会校验 Card，除非显式使用 `--no-test`；`a2a test`
 只做 discovery/security planning，不会申请 OAuth token。示例中的固定
 `KODAX_A2A_TOKEN` 是运维侧预先提供的兼容凭据，并非 KodaX 自行生成或签发。
-停用条目可随时重新启用。
+停用条目可随时重新启用。私网地址访问与非 loopback 明文 HTTP 是两项独立、
+持久化且默认拒绝的权限（`--allow-private` 与 `--allow-insecure-http`）；精确
+loopback HTTP 无需这两项授权。OAuth token endpoint 仍保持更严格的
+HTTPS 或精确 loopback 规则。Worker-hosted SDK Runtime 可通过
+`worker: { configuredA2A: true }` 让 Worker owner 装载同一配置执行平面。
 `a2a serve` 会在监听前装载已配置的 MCP/Extension 能力并固定执行权威，同时热加载
 公开信息、鉴权和限额。Agent、Skill、Extension 工具权威、工作区、tool policy
 或任务存储变更必须显式重启服务。
@@ -928,11 +988,11 @@ KodaX/                       # 4 workspace packages(FEATURE_194 v0.7.43)
 │   └── repl/                # @kodax-ai/repl —— Ink TUI
 ├── src/
 │   ├── kodax_cli.ts         # CLI 主入口（bin: `kodax`）
-│   └── sdk-*.ts             # SDK subpath 入口 → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session,runtime,sandbox,a2a,experimental-memory}
+│   └── sdk-*.ts             # SDK subpath 入口 → @kodax-ai/kodax/{agent,llm,coding,media,repl,skills,mcp,session,runtime,sandbox,a2a,experimental-memory}
 ├── scripts/
-│   ├── build-bundle.mjs     # esbuild 单 bundle 多 entry 打包（CLI + root + 12 SDK subpath + chunks）
+│   ├── build-bundle.mjs     # esbuild 单 bundle 多 entry 打包（CLI + root + 12 SDK subpath + chunks）
 │   ├── build-binary.mjs     # Bun --compile 单文件二进制打包
-│   └── release.mjs          # 构建/审计后仅临时切换 private 以 pack/publish
+│   └── release.mjs          # 构建/审计后仅临时切换 private 以 pack/publish
 └── .github/workflows/
     └── release.yml          # 推 v* tag 自动发布 GitHub Release
 ```