evolcore 0.0.21 → 0.0.23

package/dist/utils/tool-summary.js

@@ -5,6 +5,65 @@
  * Edit 工具的摘要为 diff 风格预览（支持 old/new_string 与 unified diff 两种输入）。
  */
 import fs from 'fs';
+import { parseLiteralShellArgv, resolveCodexShellCarrierString, } from '../core/permission/ec-command-parser.js';
+const DISPLAY_POSIX_SHELLS = new Set(['bash', 'sh']);
+const DISPLAY_POWERSHELLS = new Set(['pwsh', 'pwsh.exe', 'powershell', 'powershell.exe']);
+const DISPLAY_CMD_SHELLS = new Set(['cmd', 'cmd.exe']);
+const DISPLAY_CMD_INERT_SWITCHES = new Set(['/d', '/s', '/q', '/a', '/u']);
+function executableBasename(value) {
+    if (typeof value !== 'string')
+        return '';
+    return value.replaceAll('\\', '/').split('/').at(-1)?.toLowerCase() ?? '';
+}
+/** Display-only fallback for valid Codex carriers installed outside standard paths. */
+function summarizeDisplayCarrierArgv(argv) {
+    if (argv.length === 3) {
+        const executable = executableBasename(argv[0]);
+        const switchName = argv[1]?.toLowerCase();
+        if (DISPLAY_POSIX_SHELLS.has(executable) && switchName === '-lc')
+            return argv[2];
+        if (DISPLAY_POWERSHELLS.has(executable) && switchName === '-command')
+            return argv[2];
+    }
+    if (argv.length >= 3 && DISPLAY_CMD_SHELLS.has(executableBasename(argv[0]))) {
+        const executeIndex = argv.slice(1, -1).findIndex(value => value.toLowerCase() === '/c');
+        if (executeIndex >= 0 && executeIndex + 1 === argv.length - 2) {
+            const switches = argv.slice(1, executeIndex + 1);
+            if (switches.every(value => DISPLAY_CMD_INERT_SWITCHES.has(value.toLowerCase()))) {
+                return argv.at(-1);
+            }
+        }
+    }
+    return undefined;
+}
+/** Remove Codex app-server's fixed shell carrier from display-only arguments. */
+function displayShellCommand(command) {
+    if (typeof command !== 'string' || !command)
+        return undefined;
+    const parsedArgv = parseLiteralShellArgv(command);
+    const display = parsedArgv ? summarizeDisplayCarrierArgv(parsedArgv) : undefined;
+    if (display !== undefined)
+        return display;
+    // The nested PowerShell body is not POSIX shell syntax and can contain
+    // quotes, variables, redirects, and statement composition. Use the strict
+    // carrier parser only for PowerShell commands that the argv projection
+    // cannot parse; ordinary `bash -c` commands must remain unchanged.
+    const carrier = resolveCodexShellCarrierString(command);
+    return carrier?.dialect === 'powershell' ? carrier.command : undefined;
+}
+/**
+ * Build the tool arguments projected into activity/thought payloads.
+ * Execution, permission checks, and audit logging keep using the original
+ * input; only the human-facing Shell command is de-wrapped here.
+ */
+export function toolInputForDisplay(toolName, input) {
+    if (!input || toolName !== 'Shell')
+        return input;
+    const command = displayShellCommand(input.command);
+    if (!command || command === input.command)
+        return input;
+    return { ...input, command };
+}
 /**
  * 工具输入摘要（提取工具调用的可读描述，供权限审批和消息展示使用）
  */

package/dist/utils/windows-shell-trust.js

