开发参考

API、SSE、扩展方式和框架约束。运行、调试、打包与部署见项目 README。以下源码命令均在项目根目录执行，使用项目虚拟环境。

API

主入口与 1.5 一致，额外新增了若干辅助接口。

对话

方法	路径	说明
POST	`/api/chat`	主入口，SSE 流式
POST	`/api/chat/resume`	恢复被中断挂起的对话
GET	`/api/chat/interrupt`	查挂起的中断（刷新页面补渲染卡片）；有则 200，无则 204
GET	`/api/chat/history/{session_id}`	会话历史

不提供 /api/chat/only，统一使用 /api/chat。

POST /api/chat 请求体是 multipart/form-data：

字段	必填	说明
`message`	是	用户消息，支持 `#skill:<name>` 与 `#session:<uuid>` 前缀
`session_id`	否	缺省则新建会话
`thread_id`	否	必须等于 `session_id`，否则 404
`mode`	否	`plan`（先出计划待批）或 `full`（直接执行）
`file`	否	附件，落到 `/workspace/uploads/`
`request_id`	否	客户端生成的请求唯一键；同一用户重复提交返回 409 和原 `session_id`、`run_id`
`user_name`	否	归属用户，缺省 `default`（2.0 新增，替代 1.5 的鉴权依赖）

响应是 text/event-stream，头含 X-Session-Id、X-Trace-Id 与 X-Run-Id。

会话与用量

方法	路径	说明
GET	`/api/sessions`	会话列表（置顶优先）
GET	`/api/sessions/search?q=`	标题模糊搜索
DELETE	`/api/sessions/{id}`	删除会话（同时清图状态）
DELETE	`/api/messages/{id}`	删除单条消息
GET/PUT	`/api/sessions/{id}/mode`	权限模式
PUT	`/api/sessions/{id}/pin` · `/title`	置顶 · 重命名
GET	`/api/sessions/{id}/runs`	最近 50 次执行的状态与错误
GET	`/api/sessions/{id}/context`	上下文用量明细与压缩存档索引
GET	`/api/usage/today`	当日用量与额度
GET	`/api/usage/recent`	最近用量流水
PUT	`/api/usage/quota`	调整每日额度（0 = 不限）
GET	`/api/usage/pricing`	模型单价表
GET	`/api/preferences` · PUT · DELETE	用户偏好（每轮自动注入）

模型与工具

方法	路径	说明
GET	`/api/model`	模型配置与 agent 组装摘要
GET	`/api/model/tools`	工具清单（按分组）
POST	`/api/model/thinking`	切换思考级别（触发 agent 重建）
POST	`/api/model/reload`	强制重建 agent

定时任务

方法	路径	说明
GET/POST	`/api/schedules`	列表 / 新建
GET/PUT/DELETE	`/api/schedules/{id}`	详情 / 更新 / 删除
POST	`/api/schedules/{id}/pause` · `/resume` · `/run`	暂停 / 恢复 / 立即执行
GET	`/api/schedules/{id}/runs`	执行记录

运维

方法	路径	说明
GET	`/health`	逐子系统健康状态
GET	`/api/health/billing`	计费自检（单价是否覆盖当前模型）
GET	`/`	重定向到测试页
GET	`/static/index.html`	极简测试页

SSE 事件契约

14 种业务事件 + 1 种通用错误。字段名是从 1.5 前端逐行反查出来的，不是猜的。

事件	前端读取的字段
`agent_start`	`agent` · `cn_agent`
`thinking`	`message` · `cn_agent`
`thinking_token`	`content`
`executing`	`message` · `cn_agent` · `tools[]` · `cn_tools[]`
`tool_call`	`tool` · `cn_tool` · `args` · `agent_id`
`tool_result`	`tool` · `cn_tool` · `content` · `error` · `agent_id`
`token`	`content`
`updated_todo_list`	`todos`
`progress`	`message`
`interrupt`	`tool_approval{tool,args,reason,side_effect}` 或 `ask_user{questions[]}` 或 `message`
`citations`	`items[]` · `model_only`
`agent_done`	`agent` · `cn_agent` · `duration_ms` · `progress` · `context_tokens`
`agent_error`	`agent` · `cn_agent` · `message` · `duration_ms`
`done`	`duration_ms` · `usage{}`
`error`	`message` · `code` · `retry_after`

帧格式：data: {json}\n\n，每帧恒带 session_id，绑定 trace 时带 trace_id。

