qlogicagent

qlogicagent 是一个普通的 ACP Agent adapter。它由 Runtime Host 作为受监管子进程启动，通过 JSON-RPC stdio 实现标准 ACP 会话协议；它没有 qlogicagent 专属的 Host 旁路、反向 RPC 或控制面。

职责边界

Runtime Host 是以下事实的唯一权威：

• canonical owner、project、session、history 和持久化；
• Provider profile、凭据、权限策略和 Agent 进程生命周期；
• Skill、MCP、记忆、附件、媒体、连接器和其他 Host 能力。

qlogicagent 负责：

• 模型推理、规划、工具选择和单回合执行；
• Agent 原生基础工具、权限执行点和指令加载器；
• 当前 native ACP session 的有界进程内上下文；
• 连接 Host 为该会话投影的普通 MCP server。

Host canonical session ID 与 adapter native ACP session ID 是两个身份。qlogicagent 不持久化 Host transcript、标题、摘要、恢复状态或项目注册表；进程重启后由 Host 重新投影 canonical history。

协议

Host 只通过 ACP 调用 adapter：

• initialize
• authenticate / logout（由能力协商决定）
• session/new
• session/load
• session/prompt
• session/cancel
• session/close
• adapter 声明支持的标准 session 配置方法

Agent 使用标准 session/update 流式提交文本、思考和工具进度，并通过 session/request_permission 请求授权。session/prompt 结果只包含标准终止原因和可选用量。

qlogicagent 在 initialize 中声明通用 promptCapabilities.embeddedContext。Runtime 只按这个能力协商结果，以 astraclaw.agentContext _meta 投影 Host 上下文；同一规则适用于任何声明该能力的 adapter，不按 Agent ID 分支。

服务端嵌入

@xiaozhiclaw/qlogicagent-core 通过 createEmbeddedAgent 提供窄化的服务端嵌入契约。调用方只注入模型传输、工具执行器、日志和有限回合配置；账号、租户、会话、知识、业务数据与部署仍由调用产品持有。公共类型不暴露桌面 Host、ACP、MCP、Skills、子 Agent、文件系统或任务生命周期。

Skill、MCP、记忆、附件、项目、预览、安装和凭据等 Host 能力只通过会话绑定的普通 MCP/Tool 目录提供。qlogicagent 不安装、配置或管理这些 Host 能力。

更完整的 wire 边界见 docs/acp-extensions.md。

代码结构

src/
├── cli/             ACP 组合根、会话适配、权限和会话级 MCP 装配
├── agent/           推理与工具循环
├── orchestration/   Agent 内部的纯策略和子 Agent 执行构件
├── runtime/         Agent 本地运行时、提示、hooks、native session 投影
├── skills/          原生基础工具、权限检查、MCP client 和 Skill 读取
├── protocol/        ACP wire 类型与内部 turn 事件
├── transport/       ACP server 和标准事件映射
└── contracts/       内部端口契约

Provider 传输实现来自 @xiaozhiclaw/provider-core。仓内只保留传输端口和组合门面，不复制 Provider 实现。

开发

要求 Node.js 24。

pnpm install
pnpm run build
pnpm run check

本地 ACP 调试：

node dist/cli.js --acp

pnpm run check 是完整门禁，覆盖类型、机械规则、架构边界、全量测试和 npm 制品初始化。边界回归由 src/cli/ordinary-acp-adapter-boundary.test.ts 与 Runtime supervisor 测试共同锁定。

原生文件

qlogicagent 继续读取自己的原生指令文件，例如项目中的 INSTRUCTIONS.md、INSTRUCTIONS.local.md 和 .qlogicagent/rules。Host 共享指令是额外基础层，不覆盖或禁用任何 Agent 的原生指令机制。

QLOGICAGENT_HOME 只改变 adapter 原生运行数据根目录，不能改变 Host 权威、绕过 Host 凭据或建立第二份 canonical session store。

发布

发布由维护者从已与远端同步且工作区干净的 master 执行：

node scripts/release.mjs
node scripts/release.mjs --publish
npm view qlogicagent@<version> version dist.tarball dist.integrity

第一条命令只做预览和完整门禁；第二条命令显式发布同一流程校验的制品；第三条命令核对已发布版本及不可变制品信息。CI 不自动创建 tag 或发布 npm 包。