@@ -0,0 +1,201 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+const MAX_CACHE_ENTRIES = 128;
+const signatureCache = new Map();
+/**
+ * The signer name is checked only after Authenticode reports a trusted chain.
+ * Keep this list deliberately small: an unsigned or unknown Bash distribution
+ * must not enter the privileged EC command path.
+ */
+const MICROSOFT_PUBLISHER_RE = /(?:^|[,;]\s*)CN=Microsoft (?:Corporation|Windows(?: [^,;]+)?)(?:[,;]|$)/i;
+const MICROSOFT_ORG_RE = /(?:^|[,;]\s*)O=Microsoft Corporation(?:[,;]|$)/i;
+const BASH_PUBLISHER_RES = [
+    /(?:^|[,;]\s*)(?:CN|O)=Git for Windows(?:[,;]|$)/i,
+    /(?:^|[,;]\s*)(?:CN|O)=The Git Development Community(?:[,;]|$)/i,
+    // Git for Windows binaries are currently signed by project maintainer
+    // Johannes Schindelin rather than a certificate named after the project.
+    /(?:^|[,;]\s*)(?:CN|O)=Johannes Schindelin(?:[,;]|$)/i,
+    /(?:^|[,;]\s*)(?:CN|O)=Red Hat,? Inc\.(?:[,;]|$)/i,
+    /(?:^|[,;]\s*)(?:CN|O)=MSYS2(?:[,;]|$)/i,
+];
+function isValidStatus(status) {
+    return typeof status === 'string' && status.trim().toLowerCase() === 'valid';
+}
+/** Pure signature policy, separately testable without a Windows host. */
+export function isTrustedShellSignature(kind, evidence) {
+    if (!isValidStatus(evidence.status) || typeof evidence.subject !== 'string')
+        return false;
+    const subject = evidence.subject.trim();
+    if (kind === 'cmd' || kind === 'powershell') {
+        return MICROSOFT_PUBLISHER_RE.test(subject) && MICROSOFT_ORG_RE.test(subject);
+    }
+    return (MICROSOFT_PUBLISHER_RE.test(subject) && MICROSOFT_ORG_RE.test(subject))
+        || BASH_PUBLISHER_RES.some(pattern => pattern.test(subject));
+}
+function windowsSystemRoot() {
+    return process.env.SystemRoot || process.env.WINDIR || 'C:\\Windows';
+}
+function systemPowerShellPath() {
+    return path.win32.join(windowsSystemRoot(), 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');
+}
+function systemPowerShellModulePath() {
+    return path.win32.join(windowsSystemRoot(), 'System32', 'WindowsPowerShell', 'v1.0', 'Modules');
+}
+/**
+ * Windows PowerShell 5.1 must load its own Security module. A caller's
+ * PSModulePath can put PowerShell 7's module ahead of it; that module is not
+ * compatible with 5.1 and makes Get-AuthenticodeSignature fail to load.
+ */
+function systemPowerShellEnvironment() {
+    const env = { ...process.env };
+    for (const key of Object.keys(env)) {
+        if (key.toLowerCase() === 'psmodulepath')
+            delete env[key];
+    }
+    env.PSModulePath = systemPowerShellModulePath();
+    return env;
+}
+function systemWherePath() {
+    return path.win32.join(windowsSystemRoot(), 'System32', 'where.exe');
+}
+function isAbsoluteWindowsPath(value) {
+    return path.win32.isAbsolute(value) || /^\\\\[^\\/]+[\\/][^\\/]+/.test(value);
+}
+function resolveBareShellExecutable(executable, kind) {
+    const name = executable.toLowerCase().replace(/\.exe$/i, '');
+    if (kind === 'cmd' && name === 'cmd') {
+        return path.win32.join(windowsSystemRoot(), 'System32', 'cmd.exe');
+    }
+    if (kind === 'powershell' && name === 'powershell') {
+        return systemPowerShellPath();
+    }
+    const result = spawnSync(systemWherePath(), [`${name}.exe`], {
+        encoding: 'utf8',
+        timeout: 3000,
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (result.status !== 0)
+        return undefined;
+    const first = String(result.stdout || '')
+        .split(/\r?\n/)
+        .map(line => line.trim())
+        .find(Boolean);
+    return first || undefined;
+}
+function resolveShellPath(executable, kind) {
+    if (!executable)
+        return undefined;
+    // Codex can keep its POSIX carrier spelling on Windows (for example
+    // `/bin/bash`). It is a logical shell name, not a Windows root-relative
+    // filesystem path, so resolve it through the trusted Windows PATH lookup.
+    if (executable.startsWith('/') && !executable.startsWith('//')) {
+        const basename = path.posix.basename(executable);
+        return resolveBareShellExecutable(basename, kind);
+    }
+    if (isAbsoluteWindowsPath(executable))
+        return executable;
+    return resolveBareShellExecutable(executable, kind);
+}
+function isAppExecutionAliasPath(value) {
+    return /[\\/]AppData[\\/]Local[\\/]Microsoft[\\/]WindowsApps[\\/]/i.test(value);
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "''")}'`;
+}
+function probeAuthenticode(filePath) {
+    const script = [
+        '$ErrorActionPreference = "Stop"',
+        `$p = ${shellQuote(filePath)}`,
+        '$item = Get-Item -LiteralPath $p -Force',
+        'if ($item.PSIsContainer) { exit 17 }',
+        '$sig = Get-AuthenticodeSignature -LiteralPath $item.FullName',
+        '[pscustomobject]@{',
+        '  status = [string]$sig.Status',
+        '  subject = if ($sig.SignerCertificate) { [string]$sig.SignerCertificate.Subject } else { "" }',
+        '  issuer = if ($sig.SignerCertificate) { [string]$sig.SignerCertificate.Issuer } else { "" }',
+        '} | ConvertTo-Json -Compress',
+    ].join('\n');
+    const result = spawnSync(systemPowerShellPath(), [
+        '-NoLogo', '-NoProfile', '-NonInteractive', '-Command', script,
+    ], {
+        encoding: 'utf8',
+        env: systemPowerShellEnvironment(),
+        timeout: 5000,
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'ignore'],
+    });
+    if (result.status !== 0 || result.error || !String(result.stdout || '').trim())
+        return undefined;
+    try {
+        const parsed = JSON.parse(String(result.stdout));
+        return {
+            status: typeof parsed.status === 'string' ? parsed.status : undefined,
+            subject: typeof parsed.subject === 'string' ? parsed.subject : undefined,
+            issuer: typeof parsed.issuer === 'string' ? parsed.issuer : undefined,
+        };
+    }
+    catch {
+        return undefined;
+    }
+}
+function cacheKey(filePath) {
+    try {
+        return fs.realpathSync.native(filePath).toLowerCase();
+    }
+    catch {
+        return filePath.replaceAll('\\', '/').toLowerCase();
+    }
+}
+/**
+ * Verify the concrete executable selected by Codex. Non-Windows callers keep
+ * the existing parser behavior; only Windows enters the Authenticode path.
+ */
+export function isTrustedWindowsShellExecutable(executable, kind) {
+    if (process.platform !== 'win32')
+        return true;
+    const resolved = resolveShellPath(executable, kind);
+    if (!resolved)
+        return false;
+    let finalPath = resolved;
+    try {
+        finalPath = fs.realpathSync.native(resolved);
+    }
+    catch {
+        // Keep the original path for the signature probe; the stat/probe below
+        // will fail closed if the executable is not accessible.
+    }
+    // If realpath could not escape an App Execution Alias, do not authenticate
+    // the alias stub itself. A resolved WindowsApps package binary is allowed
+    // and is checked below like any other signed executable.
+    if (isAppExecutionAliasPath(finalPath))
+        return false;
+    let stat;
+    try {
+        stat = fs.statSync(finalPath);
+        if (!stat.isFile())
+            return false;
+    }
+    catch {
+        return false;
+    }
+    const key = cacheKey(finalPath);
+    const previous = signatureCache.get(key);
+    if (previous && previous.size === stat.size && previous.mtimeMs === stat.mtimeMs) {
+        return previous.trusted;
+    }
+    const trusted = isTrustedShellSignature(kind, probeAuthenticode(finalPath) ?? {});
+    signatureCache.set(key, { size: stat.size, mtimeMs: stat.mtimeMs, trusted });
+    while (signatureCache.size > MAX_CACHE_ENTRIES) {
+        const oldest = signatureCache.keys().next().value;
+        if (!oldest)
+            break;
+        signatureCache.delete(oldest);
+    }
+    return trusted;
+}
+/** Test hook: clear cached signature decisions after a fixture is replaced. */
+export function clearWindowsShellTrustCache() {
+    signatureCache.clear();
+}