HTTP 错误语义：额度超限 429；并发超限 429（带 retry_after）；上传 400/413；会话不存在或越权 404；恢复时无挂起中断 409。

契约的唯一出口是 api/sse_events.py，其他任何地方都不得手拼 data: 字符串。改字段必须同步改 tests/test_sse_contract.py。

四项核心能力（相对 1.5 的做法改进）

这是 2.0 与 1.5 的主要差异所在。

子智能体跟踪

	做法
1.5	从子图命名空间字符串 `tools:<X>` 反查 `subagent_type`；id 被上下文压缩裁掉后反查落空，子智能体身份丢失
2.0	收到 task 调用的那一刻就建 `tool_call_id → {类型, 描述}` 表，之后只按 id 查表；表由跟踪器持有，不受历史窗口影响

见 api/subagent_tracker.py。

上下文计量

	做法
1.5	tiktoken 本地估算优先，为此专门开了 `fix/context-usage-accounting` 分支修口径
2.0	真实 usage 优先（`usage_metadata`），provider 不给才回落估算并标 `usage_source=estimate`

两个量刻意分开：input_tokens 累加值是计费口径，context_tokens（最近一次调用的 input）是当前上下文占用。

见 api/context_meter.py。

自动压缩

	做法
1.5	自研 `auto_compact.py`，默认关闭，未被信任到敢开
2.0	直接用 deepagents 的 `SummarizationMiddleware`：85% 窗口触发，把被淘汰的历史追加落盘到 `/conversation_history/{thread_id}.md` 并把路径嵌进摘要，agent 能自己读回来

调节旋钮是 CONTEXT_LIMIT（声明窗口），不是阈值比例——阈值由框架固定为 85%。压缩存档位置可在 GET /api/sessions/{id}/context 的 archives 里查。

来源标注

	做法
1.5	靠提示词让模型自觉在正文写引用，再用启发式规则去正文里刮
2.0	工具侧结构化产出：工具返回 `sourced(data, sources)`，SSE 层从 ToolMessage 抽取、聚合、去重

模型漏写和编造这两种失败模式，在读工具返回值的路径上根本不存在。

见 api/source_tracker.py 与 tools/registry.py。

扩展方式

新增业务 Agent

在 extensions/<业务名>/ 下添加 __init__.py 和 extension.py。启动按目录名排序，自动加载每个 extension.py 的 setup(registry)，不需要修改工具模块列表、agent_factory.py 或主提示词。

例如 extensions/ventilation/extension.py：

from extensions import define_tool


@define_tool(group="通风", label="计算风量", name="calculate_airflow")
def airflow(area: float, speed: float) -> float:
    """根据断面积和平均风速计算风量，返回立方米每秒。

    Args:
        area: 断面积，单位平方米，必须大于零。
        speed: 平均风速，单位米每秒，不能为负。
    """
    if area <= 0 or speed < 0:
        raise ValueError("断面积必须大于零，风速不能为负")
    return area * speed


def setup(registry):
    registry.register_agent(
        name="ventilation",
        description="处理矿井通风量计算；需要用断面积和风速求风量时委派。",
        prompt="你是通风计算助手。先确认单位和输入，调用工具计算，说明结果单位。",
        tools=[airflow],
    )

define_tool 只声明元数据，不在导入时注册，函数可以直接单测。setup() 收集声明，全部通过校验后统一生效；不要在其中访问外部服务或执行业务操作。

description 自动加入主 Agent 的委派说明；prompt 是子 Agent 的系统提示词，不继承父级提示词。
tools 支持函数或已注册工具名。函数自动注册；字符串引用在所有扩展加载完成后校验，允许跨模块引用。
所有注册工具都会提供给主 Agent；子 Agent 只绑定自己的工具列表及框架内置能力。
只加工具时，在 setup() 调用 registry.register_tool(airflow)。已有工具传给多个 Agent 时会复用同一个注册名。
name 为实际工具调用名，可以与 Python 函数名不同；异步工具使用 async def。
提示词也可以放在业务目录的 Markdown 文件中，通过 Path(__file__).with_name("prompt.md").read_text(encoding="utf-8") 读取；发布包会包含这些文件。

内置示例见 extensions/demo/extension.py；extensions/core/extension.py 注册计划审批和询问用户工具，主提示词与恢复流程依赖它们，需保留。

