# AgentLLM **Repository Path**: codelint/AgentLLM ## Basic Information - **Project Name**: AgentLLM - **Description**: 一个帮助各种语言完成一轮对话的库 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-11-17 - **Last Updated**: 2026-11-19 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # AgentLLM **跨语言的 LLM 对话库项目**:把「模型调用 / 工具协议 / 工作区抽象 / MCP 客户端骨架 / 工具循环编排」封装在一处,调用方只负责**选模型、装工具、给提示词、注入工作区**。 本仓库的 Swift 实现源自 agentlint iOS App 中的独立包 `Packages/AgentLLM`(agentlint 工单 #717 抽取、#734 Linux 跨平台)。本仓库把该能力从 agentlint 中独立出来,按语言分叉演进。 | 项 | 取值 | |---|---| | 项目定位 | 跨语言 LLM 对话库:一次调用完成一轮(或带工具的多轮)对话 | | 判定标准 | 把库单独拿走放进一个全新的项目,**不依赖宿主业务的任何代码**,也能跑通一次带工具的对话 | | 主干分支 | `master`:**只放仓库说明与跨语言设计 / 接口文档,不提供任何代码** | | 语言分支 | 每种语言一个分支(`swift` …),承载该语言的完整实现与语言专属文档 | | 派生分支 | 从某个语言分支派生的工作分支,必须带该语言分支前缀标识来源(如 `swift/fix-timeout`) | | 依赖 | 各语言实现原则上只用标准库 / 系统框架,不引第三方依赖 | --- ## 1. 仓库模型:一份设计,多份实现 不同语言在类型系统、并发模型、包管理、平台覆盖面上差异太大。强行统一成一份代码,只会让每种语言都别扭。因此本项目采用: - **主干**维护**跨语言不变量**:数据结构语义、调用逻辑、事件顺序、错误口径、命令行行为; - **语言分支**只负责把这些不变量翻译成该语言最地道的写法; - **语言分支之间不得互相合并**:任何跨语言的改动,先回主干改设计,再各自落到各语言分支。 ### 分支规则 | 分支 | 内容 | 规则 | |---|---|---| | `master` | 仓库说明、跨语言设计说明、跨语言接口契约、跨语言 CLI 行为契约 | **不含任何实现代码**;任何语言分支都不向 master 合并代码,只合并「设计变更」 | | `<语言>`(如 `swift`) | 该语言的完整实现、测试、语言专属文档 | 一语言一分支;**语言分支之间不得合并** | | `<语言>/<描述>`(如 `swift/fix-timeout`) | 从某语言分支派生的工作分支 | 必须带**来源语言分支前缀**,用于标识它派生自哪个语言分支;工作完成后合回自己的语言分支 | > 「不得合并」的准确含义:禁止把 `swift` 的代码合进 `python`(或反之),也禁止用 merge 把两个语言分支的差异一次性糊在一起。跨语言共有的改动,走「主干改设计 → 各语言分支各自落地」。 > > 「不得合并」同时涵盖 cherry-pick、跨分支搬运文件与跨分支 PR 合并。 #### 约定约束内容、派生关系、提交历史与目录获取 约定共四条,涵盖**每个分支的树内容**、**分支之间的派生关系**与**各分支的提交历史**: | 维度 | 约定 | |---|---| | 主干内容 | `master` 的树内容**只有文档**(`README.md` 与 `Docs/**`),不含任何实现代码 | | 语言分支内容 | 语言分支的树内容**互不混合**(`swift` 分支不含 `.go` 文件,`go` 分支不含 `.swift` 文件) | | 派生关系 | 派生的工作分支**带来源语言前缀**(如 `swift/fix-timeout`),标识它派生自哪个语言分支 | | 提交历史 | 各分支的提交历史**彼此独立**:三条分支自共同基点 `7fb28c4` 分叉,**任何分支都不得包含另一分支的提交**;`master` 只接受主干自己的文档提交 | 这四条约定落到**本仓库**的工作区目录上,追加两条硬约束:**分支靠克隆获得、不靠切换获得**;**切换必须 1:1 对齐**(本节目录约定仅适用于本仓库的多分支模型)。 - **一个目录只服务一个分支**:每个分支用**独立克隆**得到并固定服务它(如 `src/AgentLLM-Swift/` 只服务 `swift`);要另一个分支就**另行克隆**,不要在已有目录里切分支。 - **同目录切换须 1:1 对齐**:确需在同一目录切换分支时,切换前目录须与目标分支树**完全一致**——无未提交改动、无未跟踪文件、无仓库里不存在的多余文件;不满足先清理或重新克隆,**不要**带脏状态切换;跨语言分支切换本身**不建议**。 - **例外**:`<语言>/<描述>` 工作分支(如 `swift/fix-timeout`)是该语言分支的内部约定,可在对应语言目录使用;但它同样**不得**合进 `master` 或其它语言分支。 实操上:派生新语言分支时**以目标分支的当前树内容为准**——从内容干净的主干树派生,不要从别处搬运代码。 ### 主干与语言分支的目录对照 主干与每个语言分支**在本地工作区的 `src/` 下并存于不同目录**(本仓库各分支的推荐摆放),便于逐条对照: ```text src/ ├── AgentLLM/ # 主干 master:只有仓库说明与跨语言文档 ├── AgentLLM-Swift/ # 语言分支 swift:Swift 实现(分支名 swift) ├── AgentLLM-Python/ # 语言分支 python:Python 实现(分支名 python) └── ... ``` 对照开发时的读法: 1. 先读主干 `Docs/design.md` 与 `Docs/api.md`——这是**契约**,不是建议; 2. 再读对应语言目录里的实现与测试——这是**该语言的落地**; 3. 改动先落语言分支;若涉及跨语言语义(数据结构、调用流程、事件顺序、错误口径、命令行行为),**先改主干文档**(库层见 `Docs/design.md` / `Docs/api.md`,命令行层见 `Docs/cli.md`),再回到语言分支落地。 新增语言时照此办理:克隆本仓库到 `src/AgentLLM-<语言>`,创建 `<语言>` 分支,在其中实现该语言版本,并在该分支 README 中登记与主干的差异对照表。 --- ## 2. 跨语言设计约束 所有语言分支的实现都必须遵守: 1. **数据结构一致**——同一语义的概念在各语言里字段同名、同类型、同默认值,序列化形状一致(见 [`Docs/design.md`](./Docs/design.md) 第 3 节)。 2. **调用逻辑一致**——编排循环、轮次上限、工具执行顺序、停止语义、补齐轮、超时与取消口径一致(第 4 节)。 3. **接口能力可因语言而异**——语言特性导致的**能力差异**允许存在(例如某语言没有枚举就用字符串常量、没有 `async/await` 就用回调或协程、字节与时间类型不同),但必须在**该语言分支的 README 中列出差异对照表**,说明「主干要求 → 本语言实现 → 差异原因」。 4. **不允许静默偏离**——任何与主干不一致的地方,要么在分支 README 的差异表里申报,要么改回来。 5. **序列化判定口径**——跨语言一致性以**字段集合与值一致**判定(**键序不敏感**);「逐字节一致」只在两侧使用同样的键序与转义设置时成立,属附加约束(键序与转义规则见 [`Docs/design.md`](./Docs/design.md) 第 3.4 节)。 --- ## 3. 库接口说明 完整契约见 [`Docs/api.md`](./Docs/api.md)(语言中立的字段表与语义),设计与边界见 [`Docs/design.md`](./Docs/design.md)。以下是骨架: ### 3.1 分层 | 层 | 职责 | 依赖方向 | |---|---|---| | Core | 错误类型、JSON 值、消息结构、结果结构、日志协议 | 不依赖任何其它层 | | Request | `ChatRequest` / `ProviderRequest` / 采样与思考参数 / 工具选择 | → Core | | Provider | 提供者协议、流式事件、三个默认 Provider、HTTP 策略与指标 | → Core、Request | | Tool | 工具协议、工具输出、工具上下文、工具转换器 | → Core | | Workspace | 工作区抽象、本地实现、内置文件工具 | → Core、Tool | | Orchestrator | 工具循环编排器、轮次检查点、编排事件 | → 上述全部 | | MCP | JSON-RPC 客户端骨架与传输协议 | → Core | ### 3.2 最小调用流程 ```text provider = 构造某个模型厂商的 provider(地址 + 凭证 + 模型名) request = ChatRequest(provider, messages 或 userPrompt, tools 可选) turn = 编排器.run(request) # 库内跑完「请求 → 工具 → 回灌 → 再请求」 answer = turn.text ``` 不带工具时一次模型请求即返回;带工具时由编排器自动完成工具循环,调用方看不到中间步骤。 ### 3.3 公开面清单 | 领域 | 类型 | |---|---| | 核心 | `AgentLLMError` · `JSONValue` · `Message` / `MessageContent` / `MessageRole` · `ToolCall` · `Usage` · `AssistantMessage` · `AssistantTurn` · `ToolResultRecord` | | 提供者 | `ChatModelProvider` · `ProviderEvent` · `ProviderRequest` · `ToolDefinition` · `SamplingParams` · `ThinkingConfig` · `ToolChoice` | | HTTP | `HTTPPolicy` · `RetryPolicy` · `RedirectPolicy` · `RequestGate` · `RequestInterceptor` · `AgentLLMMetrics` / `RequestMetrics` | | 工具 | `Tool` · `ToolOutput` · `ToolContext` · `ToolTransformer` · `ToolExecutionBlocked` | | 工作区 | `LLMWorkspace` · `WorkspaceEntry` · `WorkspaceCapabilities` · `WorkspaceError` | | 编排 | `ConversationOrchestrator` · `ChatRequest` · `OrchestratorEvent` · `StopReason` · `RoundPlan` · `RoundContext` | | MCP | `MCPClient` · `MCPTransport` · `MCPToolDescriptor` | | 观测 | `AgentLLMLogger` / `AgentLLMLogLevel` · `AgentLLMMetrics` / `NoopMetrics` | --- ## 4. 库做什么、不做什么 | 能力 | 归属 | |---|---| | 模型调用、流式事件、工具协议、工作区抽象、MCP 客户端骨架、工具循环编排 | **库内** | | 系统提示词 / 人设 / 规则拼接、内容安全、多模态预处理、组合模型路由 | 调用方 | | 网关凭证注入、HTTP 协议收紧(http→https)、ATS 豁免、端点路径拼接 | 调用方 | | 调用计数、用量落盘、会话统计、缓存保护、模型禁用 | 调用方 | | 流式 UI 渲染节流、本地化文案与模板 | 调用方 | | MCP 传输实现与子进程发现 | 调用方 | | 业务工具(git / ssh / asc 等) | 调用方 | | 命令行前端(参数解析 / 本地配置 / 终端渲染 / 退出码) | 业务产品层:行为契约见 [`Docs/cli.md`](./Docs/cli.md),实现不进库 | 判定口径:**库只定义抽象与协议,默认实现一律可被调用方替换**;库内不读宿主配置、不读用户偏好、不产出本地化文案、不含任何凭证。 --- ## 5. 文档 | 文档 | 内容 | |---|---| | [`Docs/design.md`](./Docs/design.md) | 跨语言设计说明:定位与边界、分层、数据结构规范、调用逻辑规范、语言差异申报方式 | | [`Docs/api.md`](./Docs/api.md) | 跨语言接口契约:类型、字段、默认值、语义、不变量 | | [`Docs/cli.md`](./Docs/cli.md) | 跨语言 CLI 行为契约:参数、配置根与目录布局、模型与凭证、提问词、工具与命令执行、输出与主题、敏感信息、退出码、语言分支实现状态表 | | [`Docs/README.md`](./Docs/README.md) | 文档索引与阅读路径 | 语言分支各自携带自己的实现级文档(Swift 版见 `swift` 分支的 `Docs/`,Go 版见 `go` 分支的 `docs/`);其中命令行前端的实现级说明随该语言分支的 CLI 文档走,行为仍以 [`Docs/cli.md`](./Docs/cli.md) 为准。 --- ## 6. 如何判断分支拓扑 判断分支之间的关系时,**不要用 `git_log` 的输出推断**。 `git_log` 返回的是**跨所有分支、按时间倒序**的提交列表(等价于 `git log --all`):各分支的提交按时间交错排列,看上去像一条线性祖先链,**实际不表示任何父子关系**。要确认拓扑,用下面几种方式: | 要判断的事 | 用什么 | |---|---| | 某分支相对另一分支多出哪些提交、文件差异如何 | `git_branch_diff`:`branch` 指定被比较的分支,`target` 指定基准分支(可用 `origin/xxx`) | | 某分支当前指向哪个提交 | 直接读 `.git/refs/heads/<分支名>` 里的引用哈希 | | 本地与远端各有哪些分支 | `git_branch` | 判断「两条分支是否互相包含」,用以上几项交叉验证;共同基点(合并基)同样应由这类工具判定,**不要**靠读提交列表猜测。 > 提醒:`git_log` 的时间序排列**不表示**父子关系。