package/kits/docs/evolcore/INDEX.md

@@ -29,14 +29,15 @@
 | 命令集 | 用途 | 触发词 | 适用场景 | 文档 |
 |--------|------|--------|----------|------|
 | `ec msg` | 私聊收发消息 | 回复/发消息/拉取/撤回/查在线 | 有对端（peerId） | `msg.md` |
-| `ec group` | 群聊收发与群管理 | 群发/建群/邀请/踢人/退群/群成员/角色/封禁/规则 | 群聊（groupId） | `group.md` |
+| `ec group` | 群聊收发与群管理 | 群发/建群/邀请/踢人/退群/群成员/角色/封禁/规则/协作 | 群聊（groupId） | `group.md`；完整协作流程见 `group-collaboration.md` |
 | `ec group rules` | 群规则文件发布与上下文注入 | 群规则/工作流程/职责分工/rules.md/发布规则 | AUN 群聊（groupId） | `group-rules.md` |
 | `ec aid` | AID 身份管理 | 身份/证书/名片/探测对端 | 任意有渠道场景 | `aid.md` |
 | `ec fs` | AUN 文件系统统一入口 | 上传/下载/看文件/列目录/删文件/配额/群空间 | 任意有渠道场景 | `fs.md` |
 | `ec storage` | 文件存储底层调试入口 | storage 调试/旧命令/底层上传下载 | 任意有渠道场景 | `storage.md` |