声明审批

有写入或外部副作用的工具使用 @define_tool(..., requires_approval=True)。也可以在 Agent 定义中设置 approval_tools=[工具函数或名称]，但必须包含在该 Agent 的 tools 中。

审批要求按工具合并： 任意扩展要求某个工具审批后，主 Agent 和所有使用该工具的子 Agent 都会先等待批准。HITL_TOOLS 环境变量可以追加工具名；拼写错误会阻止启动。

校验与生效

启动会在数据库初始化、调度器启动之前检查：

工具和 Agent 名称格式、重名、与框架内置名称冲突。
工具函数能否生成参数 schema，是否提供 docstring 或 summary。
Agent 描述和提示词非空，工具引用有效，审批工具确实绑定。
setup() 缺失或加载失败、目录/入口符号链接等问题。

新增或修改扩展后重启服务，再用 GET /api/model 查看 agent.extensions 和子 Agent 列表，用 GET /api/model/tools 查看工具。/api/model/reload 只重建已加载定义，不重新导入业务代码。

开发时运行：

.venv/bin/python -m pytest
.venv/bin/python scripts/selfcheck.py

自检使用当前数据库配置，建议在开发环境执行。扩展代码及 .md/.txt/.json/.yaml/.yml 资源自动进入发布白名单；其他资源类型需调整 release/build.py。

旧 tools.registry.register 保留兼容；新业务统一使用 define_tool 与 setup(registry)，避免导入时修改全局注册状态。

来源标注和技能

工具需要返回引用来源时，使用 tools.registry.sourced(data=..., sources=[source(...)])，SSE 层自动生成引用事件。

技能仍放在 skills/<name>/SKILL.md，带有 name、description 的 YAML frontmatter。用户可以用 #skill:<name> 指定技能；技能是操作手册，不会替代工具注册。

配置

全部配置项见 .env.example，每项都有默认值。几个容易搞错的：

变量	说明
`DEEP_AGENT_ENV_PRIORITY`	`.env` 与进程环境谁优先。`dotenv`（默认）/ `process` / `none`。跑变体实例用 `process`：`DEEP_AGENT_ENV_PRIORITY=process DB_DIALECT=mysql PORT=8081 python main.py`
`DB_DIALECT`	`mysql`（生产）/ `sqlite`（本地开发与测试，无需数据库服务）
`DB_NAME`	MySQL 库名；库不存在时启动会自动建库，不需要手工 `CREATE DATABASE`
`CONTEXT_LIMIT`	声明的上下文窗口，压缩的唯一调节旋钮。0 = 用模型登记值
`CTX_COMPACT_ENABLED`	关掉会同时失去历史落盘能力，长会话会超窗报错
`CHECKPOINTER`	`sqlite`（默认，落盘）/ `memory`（重启丢图状态）
`HITL_TOOLS`	追加需要人工审批的工具名，逗号分隔。如 `calculate` 便于自测中断闭环
`BILLING_ALLOW_UNPRICED`	模型未定价时是否按 0 计费。默认 0 = 直接报错（fail-closed）
`TFAGENTS_DAILY_TOKEN_LIMIT`	每用户每日 token 限额，0 = 不限

配置冲突会被大声报出来：若 .env 与进程环境里有同名但不同的值，启动日志会打 WARNING（含脱敏后的生效值），/health 的 config_conflicts 也能看到。这解决的是一个很费时间的现象：改了配置却不生效，却没有任何提示。

验证

# 离线单元 + SSE 契约测试（不需要密钥，不需要数据库服务）
python -m pytest

# 结构自检：导入、建表、agent 编译、工具注册
python scripts/selfcheck.py

# HTTP 层端到端（需服务已启动 + 可用密钥）
python scripts/http_e2e.py

http_e2e.py 覆盖：SSE 帧格式与响应头、落库与顺序、错误语义（404/400/409）、中断/恢复闭环、定时任务的手动触发与 cron 校验。

目录结构

main.py                    FastAPI 入口（lifespan / 健康检查 / 静态挂载）
config.py                  配置唯一入口（.env 读取与冲突检测）
api/                       chat · sse_core · session · model · usage · schedule · concurrency
  sse_events.py            ★ SSE 契约唯一事实源
  sse_core.py              ★ 流式内核（读流 → 派事件 → 收尾）
  subagent_tracker.py      子智能体生命周期跟踪
  context_meter.py         上下文计量（真实 usage 优先）
  source_tracker.py        来源标注抽取与聚合
