@jangts/agent-core 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# 变更日志
+
+本文件记录 `@jangts/agent-core` 的行为变更。接口合同与使用方式见[API 手册](development/docs/api/README.md)。
+
+## 0.2.0
+
+### 新增
+
+- `CompatibleModelPorts.completionPolicy`：宿主可注入完成判定策略。未注入时使用 `Support.completionPolicyCatalog.default`，请求、完成规则与 `MODEL_*` 分类与旧版本逐项一致。
+- `Support.completionPolicyCatalog.session`：按实际下发请求体中的 `tool_choice` 判定的标准会话完成策略，覆盖 `auto`、`required`、指定函数、`none`、字段省略与未知值。
+- `Support.createToolCallCollector`：按 index 聚合调用分片的共用实现，完成策略与直连调用方使用同一算法；ID 冲突、跨 index 重复 ID 与残缺调用按协议错误拒绝。
+- `ProviderMessage`：直连 Provider 的工具线程消息类型；`chatCompletionMessages` 显式映射 `tool_call_id` 与嵌套 `tool_calls`，不做整体透传。Core `ModelMessage` 与 `ChatProvider` 抽象签名不变。
+
+### 修复
+
+- 工具线程消息只发送声明字段，不透传原始 wire 字段或宿主附加数据；动态输入校验角色、正文类型及工具结果的非空字符串 ID。
+
+- 兼容 Provider 的 CommonJS 产物与 ESM 产物恢复一致：调用记录草稿的类型不再因只读耗时字段导致编译失败，`dist/cjs` 重新生成并导出完成策略与 collector。

package/README.md

@@ -1,5 +1,64 @@
+[English](#english) | [中文](#中文)
+
+<a id="english"></a>
+
+# @jangts/agent-core
+
+<img src="https://agent-core-docs.pages.jangts.cafe/branding/agent-core-logo.png" alt="Agent Core" width="420">
+
+A platform-independent agent runtime with a runtime API, companion Support utilities, and optional Kits. Supports ESM, CommonJS, browsers, and Node.js.
+
+[Full developer documentation](https://agent-core-docs.pages.jangts.cafe)
+
+```sh
+npm install @jangts/agent-core
+```
+
+A minimal Core call needs only a Provider and raw input. Support is optional:
+
+```ts
+import { CompatibleModelProvider, ModelRunner } from '@jangts/agent-core';
+
+const provider = new CompatibleModelProvider({ config: {
+  baseUrl: process.env.AI_BASE_URL!,
+  apiKey: process.env.AI_API_KEY!,
+  model: process.env.AI_MODEL!,
+} });
+const model = new ModelRunner({ provider });
+const text = (await model.invoke('Hello')).value;
+```
+
+This connects to a real Chat Completions-compatible model; the application supplies all three connection settings. See [Basic usage](development/docs/basic-usage.md) to override settings or add tools, context policies, and workflows.
+
+- [How it works](development/docs/mechanisms.md): collaboration, tasks, execution flow, model/tool sequences, and an application knowledge-answering example.
+- [Developer guide](development/docs/README.md): new applications, existing project integration, manual and agent-assisted development, knowledge resources, and runtime growth.
+- [API reference](development/docs/api/README.md): examples, parameters, return values, and exceptions.
+- [Complete knowledge-answering example](development/docs/api/knowledge-answering.md): reading sources, context, generation, checking, and template-based delivery.
+
+[MockGPT Kit](development/docs/api/mock.md) provides direct mock generation, Provider protocol injection, a minimal Node server, and web text sources through `@jangts/agent-core/mock`, `/mock/node`, and `/mock/web`, without a separate mock dependency import.
+
+Import Core and Support from the package root. Import Kits by module, or use the aggregate `/kits` entry point.
+
+The package manager installs streaming, mock-gpt, and other runtime dependencies automatically. See [Installation](development/docs/getting-started.md).
+
+The `agent-core-app` Skill provides resource preparation and validation tools. See [Agent-assisted development](development/docs/agent-development.md).
+
+Regular Workflow nodes assemble, select, trim, or compress context, with replaceable implementations from Support. Core retains generic trust/structure auditing, actual request measurement, budgets, and cancellation guarantees. To retain recent verbatim messages or ongoing task summaries, apply a recommended Support policy to the same configuration and override individual parameters. See [Context nodes](development/docs/api/context-processing.md).
+
+Bind fixed model definitions, Workflows, and tools ahead of time, passing only per-request state. Existing request-level Runners can join the same Engine through `bindModelRuntime` and reuse its budget and scope. Applications register `execution.observe.event` to receive execution facts; persistent logging is independently optional.
+
+`ModelRunner.sink.output` receives actual generated chunks while preserving call budgets, cancellation, and protocol validation; `invoke` still returns the complete result. Applications can use `Support.createReplyPreview` to register previewable functions and body JSON paths, then send in-progress previews with `Support.streamEvents`. Confirm the final body after business validation, or retract it on failure. Previews cannot serve as authorization, tool execution, or official history. See [Core API](development/docs/api/core.md).
+
+In this repository, `npm run test:agent-audit` builds Agent Core and MockGPT and runs logic, security, and performance regressions. Use `-- --repeat=2` for two consecutive rounds or `--no-build` to reuse existing builds. Coverage merges V8 ranges with c8/Istanbul and includes every generated ESM module, including modules not imported by existing tests. Statements, lines, functions, and branches must all reach 100%; uncovered logic fails the audit even if assertions pass. Reports are written to root `.tmp/agent-audit/`. Builds remove stale package output so moved sources cannot leave obsolete modules. Regressions use offline resources, injected ports, and loopback HTTP, without real models or public websites; they do not verify real-model comprehension or decision quality.
+
+---
+
+<a id="中文"></a>
+
 # @jangts/agent-core
 
+<img src="https://agent-core-docs.pages.jangts.cafe/branding/agent-core-logo.png" alt="Agent Core" width="420">
+
 平台无关的 Agent 运行库，提供运行 API、配套 Support 与可选 Kit。支持 ESM、CommonJS，以及浏览器／Node 环境。
 
 [完整网页开发文档](https://agent-core-docs.pages.jangts.cafe)