企业官网建设流程全解析

• AI 应用
• 人工智能
• AI Agent
• 本地部署
• 前端
• 后端
• 工作流自动化

本文聚焦 Ekko Agent（Ekko Studio 的 TypeScript Agent 运行时）内置的1passwordSkill，讲解如何借助官方opCLI 完成认证、秘密引用（secret reference）、命令注入（command injection）与安全配置模板化。读完本文，你将掌握三种认证模式的选用条件、六步标准工作流程、op run/op inject/op read的安全调用范式，以及一套"秘密永不进入模型上下文、终端输出、日志、聊天记录、shell 历史或提交文件"的硬性护栏，并理解这些规则在仓库源码层面的落地方式。

技能概览与加载机制

1passwordSkill 位于仓库的 packages/ekko-agent/skills/1password/，是一个以SKILL.md为入口、附带两份参考文档的完整技能包：

• SKILL.md：主文档，定义技能用途、标准工作流程、三种认证模式与安全护栏；
• references/get-started.md：前置条件、平台差异与连接行为说明；
• references/cli-examples.md：可复制的安全命令模式集。

每个 Skill 的SKILL.md使用 YAML frontmatter 声明元数据。1password技能的 frontmatter 如下：

--- name: 1password description: Set up and use 1Password CLI for authentication, secret references, command injection, and safe configuration templating. metadata: keywords: - op cli - secret injection - secret reference ---

从源码结构看，Ekko Agent 会按目录扫描并同步这些内置技能：EkkoDirectoryManager在 packages/ekko-agent/src/directories.ts 中通过synchronizeProfileSkills与checkProfileSkills将内置 Skill 目录同步到.ekko/skills下的 Profile 目录，判定条件是"目录内存在可读的SKILL.md"。Agent 侧则通过skill_view/skill_manage/skill_list等工具消费技能内容，AgentSkill类型（id、name、description、instructions）定义在 packages/ekko-agent/src/skills/types.ts，技能管理入口EkkoSkillManager.view()在 packages/ekko-agent/src/skills/manager.ts 中直接调用skill_view工具。

值得注意的还有运行时自动路由机制：在 packages/ekko-agent/src/runtime/runtime.ts，当模型消息命中技能关键词后，运行时会自动构造skill_view工具调用把匹配的SKILL.md内容注入后续上下文——也就是说，模型在对话中一旦谈到"注入秘密""op CLI"，1password技能的完整指令就会按需被加载，护栏随之生效。

核心原则：秘密永不进入模型上下文

技能的第一原则非常直白：优先采用"秘密永远不出现"的工作流。所谓不出现的位置包括五类：

1. 模型上下文（model context）；
2. 终端输出（terminal output）；
3. 日志（logs）；
4. 聊天记录（chat）；
5. shell 历史（shell history）以及提交进版本库的文件（committed file）。

所有后续的命令模式与护栏都是围绕这一原则展开的：不打印秘密、不把密码或一次性验证码发到聊天中、不用"打印秘密"来证明权限、注入文件默认持久化且有严格清理要求。

前置条件与平台差异

参考 references/get-started.md，使用前需确认以下条件：

• 平台支持：opCLI 支持 macOS、Windows、Linux；
• 桌面集成要求 1Password 订阅、桌面应用，且账户已解锁并登录；
• macOS：开启Settings > Developer > Integrate with 1Password CLI（Touch ID 可选）；
• Windows：先启用 Windows Hello，再开启Settings > Developer > Integrate with 1Password CLI；
• Linux：桌面集成依赖 PolKit 与认证代理。需在Settings > Security下启用系统认证，再在Settings > Developer下启用 CLI 集成；
• 多账号：配置了多个账户时，用--account或OP_ACCOUNT显式指定；
• 独立登录：可能需要先执行op account add添加账户。

关于连接行为的底层机制，文档明确指出：桌面集成使用每用户 IPC 通道——macOS 是 XPC，Linux 是 Unix-domain socket，Windows 是 named pipe。因此op必须直接在 Agent 的终端环境里运行，而 tmux 子 shell 可能无法继承对该通道的访问权。服务账户依赖OP_SERVICE_ACCOUNT_TOKEN，不依赖桌面 IPC；独立交互式登录会返回一个OP_SESSION_*环境变量导出，该变量只在执行并保留它的那个 shell 中有效。

标准工作流程

SKILL.md定义了六步标准流程，任何秘密消费操作之前都应走完：

1. 确认操作系统与 shell（决定认证方式与命令语法）；
2. 验证 CLI 存在且可用，不安装任何东西：op --version；
3. 识别当前认证模式：
   • 存在OP_SERVICE_ACCOUNT_TOKEN→ 服务账户，通常用于 CI 或无头环境；
   • 已启用 1Password 桌面集成 → 使用正在运行且已解锁的桌面应用；
   • 两者皆不满足 → 需要独立交互式登录；
4. 验证访问权限：在秘密消费操作前先执行op whoami；
5. 多账号场景使用--account或已配置的OP_ACCOUNT；
6. 优先op run或op inject；仅当输出可以被安全消费而不暴露时才用op read。

如果op不存在或认证未配置，技能要求：说明确切的前置条件，并指向官方 1Password CLI 文档。严禁静默安装 CLI、要求用户把密码或令牌粘贴进聊天、凭空捏造凭据、或在工具参数中放置秘密。

三种认证模式详解

服务账户（Service account）

服务账户由用户在对话之外、Agent 命令历史之外配置OP_SERVICE_ACCOUNT_TOKEN，Agent 不得打印或检查其值。验证方式：

op whoami op vault list

服务账户的访问权限仅限于其被授权的保险库（vault），且不依赖桌面应用。

桌面应用集成（Desktop app integration）

