evolcore 0.0.25 → 0.0.27

package/kits/docs/evolcore/aid.md

@@ -1,68 +1,76 @@
-# ec aid — AID 身份管理
-
-管理本地 AID 身份（证书、私钥、agent.md 名片），以及远程探测对端 AID。触发词：身份/证书/名片/探测对端/创建身份。
-
-## 运行边界
-
-本页列出独立终端中 `ec aid` 的完整 CLI 能力。在 EvolCore 托管 Agent 会话中，为防止会话枚举、创建、删除或切换本地身份，只允许以下精确命令：
-
-```bash
-ec aid show <当前 self AID> [--format json]
-ec aid lookup <任意合法 AID> [--format json]
+# ec aid — AID 身份管理
+
+管理本地 AID 身份（证书、私钥、agent.md 名片与头像），以及远程探测对端 AID。触发词：身份/证书/名片/头像/换头像/探测对端/创建身份。
+
+## 运行边界
+
+本页列出独立终端中 `ec aid` 的完整 CLI 能力。在 EvolCore 托管 Agent 会话中，为防止会话枚举、创建、删除或切换本地身份，只允许以下精确命令：
+
+```bash
+ec aid show <当前 self AID> [--format json]
+ec aid lookup <任意合法 AID> [--format json]
 ec aid agentmd get <任意合法 AID> [--format json]
 # 仅 request / bypass
 ec aid agentmd put <当前 self AID> [--format json]
 ec aid avatar <当前 self AID> (--file <path> | --url <https-url>) [--format json]
-```
-
+```
+
 仅允许不带选项的基本形式，或在末尾附加一组完整的 `--format json`；不能使用 `--aun-path`、未知选项、管道、重定向或其它命令。所有 `allowAccess=true` 的已认证角色（包括 visitor、member、admin、owner 及自定义角色）均开放 `lookup` 和 `agentmd get`，目标可以是任意合法 AID。`show` 只允许当前 self AID：owner/admin 返回完整本地身份诊断，visitor/member 及其它非管理角色返回不含私钥存在性、密钥匹配和签名能力的脱敏结果。三个查询可在所有 `permissionMode` 执行。`agentmd put` 和 `avatar` 会发布远端名片，属于写操作，仅允许针对当前 self AID 的 `request`、`bypass`，`readonly`、`auto` 和未知模式均拒绝。头像支持 PNG、JPEG、WebP，大小上限 500KB，分辨率 128–2048 像素，宽高比 0.8–1.25；`--url` 仅支持 HTTPS，下载由 daemon 执行并做 SSRF/重定向校验。成功 JSON 返回 `sha256`、MIME 和尺寸元数据。`lookup` 探测指定公开 AID；`get` 下载并验签指定公开名片，同时刷新本地 AID 缓存。`list`、其它 AID 的 `show/agentmd put/avatar` 以及 `new/delete` 均拒绝。独立终端不受此托管会话限制。
-
-## 子命令
-
-```bash
-# 列出本地所有 AID（实测 sign+verify）
-ec aid list [筛选选项] [--no-verify]
-
-# 查看本地 AID 详情（证书有效期、私钥状态、签名能力）
-ec aid show <aid>
-
-# 创建新 AID 身份
-ec aid new <aid> [--force]
-
-# 远程探测 AID（是否存在 + 网关 + agent.md）
-ec aid lookup <aid>
-
-# agent.md 名片：签名上传 / 下载验签
+
+## 更换头像
+
+`ec aid avatar <当前 self AID> --file <图片路径>` 从本地文件上传；`ec aid avatar <当前 self AID> --url <HTTPS 图片地址>` 下载图片后上传。两种来源必须二选一，可在末尾加 `--format json` 获取头像 URL、SHA-256、MIME 和尺寸。
+
+托管会话中的本地图片必须位于当前会话项目目录或本会话的托管 `$TMPDIR`；相对路径以会话项目目录为基准。不能读取受保护的 EvolCore 路径、符号链接，或托管临时目录中的硬链接。
+
+上传复用 menu 的头像处理流程：校验图片、上传到 AUN storage、更新并发布 `agent.md` 的 `avatar` 字段，成功后发出 `agent:avatar_updated` 事件。无需手动修改名片或再次执行 `agentmd put`。托管 Agent 只能修改自身头像，仍需通过角色与命令授权检查。
+
+## 子命令
+
+```bash
+# 列出本地所有 AID（实测 sign+verify）
+ec aid list [筛选选项] [--no-verify]
+
+# 查看本地 AID 详情（证书有效期、私钥状态、签名能力）
+ec aid show <aid>
+
+# 创建新 AID 身份
+ec aid new <aid> [--force]
+
+# 远程探测 AID（是否存在 + 网关 + agent.md）
+ec aid lookup <aid>
+
+# agent.md 名片：签名上传 / 下载验签
 ec aid agentmd put <aid>
 ec aid agentmd get <aid>
 ec aid avatar <aid> (--file <path> | --url <https-url>)