agents/                    agent_factory · agent_registry · model_factory · prompts · middleware · agent_memory
extensions/                registry · core/extension.py · demo/extension.py（统一业务扩展）
tools/                     registry（工具元数据与转换）· demo_tools（示例工具）
skills/demo-skill/         示例技能
db/                        db_conn（双方言）· mysql_schema.sql · schema_sqlite.sql · 三个 store
billing/                   pricing · guard（预检）· meter（入账）
scheduler/                 scheduler（APScheduler）· runner（独立会话执行）
obs/                       log_setup · tracing（trace_id）
static/index.html          极简测试页
tests/                     pytest（离线单元、HTTP 与真实图引擎回归）
scripts/                   selfcheck.py · http_e2e.py · start_server.sh

标 ★ 的两个文件是核心，改动时同步检查 SSE 契约与流式执行测试。

执行可靠性与隔离

统一准入：聊天、恢复和定时执行共用额度预检、并发闸、会话互斥、总超时、计量与收尾。并发满返回 429；同会话冲突返回 409。
运行状态：execution_runs 保存 running / waiting_input / success / failed / cancelled / interrupted。中断只表示等待输入，不发送完成事件；启动时将崩溃遗留的 running 标记为 interrupted。
请求去重：聊天可提交 request_id（1–128 字符）。相同用户的相同键不会再次运行，返回 409 和原会话、运行 ID；不重放旧 SSE。新任务应使用新键。
取消收尾：断连时停止消费图，保存已收到的部分回答、结算已观测用量，并释放占位。定时任务停机时等待取消收尾后再关闭 checkpoint。
持久化结算：同一流水使用稳定 ID，写账与累计额度在事务中完成。待结算数据保存在 billing_pending，服务启动后及每分钟重试。数据库完全不可写时仍只能日志告警；进程被强杀前尚未观测到的 provider 用量需要外部账单对账。
文件隔离：虚拟 /workspace/、/conversation_history/ 映射到 data/workspaces/<用户哈希>/<会话哈希>/。子智能体共享其父会话目录，其他会话不可见；/skills/ 共享只读。
定时任务：采用同一执行流程，注入模式和用户偏好；cron 与手动触发共用计划互斥，等待审批的运行记录为 waiting_input，从聊天恢复后同步结果状态。cron 显式使用 Asia/Shanghai。

Agent 人机交互

ask_user(questions)：提出一至三个必要问题并暂停，前端显示输入框；刷新页面可恢复问题卡。
request_plan_approval(plan)：提交计划等待确认。plan 模式提示词会准确指向这个工具。
批量工具审批卡完整展示每项工具及参数，批准按钮明确写出批次数量。
审批卡带 interrupt_token；恢复接口必须原样携带。服务端在会话锁内核对当前中断，过期、缺失和重复确认返回 409。
业务工具可在 @define_tool(..., requires_approval=True) 声明强制审批，组装时自动进入框架 HITL。plan 提示词本身不构成所有工具的硬权限边界，真实写操作应声明强制审批。
子智能体和摘要模型的用量计入总费用，其内部正文不混入主回答，也不覆盖主线程上下文占用。

升级已有部署

启动自动增建 execution_runs、billing_pending、request_keys，不会删除旧表。同步发布 static/app.js；自定义客户端需补传 interrupt_token。定时任务的详情、修改、删除、运行接口需携带其归属 user_name。

旧的共享 workspace/、conversation_history/ 原样保留，不会自动猜测文件归属或复制到新目录。旧会话需要的附件可重新上传；需要迁移的历史文件应先确认用户和会话归属。未登记的新模型现在会在执行前拒绝请求，不再自动写入零价；既有单价记录不会被覆盖。

已知缺口

当前只适合内网或开发环境，主要因为：

没有鉴权 —— user_name 由客户端自报，可伪造。计费与会话归属都建立在这个值上。需要为所有路由接入统一身份依赖，并区分普通用户与管理操作。
单进程 —— SQLite checkpointer、并发计数、调度器都是进程内的。多 worker 会导致会话状态分裂、定时任务重复触发。
并发计数不跨进程 —— 多进程部署需挪到 Redis/MySQL。

尚未提供业务工具/技能、MCP 接入及 remember；默认标题使用文本截断。

DEVELOPMENT.md 18 KB История Исходник