Sec

Your gofer. A second you, in a second.

你的数字孪生小二，随叫随到，迅速响应。

Sec 是一个可编程的 AI Agent SDK，也提供终端聊天 CLI。你可以直接用 CLI 与模型协作，也可以通过 Python Client 将 Sec 集成到自己的应用，或用 Extension 添加工具、命令和运行时能力。

快速开始

要求 Python 3.12 和 uv。

uv python install 3.12
uv sync
cp .env.example .env

编辑 .env，选择 OpenAI 或 Anthropic Provider，并填写模型名和 API key。也可以设置通用变量 SEC_PROVIDER、SEC_MODEL、SEC_API_KEY。不要提交包含真实凭据的 .env。

uv run python -m sec

CLI 支持交互式聊天、Session 管理、内置工作区工具和权限模式。第一次使用建议保持默认的 normal 模式；工具执行前会请求确认。详见终端 CLI 教程和权限与工具教程。

可选桌面应用

桌面应用位于 sec/apps/desktop/，与 CLI/SDK 共用主包和环境，Qt 仅作为 desktop 可选依赖。当前发行包名是 sec-gofer-agent，默认安装不包含 Qt：

pip install sec-gofer-agent
pip install 'sec-gofer-agent[desktop]'  # 需要桌面能力时安装
sec-desktop

仓库开发运行：

uv sync --extra desktop --no-editable
uv run --no-sync sec-desktop
# 或 uv run --no-sync python -m sec.apps.desktop

若数据库配置使用 opengauss+asyncpg，同步时必须同时保留两组可选依赖： uv sync --extra desktop --extra opengauss --no-editable。 pip 安装则使用 pip install 'sec-gofer-agent[desktop,opengauss]'。 后续仅同步 desktop 会移除 openGauss 方言和 asyncpg 驱动。

支持大屏专注/悬浮球切换、会话恢复、流式回答、工具审批及 CLI 斜杠命令。 Extension 安装到同一 .venv 后，可通过 --extension <name> 显式启用； 交互 CLI 也支持 /reload 查看已安装扩展，并用 /reload enable <name...> / /reload disable <name...> 在当前 Client 生命周期内切换启用集合。 进程内扩展启停仅影响后续 Trace；需要工具代码热更新时使用显式 tools-only worker 模式。AgentCard、Skill 和 MCP 管理通过共享核心资源 API 实现。 详细说明见桌面应用。

CLI 界面速览

交互式终端启动后会先显示当前运行环境摘要，再进入可编辑的 you > 输入框。下图为字段示意，实际路径、模型、Session ID 和资源数量取决于本机配置：

╭ Sec v0.1.0 — Your gofer. A second you, in a second.
│
│ ⌂  Working directory  /path/to/project
│ ◈  Model              your-model
│ #  Session            <session-id>
│ ◉  Tool mode           normal
│ ✦  Resources           1 Skills · 1 Prompts
│
│ Ctrl+C cancel Trace · Ctrl+D exit · Tab complete · /help commands
│ Press Ctrl+O for full startup help and loaded resources.
╰
you >

发出消息后，Sec 会显示流式回答和 Trace/工具状态。工具需要审批时，会显示工具名称、参数和策略原因，等待输入 y 或 n；默认拒绝。交互终端支持多行编辑和命令补全：Enter 发送，Alt+Enter 换行，Trace 运行中按 Alt+S steer 当前 Trace，按 Alt+F 将当前输入排到 Trace 之后，Tab 补全命令。Trace 运行中直接发送普通文本也会排为 follow-up。

终端不支持原始按键输入时会退回逐行输入界面；非交互式管道输入没有审批提示界面，需确认的工具调用会拒绝。详见CLI 界面与操作指南。

Python Client 一分钟

普通脚本可从同步 SecClient 开始。Client 上下文中连续调用 run() 会沿用同一个 Session 历史：

from sec.apis import SecClient

with SecClient("assistant", "遵循用户指令。") as client:
    first = client.run("解释当前项目的入口。")
    print(first.text)
    print("Session:", client.session.id)

    second = client.run("再说明它如何加载配置。")
    print(second.text)

需要 asyncio、流式事件、Session 恢复或精细 Trace 控制时使用 AsyncSecClient。两类 Client 都应使用上下文管理器；失败通过异常传播，成功的 TraceResult 提供文本、调用次数和用量信息。SDK Client 默认不附加 CLI 的内置文件/Bash 工具；通过 tools= 或 Extension 显式提供工具。完整示例见同步 Client、异步与流式 Client和Trace 控制。

选择使用方式