-
-# 删除指定本地 AID（无网络注销）
-ec aid delete <aid>
-```
-
-## list 筛选选项
-
-不指定 = 列出 mine + broken + peer-cert（隐藏 no-cert）。可组合：
-- `--mine` — 仅本地可用身份（实测可签名+验签通过）
-- `--broken` — 仅有私钥但不可用（公钥不匹配 / 证书过期 / sign 失败）
-- `--peer-cert` — 仅对端 AID（无私钥，有公钥证书）
-- `--no-cert` — 仅无私钥无证书的孤儿目录
-- `--no-verify` — 跳过 sign+verify 实测，仅静态扫描（更快）
-
-输出图标：`🔑` 有私钥 · `✅` 实测可签名/验签 · `❌` 不可签名 · `⌛` 证书过期 · `📜` 有公钥证书 · `📄` 有 agent.md
-
-## delete 批量清理
-
-批量删除**默认 dry-run，加 `--yes` 才真正执行**：
-- `ec aid delete --orphan` — 清理无私钥的外部 AID 缓存
-- `ec aid delete --no-cert` — 清理无私钥也无公钥证书的孤儿目录
-- `ec aid delete --unrecoverable` — 清理云端公钥已变更、本地不可恢复的 AID
-- `--skip-pki` — 仅用于 `--unrecoverable`，跳过 PKI 探测并按本地自检结果判断；有误删风险
-
-## 通用约定
-
-- `--format json` — 对支持结构化结果的子命令输出 JSON
-- `--aun-path <path>` — 指定 AUN keystore 根；未传时可由 `AUN_HOME` 提供
-- `aid delete --orphan|--no-cert|--unrecoverable` 默认 dry-run，`--yes` 才执行删除
-- `--help` / `-h` — 各子命令均支持
+
+# 删除指定本地 AID（无网络注销）
+ec aid delete <aid>
+```
+
+## list 筛选选项
+
+不指定 = 列出 mine + broken + peer-cert（隐藏 no-cert）。可组合：
+- `--mine` — 仅本地可用身份（实测可签名+验签通过）
+- `--broken` — 仅有私钥但不可用（公钥不匹配 / 证书过期 / sign 失败）
+- `--peer-cert` — 仅对端 AID（无私钥，有公钥证书）
+- `--no-cert` — 仅无私钥无证书的孤儿目录
+- `--no-verify` — 跳过 sign+verify 实测，仅静态扫描（更快）
+
+输出图标：`🔑` 有私钥 · `✅` 实测可签名/验签 · `❌` 不可签名 · `⌛` 证书过期 · `📜` 有公钥证书 · `📄` 有 agent.md
+
+## delete 批量清理
+
+批量删除**默认 dry-run，加 `--yes` 才真正执行**：
+- `ec aid delete --orphan` — 清理无私钥的外部 AID 缓存
+- `ec aid delete --no-cert` — 清理无私钥也无公钥证书的孤儿目录
+- `ec aid delete --unrecoverable` — 清理云端公钥已变更、本地不可恢复的 AID
+- `--skip-pki` — 仅用于 `--unrecoverable`，跳过 PKI 探测并按本地自检结果判断；有误删风险
+
+## 通用约定
+
+- `--format json` — 对支持结构化结果的子命令输出 JSON
+- `--aun-path <path>` — 指定 AUN keystore 根；未传时可由 `AUN_HOME` 提供
+- `aid delete --orphan|--no-cert|--unrecoverable` 默认 dry-run，`--yes` 才执行删除
+- `--help` / `-h` — 各子命令均支持