-| `ec agent` | EvolAgent 生命周期 | 创建/启停/热重载/改配置 | 管理员（owner/admin） | `agent.md` |
+| `ec agent` | EvolAgent 生命周期 | 创建/启停/热重载/改配置 | 管理员（owner/admin） | `agent.md`；完整创建与 Bootstrap 见 `agent-create.md` |
 | `ec contact` | Contact Book 与访问控制 | 申请添加、拉黑/解除拉黑、查拉黑 | Agent 当前私聊可申请添加；管理写操作按角色限制 | `contact.md` |
 | `ec rpc` | 底层 AUN RPC（逃生通道） | 直接调协议方法 | 高级/兜底 | `rpc.md` |
+| `ec menu-client` | 远程 Daemon Menu 请求 | 远程诊断/daemon 日志/监控/原始配置 | 非托管 eclink/运维主机 | `menu-client.md` |
 
 ## 会话自管理类（不连 AUN，操作当前会话）
 

package/kits/docs/evolcore/agent-create.md

@@ -0,0 +1,159 @@
+# 创建 EvolAgent：从创建到 Bootstrap 完成
+
+本手册用于创建一个能正常工作的 EvolAgent。创建者负责创建和观察状态；新 Agent 在自己的 Bootstrap 会话中完成首次设定。不要把创建流水线完成误认为 Agent 已激活。
+
+### AID 与 Owner 约定
+
+- AID 必须是 `{name}.{issuer}`，例如 `helper.agentid.cn`；不要使用四级域名（如 `helper.team.agentid.cn`），也不要把显示名当作 AID。
+- `--owner` 填写需求提出者或实际责任 Owner 的完整 AID，而不是默认填写当前执行者。创建者只是代办创建流程时，仍应保留需求提出者的 Owner 权限。
+
+## 生命周期与完成标准
+
+```text
+ec agent new
+    ↓
+created
+    ↓ channel 可以联系 Owner，或 Owner 首次入站
+bootstrapping
+    ↓ 新 Agent 发布 agent.md，并执行 ec agent ready
+active
+```
+
+只有 `lifecycle=active` 才表示 Agent 已完成创建流程并可正常处理普通任务。
+
+## 1. 创建者创建 Agent
+
+多个 Agent 必须串行创建和观察。不要并行启动多个 `ec agent new`：证书、热加载和 Bootstrap 会竞争连接与资源，容易造成超时、锁等待或把失败误判为未创建。
+
+在独立终端可以使用交互模式：
+
+```bash
+ec agent new helper.agentid.pub
+```
+
+在 EvolCore 托管 Agent 会话等自动化环境中，必须使用非交互模式：
+
+```bash
+ec agent new helper.agentid.pub --non-interactive \
+  --project /home/user/helper-project \
+  --baseagent codex \
+  --owner owner.agentid.pub \
+  --name "Helper" \
+  --description "协助处理项目开发任务"
+```
+
+建议先用 dry-run 检查最终参数：
+
+```bash
+ec agent new helper.agentid.pub --non-interactive \
+  --project /home/user/helper-project \
+  --baseagent codex \
+  --owner owner.agentid.pub \
+  --name "Helper" \
+  --description "协助处理项目开发任务" \
+  --dry-run --format json
+```
+
+创建时会注册 AID、写入 Agent 配置、生成并尝试发布初始 `agent.md`，然后尝试热加载。配置写盘时 `lifecycle` 初始为 `created`；channel 很快触发 Bootstrap 时，查询结果也可能已经是 `bootstrapping`：
+
+```bash
+ec agent get helper.agentid.pub lifecycle
+ec agent show helper.agentid.pub
+```
+
+如果是 menu 创建，`accepted=true` 只表示请求已受理。继续轮询 `createProgress.status` 直到 `ready` 或 `failed`。这里的 `createProgress.status=ready` **只表示后台创建流水线结束，不等于 `lifecycle=active`**。
+
+创建者应维护一个最小状态账本（可放在当前任务记录中），每个 Agent 至少记录：`aid`、需求 Owner、项目路径、创建请求是否受理、`createProgress.status`、`lifecycle`、本地 `agent.md` 是否存在/字段是否完整、名片是否已发布、最近错误、下一步和最后检查时间。重启或超时恢复时先按账本逐项核对实际状态，再决定续做，不按“上次命令是否返回”推断结果。
+
+## 2. 触发 Bootstrap
+
+当任一已启用 channel 可以联系 Owner 时，系统会向 Owner 发送固定的 Bootstrap 首条消息，并把生命周期从 `created` 切换为 `bootstrapping`。
+
+部分 channel 不能在连接时主动定位 Owner。这种情况下 Agent 会保持 `created`；Owner 需要先在该 channel 向新 Agent 发送一条消息，系统获得回复上下文后再启动 Bootstrap。
+
+`created` 状态下 Base Agent 不处理普通消息。`bootstrapping` 状态下只加载 Bootstrap 专属提示词，不加载正常的 ECK 规则、人格、记忆或命令能力卡。
+
+## 3. Owner 与新 Agent 确认名片信息
+
+以下步骤发生在**新 Agent 自己的 Bootstrap 会话**中，不由创建者代替执行。
+
+新 Agent 先读取系统注入路径指向的本地 `agent.md`，把其中格式有效的字段作为现有候选值：
+
+- `name`：简短清晰的显示名
+- `description`：一句到两句话描述职责或定位
+- `tags`：3 到 6 个非空标签
+
+交互规则：
+
+1. 已有有效值时，新 Agent 简短回显并询问保持还是修改，不要求 Owner 重新输入。
+2. 空值、占位值或格式错误的字段按缺失处理；`tags` 不足 3 个或超过 6 个也不合格。
+3. 只有 Owner 明确提供、修改、选择或确认的内容才可作为最终值。不得从普通任务、示例文字或顺带提及的内容中推断。
+4. 信息缺失、冲突或含义不清时，只追问对应部分，保留此前已明确的内容。
+5. 三项齐全后，新 Agent 必须回显整组最终值，并再次请求 Owner 明确确认。
+
+例如，Owner 可以回复：
+
+```text
+名称用 Helper；简介是“协助维护和开发项目”；标签用 coding、maintenance、typescript。请按这些值设置。
+```
+
+新 Agent 应回显这三个最终值并等待确认。Owner 再明确回复“确认”后，才能修改和发布名片。
+
+Bootstrap 完成前，新 Agent 不处理普通任务，也不执行与本流程无关的工具或命令。如果 Owner 要求跳过、先工作或同时交办普通任务，新 Agent 应说明必须先完成首次设定，并继续确认缺失字段。
+
+## 4. 新 Agent 修改并发布自己的 agent.md
+
+Owner 明确确认最终值后，新 Agent 才能编辑系统提示词中 `agentMdPath` 指向的本地文件，并且：
+
+- 只修改 YAML frontmatter 中的 `name`、`description`、`tags`。
+- 保留其他 frontmatter 字段、Markdown 正文和文件结构。
+- 修改后检查 YAML 合法，且三个字段满足上述格式要求。
+
+然后由新 Agent 使用自己的 AID 签名并发布：
+
+```bash
+ec aid agentmd put helper.agentid.pub
+```
+
+只有命令明确成功后才能继续。若发布失败，不得执行 `ready`；应向 Owner 说明具体错误，修正后再继续，不要盲目重复。
+
+## 5. 新 Agent 完成 Bootstrap
+
+发布成功后，新 Agent 执行整个 Bootstrap 的最后一个操作：
+
+```bash
+ec agent ready helper.agentid.pub
+```
+
+托管任务只能对自身 AID 执行 `ready`，不能替其他 Agent 完成 Bootstrap。只有处于 `bootstrapping` 时，`ready` 才会完成状态切换；仍为 `created` 时会失败，已经是 `active` 时重复调用则保持 `active`。
+
+`ready` 成功后，系统会：
+
+1. 将 `lifecycle` 切换为 `active`。
+2. 结束当前 Bootstrap 上下文。
+3. 创建全新的主会话。
+4. 发送正式欢迎消息。
+
+新 Agent 在 `ready` 成功后不要从旧 Bootstrap 上下文再输出一段完成说明，也不要继续处理先前夹带的普通任务；后续工作从新主会话开始。
+
+## 6. 创建者验收
+
+```bash
+ec agent get helper.agentid.pub lifecycle
+# 应输出 active
+
+ec agent show helper.agentid.pub
+```
+
+验证其它 Agent 的生命周期、配置和创建进度统一使用 `ec agent get/show/list`；`ec aid` 只用于身份、证书和名片操作，不要用 `ec aid` 代替 Agent 状态验证。
+
+验收标准：
+
+- `lifecycle` 为 `active`。
+- `agent.md` 已成功签名发布。
+- 系统已创建新的主会话并发送正式欢迎消息。
+- 新 Agent 能在新主会话中处理普通任务。
+
+如果仍为 `created`，检查 channel 是否已能联系 Owner，必要时由 Owner 主动发送首条消息。如果仍为 `bootstrapping`，回到新 Agent 的 Bootstrap 会话完成字段确认、名片发布和 `ready`，不要由创建者直接绕过引导。
+
+失败重试前必须先执行状态检查：若本地 `agent.md` 已存在且远端名片已发布，只向该 Agent 发送 `ready`/续做指令，让它在自己的 Bootstrap 会话中完成收尾；不要重复创建、重复改名片或重复发布。仅在确认创建记录不存在且名片未发布时，才重新发起创建。

package/kits/docs/evolcore/agent.md

@@ -53,6 +53,12 @@ ec agent delete <aid> [--purge]
 - `--dry-run` 只输出最终创建计划，不注册 AID、不写配置、不上传 `agent.md`。
 - `--force` 覆盖已有 `config.json`；AID 密钥保留。
 
+## 创建 Agent
+
+`ec agent new` 成功不代表新 Agent 已能处理普通任务。新 Agent 还必须完成 Bootstrap，并由自身执行 `ec agent ready <aid>` 进入 `active`。
+
+完整的创建、Bootstrap、名片发布和验收示例见：`$KITS_DOCS/evolcore/agent-create.md`。
+
 ## 头像更新
 
 头像上传通过 menu 协议暴露，不是 `ec agent` CLI 子命令：