直接运行op，使其能够触达每用户桌面集成通道：

op vault list op whoami

第一次调用可能触发 Touch ID、Windows Hello 或系统认证。如果 CLI 无法连接，应请用户打开并解锁 1Password，确认 CLI 集成已启用。不要试图通过把该模式移入 tmux 来绕开通道问题——如前所述，tmux 子 shell 很可能访问不到每用户 IPC 通道。

独立交互式登录（Standalone interactive sign-in）

交互式登录会创建会话环境变量，该变量必须留在同一个 shell 中。在 macOS/Linux 上，仅当桌面集成与服务账户均不可用时，才使用私有 tmux 会话（使用前先阅读同仓库的 tmux Skill）。

SOCKET_DIR="${EKKO_TMUX_SOCKET_DIR:-${TMPDIR:-/tmp}/ekko-tmux-sockets}" mkdir -p "$SOCKET_DIR" chmod 700 "$SOCKET_DIR" SOCKET="$SOCKET_DIR/ekko-op.sock" SESSION="op-auth-$(date +%Y%m%d-%H%M%S)" tmux -S "$SOCKET" new -d -s "$SESSION" -n shell /bin/sh tmux -S "$SOCKET" send-keys -t "$SESSION":0.0 -- 'eval "$(op signin --account my.1password.com)"' Enter tmux -S "$SOCKET" capture-pane -t "$SESSION":0.0 -p -S - | tail -40

这段脚本的核心思路：用独立 socket 与按时间戳命名的会话，把op signin的交互过程与 Agent 主终端隔离，再通过capture-pane查看登录提示状态。技能强调：

• 在登录提示期间不要排队后续命令；
• 如果需要密码、MFA 挑战或账户选择，暂停并让用户本地完成——通过附加到指定 socket 和会话进行，绝不在聊天中索要密码或一次性验证码；
• 提示返回后，向同一 pane 发送op whoami，后续命令复用同一个SOCKET和SESSION；
• Windows 上优先桌面集成或服务账户；没有明确提供的持久会话机制时，不要把 POSIX tmux 流程机械翻译成 PowerShell。

配套的 tmux Skill 提供了会话发现与轮询脚本：find-sessions.sh 可发现包括自定义 socket 路径在内的会话，wait-for-text.sh 可持续轮询 pane 输出直到匹配某个模式（默认超时 15 秒、轮询间隔 0.5 秒、检查最近 1000 行历史，可用-T、-i、-l调整），适合等待op signin完成这类交互式流程。

安全命令模式

参考 references/cli-examples.md，以下是经技能认可的安全调用方式。

认证与账户管理

op whoami op account list op signin --account <shorthand-or-signin-address>

使用秘密引用运行命令（op run）

将**秘密引用（而不是解析后的值）**保留在环境文件或环境变量中：

export DB_PASSWORD="op://app-prod/db/password" op run -- printenv SAFE_NON_SECRET_VALUE op run --env-file="./.env" -- your-command

秘密引用采用op://vault/item/field形式的 URI。op run会在启动目标命令前解析这些引用并注入进程环境。不要通过打印含秘密的环境变量来演示成功；除非用户明确需要且输出目的地安全，否则避免--no-masking。

模板注入（op inject）

op inject -i config.yml.tpl -o config.yml

生成的配置文件包含已解析的秘密。仅在用户明确要求持久化文件时才创建，创建后要收紧权限、排除出版本控制，并尽可能在完成后清理。

读取单个秘密（op read）

op read "op://app-prod/db/one-time password?attribute=otp" op read --out-file ./key.pem "op://app-prod/server/ssh/key.pem"

op read默认把秘密写到 stdout，除非使用--out-file。仅当可信的本地消费者确实需要该值时使用，且必须抑制被捕获的输出、绝不在助手回复中包含该值。输出文件与注入文件一样需要持久化秘密的全部安全措施。

安全护栏（Guardrails）

SKILL.md明确列出六条不可逾越的护栏：

1. 绝不通过聊天转发秘密值，也不把秘密包含进摘要中；
2. 绝不使用"以打印秘密来证明访问权限"的命令；改用op whoami和仅含元数据的列举命令；
3. 进程环境变量优先op run，模板优先op inject；
4. 写入注入文件或使用op read --out-file会持久化秘密材料——仅在用户明确要求时进行，并需收紧权限、排除出版本控制、说明清理方式；
5. 除非用户明确要求非掩码输出且目的地已知安全，否则不要传--no-masking；
6. 认证过期时，应修复当前模式，而不是在用户不知情的情况下切换认证模式。

这些护栏并非孤立文本：在运行时层面，runtime.ts 记录skill_view工具调用时会输出技能内容与sha256哈希用于审计，技能加载、校验、修复链路（skill_view→skill_manage，见 packages/ekko-agent/src/tools/skills.ts 的SkillManageInput定义）保证了每个 Skill 的内容可被检查与校验，让"秘密不进上下文"成为可观测、可审计的执行约束。

总结

1passwordSkill 为 Ekko Agent 提供了一套可执行的秘密管理范式：先用op --version确认环境，再按OP_SERVICE_ACCOUNT_TOKEN→ 桌面集成 → 独立登录的顺序识别认证模式，用op whoami验证权限，随后以op run/op inject完成注入，以op read --out-file处理必须落盘的场景。其精髓在于尽量让秘密只存在于解析它的进程内，而模型、终端、日志、聊天与版本库全程无感。本文所涉技能本体（SKILL.md）与两份参考文档（get-started.md、cli-examples.md）均可在仓库中直接查阅，配套的 tmux Skill 提供了独立登录所需的会话与轮询脚本。

• AI 应用
• 人工智能
• AI Agent
• 本地部署
• 前端
• 后端
• 工作流自动化