package/kits/docs/evolcore/codex-windows-sandbox.md

@@ -1,146 +1,146 @@
-# Windows 上的 Codex Sandbox 权限排障
-
-本文适用于 EvolCore 在 Windows 上调用 Codex 时，任务在启动阶段因 sandbox 权限失败的情况。目标运行方式是：Codex Desktop、EvolCore daemon 和 `ec` CLI 均以普通用户运行；只有 Codex sandbox 的安装或修复过程临时通过 UAC 提权。
-
-不要为了绕过 sandbox 错误而长期以管理员身份运行全部组件。这样不仅扩大权限，还可能使高完整性 daemon 创建的命名管道拒绝普通权限 `ec` CLI 连接。
-
-## 典型错误
-
-### `.sandbox-bin` 无法锁定
-
-```text
-helper_sandbox_lock_failed: lock sandbox bin dir C:\Users\<user>\.codex\.sandbox-bin failed:
-SetNamedSecurityInfoW sandbox dir failed: 5
-```
-
-错误码 5 是 Windows `ACCESS_DENIED`。常见原因是 `.sandbox-bin` 归 `BUILTIN\Administrators` 所有，而当前普通用户只有 `Modify`，没有修改 DACL 所需的 `WRITE_DAC`。Codex 的日常 sandbox refresh 不会请求 UAC，因此无法自行修复这个状态。
-
-### `unelevated` 无法执行 deny-read
-
-```text
-windows unelevated restricted-token sandbox cannot enforce deny-read restrictions directly;
-refusing to run unsandboxed
-```
-
-这不是同一个错误。EvolCore 会为托管 Agent 注入 deny-read 限制；Windows 的 `unelevated` backend 无法实施这些限制并会 fail closed。因此不要把下面的配置当作修复：
-
-```toml
-[windows]
-sandbox = "unelevated"
-```
-
-需要 deny-read 时应继续使用：
-
-```toml
-[windows]
-sandbox = "elevated"
-```
-
-这里的 `elevated` 指 sandbox provisioning 能通过 UAC 建立受限账户和 ACL，不表示 Desktop 或 EvolCore 必须一直以管理员运行。
-
-## 先确认错误属于哪一层
-
-在普通 PowerShell 中执行：
-
-```powershell
-codex --version
-codex doctor --json
-whoami /groups
-
-$sandboxBin = Join-Path $env:USERPROFILE '.codex\.sandbox-bin'
-Get-Item -LiteralPath $sandboxBin -Force |
-  Select-Object FullName, Attributes, LinkType
-Get-Acl -LiteralPath $sandboxBin |
-  Select-Object Owner, AreAccessRulesProtected, Sddl
-```
-
-同时检查：
-
-```powershell
-Get-Content (Join-Path $env:USERPROFILE '.codex\.sandbox\setup_error.json')
-Get-Content (Join-Path $env:USERPROFILE '.codex\.sandbox\setup_marker.json')
-Get-Content (Join-Path $env:USERPROFILE '.codex\.sandbox\sandbox.*.log') -Tail 80
-```
-
-注意以下边界：
-
-| 现象 | 所属层 | 处理方向 |
-|------|--------|----------|
-| `helper_sandbox_lock_failed` / `SetNamedSecurityInfoW ... 5` | Codex sandbox ACL | 重新 provisioning 或修复 `.sandbox-bin` owner |
-| `unelevated ... cannot enforce deny-read` | Codex sandbox 模式 | 使用 `windows.sandbox = "elevated"` |
-| `connect EPERM \\.\pipe\daemon-*` | EvolCore IPC | 让 daemon 与 CLI 使用相同用户和完整性级别 |
-| sandbox 已启动，随后出现 `POLICY_DENIED` | EvolCore 角色/权限策略 | 检查任务发起者角色和 permission mode |
-
-共享同一个项目目录或同一个 `CODEX_HOME` 本身不是错误。关键是宿主进程的完整性级别一致，以及 sandbox 基础 ACL 已正确 provisioning。
-
-## 推荐修复：重新执行 elevated provisioning
-
-1. 结束正在启动的 Codex Agent 任务，保留 Codex Desktop 和 EvolCore 的普通权限运行方式。
-2. 将 Codex Desktop 与独立安装的 Codex CLI 更新到兼容版本，避免两个版本交替刷新同一 `CODEX_HOME`。
-3. 在 Codex Desktop 的 Windows Sandbox 设置中执行 setup/repair，选择 elevated backend，并接受一次 UAC 提示。对应的 app-server 操作为 `windowsSandbox/setupStart`，模式为 `elevated`；普通用户不应自行拼接内部 RPC。
-4. provisioning 完成后关闭管理员窗口。后续 Desktop、EvolCore daemon 和 `ec` CLI 均以普通用户运行。
-5. 在普通 PowerShell 中执行验证命令。
-
-```powershell
-codex doctor --json
-codex sandbox -- cmd /c whoami
-```
-
-验收结果应满足：
-
-- `codex doctor` 中 sandbox backend 为 `elevated`，provisioning 为 `complete`，没有 `helper_sandbox_lock_failed`。
-- `codex sandbox -- cmd /c whoami` 成功，身份是专用 sandbox 用户（例如 `CodexSandboxOffline` 或 `CodexSandboxOnline`），而不是当前桌面用户。
-- 普通权限 EvolCore 任务可以进入模型执行阶段。
-
-如果 setup/repair 仍反复失败，优先使用 Codex 的修复或重新安装流程。不要先清空整个 `.codex`，其中包含会话、认证和其他用户数据。
-
-## 已验证的定向 workaround
-
-仅当官方 repair 无法完成、错误明确为 `.sandbox-bin` owner/DACL 不一致时使用。此方法只修复目录 owner，不递归改文件权限，也不删除或放宽现有 DACL。
-
-先在普通 PowerShell 中确认目标是实体目录而非重解析点：
-
-```powershell
-$sandboxBin = Join-Path $env:USERPROFILE '.codex\.sandbox-bin'
-$item = Get-Item -LiteralPath $sandboxBin -Force
-if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) {
-  throw "$sandboxBin is a reparse point; stop and inspect it manually"
-}
-Get-Acl -LiteralPath $sandboxBin | Format-List Owner, Sddl
-```
-
-然后只为下面一次操作打开管理员 PowerShell：
-
-```powershell
-$sandboxBin = Join-Path $env:USERPROFILE '.codex\.sandbox-bin'
-$currentUser = [Security.Principal.WindowsIdentity]::GetCurrent().Name
-$acl = Get-Acl -LiteralPath $sandboxBin
-$acl.SetOwner([Security.Principal.NTAccount]::new($currentUser))
-Set-Acl -LiteralPath $sandboxBin -AclObject $acl
-```
-
-关闭管理员 PowerShell，在普通 PowerShell 中重新运行：
-
-```powershell
-codex sandbox -- cmd /c whoami
-codex doctor --json
-```
-
-本 workaround 已验证可以让普通权限 refresh 越过 `SetNamedSecurityInfoW ... 5`，但它不是替代官方 provisioning 的长期安装流程。Codex 更新或 repair 可能重新设置 owner；若问题复发，应保留 `doctor` 输出和 sandbox 日志并反馈给 Codex，而不是持续扩大 ACL。
-
-## 禁止采用的规避方式
-
-- 不要给 `Everyone`、`Users` 或 `CodexSandboxUsers` 授予 `FullControl`、`WRITE_DAC` 或 `WRITE_OWNER`。
-- 不要删除 `.codex` 父目录上的 deny ACL；这些规则可能正是 deny-read 隔离的一部分。
-- 不要关闭 sandbox 或使用危险绕过参数来运行不受信任的 Agent 任务。
-- 不要让 EvolCore daemon 长期管理员运行而 CLI 保持普通权限；这会造成命名管道 `EPERM`。
-- 不要仅凭 `ec status` 中 PID 存活判断系统健康；还要确认 IPC 和实际 Agent 任务都能运行。
-
-## EvolCore 侧最终验证
-
-```powershell
-ec status
-ec agent reload <agent-aid> --format json
-```
-
-然后从一个普通 AID 向目标 Agent 发送最小测试任务。观察 daemon 日志时，正确顺序应是：sandbox 初始化成功、Codex thread 启动、任务进入工具/模型执行。若此后出现 `POLICY_DENIED`，说明 sandbox 已恢复，下一步应修复 EvolCore 的角色或任务权限，而不是继续修改 Windows ACL。
+# Windows 上的 Codex Sandbox 权限排障
+
+本文适用于 EvolCore 在 Windows 上调用 Codex 时，任务在启动阶段因 sandbox 权限失败的情况。目标运行方式是：Codex Desktop、EvolCore daemon 和 `ec` CLI 均以普通用户运行；只有 Codex sandbox 的安装或修复过程临时通过 UAC 提权。
+
+不要为了绕过 sandbox 错误而长期以管理员身份运行全部组件。这样不仅扩大权限，还可能使高完整性 daemon 创建的命名管道拒绝普通权限 `ec` CLI 连接。
+
+## 典型错误
+
+### `.sandbox-bin` 无法锁定
+
+```text
+helper_sandbox_lock_failed: lock sandbox bin dir C:\Users\<user>\.codex\.sandbox-bin failed:
+SetNamedSecurityInfoW sandbox dir failed: 5
+```
+
+错误码 5 是 Windows `ACCESS_DENIED`。常见原因是 `.sandbox-bin` 归 `BUILTIN\Administrators` 所有，而当前普通用户只有 `Modify`，没有修改 DACL 所需的 `WRITE_DAC`。Codex 的日常 sandbox refresh 不会请求 UAC，因此无法自行修复这个状态。
+
+### `unelevated` 无法执行 deny-read
+
+```text
+windows unelevated restricted-token sandbox cannot enforce deny-read restrictions directly;
+refusing to run unsandboxed
+```
+
+这不是同一个错误。EvolCore 会为托管 Agent 注入 deny-read 限制；Windows 的 `unelevated` backend 无法实施这些限制并会 fail closed。因此不要把下面的配置当作修复：
+
+```toml
+[windows]
+sandbox = "unelevated"
+```
+
+需要 deny-read 时应继续使用：
+
+```toml
+[windows]
+sandbox = "elevated"
+```
+
+这里的 `elevated` 指 sandbox provisioning 能通过 UAC 建立受限账户和 ACL，不表示 Desktop 或 EvolCore 必须一直以管理员运行。
+
+## 先确认错误属于哪一层
+
+在普通 PowerShell 中执行：
+
+```powershell
+codex --version
+codex doctor --json
+whoami /groups
+
+$sandboxBin = Join-Path $env:USERPROFILE '.codex\.sandbox-bin'
+Get-Item -LiteralPath $sandboxBin -Force |
+  Select-Object FullName, Attributes, LinkType
+Get-Acl -LiteralPath $sandboxBin |
+  Select-Object Owner, AreAccessRulesProtected, Sddl
+```
+
+同时检查：
+
+```powershell
+Get-Content (Join-Path $env:USERPROFILE '.codex\.sandbox\setup_error.json')
+Get-Content (Join-Path $env:USERPROFILE '.codex\.sandbox\setup_marker.json')
+Get-Content (Join-Path $env:USERPROFILE '.codex\.sandbox\sandbox.*.log') -Tail 80
+```
+
+注意以下边界：
+
+| 现象 | 所属层 | 处理方向 |
+|------|--------|----------|
+| `helper_sandbox_lock_failed` / `SetNamedSecurityInfoW ... 5` | Codex sandbox ACL | 重新 provisioning 或修复 `.sandbox-bin` owner |
+| `unelevated ... cannot enforce deny-read` | Codex sandbox 模式 | 使用 `windows.sandbox = "elevated"` |
+| `connect EPERM \\.\pipe\daemon-*` | EvolCore IPC | 让 daemon 与 CLI 使用相同用户和完整性级别 |
+| sandbox 已启动，随后出现 `POLICY_DENIED` | EvolCore 角色/权限策略 | 检查任务发起者角色和 permission mode |
+
+共享同一个项目目录或同一个 `CODEX_HOME` 本身不是错误。关键是宿主进程的完整性级别一致，以及 sandbox 基础 ACL 已正确 provisioning。
+
+## 推荐修复：重新执行 elevated provisioning
+
+1. 结束正在启动的 Codex Agent 任务，保留 Codex Desktop 和 EvolCore 的普通权限运行方式。
+2. 将 Codex Desktop 与独立安装的 Codex CLI 更新到兼容版本，避免两个版本交替刷新同一 `CODEX_HOME`。
+3. 在 Codex Desktop 的 Windows Sandbox 设置中执行 setup/repair，选择 elevated backend，并接受一次 UAC 提示。对应的 app-server 操作为 `windowsSandbox/setupStart`，模式为 `elevated`；普通用户不应自行拼接内部 RPC。
+4. provisioning 完成后关闭管理员窗口。后续 Desktop、EvolCore daemon 和 `ec` CLI 均以普通用户运行。
+5. 在普通 PowerShell 中执行验证命令。
+
+```powershell
+codex doctor --json
+codex sandbox -- cmd /c whoami
+```
+
+验收结果应满足：
+
+- `codex doctor` 中 sandbox backend 为 `elevated`，provisioning 为 `complete`，没有 `helper_sandbox_lock_failed`。
+- `codex sandbox -- cmd /c whoami` 成功，身份是专用 sandbox 用户（例如 `CodexSandboxOffline` 或 `CodexSandboxOnline`），而不是当前桌面用户。
+- 普通权限 EvolCore 任务可以进入模型执行阶段。
+
+如果 setup/repair 仍反复失败，优先使用 Codex 的修复或重新安装流程。不要先清空整个 `.codex`，其中包含会话、认证和其他用户数据。
+
+## 已验证的定向 workaround
+
+仅当官方 repair 无法完成、错误明确为 `.sandbox-bin` owner/DACL 不一致时使用。此方法只修复目录 owner，不递归改文件权限，也不删除或放宽现有 DACL。
+
+先在普通 PowerShell 中确认目标是实体目录而非重解析点：
+
+```powershell
+$sandboxBin = Join-Path $env:USERPROFILE '.codex\.sandbox-bin'
+$item = Get-Item -LiteralPath $sandboxBin -Force
+if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) {
+  throw "$sandboxBin is a reparse point; stop and inspect it manually"
+}
+Get-Acl -LiteralPath $sandboxBin | Format-List Owner, Sddl
+```
+
+然后只为下面一次操作打开管理员 PowerShell：
+
+```powershell
+$sandboxBin = Join-Path $env:USERPROFILE '.codex\.sandbox-bin'
+$currentUser = [Security.Principal.WindowsIdentity]::GetCurrent().Name
+$acl = Get-Acl -LiteralPath $sandboxBin
+$acl.SetOwner([Security.Principal.NTAccount]::new($currentUser))
+Set-Acl -LiteralPath $sandboxBin -AclObject $acl
+```
+
+关闭管理员 PowerShell，在普通 PowerShell 中重新运行：
+
+```powershell
+codex sandbox -- cmd /c whoami
+codex doctor --json
+```
+
+本 workaround 已验证可以让普通权限 refresh 越过 `SetNamedSecurityInfoW ... 5`，但它不是替代官方 provisioning 的长期安装流程。Codex 更新或 repair 可能重新设置 owner；若问题复发，应保留 `doctor` 输出和 sandbox 日志并反馈给 Codex，而不是持续扩大 ACL。
+
+## 禁止采用的规避方式
+
+- 不要给 `Everyone`、`Users` 或 `CodexSandboxUsers` 授予 `FullControl`、`WRITE_DAC` 或 `WRITE_OWNER`。
+- 不要删除 `.codex` 父目录上的 deny ACL；这些规则可能正是 deny-read 隔离的一部分。
+- 不要关闭 sandbox 或使用危险绕过参数来运行不受信任的 Agent 任务。
+- 不要让 EvolCore daemon 长期管理员运行而 CLI 保持普通权限；这会造成命名管道 `EPERM`。
+- 不要仅凭 `ec status` 中 PID 存活判断系统健康；还要确认 IPC 和实际 Agent 任务都能运行。
+
+## EvolCore 侧最终验证
+
+```powershell
+ec status
+ec agent reload <agent-aid> --format json
+```
+
+然后从一个普通 AID 向目标 Agent 发送最小测试任务。观察 daemon 日志时，正确顺序应是：sandbox 初始化成功、Codex thread 启动、任务进入工具/模型执行。若此后出现 `POLICY_DENIED`，说明 sandbox 已恢复，下一步应修复 EvolCore 的角色或任务权限，而不是继续修改 Windows ACL。