• 使用终端聊天：从安装与第一次对话开始。
• 集成 Python 应用：查看同步 Client或异步与流式 Client。
• 扩展 Sec：跟随创建第一个 Extension。
• 查询配置项：查看配置参数参考。
• 浏览全部教程：进入教程首页。

当前功能

• CLI：交互式与管道式对话、命令补全、Trace 控制、权限模式、Session 分支和便携式导入/导出。
• Python SDK：同步和异步 Client、流式响应、工具调用、Trace 事件与运行控制。
• 工具与策略：类型化工具定义、参数校验、工作区内置文件工具、工具审批及可替换 Policy/Executor；safe_parallel 标记只读工具以并入混合执行器的并行分组。
• AgentCard 与能力目录：选择和恢复智能体身份；Skills 支持模型原生发现、按需加载和确定性必用规则；Prompts 保留为输入模板。
• 会话内刷新：原子发布能力 generation，进行中的模型请求和完整工具批次保留旧绑定，后续请求使用新版本。
• MCP 与工具 worker：MCP 连接、发现和调用沿用核心工具审批链；显式工具 worker 支持无需重启宿主的代码更新。
• 多 Agent 委派：子任务使用独立 Session，继承能力上限、共享每轮预算、审批和取消控制；支持 fanout 并发上限、预算切片、actchain 令牌链与级联撤销。
• Extensions：通过 Python entry point 显式启用，可注册工具、Provider、Policy、SessionStore、UI handler、CLI 命令和 Trace hooks。
• Session 与存储：进程内或 SQLite SessionStore、会话恢复和分支操作；提供可实现的 ObjectStore 协议。
• 运行可靠性：模型及安全声明工具的有限重试、可控的工具错误反馈、每轮调用预算、用量统计和可选上下文压缩。
• 可观测模型：一次执行是一棵 Trace（其原子步骤为 Span）；Trajectory 提供跨多轮对话拍扁后的扁平行为序列（用户/助手/工具步骤），与技术细节解耦，便于检索和展示。

0.3.0 更新与升级说明

• 双层模型与辅助推理：新增 main/small 模型路由，以及可选的意图分类、查询改写、输出评估和 Trace 摘要；未配置小模型时复用主模型。辅助步骤默认关闭，启用后有独立调用预算，配置见 .env.example。EntityExtractor 提供独立 API，尚未接入主循环。
• 工具与委派：新增 question 宿主交互工具；safe_parallel 工具仅在策略直接允许时并行，需审批的调用仍作为串行屏障；委派增加并发上限、预算切片和令牌链撤销。
• 三层记忆：区分语义事实、情景记录和程序性偏好，新增 JSON 文件仓储；长期偏好可整理到 USER.md 自动维护区，保留手写内容。桌面端新增记忆管理页面。
• 桌面与调度：新增持久化 Cron 定时任务及管理页面，回答操作栏支持复制、反馈、标记等操作；修复对话组件销毁时的信号引用问题，以及运行中的定时任务完成后覆盖删除/停用状态的问题。
• Trace 存储：数据库 SessionStore 下复用 Client 的共享 Database；旧本地 Trace 数据库支持迁移并保留备份，本地路径可通过 SEC_DESKTOP_TRACE_STORE_PATH 配置。

从 0.2.x 升级时，建议先备份工作区 .sec/ 和数据库。自定义记忆仓储需要实现新增的 list() 接口；EpisodicRecord 不再接收 embedding 参数，向量生成由数据库仓储及注入的 Embedder 负责。SQLite 使用 FTS5，无需配置 Embedder；PostgreSQL/openGauss 向量后端的原生 vector 列和索引仍需在目标数据库环境单独验证。

安全与支持边界

• plan、normal、auto 模式对工具调用应用不同策略。auto 仅自动允许工作区范围内的内置文件工具；Bash 和其他高风险操作仍需审批。
• 内置 Bash 以当前用户权限在主机上运行，不是安全沙箱。不要执行不可信命令。
• CLI 的 Skills 和 Prompts 是提示文本，不执行 Markdown 文件中的代码；Extension 则是可执行 Python 包，只应启用可信扩展。
• 当前 Provider 支持 OpenAI 与 Anthropic 的文本和工具交互；多模态内容尚未适配。
• Dashboard、网络 A2A 和云厂商 ObjectStore 适配器尚未实现。/share、/thinking 和手动 /compact 也尚不可用。
• 工具 worker 不是安全沙箱；进程内 Extension 的任意 Provider、存储、UI 和 hooks 不支持原地代码热替换。详见 AgentCard、MCP 与 Reload。

开发与测试

uv sync
uv run python -m unittest discover -s tests -v

项目使用 uv.lock 锁定依赖。修改依赖后请一并提交 pyproject.toml 和 uv.lock。